@claudian-collab/protocol 1.0.0

package/dist/CollabTicketReferenceParser.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCollabTicketReferences = parseCollabTicketReferences;
+exports.scanCollabTicketReferences = scanCollabTicketReferences;
+const CollabConstants_1 = require("./CollabConstants");
+const CollabMarkdownProse_1 = require("./CollabMarkdownProse");
+const CLOSING_KEYWORD_PATTERN = /(?:^|[^A-Za-z])(close|closes|closed|fix|fixes|fixed|resolve|resolves|resolved)[ \t]*:?[ \t]*$/i;
+const TICKET_REFERENCE_PATTERN = /(^|[^#0-9A-Za-z_])#([1-9][0-9]*)(?![#0-9A-Za-z_])/gm;
+function relationKindBefore(maskedDescription, referenceOffset) {
+    const prefix = maskedDescription.slice(0, referenceOffset);
+    return CLOSING_KEYWORD_PATTERN.test(prefix) ? 'resolves' : 'references';
+}
+function parseCollabTicketReferences(description) {
+    if (new TextEncoder().encode(description).byteLength >
+        CollabConstants_1.COLLAB_LIMITS.maxRequestDescriptionBytes) {
+        return { status: 'invalid', reason: 'description-too-large' };
+    }
+    const scanned = scanCollabTicketReferences(description);
+    if (scanned.status === 'invalid')
+        return scanned;
+    const references = new Map();
+    for (const token of scanned.tokens) {
+        const existing = references.get(token.ticketNumber);
+        if (existing !== 'resolves' || token.kind === 'resolves') {
+            references.set(token.ticketNumber, token.kind);
+        }
+    }
+    return {
+        status: 'ok',
+        references: [...references.entries()]
+            .sort(([left], [right]) => left - right)
+            .map(([ticketNumber, kind]) => ({ ticketNumber, kind })),
+    };
+}
+function scanCollabTicketReferences(description) {
+    const prose = (0, CollabMarkdownProse_1.maskCollabMarkdownProse)(description);
+    const tokens = [];
+    for (const match of prose.matchAll(TICKET_REFERENCE_PATTERN)) {
+        const prefix = match[1] ?? '';
+        const numberToken = match[2];
+        if (!numberToken || match.index === undefined)
+            continue;
+        const ticketNumber = Number(numberToken);
+        if (!Number.isSafeInteger(ticketNumber)) {
+            return { status: 'invalid', reason: 'ticket-number-out-of-range' };
+        }
+        const referenceOffset = match.index + prefix.length;
+        tokens.push({
+            from: referenceOffset,
+            kind: relationKindBefore(prose, referenceOffset),
+            ticketNumber,
+            to: referenceOffset + numberToken.length + 1,
+        });
+    }
+    return { status: 'ok', tokens };
+}

package/dist/CollabValidation.d.ts

@@ -0,0 +1,5 @@
+export declare function isCollabProjectId(value: unknown): value is string;
+export declare function isCollabMemberId(value: unknown): value is string;
+export declare function isCollabOpaqueId(value: unknown): value is string;
+export declare function isCollabGitOid(value: unknown): value is string;
+export declare function hasUtf8ByteLengthAtMost(value: string, maximum: number): boolean;

package/dist/CollabValidation.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCollabProjectId = isCollabProjectId;
+exports.isCollabMemberId = isCollabMemberId;
+exports.isCollabOpaqueId = isCollabOpaqueId;
+exports.isCollabGitOid = isCollabGitOid;
+exports.hasUtf8ByteLengthAtMost = hasUtf8ByteLengthAtMost;
+const COLLAB_PROJECT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const COLLAB_MEMBER_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const COLLAB_OPAQUE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+const COLLAB_GIT_OID_PATTERN = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
+function isCollabProjectId(value) {
+    return typeof value === 'string' && COLLAB_PROJECT_ID_PATTERN.test(value);
+}
+function isCollabMemberId(value) {
+    return typeof value === 'string' && COLLAB_MEMBER_ID_PATTERN.test(value);
+}
+function isCollabOpaqueId(value) {
+    return typeof value === 'string' && COLLAB_OPAQUE_ID_PATTERN.test(value);
+}
+function isCollabGitOid(value) {
+    return typeof value === 'string' && COLLAB_GIT_OID_PATTERN.test(value);
+}
+function hasUtf8ByteLengthAtMost(value, maximum) {
+    return new TextEncoder().encode(value).byteLength <= maximum;
+}

package/dist/DevelopmentBootstrap.d.ts

@@ -0,0 +1,199 @@
+import { COLLAB_MAIN_REF, type CollabProtocolVersion } from './CollabConstants';
+import { type DevelopmentBootstrapOperation } from './CollabCloudBinding';
+import type { CollabDecodeResult } from './CollabProtocol';
+import type { CollabGitOid, CollabIsoTimestamp, CollabMemberId, CollabOperationId, CollabProjectId, CollabRole } from './types';
+export declare const DEVELOPMENT_BOOTSTRAP_MANIFEST_SCHEMA_VERSION: 1;
+export declare const DEVELOPMENT_BOOTSTRAP_ATTEMPT_STATES: readonly ["collecting", "validating", "ready", "activating", "rejected", "cancelled", "recovery-required", "activated"];
+export declare const DEVELOPMENT_BOOTSTRAP_ACTIVATION_PHASES: readonly ["publish-intent", "repository-published", "activated", "completed"];
+export declare const DEVELOPMENT_BOOTSTRAP_CANCELLATION_PHASES: readonly ["cancel-intent", "cancelled", "recovery-required"];
+export declare const DEVELOPMENT_BOOTSTRAP_OPERATIONS: readonly ["beginDevelopmentBootstrap", "submitDevelopmentBootstrapReport", "getDevelopmentBootstrap", "activateDevelopmentBootstrap", "cancelDevelopmentBootstrap", "putDevelopmentBootstrapGitBundle"];
+export type DevelopmentBootstrapAttemptState = typeof DEVELOPMENT_BOOTSTRAP_ATTEMPT_STATES[number];
+export type DevelopmentBootstrapActivationPhase = typeof DEVELOPMENT_BOOTSTRAP_ACTIVATION_PHASES[number];
+export type DevelopmentBootstrapCancellationPhase = typeof DEVELOPMENT_BOOTSTRAP_CANCELLATION_PHASES[number];
+export type DevelopmentBootstrapBundleState = 'missing' | 'uploaded' | 'validated';
+export type DevelopmentBootstrapObjectFormat = 'sha1' | 'sha256';
+export interface DevelopmentBootstrapComparisonMember {
+    readonly activatedAt: CollabIsoTimestamp;
+    readonly createdAt: CollabIsoTimestamp;
+    readonly displayName: string;
+    readonly memberId: CollabMemberId;
+    readonly personalRef: string;
+    readonly role: CollabRole;
+    readonly status: 'active';
+}
+export interface DevelopmentBootstrapComparison {
+    readonly mainOid: CollabGitOid;
+    readonly mainRef: typeof COLLAB_MAIN_REF;
+    readonly managerSetGeneration: number;
+    readonly members: readonly [
+        DevelopmentBootstrapComparisonMember,
+        DevelopmentBootstrapComparisonMember
+    ];
+    readonly projectCreatedAt: CollabIsoTimestamp;
+    readonly projectId: CollabProjectId;
+    readonly projectName: string;
+    readonly sourceCaFingerprint: string;
+    readonly sourceEventSequence: number;
+    readonly sourceHostMemberId: CollabMemberId;
+}
+export interface DevelopmentBootstrapSourceEligibility {
+    readonly liveInvitations: 0;
+    readonly nonActiveMemberships: 0;
+    readonly nonterminalAcceptOperations: 0;
+    readonly nonterminalHostTransfers: 0;
+    readonly nonterminalManagerOffers: 0;
+    readonly requestComments: 0;
+    readonly requests: 0;
+    readonly terminalProjectTransitions: 0;
+    readonly ticketComments: 0;
+    readonly ticketMentions: 0;
+    readonly ticketRelations: 0;
+    readonly tickets: 0;
+}
+export interface DevelopmentBootstrapGitRef {
+    readonly name: string;
+    readonly oid: CollabGitOid;
+}
+export interface DevelopmentBootstrapManifest {
+    readonly attemptId: string;
+    readonly comparison: DevelopmentBootstrapComparison;
+    readonly createdAt: CollabIsoTimestamp;
+    readonly git: {
+        readonly bundle: {
+            readonly byteCount: number;
+            readonly sha256: string;
+        };
+        readonly objectFormat: DevelopmentBootstrapObjectFormat;
+        readonly refs: readonly DevelopmentBootstrapGitRef[];
+    };
+    readonly manifestSchemaVersion: typeof DEVELOPMENT_BOOTSTRAP_MANIFEST_SCHEMA_VERSION;
+    readonly protocolVersion: CollabProtocolVersion;
+    readonly sourceEligibility: DevelopmentBootstrapSourceEligibility;
+}
+export interface DevelopmentBootstrapClientReadiness {
+    readonly cleanupSettled: true;
+    readonly collabGitChildrenDrained: true;
+    readonly conflictRecoverySettled: true;
+    readonly hostTransferSettled: true;
+    readonly joinSettled: true;
+    readonly leaveSettled: true;
+    readonly managerResponsibilitySettled: true;
+    readonly projectOperationQueueDrained: true;
+    readonly projectSetupSettled: true;
+    readonly projectWorkSessionClosed: true;
+    readonly publishSettled: true;
+    readonly reconciliationSettled: true;
+    readonly reconnectSettled: true;
+    readonly repositoryIdentityExact: true;
+    readonly retirementSettled: true;
+}
+export interface DevelopmentHostStopAttestation {
+    readonly attemptId: string;
+    readonly autoStartDisabled: true;
+    readonly fenceDurable: true;
+    readonly fenceId: string;
+    readonly hostStopped: true;
+    readonly manifestSha256: string;
+    readonly projectId: CollabProjectId;
+    readonly resourcesDrained: true;
+    readonly routeUnregistered: true;
+    readonly stoppedAt: CollabIsoTimestamp;
+}
+export interface DevelopmentBootstrapReport {
+    readonly attemptId: string;
+    readonly capturedAt: CollabIsoTimestamp;
+    readonly clientReadiness: DevelopmentBootstrapClientReadiness;
+    readonly comparison: DevelopmentBootstrapComparison;
+    readonly hostStopAttestation?: DevelopmentHostStopAttestation;
+    readonly observedPersonalRefOid: CollabGitOid;
+    readonly reporterMemberId: CollabMemberId;
+}
+export interface DevelopmentBootstrapActivationResult {
+    readonly activatedAt: CollabIsoTimestamp;
+    readonly activationOperationId: CollabOperationId;
+    readonly placementGeneration: number;
+    readonly projectId: CollabProjectId;
+}
+export interface DevelopmentBootstrapAttemptStatus {
+    readonly activationPhase?: DevelopmentBootstrapActivationPhase;
+    readonly activationResult?: DevelopmentBootstrapActivationResult;
+    readonly attemptId: string;
+    readonly bundleState: DevelopmentBootstrapBundleState;
+    readonly cancellationPhase?: DevelopmentBootstrapCancellationPhase;
+    readonly createdAt: CollabIsoTimestamp;
+    readonly expiresAt: CollabIsoTimestamp;
+    readonly manifestSha256: string;
+    readonly projectId: CollabProjectId;
+    readonly reporterMemberIds: readonly CollabMemberId[];
+    readonly state: DevelopmentBootstrapAttemptState;
+}
+export interface BeginDevelopmentBootstrapRequest {
+    readonly manifest: DevelopmentBootstrapManifest;
+}
+export interface SubmitDevelopmentBootstrapReportRequest {
+    readonly attemptId: string;
+    readonly report: DevelopmentBootstrapReport;
+}
+export interface GetDevelopmentBootstrapRequest {
+    readonly attemptId: string;
+}
+export interface ActivateDevelopmentBootstrapRequest {
+    readonly attemptId: string;
+    readonly manifestSha256: string;
+}
+export interface CancelDevelopmentBootstrapRequest {
+    readonly attemptId: string;
+}
+export interface PutDevelopmentBootstrapGitBundleRequest {
+    readonly attemptId: string;
+    readonly byteCount: number;
+    readonly contentEncoding: 'identity';
+    readonly contentType: 'application/x-git-bundle';
+    readonly sha256: string;
+}
+export interface DevelopmentBootstrapOperationMap {
+    readonly activateDevelopmentBootstrap: {
+        readonly request: ActivateDevelopmentBootstrapRequest;
+        readonly response: DevelopmentBootstrapAttemptStatus;
+    };
+    readonly beginDevelopmentBootstrap: {
+        readonly request: BeginDevelopmentBootstrapRequest;
+        readonly response: DevelopmentBootstrapAttemptStatus;
+    };
+    readonly cancelDevelopmentBootstrap: {
+        readonly request: CancelDevelopmentBootstrapRequest;
+        readonly response: DevelopmentBootstrapAttemptStatus;
+    };
+    readonly getDevelopmentBootstrap: {
+        readonly request: GetDevelopmentBootstrapRequest;
+        readonly response: DevelopmentBootstrapAttemptStatus;
+    };
+    readonly putDevelopmentBootstrapGitBundle: {
+        readonly request: PutDevelopmentBootstrapGitBundleRequest;
+        readonly response: DevelopmentBootstrapAttemptStatus;
+    };
+    readonly submitDevelopmentBootstrapReport: {
+        readonly request: SubmitDevelopmentBootstrapReportRequest;
+        readonly response: DevelopmentBootstrapAttemptStatus;
+    };
+}
+export interface DevelopmentBootstrapOperationCodec<Request, Response> {
+    readonly decodeRequest: (value: unknown) => CollabDecodeResult<Request>;
+    readonly decodeResponse: (value: unknown) => Response;
+}
+type DevelopmentBootstrapCodecMap = {
+    readonly [Operation in DevelopmentBootstrapOperation]: DevelopmentBootstrapOperationCodec<DevelopmentBootstrapOperationMap[Operation]['request'], DevelopmentBootstrapOperationMap[Operation]['response']>;
+};
+export declare function decodeDevelopmentBootstrapManifest(value: unknown): DevelopmentBootstrapManifest;
+export declare function encodeDevelopmentBootstrapManifestCanonicalJson(value: DevelopmentBootstrapManifest): string;
+export declare function decodeDevelopmentBootstrapReport(value: unknown): DevelopmentBootstrapReport;
+export declare const DEVELOPMENT_BOOTSTRAP_OPERATION_CODECS: Readonly<{
+    readonly beginDevelopmentBootstrap: DevelopmentBootstrapOperationCodec<BeginDevelopmentBootstrapRequest, DevelopmentBootstrapAttemptStatus>;
+    readonly submitDevelopmentBootstrapReport: DevelopmentBootstrapOperationCodec<SubmitDevelopmentBootstrapReportRequest, DevelopmentBootstrapAttemptStatus>;
+    readonly getDevelopmentBootstrap: DevelopmentBootstrapOperationCodec<GetDevelopmentBootstrapRequest, DevelopmentBootstrapAttemptStatus>;
+    readonly activateDevelopmentBootstrap: DevelopmentBootstrapOperationCodec<ActivateDevelopmentBootstrapRequest, DevelopmentBootstrapAttemptStatus>;
+    readonly cancelDevelopmentBootstrap: DevelopmentBootstrapOperationCodec<CancelDevelopmentBootstrapRequest, DevelopmentBootstrapAttemptStatus>;
+    readonly putDevelopmentBootstrapGitBundle: DevelopmentBootstrapOperationCodec<PutDevelopmentBootstrapGitBundleRequest, DevelopmentBootstrapAttemptStatus>;
+}>;
+export declare function developmentBootstrapOperationCodec<Operation extends DevelopmentBootstrapOperation>(operation: Operation): DevelopmentBootstrapCodecMap[Operation];
+export {};