@muhammad_zihad/prless 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammad AR Zihad
+
+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,97 @@
+# PRless
+
+A local, GitHub-style code review tool with an agent-agnostic AI handoff. Review a local
+git diff in the browser, leave inline comments anchored to specific lines, then export the
+comments to a file that any CLI coding agent (Claude Code, Codex, …) can read and act on.
+
+## Install
+
+Requires **Node.js 18+**. One command on every platform — macOS, Linux, and Windows:
+
+```bash
+npm install -g @muhammad_zihad/prless
+```
+
+That puts a `prless` command on your PATH (on Windows, npm generates the `.cmd`/PowerShell
+shims automatically). Prefer not to install globally? Run it on demand with `npx`:
+
+```bash
+npx @muhammad_zihad/prless open .
+```
+
+### macOS / Linux via Homebrew
+
+```bash
+brew install muhammadZihad/tap/prless
+```
+
+`brew` installs Node for you. See [packaging/README.md](packaging/README.md) for publishing
+the npm package and setting up the tap.
+
+### From source
+
+```bash
+git clone https://github.com/muhammadZihad/prless.git && cd prless
+npm install        # builds automatically via the prepare script
+npm link           # makes `prless` available globally
+```
+
+## Use
+
+```bash
+prless open .                  # review the git repo in the current directory
+prless open ~/projects/my-app  # review a repo by path
+prless open ./my-app --port 4200
+prless help                    # show usage
+```
+
+Works on macOS, Linux, and Windows. This starts a local server and opens the UI in your
+browser. You can:
+
+- **Pick a diff source** — working tree vs HEAD, staged vs HEAD, or compare two branches.
+- **Comment inline** — click a line's gutter to leave a comment (⌘/Ctrl+Enter to submit).
+- **Resolve / delete** comments; toggle split / unified view.
+- **Switch the app theme** — light or dark (defaults to your OS setting, remembered per browser).
+- **Choose a syntax theme** — Auto, GitHub Light/Dark, One Dark, Dracula, Nord, Monokai,
+  Solarized Light. The diff renders as a self-contained editor surface, so any code theme
+  looks right regardless of the app theme.
+- **Export for AI** — writes open comments to `.prless/review.md`.
+
+Typography uses Geist (UI) and JetBrains Mono (code), bundled locally so it works offline.
+
+Comments persist in `.prless/comments.json` in the repo (gitignore the `.prless/` folder).
+
+## Hand off to an agent
+
+After exporting, run your agent in the repo and point it at the file:
+
+```bash
+claude   # then: "address the comments in .prless/review.md"
+# or
+codex "address the comments in .prless/review.md"
+```
+
+`review.md` lists each open comment grouped by file, with the target line, side, and the
+requested change — no API keys or MCP required.
+
+## Develop
+
+```bash
+npm run dev        # Vite UI on :5174 (proxying /api) + API on :4100 with reload
+npm test           # vitest (git, comments, export)
+npm run typecheck
+```
+
+## Layout
+
+```
+src/
+  shared/types.ts        # types shared by server + web
+  server/                # Fastify API + CLI (git diff, comment store, review.md export)
+  web/                   # React + Vite UI (react-diff-view)
+```
+
+## Scope
+
+Local, single-user. No GitHub PR ingestion, no auth/DB, no MCP — handoff is the exported
+file. These are deliberate non-goals and can be layered on later.

package/dist/server/cli.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import open from 'open';
+import { buildServer } from './index.js';
+import { assertGitRepo, createGit, GitError } from './git.js';
+const USAGE = `prless — local code review with agent-agnostic AI handoff
+
+Usage:
+  prless open <repository>   Review a git repository at the given path
+  prless open .              Review the git repository in the current directory
+  prless help                Show this help
+
+Options (for "open"):
+  --port <n>     Port to serve on (default 4100, or $PRLESS_PORT)
+  --no-open      Do not launch a browser automatically
+  --dev          Internal: run the API only (UI served by the Vite dev server)
+
+Examples:
+  prless open .
+  prless open ~/projects/my-app
+  prless open ./my-app --port 4200
+`;
+function parseOpenArgs(rest) {
+    let repoArg;
+    let dev = false;
+    let noOpen = false;
+    let port = Number(process.env.PRLESS_PORT ?? 4100);
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (a === '--dev')
+            dev = true;
+        else if (a === '--no-open')
+            noOpen = true;
+        else if (a === '--port')
+            port = Number(rest[++i]);
+        else if (!a.startsWith('-') && repoArg === undefined)
+            repoArg = a;
+    }
+    if (repoArg === undefined) {
+        console.error('prless: "open" requires a repository path (use "." for the current directory).\n');
+        console.error(USAGE);
+        process.exit(1);
+    }
+    return {
+        // path.resolve normalises against cwd on every platform (mac/linux/windows).
+        repoRoot: path.resolve(repoArg),
+        dev,
+        noOpen,
+        port,
+    };
+}
+async function runOpen(opts) {
+    const git = createGit(opts.repoRoot);
+    try {
+        await assertGitRepo(git);
+    }
+    catch (err) {
+        if (err instanceof GitError) {
+            console.error(`prless: ${opts.repoRoot} is not a git repository.`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    const app = await buildServer({ repoRoot: opts.repoRoot, dev: opts.dev });
+    await app.listen({ port: opts.port, host: '127.0.0.1' });
+    const url = opts.dev ? `http://localhost:5174` : `http://localhost:${opts.port}`;
+    console.log(`prless: reviewing ${opts.repoRoot}`);
+    console.log(`prless: serving ${opts.dev ? 'API' : 'UI'} on http://localhost:${opts.port}`);
+    if (opts.dev)
+        console.log(`prless: open the Vite dev server at ${url}`);
+    if (!opts.dev && !opts.noOpen) {
+        await open(url).catch(() => {
+            // Launching a browser is best-effort and varies by platform.
+            console.log(`prless: open ${url} in your browser`);
+        });
+    }
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const command = argv[0];
+    const rest = argv.slice(1);
+    switch (command) {
+        case 'open':
+            await runOpen(parseOpenArgs(rest));
+            break;
+        case 'help':
+        case '--help':
+        case '-h':
+        case undefined:
+            console.log(USAGE);
+            break;
+        default:
+            console.error(`prless: unknown command "${command}"\n`);
+            console.error(USAGE);
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/server/comments.js

@@ -0,0 +1,73 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+export class CommentStore {
+    dir;
+    file;
+    constructor(repoRoot) {
+        this.dir = path.join(repoRoot, '.prless');
+        this.file = path.join(this.dir, 'comments.json');
+    }
+    get filePath() {
+        return this.file;
+    }
+    async list() {
+        try {
+            const raw = await readFile(this.file, 'utf8');
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                return [];
+            }
+            throw err;
+        }
+    }
+    async add(input) {
+        const comments = await this.list();
+        const now = new Date().toISOString();
+        const comment = {
+            id: randomUUID(),
+            file: input.file,
+            line: input.line,
+            side: input.side,
+            snippet: input.snippet ?? '',
+            body: input.body,
+            status: 'open',
+            createdAt: now,
+            updatedAt: now,
+        };
+        comments.push(comment);
+        await this.save(comments);
+        return comment;
+    }
+    async patch(id, patch) {
+        const comments = await this.list();
+        const idx = comments.findIndex((c) => c.id === id);
+        if (idx === -1)
+            return null;
+        const existing = comments[idx];
+        const updated = {
+            ...existing,
+            body: patch.body ?? existing.body,
+            status: patch.status ?? existing.status,
+            updatedAt: new Date().toISOString(),
+        };
+        comments[idx] = updated;
+        await this.save(comments);
+        return updated;
+    }
+    async remove(id) {
+        const comments = await this.list();
+        const next = comments.filter((c) => c.id !== id);
+        if (next.length === comments.length)
+            return false;
+        await this.save(next);
+        return true;
+    }
+    async save(comments) {
+        await mkdir(this.dir, { recursive: true });
+        await writeFile(this.file, JSON.stringify(comments, null, 2) + '\n', 'utf8');
+    }
+}

package/dist/server/comments.test.js

@@ -0,0 +1,42 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { CommentStore } from './comments.js';
+describe('CommentStore', () => {
+    let dir;
+    let store;
+    beforeEach(async () => {
+        dir = await mkdtemp(path.join(tmpdir(), 'prless-'));
+        store = new CommentStore(dir);
+    });
+    afterEach(async () => {
+        await rm(dir, { recursive: true, force: true });
+    });
+    it('returns an empty list before anything is written', async () => {
+        expect(await store.list()).toEqual([]);
+    });
+    it('adds, persists and round-trips a comment', async () => {
+        const created = await store.add({ file: 'a.ts', line: 3, side: 'new', body: 'hi', snippet: 'x' });
+        expect(created.id).toBeTruthy();
+        expect(created.status).toBe('open');
+        const reread = await new CommentStore(dir).list();
+        expect(reread).toHaveLength(1);
+        expect(reread[0].body).toBe('hi');
+    });
+    it('patches status and body', async () => {
+        const created = await store.add({ file: 'a.ts', line: 1, side: 'new', body: 'orig' });
+        const patched = await store.patch(created.id, { status: 'resolved', body: 'edited' });
+        expect(patched?.status).toBe('resolved');
+        expect(patched?.body).toBe('edited');
+    });
+    it('returns null when patching a missing id', async () => {
+        expect(await store.patch('nope', { status: 'resolved' })).toBeNull();
+    });
+    it('removes a comment', async () => {
+        const created = await store.add({ file: 'a.ts', line: 1, side: 'new', body: 'x' });
+        expect(await store.remove(created.id)).toBe(true);
+        expect(await store.list()).toEqual([]);
+        expect(await store.remove(created.id)).toBe(false);
+    });
+});

package/dist/server/export.js

@@ -0,0 +1,47 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+const HEADER = `# Code Review — action required
+
+You are addressing review comments on this repository. For each comment below,
+make the requested change in the referenced file, then briefly note what you changed.
+Line numbers refer to the indicated side of the diff ("new" = current file contents,
+"old" = the version before the change).
+`;
+/**
+ * Render open comments into a deterministic, agent-friendly markdown document,
+ * grouped by file and ordered by line. Pure function for easy testing.
+ */
+export function renderReviewMarkdown(comments) {
+    const open = comments.filter((c) => c.status === 'open');
+    if (open.length === 0) {
+        return `${HEADER}\n_No open comments._\n`;
+    }
+    const byFile = new Map();
+    for (const c of open) {
+        const bucket = byFile.get(c.file) ?? [];
+        bucket.push(c);
+        byFile.set(c.file, bucket);
+    }
+    const sections = [];
+    for (const file of [...byFile.keys()].sort()) {
+        const lines = byFile
+            .get(file)
+            .slice()
+            .sort((a, b) => a.line - b.line || a.createdAt.localeCompare(b.createdAt));
+        const items = lines.map((c) => {
+            const snippet = c.snippet.trim();
+            const context = snippet ? ` \`${snippet}\`` : '';
+            const body = c.body.trim().replace(/\n/g, '\n    ');
+            return `- **Line ${c.line} (${c.side}):**${context}\n  → ${body}`;
+        });
+        sections.push(`## ${file}\n\n${items.join('\n\n')}`);
+    }
+    return `${HEADER}\n${sections.join('\n\n')}\n`;
+}
+export async function exportReview(repoRoot, comments) {
+    const dir = path.join(repoRoot, '.prless');
+    const file = path.join(dir, 'review.md');
+    await mkdir(dir, { recursive: true });
+    await writeFile(file, renderReviewMarkdown(comments), 'utf8');
+    return { path: file, count: comments.filter((c) => c.status === 'open').length };
+}

package/dist/server/export.test.js

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { renderReviewMarkdown } from './export.js';
+function comment(overrides) {
+    return {
+        id: 'id',
+        file: 'src/a.ts',
+        line: 1,
+        side: 'new',
+        snippet: '',
+        body: 'do something',
+        status: 'open',
+        createdAt: '2026-01-01T00:00:00.000Z',
+        updatedAt: '2026-01-01T00:00:00.000Z',
+        ...overrides,
+    };
+}
+describe('renderReviewMarkdown', () => {
+    it('renders an empty placeholder when there are no open comments', () => {
+        const md = renderReviewMarkdown([comment({ status: 'resolved' })]);
+        expect(md).toContain('_No open comments._');
+    });
+    it('groups open comments by file, sorted by line, with line context', () => {
+        const md = renderReviewMarkdown([
+            comment({ id: '1', file: 'src/b.ts', line: 5, side: 'new', snippet: 'return x', body: 'guard null' }),
+            comment({ id: '2', file: 'src/a.ts', line: 10, side: 'old', snippet: 'let u', body: 'rename u' }),
+            comment({ id: '3', file: 'src/a.ts', line: 2, side: 'new', snippet: 'const z=1', body: 'inline this' }),
+        ]);
+        // Files alphabetical: a.ts before b.ts
+        expect(md.indexOf('## src/a.ts')).toBeLessThan(md.indexOf('## src/b.ts'));
+        // Within a.ts, line 2 before line 10
+        expect(md.indexOf('Line 2 (new)')).toBeLessThan(md.indexOf('Line 10 (old)'));
+        expect(md).toContain('`return x`');
+        expect(md).toContain('→ guard null');
+    });
+    it('excludes resolved comments', () => {
+        const md = renderReviewMarkdown([
+            comment({ id: '1', body: 'keep me', status: 'open' }),
+            comment({ id: '2', body: 'drop me', status: 'resolved' }),
+        ]);
+        expect(md).toContain('keep me');
+        expect(md).not.toContain('drop me');
+    });
+});

package/dist/server/git.js

@@ -0,0 +1,46 @@
+import { simpleGit } from 'simple-git';
+export class GitError extends Error {
+}
+export function createGit(repoRoot) {
+    return simpleGit({ baseDir: repoRoot });
+}
+export async function assertGitRepo(git) {
+    const isRepo = await git.checkIsRepo();
+    if (!isRepo) {
+        throw new GitError('Not a git repository');
+    }
+}
+export async function getRefs(git) {
+    const branchSummary = await git.branchLocal();
+    return {
+        current: branchSummary.current,
+        branches: branchSummary.all,
+    };
+}
+/**
+ * Produce a unified diff for the requested mode.
+ * - working: all uncommitted changes vs HEAD (staged + unstaged)
+ * - staged: staged changes only
+ * - compare: `git diff <base> <head>` (two-dot)
+ */
+export async function getDiff(git, mode, base, head) {
+    let args;
+    switch (mode) {
+        case 'staged':
+            args = ['--staged'];
+            break;
+        case 'compare':
+            if (!base || !head) {
+                throw new GitError('compare mode requires both base and head');
+            }
+            args = [base, head];
+            break;
+        case 'working':
+        default:
+            args = ['HEAD'];
+            break;
+    }
+    // Stable, machine-friendly diff output.
+    const raw = await git.diff(['--no-color', ...args]);
+    return { mode, base, head, raw };
+}

package/dist/server/git.test.js

@@ -0,0 +1,36 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { assertGitRepo, createGit, getDiff, getRefs } from './git.js';
+describe('git layer', () => {
+    let dir;
+    beforeEach(async () => {
+        dir = await mkdtemp(path.join(tmpdir(), 'prless-git-'));
+        const git = createGit(dir);
+        await git.init();
+        await git.addConfig('user.email', 'test@example.com');
+        await git.addConfig('user.name', 'Test');
+        await writeFile(path.join(dir, 'a.ts'), 'const a = 1;\n');
+        await git.add('.');
+        await git.commit('init');
+    });
+    afterEach(async () => {
+        await rm(dir, { recursive: true, force: true });
+    });
+    it('detects a git repo', async () => {
+        await expect(assertGitRepo(createGit(dir))).resolves.toBeUndefined();
+    });
+    it('lists refs including the current branch', async () => {
+        const refs = await getRefs(createGit(dir));
+        expect(refs.current).toBeTruthy();
+        expect(refs.branches).toContain(refs.current);
+    });
+    it('produces a working-tree diff for uncommitted changes', async () => {
+        await writeFile(path.join(dir, 'a.ts'), 'const a = 2;\n');
+        const res = await getDiff(createGit(dir), 'working');
+        expect(res.raw).toContain('a.ts');
+        expect(res.raw).toContain('-const a = 1;');
+        expect(res.raw).toContain('+const a = 2;');
+    });
+});

package/dist/server/index.js

@@ -0,0 +1,31 @@
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { existsSync } from 'node:fs';
+import Fastify from 'fastify';
+import fastifyStatic from '@fastify/static';
+import { CommentStore } from './comments.js';
+import { createGit } from './git.js';
+import { registerApiRoutes } from './routes.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export async function buildServer(opts) {
+    const app = Fastify({ logger: false });
+    const git = createGit(opts.repoRoot);
+    const store = new CommentStore(opts.repoRoot);
+    await registerApiRoutes(app, { repoRoot: opts.repoRoot, git, store });
+    // In dev, Vite serves the UI and proxies /api here. In a built install we
+    // serve the compiled web assets ourselves so the CLI is a single process.
+    if (!opts.dev) {
+        const webRoot = path.join(__dirname, '..', 'web');
+        if (existsSync(webRoot)) {
+            await app.register(fastifyStatic, { root: webRoot });
+            // SPA fallback for any non-API route.
+            app.setNotFoundHandler((request, reply) => {
+                if (request.url.startsWith('/api')) {
+                    return reply.code(404).send({ error: 'not found' });
+                }
+                return reply.sendFile('index.html');
+            });
+        }
+    }
+    return app;
+}

package/dist/server/routes.js

@@ -0,0 +1,59 @@
+import { exportReview } from './export.js';
+import { getDiff, getRefs, GitError } from './git.js';
+export async function registerApiRoutes(app, ctx) {
+    app.get('/api/refs', async () => {
+        return getRefs(ctx.git);
+    });
+    app.get('/api/diff', async (request, reply) => {
+        const q = request.query;
+        const mode = (q.mode ?? 'working');
+        try {
+            return await getDiff(ctx.git, mode, q.base, q.head);
+        }
+        catch (err) {
+            if (err instanceof GitError) {
+                return reply.code(400).send({ error: err.message });
+            }
+            throw err;
+        }
+    });
+    app.get('/api/comments', async () => {
+        return ctx.store.list();
+    });
+    app.post('/api/comments', async (request, reply) => {
+        const body = request.body;
+        if (!body || !body.file || typeof body.line !== 'number' || !body.side || !body.body) {
+            return reply.code(400).send({ error: 'file, line, side and body are required' });
+        }
+        const created = await ctx.store.add({
+            file: body.file,
+            line: body.line,
+            side: body.side,
+            body: body.body,
+            snippet: body.snippet,
+        });
+        return reply.code(201).send(created);
+    });
+    app.patch('/api/comments/:id', async (request, reply) => {
+        const { id } = request.params;
+        const patch = request.body;
+        const updated = await ctx.store.patch(id, patch);
+        if (!updated) {
+            return reply.code(404).send({ error: 'comment not found' });
+        }
+        return updated;
+    });
+    app.delete('/api/comments/:id', async (request, reply) => {
+        const { id } = request.params;
+        const ok = await ctx.store.remove(id);
+        if (!ok) {
+            return reply.code(404).send({ error: 'comment not found' });
+        }
+        return reply.code(204).send();
+    });
+    app.post('/api/export', async () => {
+        const comments = await ctx.store.list();
+        const result = await exportReview(ctx.repoRoot, comments);
+        return result;
+    });
+}

package/dist/shared/types.js

@@ -0,0 +1 @@
+export {};