@claudian-collab/protocol 1.0.0

package/dist/CollabError.d.ts

@@ -0,0 +1,27 @@
+export declare const COLLAB_ERROR_CODES: readonly ["protocol-version-unsupported", "protocol-payload-invalid", "project-not-found", "quota-exceeded", "authentication-failed", "authorization-denied", "membership-revoked", "stale-main", "stale-request-head", "personal-ref-diverged", "content-conflict", "description-required", "request-not-open", "request-head-not-pushed", "ticket-not-found", "resolving-ticket-reference-not-found", "ticket-not-open", "stale-ticket", "stale-request-metadata", "authority-not-synchronized", "idempotency-conflict", "acceptance-recovery-required", "authority-integrity-error", "operation-timeout", "operation-failed"];
+export type CollabErrorCode = typeof COLLAB_ERROR_CODES[number];
+export type CollabErrorGroup = 'setup' | 'path' | 'authorization' | 'state' | 'integrity' | 'operation';
+declare const COLLAB_RECOVERY_ACTIONS: readonly ["retry", "review-conflicts", "request-access"];
+export type CollabRecoveryAction = typeof COLLAB_RECOVERY_ACTIONS[number];
+export type CollabDiagnosticValue = string | number | boolean | null | readonly CollabDiagnosticValue[] | {
+    readonly [key: string]: CollabDiagnosticValue;
+};
+export type CollabDiagnosticContext = Readonly<Record<string, CollabDiagnosticValue>>;
+export declare function sanitizeCollabDiagnosticContext(context?: Readonly<Record<string, unknown>>): CollabDiagnosticContext;
+export declare function collabErrorGroup(code: CollabErrorCode): CollabErrorGroup;
+export interface CollabErrorOptions {
+    code: CollabErrorCode;
+    safeContext?: Readonly<Record<string, unknown>>;
+    recoveryActions?: readonly CollabRecoveryAction[];
+    cause?: unknown;
+}
+export declare class CollabError extends Error {
+    readonly code: CollabErrorCode;
+    readonly group: CollabErrorGroup;
+    readonly safeContext: CollabDiagnosticContext;
+    readonly recoveryActions: readonly CollabRecoveryAction[];
+    readonly cause?: unknown;
+    constructor(options: CollabErrorOptions);
+    toJSON(): Readonly<Record<string, unknown>>;
+}
+export {};

package/dist/CollabError.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CollabError = exports.COLLAB_ERROR_CODES = void 0;
+exports.sanitizeCollabDiagnosticContext = sanitizeCollabDiagnosticContext;
+exports.collabErrorGroup = collabErrorGroup;
+exports.COLLAB_ERROR_CODES = Object.freeze([
+    'protocol-version-unsupported',
+    'protocol-payload-invalid',
+    'project-not-found',
+    'quota-exceeded',
+    'authentication-failed',
+    'authorization-denied',
+    'membership-revoked',
+    'stale-main',
+    'stale-request-head',
+    'personal-ref-diverged',
+    'content-conflict',
+    'description-required',
+    'request-not-open',
+    'request-head-not-pushed',
+    'ticket-not-found',
+    'resolving-ticket-reference-not-found',
+    'ticket-not-open',
+    'stale-ticket',
+    'stale-request-metadata',
+    'authority-not-synchronized',
+    'idempotency-conflict',
+    'acceptance-recovery-required',
+    'authority-integrity-error',
+    'operation-timeout',
+    'operation-failed',
+]);
+const COLLAB_RECOVERY_ACTIONS = Object.freeze([
+    'retry',
+    'review-conflicts',
+    'request-access',
+]);
+const COLLAB_ERROR_CODE_SET = new Set(exports.COLLAB_ERROR_CODES);
+const COLLAB_RECOVERY_ACTION_SET = new Set(COLLAB_RECOVERY_ACTIONS);
+const SAFE_CONTEXT_RULES = Object.freeze({
+    endpoint: 'path',
+    exitCode: 'number',
+    field: 'token',
+    kind: 'token',
+    limit: 'number',
+    operation: 'token',
+    operationId: 'id',
+    path: 'path',
+    projectId: 'id',
+    quota: 'token',
+    reason: 'token',
+    receivedVersion: 'number',
+    recordKind: 'token',
+    retiredAt: 'timestamp',
+    side: 'token',
+    status: 'token',
+    supportedVersion: 'number',
+    ticketNumber: 'number',
+});
+const SAFE_TOKEN_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const SAFE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+function sanitizeAllowedValue(rule, value) {
+    switch (rule) {
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value) ? value : null;
+        case 'path':
+            return typeof value === 'string' ? '[PATH]' : null;
+        case 'timestamp':
+            return typeof value === 'string'
+                && !Number.isNaN(Date.parse(value))
+                && new Date(value).toISOString() === value
+                ? value
+                : null;
+        case 'id':
+            return typeof value === 'string' && SAFE_ID_PATTERN.test(value) ? value : null;
+        case 'token':
+            return typeof value === 'string' && SAFE_TOKEN_PATTERN.test(value) ? value : null;
+    }
+}
+function sanitizeCollabDiagnosticContext(context = {}) {
+    const result = {};
+    for (const [key, value] of Object.entries(context)) {
+        const rule = SAFE_CONTEXT_RULES[key];
+        if (!rule)
+            continue;
+        const sanitized = sanitizeAllowedValue(rule, value);
+        if (sanitized !== null)
+            result[key] = sanitized;
+    }
+    return result;
+}
+function collabErrorGroup(code) {
+    switch (code) {
+        case 'protocol-version-unsupported':
+        case 'protocol-payload-invalid':
+            return 'setup';
+        case 'project-not-found':
+        case 'quota-exceeded':
+            return 'path';
+        case 'authentication-failed':
+        case 'authorization-denied':
+        case 'membership-revoked':
+            return 'authorization';
+        case 'stale-main':
+        case 'stale-request-head':
+        case 'personal-ref-diverged':
+        case 'content-conflict':
+        case 'description-required':
+        case 'request-not-open':
+        case 'request-head-not-pushed':
+        case 'ticket-not-found':
+        case 'resolving-ticket-reference-not-found':
+        case 'ticket-not-open':
+        case 'stale-ticket':
+        case 'stale-request-metadata':
+        case 'authority-not-synchronized':
+        case 'idempotency-conflict':
+            return 'state';
+        case 'acceptance-recovery-required':
+        case 'authority-integrity-error':
+            return 'integrity';
+        case 'operation-timeout':
+        case 'operation-failed':
+            return 'operation';
+    }
+}
+class CollabError extends Error {
+    code;
+    group;
+    safeContext;
+    recoveryActions;
+    constructor(options) {
+        if (!COLLAB_ERROR_CODE_SET.has(options.code)) {
+            throw new TypeError('Unsupported Collab error code');
+        }
+        if (!(options.recoveryActions ?? []).every(action => COLLAB_RECOVERY_ACTION_SET.has(action))) {
+            throw new TypeError('Unsupported Collab recovery action');
+        }
+        super(`collab.error.${options.code}`);
+        this.name = 'CollabError';
+        this.code = options.code;
+        this.group = collabErrorGroup(options.code);
+        this.safeContext = Object.freeze(sanitizeCollabDiagnosticContext(options.safeContext));
+        this.recoveryActions = Object.freeze([...(options.recoveryActions ?? [])]);
+        if (options.cause !== undefined) {
+            Object.defineProperty(this, 'cause', {
+                configurable: false,
+                enumerable: false,
+                value: options.cause,
+                writable: false,
+            });
+        }
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            group: this.group,
+            message: this.message,
+            safeContext: this.safeContext,
+            recoveryActions: this.recoveryActions,
+        };
+    }
+}
+exports.CollabError = CollabError;

package/dist/CollabMarkdownProse.d.ts

@@ -0,0 +1 @@
+export declare function maskCollabMarkdownProse(markdown: string): string;

package/dist/CollabMarkdownProse.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maskCollabMarkdownProse = maskCollabMarkdownProse;
+const markdown_1 = require("@lezer/markdown");
+const MASKED_MARKDOWN_NODES = new Set([
+    'CodeBlock',
+    'Comment',
+    'CommentBlock',
+    'FencedCode',
+    'HTMLBlock',
+    'HTMLTag',
+    'Image',
+    'InlineCode',
+    'LinkLabel',
+    'LinkReference',
+    'LinkTitle',
+    'ProcessingInstruction',
+    'ProcessingInstructionBlock',
+    'URL',
+]);
+const BOUNDARY_MASKED_MARKDOWN_NODES = new Set(['Entity']);
+function maskCollabMarkdownProse(markdown) {
+    const maskedRanges = [];
+    const escapes = [];
+    markdown_1.parser.parse(markdown).iterate({
+        enter(node) {
+            if (node.name === 'Escape') {
+                escapes.push({ from: node.from, to: node.to });
+                return false;
+            }
+            if (MASKED_MARKDOWN_NODES.has(node.name)
+                || BOUNDARY_MASKED_MARKDOWN_NODES.has(node.name)) {
+                maskedRanges.push({
+                    from: node.from,
+                    preservesBoundary: BOUNDARY_MASKED_MARKDOWN_NODES.has(node.name),
+                    to: node.to,
+                });
+                return false;
+            }
+            return true;
+        },
+    });
+    const output = markdown.split('');
+    for (const range of maskedRanges) {
+        for (let offset = range.from; offset < range.to; offset += 1) {
+            if (markdown[offset] !== '\n' && markdown[offset] !== '\r') {
+                output[offset] = range.preservesBoundary ? '_' : ' ';
+            }
+        }
+    }
+    for (const escape of escapes) {
+        const escaped = markdown.slice(escape.from + 1, escape.to);
+        output[escape.from] = ' ';
+        output[escape.from + 1] = escaped === '@' || escaped === '#' ? '_' : escaped;
+    }
+    return output.join('');
+}

package/dist/CollabMemberMentionParser.d.ts

@@ -0,0 +1,6 @@
+import type { CollabMemberId } from './types';
+export interface CollabMemberMentionTarget {
+    readonly displayName: string;
+    readonly memberId: CollabMemberId;
+}
+export declare function parseCollabMemberMentions(markdown: string, targets: readonly CollabMemberMentionTarget[]): readonly CollabMemberId[];

package/dist/CollabMemberMentionParser.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCollabMemberMentions = parseCollabMemberMentions;
+const CollabMarkdownProse_1 = require("./CollabMarkdownProse");
+const MENTION_ADJACENT_CHARACTER = /[\p{L}\p{N}_@-]/u;
+function parseCollabMemberMentions(markdown, targets) {
+    const candidates = mentionCandidates(targets);
+    if (candidates.length === 0)
+        return [];
+    const prose = (0, CollabMarkdownProse_1.maskCollabMarkdownProse)(markdown);
+    const memberIds = new Set();
+    let searchFrom = 0;
+    while (searchFrom < prose.length) {
+        const mentionStart = prose.indexOf('@', searchFrom);
+        if (mentionStart < 0)
+            break;
+        searchFrom = mentionStart + 1;
+        const preceding = prose[mentionStart - 1];
+        if (preceding !== undefined && MENTION_ADJACENT_CHARACTER.test(preceding))
+            continue;
+        const candidate = candidates.find(entry => {
+            if (!prose.startsWith(entry.name, mentionStart + 1))
+                return false;
+            const following = prose[mentionStart + entry.name.length + 1];
+            return following === undefined || !MENTION_ADJACENT_CHARACTER.test(following);
+        });
+        if (!candidate)
+            continue;
+        memberIds.add(candidate.memberId);
+        searchFrom = mentionStart + candidate.name.length + 1;
+    }
+    return [...memberIds];
+}
+function mentionCandidates(targets) {
+    const byName = new Map();
+    for (const target of targets) {
+        const name = target.displayName.trim();
+        if (name.length === 0)
+            continue;
+        const existing = byName.get(name);
+        if (existing === undefined) {
+            byName.set(name, { memberId: target.memberId, name });
+        }
+        else if (existing?.memberId !== target.memberId) {
+            byName.set(name, null);
+        }
+    }
+    return [...byName.values()]
+        .filter((candidate) => candidate !== null)
+        .sort((left, right) => right.name.length - left.name.length);
+}

package/dist/CollabProtocol.d.ts

@@ -0,0 +1,144 @@
+import { type CollabProtocolVersion } from './CollabConstants';
+import { CollabError } from './CollabError';
+import type { CollabChangeRequest, CollabComment, CollabCommentPage, CollabGitOid, CollabIdempotencyKey, CollabProjectId, CollabRequestDetail, CollabRequestId, CollabResolvingTicketExpectation, CollabTicketAcceptedRelationPage, CollabTicketComment, CollabTicketCommentPage, CollabTicketDetail, CollabTicketId, CollabTicketPage, CollabTicketStatus, CollabTicketSummary } from './types';
+export interface CollabProtocolEnvelope<T> {
+    protocolVersion: CollabProtocolVersion;
+    requestId: string;
+    data: T;
+}
+export type CollabDecodeFailure = {
+    status: 'invalid';
+    error: CollabError;
+} | {
+    status: 'unsupported-version';
+    receivedVersion: number;
+    error: CollabError;
+};
+export type CollabDecodeResult<T> = {
+    status: 'ok';
+    value: T;
+} | CollabDecodeFailure;
+export interface CollabMutationContext {
+    projectId: CollabProjectId;
+    idempotencyKey: CollabIdempotencyKey;
+}
+export interface GetRequestRequest {
+    projectId: CollabProjectId;
+    requestId: CollabRequestId;
+}
+export interface EnsureMyRequestRequest extends CollabMutationContext {
+    expectedMainOid: CollabGitOid;
+    headOid: CollabGitOid;
+    description: string;
+}
+export interface EnsureMyRequestResponse {
+    mainOid: CollabGitOid;
+    request: CollabChangeRequest;
+}
+export interface CreateCommentRequest extends CollabMutationContext {
+    requestId: CollabRequestId;
+    body: string;
+}
+export interface CreateCommentResponse {
+    comment: CollabComment;
+    request: CollabChangeRequest;
+}
+export interface ListTicketsRequest {
+    projectId: CollabProjectId;
+    status: CollabTicketStatus | 'all';
+    cursor?: string;
+    limit?: number;
+}
+export interface ListRequestCommentsRequest {
+    projectId: CollabProjectId;
+    requestId: CollabRequestId;
+    cursor?: string;
+    limit?: number;
+}
+export interface ListTicketCommentsRequest {
+    projectId: CollabProjectId;
+    ticketId: CollabTicketId;
+    cursor?: string;
+    limit?: number;
+}
+export interface ListTicketAcceptedRelationsRequest {
+    projectId: CollabProjectId;
+    ticketId: CollabTicketId;
+    cursor?: string;
+    limit?: number;
+}
+export interface GetTicketRequest {
+    projectId: CollabProjectId;
+    ticketId: CollabTicketId;
+}
+export interface CreateTicketRequest extends CollabMutationContext {
+    title: string;
+    body: string;
+}
+export interface CreateTicketResponse {
+    ticket: CollabTicketDetail;
+}
+export interface UpdateTicketContentRequest extends CollabMutationContext {
+    ticketId: CollabTicketId;
+    expectedRevision: number;
+    title: string;
+    body: string;
+}
+export interface CreateTicketCommentRequest extends CollabMutationContext {
+    ticketId: CollabTicketId;
+    body: string;
+}
+export interface CreateTicketCommentResponse {
+    comment: CollabTicketComment;
+    ticket: CollabTicketSummary;
+}
+export interface ChangeTicketStatusRequest extends CollabMutationContext {
+    ticketId: CollabTicketId;
+    expectedRevision: number;
+}
+export interface TicketMutationResponse {
+    ticket: CollabTicketSummary;
+}
+export interface UpdateMyRequestMetadataRequest extends CollabMutationContext {
+    requestId: CollabRequestId;
+    expectedHeadOid: CollabGitOid;
+    expectedRequestRevision: number;
+    description: string;
+}
+export interface UpdateMyRequestMetadataResponse {
+    request: CollabChangeRequest;
+}
+export interface AcceptRequest extends CollabMutationContext {
+    requestId: CollabRequestId;
+    expectedMainOid: CollabGitOid;
+    expectedHeadOid: CollabGitOid;
+    expectedRequestRevision: number;
+    expectedResolvingTickets: readonly CollabResolvingTicketExpectation[];
+}
+export interface AcceptResponse {
+    request: CollabChangeRequest;
+    mainOid: CollabGitOid;
+    mergeCommitOid: CollabGitOid;
+}
+export interface CollabControlOperationDefinition<Request, Response> {
+    request: Request;
+    response: Response;
+}
+export interface CollabControlOperationMap {
+    getRequest: CollabControlOperationDefinition<GetRequestRequest, CollabRequestDetail>;
+    listRequestComments: CollabControlOperationDefinition<ListRequestCommentsRequest, CollabCommentPage>;
+    ensureMyRequest: CollabControlOperationDefinition<EnsureMyRequestRequest, EnsureMyRequestResponse>;
+    createComment: CollabControlOperationDefinition<CreateCommentRequest, CreateCommentResponse>;
+    listTickets: CollabControlOperationDefinition<ListTicketsRequest, CollabTicketPage>;
+    getTicket: CollabControlOperationDefinition<GetTicketRequest, CollabTicketDetail>;
+    listTicketComments: CollabControlOperationDefinition<ListTicketCommentsRequest, CollabTicketCommentPage>;
+    listTicketAcceptedRelations: CollabControlOperationDefinition<ListTicketAcceptedRelationsRequest, CollabTicketAcceptedRelationPage>;
+    createTicket: CollabControlOperationDefinition<CreateTicketRequest, CreateTicketResponse>;
+    updateTicketContent: CollabControlOperationDefinition<UpdateTicketContentRequest, TicketMutationResponse>;
+    createTicketComment: CollabControlOperationDefinition<CreateTicketCommentRequest, CreateTicketCommentResponse>;
+    closeTicket: CollabControlOperationDefinition<ChangeTicketStatusRequest, TicketMutationResponse>;
+    reopenTicket: CollabControlOperationDefinition<ChangeTicketStatusRequest, TicketMutationResponse>;
+    updateMyRequestMetadata: CollabControlOperationDefinition<UpdateMyRequestMetadataRequest, UpdateMyRequestMetadataResponse>;
+    acceptRequest: CollabControlOperationDefinition<AcceptRequest, AcceptResponse>;
+}
+export declare function decodeCollabProtocolEnvelope<T = unknown>(input: unknown): CollabDecodeResult<CollabProtocolEnvelope<T>>;

package/dist/CollabProtocol.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeCollabProtocolEnvelope = decodeCollabProtocolEnvelope;
+const CollabConstants_1 = require("./CollabConstants");
+const CollabError_1 = require("./CollabError");
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasExactKeys(record, required) {
+    const allowed = new Set(required);
+    return required.every(key => Object.hasOwn(record, key))
+        && Object.keys(record).every(key => allowed.has(key));
+}
+function requiredString(record, field) {
+    const value = record[field];
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function invalidPayload(field) {
+    return {
+        status: 'invalid',
+        error: new CollabError_1.CollabError({
+            code: 'protocol-payload-invalid',
+            safeContext: { field },
+        }),
+    };
+}
+function unsupportedVersion(receivedVersion) {
+    return {
+        status: 'unsupported-version',
+        receivedVersion,
+        error: new CollabError_1.CollabError({
+            code: 'protocol-version-unsupported',
+            safeContext: {
+                receivedVersion,
+                supportedVersion: CollabConstants_1.COLLAB_PROTOCOL_VERSION,
+            },
+        }),
+    };
+}
+function decodeVersion(record) {
+    const version = record.protocolVersion;
+    if (typeof version !== 'number' || !Number.isInteger(version)) {
+        return invalidPayload('protocolVersion');
+    }
+    if (version !== CollabConstants_1.COLLAB_PROTOCOL_VERSION)
+        return unsupportedVersion(version);
+    return { status: 'ok', value: CollabConstants_1.COLLAB_PROTOCOL_VERSION };
+}
+function decodeCollabProtocolEnvelope(input) {
+    if (!isRecord(input) || !hasExactKeys(input, ['protocolVersion', 'requestId', 'data'])) {
+        return invalidPayload('envelope');
+    }
+    const version = decodeVersion(input);
+    if (version.status !== 'ok')
+        return version;
+    const requestId = requiredString(input, 'requestId');
+    if (!requestId)
+        return invalidPayload('requestId');
+    return {
+        status: 'ok',
+        value: {
+            data: input.data,
+            protocolVersion: version.value,
+            requestId,
+        },
+    };
+}

package/dist/CollabRequestTicketRequestCodecs.d.ts

@@ -0,0 +1,5 @@
+import type { CollabControlOperationMap, CollabDecodeResult } from './CollabProtocol';
+export type CollabRequestTicketOperation = 'acceptRequest' | 'closeTicket' | 'createComment' | 'createTicket' | 'createTicketComment' | 'ensureMyRequest' | 'getRequest' | 'getTicket' | 'listRequestComments' | 'listTicketAcceptedRelations' | 'listTicketComments' | 'listTickets' | 'reopenTicket' | 'updateMyRequestMetadata' | 'updateTicketContent';
+type OperationRequest<Operation extends CollabRequestTicketOperation> = CollabControlOperationMap[Operation]['request'];
+export declare function decodeCollabRequestTicketOperationRequest<Operation extends CollabRequestTicketOperation>(operation: Operation, input: unknown): CollabDecodeResult<OperationRequest<Operation>>;
+export {};