@tequila99/githuman 0.4.0 → 0.4.1

package/README.md

@@ -114,6 +114,13 @@ node dist/cli/index.js serve --db-prefix myteam-   # .githuman/myteam-reviews.db
 node dist/cli/index.js list --db-prefix ""         # .githuman/reviews.db (оригинальный githuman)
 ```
 
+### HTTP API
+
+Сервер отдаёт OpenAPI-спецификацию своего API по адресу `/api/openapi.json`
+(OpenAPI 3.1, всегда). Swagger UI — на `/api/docs`, только с флагом
+`--api-docs` (`pnpm run dev:server` включает его сам). Агентские маршруты
+попадают в спецификацию, только когда сервер их отдаёт (loopback-хост).
+
 ## Разработка
 
 Два процесса нужны одновременно — backend (Fastify, автоперезапуск при
@@ -134,7 +141,7 @@ githuman — запустите `dev:server` из cwd того репозито
 ```bash
 cd /path/to/other/repo
 node --watch-path=/path/to/githuman/src \
-  /path/to/githuman/src/cli/index.ts serve --no-open
+  /path/to/githuman/src/cli/index.ts serve --no-open --api-docs
 ```
 
 Прочие команды:

package/dist/cli/config.js

@@ -53,7 +53,8 @@ export function parseServeArgs(argv) {
             host: { type: 'string' },
             open: { type: 'boolean', default: true },
             'no-open': { type: 'boolean', default: false },
-            'db-prefix': { type: 'string' }
+            'db-prefix': { type: 'string' },
+            'api-docs': { type: 'boolean', default: false }
         },
         strict: false
     });
@@ -61,5 +62,6 @@ export function parseServeArgs(argv) {
     const host = resolveHost(typeof values.host === 'string' ? values.host : undefined);
     const open = values['no-open'] === true ? false : values.open !== false;
     const dbPrefix = resolveDbPrefix(typeof values['db-prefix'] === 'string' ? values['db-prefix'] : undefined);
-    return { port, host, open, dbPrefix };
+    const apiDocs = values['api-docs'] === true;
+    return { port, host, open, dbPrefix, apiDocs };
 }

package/dist/cli/server-runtime.js

@@ -63,6 +63,7 @@ export async function startServer(options) {
         repositoryPath,
         db,
         watchFiles: true,
+        apiDocs: options.apiDocs === true,
         // Agents can run commands, so they are only offered on a loopback bind.
         ...(isLoopbackHost(options.host)
             ? {

package/dist/server/app.js

@@ -4,6 +4,8 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import Fastify from 'fastify';
 import fastifyStatic from '@fastify/static';
+import fastifySwagger from '@fastify/swagger';
+import fastifySwaggerUi from '@fastify/swagger-ui';
 // @fastify/sse's published types declare an ESM default export that doesn't match
 // its actual CJS runtime shape, so the default import resolves to the whole module
 // namespace under NodeNext — cast it back to the plugin function type.
@@ -17,6 +19,8 @@ import { commentRoutes } from "./routes/comments.js";
 import { exportRoutes } from "./routes/export.js";
 import { eventRoutes } from "./routes/events.js";
 import { agentRoutes } from "./routes/agent.js";
+import { openApiRoutes } from "./routes/openapi.js";
+import { openApiOptions } from "./config/openapi.js";
 import { createSessionRegistry } from "./services/agent/session-registry.js";
 import { createTestDatabase } from "./db/index.js";
 import { createEventBus } from "./event-bus.js";
@@ -29,6 +33,12 @@ export function buildApp(options = {}) {
     const db = options.db ?? createTestDatabase();
     const eventBus = options.eventBus ?? createEventBus();
     app.register(fastifySse);
+    // The spec collects routes as they are added, so it comes before them.
+    app.register(fastifySwagger, openApiOptions());
+    if (options.apiDocs) {
+        app.register(fastifySwaggerUi, { routePrefix: '/api/docs' });
+    }
+    app.register(openApiRoutes);
     app.register(healthRoutes);
     app.register(appInfoRoutes);
     app.register(diffRoutes, { repositoryPath });

package/dist/server/config/openapi.js

@@ -0,0 +1,29 @@
+import { getAppVersion } from "../app-version.js";
+/**
+ * Options of `@fastify/swagger`. OpenAPI 3.1 because TypeBox writes null as
+ * `{ type: 'null' }`, and OpenAPI 3.0 does not allow it.
+ */
+export function openApiOptions() {
+    return {
+        openapi: {
+            openapi: '3.1.0',
+            info: {
+                title: 'githuman',
+                version: getAppVersion(),
+                description: 'HTTP API of the local githuman server. The API has no authentication: the tool is local.'
+            },
+            tags: [
+                { name: 'diff', description: 'Changes of the working tree and refs.' },
+                { name: 'git', description: 'Repository facts, files and index.' },
+                { name: 'reviews', description: 'Reviews and their export.' },
+                { name: 'comments', description: 'Comments of reviews.' },
+                { name: 'events', description: 'Server-sent change events.' },
+                { name: 'app', description: 'Server version and health.' },
+                {
+                    name: 'agent',
+                    description: 'Agent chats. The server has these routes only on a loopback host, and each request needs a local Host and Origin.'
+                }
+            ]
+        }
+    };
+}

package/dist/server/repositories/review.repo.js

@@ -1,12 +1,28 @@
 import { UniqueNameError } from "../errors/reviews.js";
-function rowToReview(row) {
+// Every column but snapshot_data: the list doesn't need the diff, and it is
+// requested on each review/comment event (#56). Update this list when
+// ReviewSummaryRow changes: a missing column reads as undefined, silently.
+const SUMMARY_COLUMNS = [
+    'id',
+    'repository_path',
+    'base_ref',
+    'source_type',
+    'source_ref',
+    'status',
+    'name',
+    'branch',
+    'created_at',
+    'updated_at'
+]
+    .map(column => `reviews.${column}`)
+    .join(', ');
+function rowToSummary(row) {
     return {
         id: row.id,
         repositoryPath: row.repository_path,
         baseRef: row.base_ref,
         sourceType: row.source_type,
         sourceRef: row.source_ref,
-        snapshotData: row.snapshot_data,
         status: row.status,
         name: row.name,
         branch: row.branch,
@@ -14,6 +30,9 @@ function rowToReview(row) {
         updatedAt: row.updated_at
     };
 }
+function rowToReview(row) {
+    return { ...rowToSummary(row), snapshotData: row.snapshot_data };
+}
 export function createReview(db, review) {
     try {
         db.prepare(`INSERT INTO reviews (id, repository_path, base_ref, source_type, source_ref, snapshot_data, status, name, branch, created_at, updated_at)
@@ -32,6 +51,13 @@ export function findReviewById(db, id) {
     const row = db.prepare('SELECT * FROM reviews WHERE id = ?').get(id);
     return row ? rowToReview(row) : null;
 }
+/** Reads a review without its snapshot, for callers that only need its fields (#57). */
+export function findReviewSummaryById(db, id) {
+    const row = db
+        .prepare(`SELECT ${SUMMARY_COLUMNS} FROM reviews WHERE id = ?`)
+        .get(id);
+    return row ? rowToSummary(row) : null;
+}
 export function listReviews(db, filters = {}) {
     const { branch, search, createdFrom, createdTo, filePaths } = filters;
     const conditions = [];
@@ -56,12 +82,12 @@ export function listReviews(db, filters = {}) {
     }
     const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
     const rows = db
-        .prepare(`SELECT DISTINCT reviews.* FROM reviews
+        .prepare(`SELECT DISTINCT ${SUMMARY_COLUMNS} FROM reviews
        ${joins.join(' ')}
        ${whereClause}
        ORDER BY reviews.created_at DESC`)
         .all(...params);
-    const reviews = rows.map(rowToReview);
+    const reviews = rows.map(rowToSummary);
     // Done in JS, not SQL `LOWER()`/`NOCASE` (ASCII-only in SQLite without the
     // ICU extension) — `String.prototype.toLowerCase()` handles Cyrillic and
     // other non-ASCII scripts correctly (see ADR 0017).
@@ -82,5 +108,5 @@ export function updateReviewStatus(db, id, status) {
     if (result.changes === 0) {
         return null;
     }
-    return findReviewById(db, id);
+    return findReviewSummaryById(db, id);
 }

package/dist/server/routes/agent.js

@@ -1,5 +1,7 @@
 import { NotFoundError } from "../errors/http.js";
-import { SessionParams, PermissionParams, CreateSessionBody, AutoApproveBody, FileSearchQuery, PromptBody, PermissionBody, ConfigBody } from "../../shared/agents/schemas.js";
+import { Type } from '@sinclair/typebox';
+import { SessionParams, PermissionParams, CreateSessionBody, AutoApproveBody, FileSearchQuery, PromptBody, PermissionBody, ConfigBody, AgentPresetInfoSchema, AgentSessionInfoSchema, AgentFileSearchResponseSchema, AgentEventsHeaders, AgentStreamSchema } from "../../shared/agents/schemas.js";
+import { ApiErrorSchema, ERROR_RESPONSES, NoContentSchema } from "../../shared/http/schemas.js";
 import { buildPromptBlocks } from "../services/agent/context-builder.js";
 import { MAX_ATTACHMENT_BYTES, DEFAULT_FILE_SEARCH_LIMIT } from "../../shared/agents/constants.js";
 import { createFileIndex } from "../services/agent/file-index.js";
@@ -8,6 +10,16 @@ import { requireLocalOrigin } from "../hooks/agents/local-origin.js";
 import { findReviewById } from "../repositories/review.repo.js";
 /** Room for a handful of max-size base64 attachments; the schema caps each one. */
 const PROMPT_BODY_LIMIT = 5 * Math.ceil((MAX_ATTACHMENT_BYTES * 4) / 3) + 1024 * 1024;
+// OpenAPI group of these routes.
+const TAGS = ['agent'];
+// The spec shows the local-origin guard on each operation, not only on the tag.
+const AGENT_ERROR_RESPONSES = {
+    ...ERROR_RESPONSES,
+    403: {
+        ...ApiErrorSchema,
+        description: 'Host or Origin of the request is not local.'
+    }
+};
 export async function agentRoutes(app, opts) {
     const { registry, db, repositoryPath, eventBus } = opts;
     const typedApp = app.withTypeProvider();
@@ -17,9 +29,44 @@ export async function agentRoutes(app, opts) {
         registry.closeAll();
         fileIndex.close();
     });
-    typedApp.get('/api/agent/presets', async () => registry.listPresets());
-    typedApp.get('/api/agent/sessions', async () => registry.list());
-    typedApp.post('/api/agent/sessions', { schema: { body: CreateSessionBody } }, async (request, reply) => {
+    typedApp.get('/api/agent/presets', {
+        schema: {
+            tags: TAGS,
+            summary: 'List agent presets',
+            response: {
+                200: Type.Array(AgentPresetInfoSchema, {
+                    description: 'Presets from the config.'
+                }),
+                ...AGENT_ERROR_RESPONSES
+            }
+        }
+    }, async () => registry.listPresets());
+    typedApp.get('/api/agent/sessions', {
+        schema: {
+            tags: TAGS,
+            summary: 'List chat sessions',
+            response: {
+                200: Type.Array(AgentSessionInfoSchema, {
+                    description: 'Open and closed sessions.'
+                }),
+                ...AGENT_ERROR_RESPONSES
+            }
+        }
+    }, async () => registry.list());
+    typedApp.post('/api/agent/sessions', {
+        schema: {
+            tags: TAGS,
+            summary: 'Start a chat session',
+            body: CreateSessionBody,
+            response: {
+                201: {
+                    ...AgentSessionInfoSchema,
+                    description: 'The session. The agent starts in the background.'
+                },
+                ...AGENT_ERROR_RESPONSES
+            }
+        }
+    }, async (request, reply) => {
         const { presetId, reviewId, name } = request.body;
         if (reviewId !== undefined && !findReviewById(db, reviewId)) {
             throw new NotFoundError(`Review ${reviewId} not found`);
@@ -29,21 +76,46 @@ export async function agentRoutes(app, opts) {
         reply.code(201);
         return session.info();
     });
-    typedApp.get('/api/agent/sessions/:id', { schema: { params: SessionParams } }, async (request) => {
+    typedApp.get('/api/agent/sessions/:id', {
+        schema: {
+            tags: TAGS,
+            summary: 'Get a chat session',
+            params: SessionParams,
+            response: { 200: AgentSessionInfoSchema, ...AGENT_ERROR_RESPONSES }
+        }
+    }, async (request) => {
         const session = registry.get(request.params.id);
         if (!session) {
             throw new NotFoundError('Session not found');
         }
         return session.info();
     });
-    typedApp.delete('/api/agent/sessions/:id', { schema: { params: SessionParams } }, async (request, reply) => {
+    typedApp.delete('/api/agent/sessions/:id', {
+        schema: {
+            tags: TAGS,
+            summary: 'Close a chat session and stop its agent',
+            params: SessionParams,
+            response: { 204: NoContentSchema, ...AGENT_ERROR_RESPONSES }
+        }
+    }, async (request, reply) => {
         if (!registry.close(request.params.id)) {
             throw new NotFoundError('Session not found');
         }
-        return reply.code(204).send();
+        return reply.code(204).send(null);
     });
     typedApp.post('/api/agent/sessions/:id/prompt', {
-        schema: { params: SessionParams, body: PromptBody },
+        schema: {
+            tags: TAGS,
+            summary: 'Send a message to the agent',
+            description: 'The answer comes over GET /api/agent/events. 202 means the session took the message.',
+            params: SessionParams,
+            body: PromptBody,
+            response: {
+                // No content type: the answer has no body, as before the schema.
+                202: { description: 'The session took the message. No body.' },
+                ...AGENT_ERROR_RESPONSES
+            }
+        },
         bodyLimit: PROMPT_BODY_LIMIT
     }, async (request, reply) => {
         const session = registry.get(request.params.id);
@@ -61,44 +133,99 @@ export async function agentRoutes(app, opts) {
         session.prompt(blocks, request.body);
         return reply.code(202).send();
     });
-    typedApp.post('/api/agent/sessions/:id/cancel', { schema: { params: SessionParams } }, async (request, reply) => {
+    typedApp.post('/api/agent/sessions/:id/cancel', {
+        schema: {
+            tags: TAGS,
+            summary: 'Cancel the current turn',
+            params: SessionParams,
+            response: { 204: NoContentSchema, ...AGENT_ERROR_RESPONSES }
+        }
+    }, async (request, reply) => {
         const session = registry.get(request.params.id);
         if (!session) {
             throw new NotFoundError('Session not found');
         }
         await session.cancel();
-        return reply.code(204).send();
+        return reply.code(204).send(null);
     });
-    typedApp.post('/api/agent/sessions/:id/permissions/:requestId', { schema: { params: PermissionParams, body: PermissionBody } }, async (request, reply) => {
+    typedApp.post('/api/agent/sessions/:id/permissions/:requestId', {
+        schema: {
+            tags: TAGS,
+            summary: 'Answer a permission request',
+            params: PermissionParams,
+            body: PermissionBody,
+            response: { 204: NoContentSchema, ...AGENT_ERROR_RESPONSES }
+        }
+    }, async (request, reply) => {
         const session = registry.get(request.params.id);
         if (!session?.answerPermission(request.params.requestId, request.body.optionId)) {
             throw new NotFoundError('No such pending permission request');
         }
-        return reply.code(204).send();
+        return reply.code(204).send(null);
     });
-    typedApp.post('/api/agent/sessions/:id/config', { schema: { params: SessionParams, body: ConfigBody } }, async (request, reply) => {
+    typedApp.post('/api/agent/sessions/:id/config', {
+        schema: {
+            tags: TAGS,
+            summary: 'Change an agent setting',
+            params: SessionParams,
+            body: ConfigBody,
+            response: { 204: NoContentSchema, ...AGENT_ERROR_RESPONSES }
+        }
+    }, async (request, reply) => {
         const session = registry.get(request.params.id);
         if (!session) {
             throw new NotFoundError('Session not found');
         }
         await session.setConfig(request.body.configId, request.body.value);
-        return reply.code(204).send();
+        return reply.code(204).send(null);
     });
-    typedApp.post('/api/agent/sessions/:id/auto-approve', { schema: { params: SessionParams, body: AutoApproveBody } }, async (request, reply) => {
+    typedApp.post('/api/agent/sessions/:id/auto-approve', {
+        schema: {
+            tags: TAGS,
+            summary: 'Switch auto-approve of a session',
+            params: SessionParams,
+            body: AutoApproveBody,
+            response: { 204: NoContentSchema, ...AGENT_ERROR_RESPONSES }
+        }
+    }, async (request, reply) => {
         const session = registry.get(request.params.id);
         if (!session) {
             throw new NotFoundError('Session not found');
         }
         session.setAutoApprove(request.body.enabled);
-        return reply.code(204).send();
+        return reply.code(204).send(null);
     });
-    typedApp.get('/api/agent/files', { schema: { querystring: FileSearchQuery } }, async (request) => ({
+    typedApp.get('/api/agent/files', {
+        schema: {
+            tags: TAGS,
+            summary: 'Find repository files for the context picker',
+            querystring: FileSearchQuery,
+            response: {
+                200: AgentFileSearchResponseSchema,
+                ...AGENT_ERROR_RESPONSES
+            }
+        }
+    }, async (request) => ({
         files: await fileIndex.search(request.query.q ?? '', request.query.limit ?? DEFAULT_FILE_SEARCH_LIMIT)
     }));
     // One stream for every chat (ADR 0024): browsers allow ~6 connections per
     // origin over HTTP/1.1, so a stream per session would starve the page's own
     // requests. Event ids are shared across sessions, so `Last-Event-ID` works.
-    typedApp.get('/api/agent/events', { sse: true }, async (request, reply) => {
+    typedApp.get('/api/agent/events', {
+        sse: true,
+        schema: {
+            tags: TAGS,
+            summary: 'Stream of all chat sessions',
+            headers: AgentEventsHeaders,
+            response: {
+                200: {
+                    description: 'An SSE stream that stays open.',
+                    content: { 'text/event-stream': { schema: AgentStreamSchema } }
+                },
+                ...AGENT_ERROR_RESPONSES
+            }
+        }
+    }, async (request, reply) => {
         const lastEventId = Number(request.headers['last-event-id']);
         reply.sse.keepAlive();
         // Flushes the headers: with no session yet nothing else would be sent, and

package/dist/server/routes/app-info.js

@@ -1,6 +1,13 @@
 import { getAppVersion } from "../app-version.js";
+import { AppInfoSchema } from "../../shared/app/schemas.js";
 export async function appInfoRoutes(app) {
-    app.get('/api/app-info', async () => {
+    app.withTypeProvider().get('/api/app-info', {
+        schema: {
+            tags: ['app'],
+            summary: 'Server version',
+            response: { 200: AppInfoSchema }
+        }
+    }, async () => {
         return { version: getAppVersion() };
     });
 }

package/dist/server/routes/comments.js

@@ -2,31 +2,26 @@ import { NotFoundError } from "../errors/http.js";
 import { Type } from '@sinclair/typebox';
 import { getReview } from "../services/review.service.js";
 import { createComment, getComments, editComment, removeComment, resolveComment, unresolveComment } from "../services/comment.service.js";
-// Null goes first in each union: Fastify's Ajv coerces types, and with
-// Integer (or String) first it turns a JSON null into 0 (or "") before the
-// Null branch is ever tried — a file-level comment would be stored as line 0.
-const CreateCommentBody = Type.Object({
-    filePath: Type.String({ minLength: 1 }),
-    lineNumber: Type.Optional(Type.Union([Type.Null(), Type.Integer()])),
-    lineNumberEnd: Type.Optional(Type.Union([Type.Null(), Type.Integer()])),
-    lineType: Type.Optional(Type.Union([
-        Type.Null(),
-        Type.Literal('added'),
-        Type.Literal('removed'),
-        Type.Literal('context')
-    ])),
-    content: Type.String(),
-    suggestion: Type.Optional(Type.Union([Type.Null(), Type.String()]))
-});
-const UpdateCommentBody = Type.Object({
-    content: Type.String()
-});
-const ReviewIdParams = Type.Object({ id: Type.String() });
-const CommentIdParams = Type.Object({ id: Type.String() });
+import { CommentIdParams, CommentSchema, CreateCommentBody, UpdateCommentBody } from "../../shared/comments/schemas.js";
+import { ReviewIdParams } from "../../shared/reviews/schemas.js";
+import { ERROR_RESPONSES, NoContentSchema } from "../../shared/http/schemas.js";
+// OpenAPI group of these routes.
+const TAGS = ['comments'];
 export async function commentRoutes(app, opts) {
     const { db, eventBus } = opts;
     const typedApp = app.withTypeProvider();
-    typedApp.post('/api/reviews/:id/comments', { schema: { params: ReviewIdParams, body: CreateCommentBody } }, async (request, reply) => {
+    typedApp.post('/api/reviews/:id/comments', {
+        schema: {
+            tags: TAGS,
+            summary: 'Add a comment to a review',
+            params: ReviewIdParams,
+            body: CreateCommentBody,
+            response: {
+                201: { ...CommentSchema, description: 'The new comment.' },
+                ...ERROR_RESPONSES
+            }
+        }
+    }, async (request, reply) => {
         if (!getReview(db, request.params.id)) {
             throw new NotFoundError(`Review ${request.params.id} not found`);
         }
@@ -34,34 +29,85 @@ export async function commentRoutes(app, opts) {
         reply.code(201);
         return comment;
     });
-    typedApp.get('/api/reviews/:id/comments', { schema: { params: ReviewIdParams } }, async (request) => {
+    typedApp.get('/api/reviews/:id/comments', {
+        schema: {
+            tags: TAGS,
+            summary: 'List comments of a review',
+            params: ReviewIdParams,
+            response: {
+                200: Type.Array(CommentSchema, {
+                    description: 'Comments of the review.'
+                }),
+                ...ERROR_RESPONSES
+            }
+        }
+    }, async (request) => {
         if (!getReview(db, request.params.id)) {
             throw new NotFoundError(`Review ${request.params.id} not found`);
         }
         return getComments(db, request.params.id);
     });
-    typedApp.patch('/api/comments/:id', { schema: { params: CommentIdParams, body: UpdateCommentBody } }, async (request) => {
+    typedApp.patch('/api/comments/:id', {
+        schema: {
+            tags: TAGS,
+            summary: 'Change the comment text',
+            params: CommentIdParams,
+            body: UpdateCommentBody,
+            response: {
+                200: { ...CommentSchema, description: 'The changed comment.' },
+                ...ERROR_RESPONSES
+            }
+        }
+    }, async (request) => {
         const updated = editComment(db, request.params.id, request.body.content, eventBus);
         if (!updated) {
             throw new NotFoundError(`Comment ${request.params.id} not found`);
         }
         return updated;
     });
-    typedApp.patch('/api/comments/:id/resolve', { schema: { params: CommentIdParams } }, async (request) => {
+    typedApp.patch('/api/comments/:id/resolve', {
+        schema: {
+            tags: TAGS,
+            summary: 'Mark a comment as resolved',
+            params: CommentIdParams,
+            response: {
+                200: { ...CommentSchema, description: 'The changed comment.' },
+                ...ERROR_RESPONSES
+            }
+        }
+    }, async (request) => {
         const updated = resolveComment(db, request.params.id, eventBus);
         if (!updated) {
             throw new NotFoundError(`Comment ${request.params.id} not found`);
         }
         return updated;
     });
-    typedApp.patch('/api/comments/:id/unresolve', { schema: { params: CommentIdParams } }, async (request) => {
+    typedApp.patch('/api/comments/:id/unresolve', {
+        schema: {
+            tags: TAGS,
+            summary: 'Mark a comment as not resolved',
+            params: CommentIdParams,
+            response: {
+                200: { ...CommentSchema, description: 'The changed comment.' },
+                ...ERROR_RESPONSES
+            }
+        }
+    }, async (request) => {
         const updated = unresolveComment(db, request.params.id, eventBus);
         if (!updated) {
             throw new NotFoundError(`Comment ${request.params.id} not found`);
         }
         return updated;
     });
-    typedApp.delete('/api/comments/:id', { schema: { params: CommentIdParams } }, async (request, reply) => {
+    typedApp.delete('/api/comments/:id', {
+        schema: {
+            tags: TAGS,
+            summary: 'Delete a comment',
+            description: 'A missing comment also gives 204.',
+            params: CommentIdParams,
+            response: { 204: NoContentSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request, reply) => {
         removeComment(db, request.params.id, eventBus);
         reply.code(204);
     });