@tequila99/githuman 0.3.0 → 0.4.1

package/dist/server/routes/diff.js

@@ -1,23 +1,71 @@
 import { BadRequestError } from "../errors/http.js";
 import { Type } from '@sinclair/typebox';
-import { getStagedDiff, getUnstagedDiff, getBranchDiff, getCommitsDiff } from "../services/diff.service.js";
-const BranchQuery = Type.Object({
-    base: Type.String({ minLength: 1 })
-});
-const CommitsQuery = Type.Object({
-    from: Type.String({ minLength: 1 }),
-    to: Type.String({ minLength: 1 })
-});
+import { getBranchDiff, getCommitsDiff, getDiffSummaries, getFileDiff } from "../services/diff.service.js";
+import { resolveWithinRepo } from "../services/git.service.js";
+import { errorMessage } from "../../shared/utils/error-message.js";
+import { BranchQuery, CommitsQuery, DiffFileSchema, DiffFileSummarySchema, FileQuery, SourceParams } from "../../shared/diff/schemas.js";
+import { ERROR_RESPONSES } from "../../shared/http/schemas.js";
+// OpenAPI group of these routes.
+const TAGS = ['diff'];
 export async function diffRoutes(app, opts) {
     const { repositoryPath } = opts;
     const typedApp = app.withTypeProvider();
-    typedApp.get('/api/diff/staged', async () => {
-        return getStagedDiff(repositoryPath);
-    });
-    typedApp.get('/api/diff/unstaged', async () => {
-        return getUnstagedDiff(repositoryPath);
+    // Files without hunks, then one file with hunks: the list stays small (ADR 0033).
+    typedApp.get('/api/diff/:source/files', {
+        schema: {
+            tags: TAGS,
+            summary: 'List changed files without hunks',
+            params: SourceParams,
+            response: {
+                200: Type.Array(DiffFileSummarySchema, {
+                    description: 'Changed files of the side.'
+                }),
+                ...ERROR_RESPONSES
+            }
+        }
+    }, async (request) => getDiffSummaries(repositoryPath, request.params.source));
+    typedApp.get('/api/diff/:source/file', {
+        schema: {
+            tags: TAGS,
+            summary: 'Get one changed file with hunks',
+            params: SourceParams,
+            querystring: FileQuery,
+            response: {
+                200: { ...DiffFileSchema, description: 'The file with its hunks.' },
+                ...ERROR_RESPONSES
+            }
+        }
+    }, async (request) => {
+        const { path, oldPath, status } = request.query;
+        // Only a path outside the repository is a bad request. Other errors stay server errors.
+        try {
+            resolveWithinRepo(repositoryPath, path);
+            if (oldPath !== undefined)
+                resolveWithinRepo(repositoryPath, oldPath);
+        }
+        catch (err) {
+            throw new BadRequestError(errorMessage(err), { cause: err });
+        }
+        return getFileDiff(repositoryPath, request.params.source, {
+            oldPath: oldPath ?? path,
+            newPath: path,
+            status
+        });
     });
-    typedApp.get('/api/diff/branch', { schema: { querystring: BranchQuery } }, async (request) => {
+    typedApp.get('/api/diff/branch', {
+        schema: {
+            tags: TAGS,
+            summary: 'Diff of HEAD against a ref',
+            description: 'No UI calls it yet. It is kept for branch reviews.',
+            querystring: BranchQuery,
+            response: {
+                200: Type.Array(DiffFileSchema, {
+                    description: 'Changed files with hunks.'
+                }),
+                ...ERROR_RESPONSES
+            }
+        }
+    }, async (request) => {
         try {
             return await getBranchDiff(repositoryPath, request.query.base);
         }
@@ -26,7 +74,20 @@ export async function diffRoutes(app, opts) {
             throw new BadRequestError(message, { cause: err });
         }
     });
-    typedApp.get('/api/diff/commits', { schema: { querystring: CommitsQuery } }, async (request) => {
+    typedApp.get('/api/diff/commits', {
+        schema: {
+            tags: TAGS,
+            summary: 'Diff between two refs',
+            description: 'No UI calls it yet. It is kept for commit reviews.',
+            querystring: CommitsQuery,
+            response: {
+                200: Type.Array(DiffFileSchema, {
+                    description: 'Changed files with hunks.'
+                }),
+                ...ERROR_RESPONSES
+            }
+        }
+    }, async (request) => {
         try {
             return await getCommitsDiff(repositoryPath, request.query.from, request.query.to);
         }

package/dist/server/routes/events.js

@@ -1,8 +1,21 @@
 import { safeSend } from "../utils/sse.js";
+import { EventStreamSchema } from "../../shared/events/schemas.js";
 export async function eventRoutes(app, opts) {
     const { eventBus, instanceId } = opts;
     const hello = { instanceId };
-    app.get('/api/events', { sse: true }, async (request, reply) => {
+    app.get('/api/events', {
+        sse: true,
+        schema: {
+            tags: ['events'],
+            summary: 'Stream of review, comment and file changes',
+            response: {
+                200: {
+                    description: 'An SSE stream that stays open.',
+                    content: { 'text/event-stream': { schema: EventStreamSchema } }
+                }
+            }
+        }
+    }, async (request, reply) => {
         reply.sse.keepAlive();
         await reply.sse.send({ event: 'connected', data: hello });
         // The client can leave during the await; a later `onClose` would never run.

package/dist/server/routes/export.js

@@ -1,13 +1,30 @@
 import { Type } from '@sinclair/typebox';
 import { exportAsJson, exportAsMarkdown } from "../services/export.service.js";
-const ExportParams = Type.Object({ id: Type.String() });
-const ExportQuery = Type.Object({
-    format: Type.Union([Type.Literal('json'), Type.Literal('markdown')])
-});
+import { ExportQuery, ReviewExportSchema, ReviewIdParams } from "../../shared/reviews/schemas.js";
+import { ERROR_RESPONSES } from "../../shared/http/schemas.js";
 export async function exportRoutes(app, opts) {
     const { db, repositoryPath } = opts;
     const typedApp = app.withTypeProvider();
-    typedApp.get('/api/reviews/:id/export', { schema: { params: ExportParams, querystring: ExportQuery } }, async (request, reply) => {
+    typedApp.get('/api/reviews/:id/export', {
+        schema: {
+            tags: ['reviews'],
+            summary: 'Export a review with its comments',
+            params: ReviewIdParams,
+            querystring: ExportQuery,
+            response: {
+                200: {
+                    description: 'The review as JSON or as a markdown report.',
+                    content: {
+                        'application/json': { schema: ReviewExportSchema },
+                        'text/markdown': {
+                            schema: Type.String({ description: 'Markdown report.' })
+                        }
+                    }
+                },
+                ...ERROR_RESPONSES
+            }
+        }
+    }, async (request, reply) => {
         if (request.query.format === 'json') {
             return exportAsJson(db, request.params.id);
         }

package/dist/server/routes/git.js

@@ -1,27 +1,29 @@
 import { BadRequestError } from "../errors/http.js";
-import { Type } from '@sinclair/typebox';
 import { getRepositoryInfo, stagePaths, unstagePaths, discardPaths, getFilesAtRef, getFileAtRef } from "../services/git.service.js";
-const TreeParams = Type.Object({
-    ref: Type.String({ minLength: 1 })
-});
-const FileContentQuery = Type.Object({
-    ref: Type.String({ minLength: 1 })
-});
-/** Body for `/stage` and `/unstage`: an omitted/empty `paths` means "all". */
-const OptionalPathsBody = Type.Object({
-    paths: Type.Optional(Type.Array(Type.String()))
-});
-/** Body for `/discard`: `paths` is required — no "discard everything". */
-const DiscardBody = Type.Object({
-    paths: Type.Array(Type.String(), { minItems: 1 })
-});
+import { DiscardBody, FileContentQuery, FileContentResponseSchema, FileParams, FileTreeResponseSchema, OkSchema, OptionalPathsBody, RepositoryInfoSchema, TreeParams } from "../../shared/git/schemas.js";
+import { ERROR_RESPONSES } from "../../shared/http/schemas.js";
+// OpenAPI group of these routes.
+const TAGS = ['git'];
 export async function gitRoutes(app, opts) {
     const { repositoryPath } = opts;
     const typedApp = app.withTypeProvider();
-    app.get('/api/git/info', async () => {
+    typedApp.get('/api/git/info', {
+        schema: {
+            tags: TAGS,
+            summary: 'Repository facts',
+            response: { 200: RepositoryInfoSchema, ...ERROR_RESPONSES }
+        }
+    }, async () => {
         return getRepositoryInfo(repositoryPath);
     });
-    typedApp.post('/api/git/stage', { schema: { body: OptionalPathsBody } }, async (request) => {
+    typedApp.post('/api/git/stage', {
+        schema: {
+            tags: TAGS,
+            summary: 'Stage paths',
+            body: OptionalPathsBody,
+            response: { 200: OkSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request) => {
         try {
             await stagePaths(repositoryPath, request.body.paths ?? []);
             return { ok: true };
@@ -31,7 +33,14 @@ export async function gitRoutes(app, opts) {
             throw new BadRequestError(message, { cause: err });
         }
     });
-    typedApp.post('/api/git/unstage', { schema: { body: OptionalPathsBody } }, async (request) => {
+    typedApp.post('/api/git/unstage', {
+        schema: {
+            tags: TAGS,
+            summary: 'Unstage paths',
+            body: OptionalPathsBody,
+            response: { 200: OkSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request) => {
         try {
             await unstagePaths(repositoryPath, request.body.paths ?? []);
             return { ok: true };
@@ -41,7 +50,14 @@ export async function gitRoutes(app, opts) {
             throw new BadRequestError(message, { cause: err });
         }
     });
-    typedApp.post('/api/git/discard', { schema: { body: DiscardBody } }, async (request) => {
+    typedApp.post('/api/git/discard', {
+        schema: {
+            tags: TAGS,
+            summary: 'Discard working-tree changes of paths',
+            body: DiscardBody,
+            response: { 200: OkSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request) => {
         try {
             await discardPaths(repositoryPath, request.body.paths);
             return { ok: true };
@@ -51,7 +67,14 @@ export async function gitRoutes(app, opts) {
             throw new BadRequestError(message, { cause: err });
         }
     });
-    typedApp.get('/api/git/tree/:ref', { schema: { params: TreeParams } }, async (request) => {
+    typedApp.get('/api/git/tree/:ref', {
+        schema: {
+            tags: TAGS,
+            summary: 'List files at a ref',
+            params: TreeParams,
+            response: { 200: FileTreeResponseSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request) => {
         const { ref } = request.params;
         try {
             const files = await getFilesAtRef(repositoryPath, ref);
@@ -62,7 +85,15 @@ export async function gitRoutes(app, opts) {
             throw new BadRequestError(message, { cause: err });
         }
     });
-    typedApp.get('/api/git/file/*', { schema: { querystring: FileContentQuery } }, async (request) => {
+    typedApp.get('/api/git/file/*', {
+        schema: {
+            tags: TAGS,
+            summary: 'Read one file at a ref',
+            params: FileParams,
+            querystring: FileContentQuery,
+            response: { 200: FileContentResponseSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request) => {
         const filePath = request.params['*'];
         const { ref } = request.query;
         if (!filePath) {

package/dist/server/routes/health.js

@@ -1,5 +1,12 @@
+import { HealthSchema } from "../../shared/app/schemas.js";
 export async function healthRoutes(app) {
-    app.get('/health', async () => {
+    app.withTypeProvider().get('/health', {
+        schema: {
+            tags: ['app'],
+            summary: 'Liveness check',
+            response: { 200: HealthSchema }
+        }
+    }, async () => {
         return { status: 'ok' };
     });
 }

package/dist/server/routes/openapi.js

@@ -0,0 +1,4 @@
+export async function openApiRoutes(app) {
+    // No authentication (ADR 0008): the spec tells no more than the API itself.
+    app.get('/api/openapi.json', { schema: { hide: true } }, async () => app.swagger());
+}

package/dist/server/routes/reviews.js

@@ -2,43 +2,41 @@ import { NotFoundError, BadRequestError } from "../errors/http.js";
 import { Type } from '@sinclair/typebox';
 import { createReview, getReview, getReviews, setReviewStatus, removeReview } from "../services/review.service.js";
 import { getRepositoryInfo } from "../services/git.service.js";
-const CreateReviewBody = Type.Object({
-    sourceType: Type.Optional(Type.Union([
-        Type.Literal('local'),
-        Type.Literal('staged'),
-        Type.Literal('unstaged'),
-        Type.Literal('branch'),
-        Type.Literal('commits')
-    ])),
-    sourceRef: Type.Optional(Type.String()),
-    baseRef: Type.Optional(Type.String()),
-    name: Type.Optional(Type.String())
-});
-const ReviewsQuery = Type.Object({
-    branch: Type.Optional(Type.String()),
-    search: Type.Optional(Type.String()),
-    createdFrom: Type.Optional(Type.String()),
-    createdTo: Type.Optional(Type.String()),
-    /** Comma-separated file paths — reviews matching any of them are returned. */
-    files: Type.Optional(Type.String())
-});
-const UpdateReviewBody = Type.Object({
-    status: Type.Optional(Type.Union([
-        Type.Literal('in_progress'),
-        Type.Literal('approved'),
-        Type.Literal('changes_requested')
-    ]))
-});
-const ReviewIdParams = Type.Object({ id: Type.String() });
+import { CreateReviewBody, ReviewIdParams, ReviewSchema, ReviewSummarySchema, ReviewsQuery, UpdateReviewBody } from "../../shared/reviews/schemas.js";
+import { ERROR_RESPONSES, NoContentSchema } from "../../shared/http/schemas.js";
+// OpenAPI group of these routes.
+const TAGS = ['reviews'];
 export async function reviewRoutes(app, opts) {
     const { repositoryPath, db, eventBus } = opts;
     const typedApp = app.withTypeProvider();
-    typedApp.post('/api/reviews', { schema: { body: CreateReviewBody } }, async (request, reply) => {
+    typedApp.post('/api/reviews', {
+        schema: {
+            tags: TAGS,
+            summary: 'Create a review from the current diff',
+            body: CreateReviewBody,
+            response: {
+                201: { ...ReviewSchema, description: 'The new review.' },
+                ...ERROR_RESPONSES
+            }
+        }
+    }, async (request, reply) => {
         const review = await createReview(db, repositoryPath, request.body, eventBus);
         reply.code(201);
         return review;
     });
-    typedApp.get('/api/reviews', { schema: { querystring: ReviewsQuery } }, async (request) => {
+    typedApp.get('/api/reviews', {
+        schema: {
+            tags: TAGS,
+            summary: 'List reviews, newest first',
+            querystring: ReviewsQuery,
+            response: {
+                200: Type.Array(ReviewSummarySchema, {
+                    description: 'Reviews without snapshots.'
+                }),
+                ...ERROR_RESPONSES
+            }
+        }
+    }, async (request) => {
         const { branch, search, createdFrom, createdTo, files } = request.query;
         const resolvedBranch = branch ?? (await getRepositoryInfo(repositoryPath)).branch;
         return getReviews(db, {
@@ -51,14 +49,35 @@ export async function reviewRoutes(app, opts) {
                 : undefined
         });
     });
-    typedApp.get('/api/reviews/:id', { schema: { params: ReviewIdParams } }, async (request) => {
+    typedApp.get('/api/reviews/:id', {
+        schema: {
+            tags: TAGS,
+            summary: 'Get a review with its snapshot',
+            params: ReviewIdParams,
+            response: { 200: ReviewSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request) => {
         const review = getReview(db, request.params.id);
         if (!review) {
             throw new NotFoundError(`Review ${request.params.id} not found`);
         }
         return review;
     });
-    typedApp.patch('/api/reviews/:id', { schema: { params: ReviewIdParams, body: UpdateReviewBody } }, async (request) => {
+    typedApp.patch('/api/reviews/:id', {
+        schema: {
+            tags: TAGS,
+            summary: 'Change the review status',
+            params: ReviewIdParams,
+            body: UpdateReviewBody,
+            response: {
+                200: {
+                    ...ReviewSummarySchema,
+                    description: 'The changed review without its snapshot.'
+                },
+                ...ERROR_RESPONSES
+            }
+        }
+    }, async (request) => {
         if (!request.body.status) {
             throw new BadRequestError('"status" is required');
         }
@@ -68,7 +87,14 @@ export async function reviewRoutes(app, opts) {
         }
         return updated;
     });
-    typedApp.delete('/api/reviews/:id', { schema: { params: ReviewIdParams } }, async (request, reply) => {
+    typedApp.delete('/api/reviews/:id', {
+        schema: {
+            tags: TAGS,
+            summary: 'Delete a review and its comments',
+            params: ReviewIdParams,
+            response: { 204: NoContentSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request, reply) => {
         if (!getReview(db, request.params.id)) {
             throw new NotFoundError(`Review ${request.params.id} not found`);
         }

package/dist/server/services/agent/agent-session.js

@@ -195,6 +195,7 @@ export class AgentSession {
      * Changes a session setting (model, mode, …) and returns the agent's new
      * full set of options. Validated against what the agent itself offered, so
      * an unknown id or value is rejected here rather than sent on.
+     * `value` is `unknown`: the route schema gives it no type (see ConfigBody).
      */
     async setConfig(configId, value) {
         const connection = this.#connection;
@@ -208,9 +209,10 @@ export class AgentSession {
         if (!option) {
             throw new AgentConfigError(`Unknown setting "${configId}"`);
         }
-        if (option.type === 'boolean'
-            ? typeof value !== 'boolean'
-            : !option.options?.some(c => c.value === value)) {
+        if ((typeof value !== 'boolean' && typeof value !== 'string') ||
+            (option.type === 'boolean'
+                ? typeof value !== 'boolean'
+                : !option.options?.some(c => c.value === value))) {
             throw new AgentConfigError(`Invalid value for "${option.name}"`);
         }
         try {

package/dist/server/services/diff.service.js

@@ -1,7 +1,15 @@
 import { diffLines } from 'diff';
-import { assertSafeRef, getFileAtRef, getFilesAtRefBatch, listChangedPaths, listUntrackedPaths } from "./git.service.js";
+import { stat } from 'node:fs/promises';
+import { assertSafeRef, listChangedSummaries, resolveWithinRepo, getFileAtRef, getFilesAtRefBatch, listChangedPaths, listUntrackedPaths } from "./git.service.js";
 /** Unchanged lines kept around each change in a hunk, as in `git diff`. */
 const CONTEXT_LINES = 3;
+/** Stamp of a worktree file that cannot be read. */
+const GONE_STAMP = 'gone';
+/**
+ * Line count and binary flag of untracked files, by repository and path. A refetch runs on
+ * every save, so an untracked file is read again only when its stamp changes.
+ */
+const untrackedCounts = new Map();
 function splitLines(text) {
     if (text === '')
         return [];
@@ -161,3 +169,113 @@ export async function getCommitsDiff(repoPath, from, to) {
     assertSafeRef(to);
     return buildDiffFiles(repoPath, [from, to], from, to);
 }
+/**
+ * `mtime:ctime:inode:size` of a file in the worktree. It costs no read. The inode catches
+ * a file replaced by rename. Known limit: an edit of the same size within one timestamp
+ * tick of the file system keeps the stamp.
+ */
+async function worktreeStamp(repoPath, path) {
+    try {
+        const info = await stat(resolveWithinRepo(repoPath, path));
+        return `${info.mtimeMs}:${info.ctimeMs}:${info.ino}:${info.size}`;
+    }
+    catch {
+        return GONE_STAMP;
+    }
+}
+function countLines(content) {
+    return splitLines(content).length;
+}
+/**
+ * Builds a signature from both sides of the diff. Equal signatures must mean equal hunks,
+ * so the old side counts too: a change of only HEAD or only the index changes the hunks.
+ */
+function signatureOf(change, oldSide, newSide) {
+    return [
+        change.status,
+        change.oldPath,
+        change.newPath,
+        change.additions,
+        change.deletions,
+        oldSide,
+        newSide
+    ].join('|');
+}
+/** Counts the lines of an untracked file. The file is read only when its stamp changed. */
+async function untrackedSummary(repoPath, path) {
+    const stamp = await worktreeStamp(repoPath, path);
+    const key = `${repoPath}\0${path}`;
+    let counts = untrackedCounts.get(key);
+    if (!counts || counts.stamp !== stamp) {
+        const file = await getFileAtRef(repoPath, 'WORKTREE', path);
+        counts = {
+            stamp,
+            additions: file.isBinary ? 0 : countLines(file.content),
+            isBinary: file.isBinary
+        };
+        if (stamp === GONE_STAMP) {
+            untrackedCounts.delete(key);
+        }
+        else {
+            untrackedCounts.set(key, counts);
+        }
+    }
+    const change = {
+        oldPath: path,
+        newPath: path,
+        status: 'added',
+        additions: counts.additions,
+        deletions: 0,
+        isBinary: counts.isBinary
+    };
+    return { ...change, signature: signatureOf(change, '', stamp) };
+}
+/** Drops the cached counts of files that are no longer untracked in this repository. */
+function pruneUntrackedCounts(repoPath, untrackedPaths) {
+    const prefix = `${repoPath}\0`;
+    const alive = new Set(untrackedPaths.map(path => prefix + path));
+    for (const key of untrackedCounts.keys()) {
+        if (key.startsWith(prefix) && !alive.has(key))
+            untrackedCounts.delete(key);
+    }
+}
+/**
+ * Lists the files of one diff side with counts and a signature, but no hunks (ADR 0033).
+ * Counts come from git, the hunks of `getFileDiff` from `diffLines`: they may differ by a few lines.
+ */
+export async function getDiffSummaries(repoPath, source) {
+    if (source === 'staged') {
+        const changes = await listChangedSummaries(repoPath, ['--cached']);
+        return changes.map(({ oldOid, newOid, ...change }) => ({
+            ...change,
+            signature: signatureOf(change, oldOid, newOid)
+        }));
+    }
+    const [changes, untrackedPaths] = await Promise.all([
+        listChangedSummaries(repoPath, []),
+        listUntrackedPaths(repoPath)
+    ]);
+    // The new side is the worktree: git prints zeros for its blob id, so a stamp stands in.
+    const tracked = await Promise.all(changes.map(async ({ oldOid, newOid: _newOid, ...change }) => ({
+        ...change,
+        signature: signatureOf(change, oldOid, await worktreeStamp(repoPath, change.newPath))
+    })));
+    const untracked = await Promise.all(untrackedPaths.map(path => untrackedSummary(repoPath, path)));
+    pruneUntrackedCounts(repoPath, untrackedPaths);
+    return [...tracked, ...untracked];
+}
+/**
+ * Builds the diff of one file. The caller passes the summary's paths and status, so no
+ * whole-repository listing runs per file. Untracked files have no index entry: their old side is empty.
+ */
+export async function getFileDiff(repoPath, source, meta) {
+    const [oldRef, newRef] = source === 'staged' ? ['HEAD', 'INDEX'] : ['INDEX', 'WORKTREE'];
+    const [oldFile, newFile] = await Promise.all([
+        getFileAtRef(repoPath, oldRef, meta.oldPath),
+        getFileAtRef(repoPath, newRef, meta.newPath)
+    ]);
+    return computeFileDiff(oldFile.content, newFile.content, {
+        ...meta,
+        isBinary: oldFile.isBinary || newFile.isBinary
+    });
+}