@north-light/crouter 0.3.170 → 0.3.172

package/dist/daemon/api/handlers/review-comments.js

@@ -0,0 +1,500 @@
+// Canonical daemon-owned review comment routes. The handlers validate wire
+// input and derive authorship; review/comment state remains in the review
+// services and comment delivery remains a post-commit best effort.
+import { randomUUID } from 'node:crypto';
+import { ApiError } from '../../../api/index.js';
+import { getNode } from '../../../core/canvas/canvas.js';
+import { isSafeNodeId } from '../../../core/canvas/paths.js';
+import { createComment, deleteComment, editComment, getComment, listCommentEvents, listComments, listReviewEvents, reopenComment, resolveComment, } from '../../../core/review/comments.js';
+import { withCanvasWrite } from '../../../core/canvas/db.js';
+import { captureAnchorText, requireCurrentDocumentLocked } from '../../../core/review/document.js';
+import { applyRangeBatch } from '../../../core/review/remap.js';
+import { getReview, getReviewByCompanion } from '../../../core/review/store.js';
+import { ReviewOperationError } from '../../../core/review/types.js';
+import { notifyComment } from '../../review/comment-notify.js';
+import { toReviewCommentDTO, toReviewCommentEventDTO } from '../map.js';
+const COMMENT_ID = /^[a-f0-9]{32}$/;
+const SHA256 = /^[a-f0-9]{64}$/;
+const COMMENT_STATUSES = new Set(['open', 'resolved', 'deleted', 'all']);
+const DELIVER_MODES = new Set(['wake', 'quiet']);
+function invalidRequest(violations) {
+    throw new ApiError(400, 'invalid_request', 'review comment request is invalid', { violations });
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function objectBody(body, allowed, violations) {
+    if (!isRecord(body)) {
+        violations.push({ field: 'body', problem: 'must be an object', received: body });
+        return {};
+    }
+    for (const key of Object.keys(body)) {
+        if (!allowed.includes(key))
+            violations.push({ field: key, problem: 'is not allowed', received: body[key] });
+    }
+    return body;
+}
+function requiredString(body, field, violations) {
+    const value = body[field];
+    if (typeof value !== 'string' || value.trim() === '') {
+        violations.push({ field, problem: 'must be a non-empty string', ...(value === undefined ? {} : { received: value }) });
+        return undefined;
+    }
+    return value;
+}
+function optionalSha256(body, field, violations) {
+    const value = body[field];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || !SHA256.test(value)) {
+        violations.push({ field, problem: 'must be a lowercase SHA-256 hex digest', received: value });
+        return undefined;
+    }
+    return value;
+}
+function requiredSha256(body, field, violations) {
+    const value = body[field];
+    if (typeof value !== 'string' || !SHA256.test(value)) {
+        violations.push({ field, problem: 'must be a lowercase SHA-256 hex digest', ...(value === undefined ? {} : { received: value }) });
+        return undefined;
+    }
+    return value;
+}
+function optionalDeliver(body, violations) {
+    const value = body['deliver'];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || !DELIVER_MODES.has(value)) {
+        violations.push({ field: 'deliver', problem: 'must be wake or quiet', received: value });
+        return undefined;
+    }
+    return value;
+}
+function optionalRevision(body, violations) {
+    const value = body['if_revision'];
+    if (value === undefined)
+        return undefined;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        violations.push({ field: 'if_revision', problem: 'must be a non-negative safe integer', received: value });
+        return undefined;
+    }
+    return value;
+}
+function actorFrom(body, violations) {
+    const value = body['actor_node_id'];
+    if (value === undefined || value === null)
+        return { kind: 'human', node_id: null };
+    if (typeof value !== 'string' || !isSafeNodeId(value)) {
+        violations.push({ field: 'actor_node_id', problem: 'must be a safe node id or null', received: value });
+        return null;
+    }
+    return { kind: 'node', node_id: value };
+}
+function requireKnownNode(nodeId, field, violations) {
+    if (getNode(nodeId) === null) {
+        violations.push({ field, problem: 'must name an existing node', received: nodeId });
+    }
+}
+function requireKnownActor(actor, violations) {
+    if (actor.node_id !== null)
+        requireKnownNode(actor.node_id, 'actor_node_id', violations);
+}
+function anchorFrom(value, field, violations) {
+    if (!isRecord(value)) {
+        violations.push({ field, problem: 'must be an anchor object', received: value });
+        return undefined;
+    }
+    const allowed = ['line', 'end_line', 'col_start', 'col_end', 'quote'];
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key))
+            violations.push({ field: `${field}.${key}`, problem: 'is not allowed', received: value[key] });
+    }
+    const line = value['line'];
+    const endLine = value['end_line'];
+    if (typeof line !== 'number')
+        violations.push({ field: `${field}.line`, problem: 'must be a number', ...(line === undefined ? {} : { received: line }) });
+    if (typeof endLine !== 'number')
+        violations.push({ field: `${field}.end_line`, problem: 'must be a number', ...(endLine === undefined ? {} : { received: endLine }) });
+    for (const key of ['col_start', 'col_end']) {
+        const column = value[key];
+        if (column !== undefined && typeof column !== 'number') {
+            violations.push({ field: `${field}.${key}`, problem: 'must be a number', received: column });
+        }
+    }
+    if (value['quote'] !== undefined && typeof value['quote'] !== 'string') {
+        violations.push({ field: `${field}.quote`, problem: 'must be a string', received: value['quote'] });
+    }
+    if (typeof line !== 'number' || typeof endLine !== 'number')
+        return undefined;
+    return {
+        line,
+        end_line: endLine,
+        ...(typeof value['col_start'] === 'number' ? { col_start: value['col_start'] } : {}),
+        ...(typeof value['col_end'] === 'number' ? { col_end: value['col_end'] } : {}),
+        ...(typeof value['quote'] === 'string' ? { quote: value['quote'] } : {}),
+    };
+}
+function requireReviewId(ctx, violations) {
+    const reviewId = ctx.params['review_id'];
+    if (reviewId === undefined || !isSafeNodeId(reviewId)) {
+        violations.push({ field: 'review_id', problem: 'must be a safe review id', ...(reviewId === undefined ? {} : { received: reviewId }) });
+        return undefined;
+    }
+    return reviewId;
+}
+function requireCommentId(ctx, violations) {
+    const commentId = ctx.params['comment_id'];
+    if (commentId === undefined || !COMMENT_ID.test(commentId)) {
+        violations.push({ field: 'comment_id', problem: 'must be a 32-character lowercase hexadecimal id', ...(commentId === undefined ? {} : { received: commentId }) });
+        return undefined;
+    }
+    return commentId;
+}
+function requireVisibleReview(reviewId) {
+    const review = getReview(reviewId);
+    if (review === null || review.state === 'binding') {
+        throw new ReviewOperationError('unknown_review', 'review was not found', { received: reviewId });
+    }
+    return review;
+}
+function requireOpenReview(reviewId) {
+    const review = requireVisibleReview(reviewId);
+    if (review.state !== 'open') {
+        throw new ReviewOperationError('review_not_open', 'review is not open', { review_id: reviewId, state: review.state });
+    }
+    return review;
+}
+function requireCompanionReview(actorNodeId) {
+    const review = actorNodeId === null ? null : getReviewByCompanion(actorNodeId);
+    if (review === null || review.state !== 'open') {
+        throw new ReviewOperationError('review_required', 'an open review is required when no review id is supplied', { actor_node_id: actorNodeId });
+    }
+    return review;
+}
+function toDetail(comment) {
+    return {
+        comment: toReviewCommentDTO(comment),
+        events: listCommentEvents(comment.comment_id).map(toReviewCommentEventDTO),
+    };
+}
+function deliveryFailure(review, error) {
+    return {
+        attempted: true,
+        target_node_id: review.companion_node_id,
+        status: 'failed',
+        woke: false,
+        error: error instanceof Error ? error.message : String(error),
+    };
+}
+async function mutationResult(args) {
+    if (!args.changed)
+        return { comment: toReviewCommentDTO(args.comment), changed: false };
+    let delivery;
+    try {
+        delivery = await notifyComment({
+            review: args.review,
+            comment: args.comment,
+            verb: args.verb,
+            actor_node_id: args.actor.node_id,
+            deliver: args.deliver,
+            operation_id: args.operationId,
+        });
+    }
+    catch (error) {
+        // State and its audit were committed before notification. A notification or
+        // notification-audit failure therefore remains a successful mutation.
+        delivery = deliveryFailure(args.review, error);
+    }
+    return { comment: toReviewCommentDTO(args.comment), changed: true, delivery };
+}
+function parseCreate(ctx, selectorKind) {
+    const violations = [];
+    const body = objectBody(ctx.body, ['text', 'anchor', 'doc_hash', 'actor_node_id', 'deliver'], violations);
+    const selector = selectorKind === 'review'
+        ? (() => {
+            const review_id = requireReviewId(ctx, violations);
+            return review_id === undefined ? undefined : { kind: 'review', review_id };
+        })()
+        : { kind: 'self' };
+    const text = requiredString(body, 'text', violations);
+    const anchor = anchorFrom(body['anchor'], 'anchor', violations);
+    const doc_hash = optionalSha256(body, 'doc_hash', violations);
+    const actor = actorFrom(body, violations);
+    const deliver = optionalDeliver(body, violations);
+    if (actor !== null)
+        requireKnownActor(actor, violations);
+    if (violations.length > 0 || selector === undefined || text === undefined || anchor === undefined || actor === null)
+        invalidRequest(violations);
+    return { selector, text, anchor, ...(doc_hash === undefined ? {} : { doc_hash }), actor, ...(deliver === undefined ? {} : { deliver }) };
+}
+function parseAction(ctx, needsText) {
+    const violations = [];
+    const body = objectBody(ctx.body, needsText
+        ? ['text', 'actor_node_id', 'deliver', 'if_revision']
+        : ['actor_node_id', 'deliver', 'if_revision'], violations);
+    const comment_id = requireCommentId(ctx, violations);
+    const text = needsText ? requiredString(body, 'text', violations) : undefined;
+    const actor = actorFrom(body, violations);
+    const deliver = optionalDeliver(body, violations);
+    const if_revision = optionalRevision(body, violations);
+    if (actor !== null)
+        requireKnownActor(actor, violations);
+    if (violations.length > 0 || comment_id === undefined || actor === null || (needsText && text === undefined))
+        invalidRequest(violations);
+    return {
+        comment_id,
+        ...(text === undefined ? {} : { text }),
+        actor,
+        ...(deliver === undefined ? {} : { deliver }),
+        ...(if_revision === undefined ? {} : { if_revision }),
+    };
+}
+function parseRangeBatch(ctx) {
+    const violations = [];
+    const body = objectBody(ctx.body, ['from_doc_hash', 'to_doc_hash', 'entries'], violations);
+    const review_id = requireReviewId(ctx, violations);
+    const from_doc_hash = requiredSha256(body, 'from_doc_hash', violations);
+    const to_doc_hash = requiredSha256(body, 'to_doc_hash', violations);
+    const entriesRaw = body['entries'];
+    const entries = [];
+    if (!Array.isArray(entriesRaw)) {
+        violations.push({ field: 'entries', problem: 'must be an array', received: entriesRaw });
+    }
+    else {
+        entriesRaw.forEach((raw, index) => {
+            const field = `entries[${index}]`;
+            if (!isRecord(raw)) {
+                violations.push({ field, problem: 'must be an object', received: raw });
+                return;
+            }
+            for (const key of Object.keys(raw)) {
+                if (!['comment_id', 'anchor', 'detached'].includes(key))
+                    violations.push({ field: `${field}.${key}`, problem: 'is not allowed', received: raw[key] });
+            }
+            const commentId = raw['comment_id'];
+            if (typeof commentId !== 'string' || !COMMENT_ID.test(commentId)) {
+                violations.push({ field: `${field}.comment_id`, problem: 'must be a 32-character lowercase hexadecimal id', received: commentId });
+                return;
+            }
+            const hasAnchor = raw['anchor'] !== undefined;
+            const detachedValue = raw['detached'];
+            if (detachedValue !== undefined && detachedValue !== true) {
+                violations.push({ field: `${field}.detached`, problem: 'must be true when present', received: detachedValue });
+            }
+            const detached = detachedValue === true;
+            if (hasAnchor === detached) {
+                violations.push({ field, problem: 'must provide exactly one of anchor or detached: true' });
+                return;
+            }
+            if (detached) {
+                entries.push({ comment_id: commentId, detached: true });
+                return;
+            }
+            const anchor = anchorFrom(raw['anchor'], `${field}.anchor`, violations);
+            if (anchor !== undefined)
+                entries.push({ comment_id: commentId, anchor });
+        });
+    }
+    if (violations.length > 0 || review_id === undefined || from_doc_hash === undefined || to_doc_hash === undefined || !Array.isArray(entriesRaw))
+        invalidRequest(violations);
+    return { review_id, request: { from_doc_hash, to_doc_hash, entries } };
+}
+function parseListQuery(ctx, selectorKind, violations) {
+    for (const [field, value] of ctx.query) {
+        if (field !== 'status' && (field !== 'actor_node_id' || selectorKind !== 'self')) {
+            violations.push({ field, problem: 'is not allowed', received: value });
+        }
+    }
+    const values = ctx.query.getAll('status');
+    if (values.length > 1 || (values.length === 1 && !COMMENT_STATUSES.has(values[0]))) {
+        violations.push({ field: 'status', problem: 'must be open, resolved, deleted, or all', received: values.length > 1 ? values : values[0] });
+    }
+    const actors = ctx.query.getAll('actor_node_id');
+    let actor_node_id = null;
+    if (actors.length > 1) {
+        violations.push({ field: 'actor_node_id', problem: 'must appear at most once', received: actors });
+    }
+    else if (actors.length === 1) {
+        const value = actors[0];
+        if (!isSafeNodeId(value)) {
+            violations.push({ field: 'actor_node_id', problem: 'must be a safe node id', received: value });
+        }
+        else {
+            actor_node_id = value;
+            requireKnownNode(value, 'actor_node_id', violations);
+        }
+    }
+    return {
+        ...(values.length === 0 ? {} : { status: values[0] }),
+        actor_node_id,
+    };
+}
+function parseEventQuery(ctx, violations) {
+    const parsed = {};
+    for (const [field, value] of ctx.query) {
+        if (field !== 'since_seq' && field !== 'limit')
+            violations.push({ field, problem: 'is not allowed', received: value });
+    }
+    for (const field of ['since_seq', 'limit']) {
+        const values = ctx.query.getAll(field);
+        if (values.length > 1) {
+            violations.push({ field, problem: 'must appear at most once', received: values });
+            continue;
+        }
+        if (values.length === 0)
+            continue;
+        const raw = values[0];
+        const value = Number(raw);
+        if (!Number.isSafeInteger(value) || value < 0 || String(value) !== raw) {
+            violations.push({ field, problem: 'must be a non-negative safe integer', received: raw });
+            continue;
+        }
+        parsed[field] = value;
+    }
+    if (parsed.limit !== undefined && parsed.limit < 1) {
+        violations.push({ field: 'limit', problem: 'must be at least 1', received: parsed.limit });
+    }
+    return parsed;
+}
+async function handleCreate(ctx, selectorKind) {
+    const request = parseCreate(ctx, selectorKind);
+    const operationId = randomUUID();
+    const committed = withCanvasWrite((db) => {
+        const review = request.selector.kind === 'review'
+            ? requireOpenReview(request.selector.review_id)
+            : requireOpenReview(requireCompanionReview(request.actor.node_id).review_id);
+        const source = requireCurrentDocumentLocked(db, review.review_id, request.doc_hash ?? review.anchor_base_sha256);
+        const mutation = createComment({
+            review_id: review.review_id,
+            text: request.text,
+            anchor: request.anchor,
+            line_text: captureAnchorText(source.lines, request.anchor),
+            doc_hash: source.sha256,
+            actor: request.actor,
+            operation_id: operationId,
+        });
+        return { review, mutation };
+    });
+    return {
+        status: 200,
+        body: await mutationResult({
+            review: committed.review,
+            ...committed.mutation,
+            verb: 'create',
+            actor: request.actor,
+            deliver: request.deliver,
+            operationId,
+        }),
+    };
+}
+function handleList(ctx, selectorKind) {
+    const violations = [];
+    const selector = selectorKind === 'review'
+        ? (() => {
+            const review_id = requireReviewId(ctx, violations);
+            return review_id === undefined ? undefined : { kind: 'review', review_id };
+        })()
+        : { kind: 'self' };
+    const query = parseListQuery(ctx, selectorKind, violations);
+    if (violations.length > 0 || selector === undefined)
+        invalidRequest(violations);
+    const review = selector.kind === 'review'
+        ? requireVisibleReview(selector.review_id)
+        : requireCompanionReview(query.actor_node_id);
+    const body = {
+        review_id: review.review_id,
+        comments: listComments(review.review_id, query).map(toReviewCommentDTO),
+    };
+    return { status: 200, body };
+}
+function handleEvents(ctx) {
+    const violations = [];
+    const reviewId = requireReviewId(ctx, violations);
+    const query = parseEventQuery(ctx, violations);
+    if (violations.length > 0 || reviewId === undefined)
+        invalidRequest(violations);
+    const review = requireVisibleReview(reviewId);
+    const page = listReviewEvents(review.review_id, query);
+    const body = {
+        review_id: review.review_id,
+        events: page.events.map(toReviewCommentEventDTO),
+        next_since_seq: page.events.length === 0 ? null : page.next_since_seq,
+    };
+    return { status: 200, body };
+}
+function handleRanges(ctx) {
+    const { review_id, request } = parseRangeBatch(ctx);
+    const operationId = randomUUID();
+    const result = withCanvasWrite(() => {
+        const review = requireOpenReview(review_id);
+        const nondeleted = listComments(review.review_id).length;
+        const applied = applyRangeBatch({
+            review_id: review.review_id,
+            ...request,
+            actor: { kind: 'human', node_id: null },
+            operation_id: operationId,
+        });
+        return { review, nondeleted, applied };
+    });
+    const body = {
+        review_id: result.review.review_id,
+        anchor_base_sha256: result.applied.anchor_base_sha256,
+        updated: result.applied.updated,
+        detached: result.applied.detached,
+        unchanged: result.nondeleted - result.applied.updated,
+    };
+    return { status: 200, body };
+}
+function handleDetail(ctx) {
+    const violations = [];
+    const commentId = requireCommentId(ctx, violations);
+    if (violations.length > 0 || commentId === undefined)
+        invalidRequest(violations);
+    const comment = getComment(commentId);
+    if (comment === null)
+        throw new ReviewOperationError('unknown_comment', 'comment was not found', { received: commentId });
+    requireVisibleReview(comment.review_id);
+    return { status: 200, body: toDetail(comment) };
+}
+async function handleAction(ctx, verb) {
+    const request = parseAction(ctx, verb === 'edit');
+    const operationId = randomUUID();
+    const committed = withCanvasWrite(() => {
+        const existing = getComment(request.comment_id);
+        if (existing === null)
+            throw new ReviewOperationError('unknown_comment', 'comment was not found', { received: request.comment_id });
+        const review = requireOpenReview(existing.review_id);
+        const mutation = verb === 'edit'
+            ? editComment(request.comment_id, { text: request.text, actor: request.actor, operation_id: operationId, if_revision: request.if_revision })
+            : verb === 'resolve'
+                ? resolveComment(request.comment_id, { actor: request.actor, operation_id: operationId, if_revision: request.if_revision })
+                : verb === 'reopen'
+                    ? reopenComment(request.comment_id, { actor: request.actor, operation_id: operationId, if_revision: request.if_revision })
+                    : deleteComment(request.comment_id, { actor: request.actor, operation_id: operationId, if_revision: request.if_revision });
+        return { review, mutation };
+    });
+    return {
+        status: 200,
+        body: await mutationResult({
+            review: committed.review,
+            ...committed.mutation,
+            verb,
+            actor: request.actor,
+            deliver: request.deliver,
+            operationId,
+        }),
+    };
+}
+export const reviewCommentRoutes = [
+    { method: 'POST', pattern: '/v1/human/reviews/self/comments', handler: (ctx) => handleCreate(ctx, 'self') },
+    { method: 'GET', pattern: '/v1/human/reviews/self/comments', handler: (ctx) => handleList(ctx, 'self') },
+    { method: 'POST', pattern: '/v1/human/reviews/:review_id/comments', handler: (ctx) => handleCreate(ctx, 'review') },
+    { method: 'GET', pattern: '/v1/human/reviews/:review_id/comments', handler: (ctx) => handleList(ctx, 'review') },
+    { method: 'GET', pattern: '/v1/human/reviews/:review_id/comment-events', handler: handleEvents },
+    { method: 'POST', pattern: '/v1/human/reviews/:review_id/comment-ranges', handler: handleRanges },
+    { method: 'GET', pattern: '/v1/human/comments/:comment_id', handler: handleDetail },
+    { method: 'POST', pattern: '/v1/human/comments/:comment_id/edit', handler: (ctx) => handleAction(ctx, 'edit') },
+    { method: 'POST', pattern: '/v1/human/comments/:comment_id/resolve', handler: (ctx) => handleAction(ctx, 'resolve') },
+    { method: 'POST', pattern: '/v1/human/comments/:comment_id/reopen', handler: (ctx) => handleAction(ctx, 'reopen') },
+    { method: 'POST', pattern: '/v1/human/comments/:comment_id/delete', handler: (ctx) => handleAction(ctx, 'delete') },
+];

package/dist/daemon/api/handlers/reviews.d.ts

@@ -0,0 +1,2 @@
+import type { RouteTable } from '../router.js';
+export declare const reviewRoutes: RouteTable;