pierre-review 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Wakeman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# pierre-review
+
+A **local-only dashboard for tracking your team's GitHub PR activity** across
+multiple repositories. Run it on your machine, see at a glance who's doing what,
+which PRs are stalled, which review threads are sitting untouched, and what needs
+_your_ attention right now — all rendered as an interactive timeline.
+
+There's no hosted backend, no database server, and no stored credentials. It
+authenticates by shelling out to your already-logged-in `gh` CLI, syncs activity
+into a local SQLite file, and serves the dashboard from a single local process.
+
+## Quick start
+
+```bash
+npx pierre-review
+```
+
+This starts the server, prints a local URL, and opens your browser to it.
+
+Or install globally and use the short command:
+
+```bash
+npm install -g pierre-review
+pierre
+```
+
+## Prerequisites
+
+- **Node.js ≥ 20.**
+- **GitHub CLI**, installed and authenticated. Install it from
+  <https://cli.github.com>, then run:
+
+  ```bash
+  gh auth login
+  ```
+
+  `pierre` reads your team's activity using your `gh` token. It pre-checks this on
+  startup and exits with a friendly message if `gh` is missing or not authed.
+
+> **Native module note:** `pierre-review` depends on `better-sqlite3`, a native
+> addon. npm installs a prebuilt binary for common platforms; if none matches your
+> Node/OS/arch, npm compiles it from source on install (needs a C++ toolchain —
+> Xcode Command Line Tools on macOS, `build-essential` + Python on Linux, MSVC
+> build tools on Windows).
+
+## Usage
+
+```
+pierre [options]
+pierre-review [options]
+```
+
+| Flag | Env | Default | Description |
+|------|-----|---------|-------------|
+| `--no-open` | `NO_OPEN` | — | Don't open the browser on start. |
+| `--port <n>` | `PORT` | `4000` | Port to listen on. |
+| `--db <path>` | `DATABASE_URL` | `~/.pierre-review/pierre-review.sqlite` | SQLite DB path. |
+| `-h`, `--help` | — | — | Show usage. |
+
+Examples:
+
+```bash
+pierre --port 4123 --no-open
+pierre --db /tmp/pierre.sqlite
+```
+
+## Data directory
+
+By default the local SQLite database lives at:
+
+```
+~/.pierre-review/pierre-review.sqlite
+```
+
+The directory is created automatically. Override the location with `--db` or the
+`DATABASE_URL` environment variable. No team activity data or credentials are ever
+sent anywhere — everything stays on your machine.
+
+## How it works
+
+Once running, open the printed URL (default <http://localhost:4000>). Add the
+repositories you want to watch from the in-app picker; the app syncs their PR
+activity (full backfill on first sync, incremental every few minutes thereafter)
+into your local DB and renders it as a timeline.
+
+## License
+
+MIT

package/dist/api/plugins/error-handler.js

@@ -0,0 +1,40 @@
+// Centralised error handling: validation errors -> 400, anything with an
+// explicit statusCode is honoured, everything else -> 500.
+//
+// `spaFallback` is set in single-process production mode (when the built SPA is
+// served alongside the API). Fastify allows only one not-found handler per
+// context, so the SPA fallback lives here rather than as a second
+// setNotFoundHandler in app.ts.
+export function registerErrorHandler(app, spaFallback = false) {
+    app.setErrorHandler((err, req, reply) => {
+        if (err.validation) {
+            reply.status(400).send({
+                error: 'ValidationError',
+                message: err.message,
+                details: err.validation,
+            });
+            return;
+        }
+        const status = err.statusCode ?? 500;
+        if (status >= 500) {
+            req.log.error({ err }, 'request failed');
+        }
+        reply.status(status).send({
+            error: err.name || 'Error',
+            message: err.message,
+        });
+    });
+    app.setNotFoundHandler((req, reply) => {
+        // SPA fallback: any non-/api GET that didn't match a static asset returns
+        // index.html so client-side routes work on reload. Unknown /api routes still
+        // return JSON 404 (below). `reply.sendFile` is decorated by @fastify/static.
+        if (spaFallback && req.method === 'GET' && !req.url.startsWith('/api')) {
+            return reply.sendFile('index.html');
+        }
+        return reply.status(404).send({
+            error: 'NotFound',
+            message: `Route ${req.method} ${req.url} not found`,
+        });
+    });
+}
+//# sourceMappingURL=error-handler.js.map

package/dist/api/routes/health.js

@@ -0,0 +1,7 @@
+export async function healthRoutes(app) {
+    app.get('/api/health', async () => ({
+        status: 'ok',
+        time: new Date().toISOString(),
+    }));
+}
+//# sourceMappingURL=health.js.map

package/dist/api/routes/me.js

@@ -0,0 +1,34 @@
+import { ensureLocalUser } from '../../github/local-user.js';
+import { dismissMyTurn, getMyTurn } from '../../db/queries.js';
+const dismissSchema = {
+    body: {
+        type: 'object',
+        required: ['kind', 'refId'],
+        additionalProperties: false,
+        properties: {
+            kind: { type: 'string', enum: ['review_request', 'thread'] },
+            refId: { type: 'integer' },
+        },
+    },
+};
+export async function meRoutes(app) {
+    app.get('/api/me', async () => {
+        const user = ensureLocalUser();
+        const myTurn = getMyTurn();
+        return {
+            user,
+            counts: {
+                awaitingReview: myTurn.awaitingReview.length,
+                yourPrsActivity: myTurn.yourPrs.length,
+                threadsAwaiting: myTurn.threadsAwaiting.length,
+            },
+        };
+    });
+    app.get('/api/my-turn', async () => getMyTurn());
+    app.post('/api/my-turn/dismiss', { schema: dismissSchema }, async (req) => {
+        const { kind, refId } = req.body;
+        dismissMyTurn(kind, refId);
+        return { status: 'ok' };
+    });
+}
+//# sourceMappingURL=me.js.map

package/dist/api/routes/mergers.js

@@ -0,0 +1,7 @@
+import { getMergers } from '../../db/queries.js';
+// Per-repo "merge rights" inference (distinct users who've merged a PR there).
+// Reference data — no filters; the frontend looks it up per timeline row.
+export async function mergersRoutes(app) {
+    app.get('/api/mergers', async () => getMergers());
+}
+//# sourceMappingURL=mergers.js.map

package/dist/api/routes/open-prs.js

@@ -0,0 +1,21 @@
+import { getOpenPrs } from '../../db/queries.js';
+function parseIntList(raw) {
+    if (!raw)
+        return null;
+    const ids = raw
+        .split(',')
+        .map((s) => Number.parseInt(s.trim(), 10))
+        .filter((n) => Number.isFinite(n));
+    return ids.length > 0 ? ids : null;
+}
+export async function openPrsRoutes(app) {
+    app.get('/api/open-prs', async (req) => {
+        const q = req.query;
+        const prs = getOpenPrs({
+            repoIds: parseIntList(q.repoIds),
+            userIds: parseIntList(q.userIds),
+        });
+        return { prs };
+    });
+}
+//# sourceMappingURL=open-prs.js.map

package/dist/api/routes/prs.js

@@ -0,0 +1,50 @@
+import { getPrDetail, markPrViewed } from '../../db/queries.js';
+const idParamSchema = {
+    params: {
+        type: 'object',
+        required: ['id'],
+        properties: { id: { type: 'integer' } },
+    },
+};
+const markViewedSchema = {
+    ...idParamSchema,
+    body: {
+        type: 'object',
+        additionalProperties: false,
+        properties: { sha: { type: 'string' } },
+    },
+};
+export async function prRoutes(app) {
+    app.get('/api/prs/:id', { schema: idParamSchema }, async (req, reply) => {
+        const { id } = req.params;
+        const pr = getPrDetail(id);
+        if (!pr) {
+            reply.status(404);
+            return { error: 'NotFound', message: `PR ${id} not found` };
+        }
+        return pr;
+    });
+    // Record that the local user has seen this PR up to `sha` (defaults to the
+    // current head). Clears "new since last viewed" badges.
+    app.post('/api/prs/:id/mark-viewed', { schema: markViewedSchema }, async (req, reply) => {
+        const { id } = req.params;
+        const { sha } = (req.body ?? {});
+        const ok = markPrViewed(id, sha);
+        if (!ok) {
+            reply.status(404);
+            return { error: 'NotFound', message: `PR ${id} not found` };
+        }
+        return { status: 'ok' };
+    });
+    // Explicit "I've seen this" without opening — same effect as mark-viewed.
+    app.post('/api/prs/:id/dismiss', { schema: idParamSchema }, async (req, reply) => {
+        const { id } = req.params;
+        const ok = markPrViewed(id);
+        if (!ok) {
+            reply.status(404);
+            return { error: 'NotFound', message: `PR ${id} not found` };
+        }
+        return { status: 'ok' };
+    });
+}
+//# sourceMappingURL=prs.js.map

package/dist/api/routes/repos.js

@@ -0,0 +1,188 @@
+import { getGraphqlClient } from '../../github/client.js';
+import { REPO_ID_QUERY, REPO_SEARCH_QUERY, } from '../../github/queries.js';
+import { upsertRepo } from '../../sync/upsert.js';
+import { getSyncStatus, isSyncRunning, runSyncForRepo, } from '../../sync/sync-manager.js';
+import { deleteRepo, getRepo, getWatchedRepoNodeIds, listRepos, } from '../../db/queries.js';
+const createRepoSchema = {
+    body: {
+        type: 'object',
+        required: ['owner', 'name'],
+        additionalProperties: false,
+        properties: {
+            owner: { type: 'string', minLength: 1 },
+            name: { type: 'string', minLength: 1 },
+        },
+    },
+};
+const idParamSchema = {
+    params: {
+        type: 'object',
+        required: ['id'],
+        properties: { id: { type: 'integer' } },
+    },
+};
+const syncSchema = {
+    ...idParamSchema,
+    querystring: {
+        type: 'object',
+        additionalProperties: false,
+        properties: { full: { type: 'boolean', default: false } },
+    },
+};
+const searchSchema = {
+    querystring: {
+        type: 'object',
+        required: ['q'],
+        additionalProperties: false,
+        properties: {
+            q: { type: 'string', minLength: 1, maxLength: 256 },
+            cursor: { type: 'string', minLength: 1 },
+            limit: { type: 'integer', default: 10, minimum: 1, maximum: 25 },
+        },
+    },
+};
+export async function repoRoutes(app) {
+    app.get('/api/repos', async () => listRepos());
+    // Live GitHub repository search for the Add-repo picker. Best-match ordering
+    // (GitHub default), already-watched repos filtered out, owned/member repos
+    // floated to the top. Detail comes straight from GitHub — nothing persisted.
+    app.get('/api/repos/search', { schema: searchSchema }, async (req, reply) => {
+        const { q, cursor, limit } = req.query;
+        const term = q.trim();
+        if (!term) {
+            reply.status(400);
+            return { error: 'BadRequest', message: 'Search query must not be empty' };
+        }
+        const client = getGraphqlClient();
+        let resp;
+        try {
+            // NB: the GraphQL variable is `searchQuery`, not `query` — @octokit/graphql
+            // reserves `query` for the document body and rejects it as a variable name.
+            resp = await client(REPO_SEARCH_QUERY, {
+                searchQuery: term,
+                first: limit,
+                cursor: cursor ?? null,
+            });
+        }
+        catch (err) {
+            reply.status(502);
+            return {
+                error: 'GitHubError',
+                message: err instanceof Error ? err.message : 'GitHub search failed',
+            };
+        }
+        const watched = getWatchedRepoNodeIds();
+        const me = resp.viewer.login.toLowerCase();
+        const orgLogins = new Set(resp.viewer.organizations.nodes.map((o) => o.login.toLowerCase()));
+        const results = resp.search.nodes
+            // Guard the union: type:REPOSITORY yields repositories, but a non-repo node
+            // would serialise as {} (no id) — drop those, then drop already-watched.
+            .filter((n) => typeof n.id === 'string')
+            .filter((n) => !watched.has(n.id))
+            .map((n) => {
+            const ownerLogin = n.owner.login;
+            return {
+                githubNodeId: n.id,
+                owner: ownerLogin,
+                name: n.name,
+                fullName: n.nameWithOwner,
+                description: n.description,
+                ownerAvatarUrl: n.owner.avatarUrl,
+                stargazerCount: n.stargazerCount,
+                openPrCount: n.pullRequests.totalCount,
+                url: n.url,
+                isPrivate: n.isPrivate,
+                isOwnedOrMember: ownerLogin.toLowerCase() === me ||
+                    orgLogins.has(ownerLogin.toLowerCase()),
+            };
+        });
+        // Float owned/member repos to the top, preserving GitHub's best-match order
+        // within each group (Array.prototype.sort is stable on Node ≥ 12).
+        results.sort((a, b) => Number(b.isOwnedOrMember) - Number(a.isOwnedOrMember));
+        const body = {
+            results,
+            hasNextPage: resp.search.pageInfo.hasNextPage,
+            cursor: resp.search.pageInfo.endCursor,
+        };
+        return body;
+    });
+    app.post('/api/repos', { schema: createRepoSchema }, async (req, reply) => {
+        const { owner, name } = req.body;
+        const client = getGraphqlClient();
+        let resp;
+        try {
+            resp = await client(REPO_ID_QUERY, { owner, name });
+        }
+        catch (err) {
+            reply.status(502);
+            return {
+                error: 'GitHubError',
+                message: err instanceof Error ? err.message : 'GitHub request failed',
+            };
+        }
+        if (!resp.repository) {
+            reply.status(404);
+            return {
+                error: 'NotFound',
+                message: `Repository ${owner}/${name} not found or inaccessible. Check the name and your gh auth / SSO.`,
+            };
+        }
+        const canonOwner = resp.repository.owner.login;
+        const canonName = resp.repository.name;
+        const repoId = upsertRepo(canonOwner, canonName, resp.repository.id);
+        // Kick off the initial backfill in the background.
+        runSyncForRepo(repoId, app.log, { background: true });
+        reply.status(201);
+        return getRepo(repoId);
+    });
+    app.delete('/api/repos/:id', { schema: idParamSchema }, async (req, reply) => {
+        const { id } = req.params;
+        // A sync in flight would re-create the repo (and its rows) right after we
+        // delete them, since the sync's upserts are still running. Refuse until it
+        // settles — the cron tick / initial backfill is short.
+        if (isSyncRunning(id)) {
+            reply.status(409);
+            return {
+                error: 'Conflict',
+                message: 'A sync is running for this repo — try removing it again in a moment.',
+            };
+        }
+        const ok = deleteRepo(id);
+        if (!ok) {
+            reply.status(404);
+            return { error: 'NotFound', message: `Repo ${id} not found` };
+        }
+        reply.status(204);
+        return null;
+    });
+    app.post('/api/repos/:id/sync', { schema: syncSchema }, async (req, reply) => {
+        const { id } = req.params;
+        if (!getRepo(id)) {
+            reply.status(404);
+            return { error: 'NotFound', message: `Repo ${id} not found` };
+        }
+        // ?full=true forces a full backfill (catches CI/thread-resolve changes
+        // that don't bump PR.updatedAt and so lag the incremental path).
+        const { full } = req.query;
+        const started = runSyncForRepo(id, app.log, {
+            background: true,
+            forceFull: full === true,
+        });
+        if (!started) {
+            reply.status(409);
+            return { error: 'Conflict', message: 'A sync is already running for this repo' };
+        }
+        reply.status(202);
+        return { status: 'started' };
+    });
+    app.get('/api/repos/:id/sync-status', { schema: idParamSchema }, async (req, reply) => {
+        const { id } = req.params;
+        const status = getSyncStatus(id);
+        if (!getRepo(id)) {
+            reply.status(404);
+            return { error: 'NotFound', message: `Repo ${id} not found` };
+        }
+        return status;
+    });
+}
+//# sourceMappingURL=repos.js.map

package/dist/api/routes/threads.js

@@ -0,0 +1,20 @@
+import { getThreadDetail } from '../../db/queries.js';
+const idParamSchema = {
+    params: {
+        type: 'object',
+        required: ['id'],
+        properties: { id: { type: 'integer' } },
+    },
+};
+export async function threadRoutes(app) {
+    app.get('/api/threads/:id', { schema: idParamSchema }, async (req, reply) => {
+        const { id } = req.params;
+        const thread = getThreadDetail(id);
+        if (!thread) {
+            reply.status(404);
+            return { error: 'NotFound', message: `Thread ${id} not found` };
+        }
+        return thread;
+    });
+}
+//# sourceMappingURL=threads.js.map

package/dist/api/routes/timeline.js

@@ -0,0 +1,73 @@
+import { getTimeline } from '../../db/queries.js';
+const DAY_MS = 24 * 60 * 60 * 1000;
+// Local copies of the shared value constants. `@pierre-review/shared` is a
+// types-only workspace package that is NOT shipped in the published tarball, so
+// the backend must not import runtime values from it (only `import type`, which
+// `verbatimModuleSyntax` erases). Keep these in sync with packages/shared.
+const EVENT_TYPES = [
+    'pr_opened',
+    'pr_merged',
+    'pr_closed',
+    'pr_reopened',
+    'pr_ready_for_review',
+    'review_submitted',
+    'review_comment',
+    'pr_comment',
+    'commit_pushed',
+];
+const PR_STATUSES = ['draft', 'open', 'merged', 'closed'];
+function parseIntList(raw) {
+    if (!raw)
+        return null;
+    const ids = raw
+        .split(',')
+        .map((s) => Number.parseInt(s.trim(), 10))
+        .filter((n) => Number.isFinite(n));
+    return ids.length > 0 ? ids : null;
+}
+function parseTypes(raw) {
+    if (!raw)
+        return null;
+    const allowed = new Set(EVENT_TYPES);
+    const types = raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => allowed.has(s));
+    return types.length > 0 ? types : null;
+}
+// Absent (undefined) → null = no status filter (show all). Present, even empty
+// ("") → an explicit (possibly empty) set, so deselecting every status shows
+// nothing rather than falling back to "all".
+function parseStatuses(raw) {
+    if (raw === undefined)
+        return null;
+    const allowed = new Set(PR_STATUSES);
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => allowed.has(s));
+}
+function parseDate(raw, fallback) {
+    if (!raw)
+        return fallback;
+    const d = new Date(raw);
+    return Number.isNaN(d.getTime()) ? fallback : d;
+}
+export async function timelineRoutes(app) {
+    app.get('/api/timeline', async (req) => {
+        const q = req.query;
+        const now = new Date();
+        const filters = {
+            from: parseDate(q.from, new Date(now.getTime() - 14 * DAY_MS)),
+            to: parseDate(q.to, now),
+            repoIds: parseIntList(q.repoIds),
+            userIds: parseIntList(q.userIds),
+            types: parseTypes(q.types),
+            statuses: parseStatuses(q.statuses),
+            excludeBots: q.excludeBots !== 'false',
+            excludeStale: q.excludeStale === 'true',
+        };
+        return getTimeline(filters);
+    });
+}
+//# sourceMappingURL=timeline.js.map

package/dist/api/routes/users.js

@@ -0,0 +1,28 @@
+import { listUsers, setUserBot } from '../../db/queries.js';
+const patchUserSchema = {
+    params: {
+        type: 'object',
+        required: ['id'],
+        properties: { id: { type: 'integer' } },
+    },
+    body: {
+        type: 'object',
+        required: ['isBot'],
+        additionalProperties: false,
+        properties: { isBot: { type: 'boolean' } },
+    },
+};
+export async function userRoutes(app) {
+    app.get('/api/users', async () => listUsers());
+    app.patch('/api/users/:id', { schema: patchUserSchema }, async (req, reply) => {
+        const { id } = req.params;
+        const { isBot } = req.body;
+        const updated = setUserBot(id, isBot);
+        if (!updated) {
+            reply.status(404);
+            return { error: 'NotFound', message: `User ${id} not found` };
+        }
+        return updated;
+    });
+}
+//# sourceMappingURL=users.js.map

package/dist/app.js

@@ -0,0 +1,48 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import Fastify, {} from 'fastify';
+import cors from '@fastify/cors';
+import fastifyStatic from '@fastify/static';
+import { registerErrorHandler } from './api/plugins/error-handler.js';
+import { healthRoutes } from './api/routes/health.js';
+import { repoRoutes } from './api/routes/repos.js';
+import { userRoutes } from './api/routes/users.js';
+import { timelineRoutes } from './api/routes/timeline.js';
+import { prRoutes } from './api/routes/prs.js';
+import { threadRoutes } from './api/routes/threads.js';
+import { meRoutes } from './api/routes/me.js';
+import { openPrsRoutes } from './api/routes/open-prs.js';
+import { mergersRoutes } from './api/routes/mergers.js';
+export async function buildApp() {
+    const app = Fastify({
+        logger: {
+            level: process.env.LOG_LEVEL ?? 'info',
+            transport: process.env.NODE_ENV === 'production'
+                ? undefined
+                : { target: 'pino-pretty', options: { translateTime: 'HH:MM:ss' } },
+        },
+    });
+    await app.register(cors, { origin: true });
+    // Single-process production mode: serve the built SPA when the bundled assets
+    // exist next to the compiled server (release/dist → release/public). In dev
+    // there is no sibling `public/` dir, so this no-ops and Vite (:5173) serves the
+    // UI by proxying /api back to this server — dev stays unchanged.
+    const publicDir = resolve(import.meta.dirname, '../public');
+    const serveSpa = existsSync(resolve(publicDir, 'index.html'));
+    if (serveSpa) {
+        await app.register(fastifyStatic, { root: publicDir, wildcard: false });
+    }
+    // The not-found handler doubles as the SPA fallback when serving the SPA.
+    registerErrorHandler(app, serveSpa);
+    await app.register(healthRoutes);
+    await app.register(repoRoutes);
+    await app.register(userRoutes);
+    await app.register(timelineRoutes);
+    await app.register(prRoutes);
+    await app.register(threadRoutes);
+    await app.register(meRoutes);
+    await app.register(openPrsRoutes);
+    await app.register(mergersRoutes);
+    return app;
+}
+//# sourceMappingURL=app.js.map

package/dist/ascii.js

@@ -0,0 +1,12 @@
+// Cursive "Pierre" banner shown by the CLI on launch — figlet "Script" font
+// (a flowing handwriting style). 5 lines, max 30 columns, so it
+// renders cleanly in any terminal. String.raw keeps the backslashes literal.
+export const PIERRE_ASCII = String.raw `
+  , __
+ /|/  \o
+  |___/    _   ,_    ,_    _
+  |    |  |/  /  |  /  |  |/
+  |    |_/|__/   |_/   |_/|__/
+`;
+export const TAGLINE = "Local-only dashboard for your team's GitHub PR activity.";
+//# sourceMappingURL=ascii.js.map