@tequila99/githuman 0.4.0 → 0.4.2

package/dist/server/routes/diff.js

@@ -1,40 +1,41 @@
 import { BadRequestError } from "../errors/http.js";
 import { Type } from '@sinclair/typebox';
-import { getStagedDiff, getUnstagedDiff, getBranchDiff, getCommitsDiff, getDiffSummaries, getFileDiff } from "../services/diff.service.js";
+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";
-const BranchQuery = Type.Object({
-    base: Type.String({ minLength: 1 })
-});
-const CommitsQuery = Type.Object({
-    from: Type.String({ minLength: 1 }),
-    to: Type.String({ minLength: 1 })
-});
-const SourceParams = Type.Object({
-    source: Type.Union([Type.Literal('staged'), Type.Literal('unstaged')])
-});
-const FileQuery = Type.Object({
-    path: Type.String({ minLength: 1 }),
-    oldPath: Type.Optional(Type.String({ minLength: 1 })),
-    status: Type.Union([
-        Type.Literal('added'),
-        Type.Literal('modified'),
-        Type.Literal('deleted'),
-        Type.Literal('renamed')
-    ])
-});
+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: { params: SourceParams } }, async (request) => getDiffSummaries(repositoryPath, request.params.source));
-    typedApp.get('/api/diff/:source/file', { schema: { params: SourceParams, querystring: FileQuery } }, async (request) => {
+    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 {
@@ -51,7 +52,20 @@ export async function diffRoutes(app, opts) {
             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);
         }
@@ -60,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,6 +1,7 @@
 import { diffLines } from 'diff';
 import { stat } from 'node:fs/promises';
 import { assertSafeRef, listChangedSummaries, resolveWithinRepo, getFileAtRef, getFilesAtRefBatch, listChangedPaths, listUntrackedPaths } from "./git.service.js";
+import { createPreambleReader } from "../../shared/diff/preamble.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. */
@@ -57,6 +58,27 @@ function windowHunks(lines, contextLines = CONTEXT_LINES) {
     }
     return hunks;
 }
+/**
+ * Gives each hunk the unchanged lines above it, for the highlighter. A hunk with no new
+ * line (a deleted file) takes them from the old side. A side is split into lines only when
+ * a hunk needs it: a hunk at the top of a file has no preamble.
+ */
+function withPreambles(hunks, meta, oldContent, newContent) {
+    let oldReader;
+    let newReader;
+    return hunks.map(hunk => {
+        let preamble = [];
+        if (hunk.newStart > 1) {
+            newReader ??= createPreambleReader(meta.newPath, splitLines(newContent));
+            preamble = newReader(hunk.newStart);
+        }
+        else if (hunk.newStart === 0 && hunk.oldStart > 1) {
+            oldReader ??= createPreambleReader(meta.oldPath, splitLines(oldContent));
+            preamble = oldReader(hunk.oldStart);
+        }
+        return preamble.length > 0 ? { ...hunk, preamble } : hunk;
+    });
+}
 export function computeFileDiff(oldContent, newContent, meta) {
     const base = {
         oldPath: meta.oldPath,
@@ -105,7 +127,7 @@ export function computeFileDiff(oldContent, newContent, meta) {
             }
         }
     }
-    const hunks = windowHunks(lines);
+    const hunks = withPreambles(windowHunks(lines), meta, oldContent, newContent);
     return { ...base, additions, deletions, hunks };
 }
 /**