@unson/brainbase-mcp 0.6.0 → 0.7.0

package/dist/canonical-task-contract.d.ts

@@ -0,0 +1,9 @@
+export declare const CANONICAL_TASK_STATUSES: readonly ["pending", "in_progress", "waiting", "completed", "cancelled"];
+export type CanonicalTaskStatus = typeof CANONICAL_TASK_STATUSES[number];
+export declare const CANONICAL_TASK_PRIORITIES: readonly ["low", "medium", "high", "urgent"];
+export type CanonicalTaskPriority = typeof CANONICAL_TASK_PRIORITIES[number];
+export declare function isCanonicalTaskStatus(value: unknown): value is CanonicalTaskStatus;
+export declare function isCanonicalTaskPriority(value: unknown): value is CanonicalTaskPriority;
+export declare function normalizeCanonicalTaskProjectCodes(value: unknown): string[];
+export declare function hasInvalidCanonicalTaskProjectCode(value: unknown): boolean;
+export declare function canTransitionCanonicalTaskStatus(from: unknown, to: unknown): boolean;

package/dist/canonical-task-contract.js

@@ -0,0 +1,39 @@
+export const CANONICAL_TASK_STATUSES = [
+    'pending',
+    'in_progress',
+    'waiting',
+    'completed',
+    'cancelled',
+];
+export const CANONICAL_TASK_PRIORITIES = ['low', 'medium', 'high', 'urgent'];
+const STATUS_SET = new Set(CANONICAL_TASK_STATUSES);
+const PRIORITY_SET = new Set(CANONICAL_TASK_PRIORITIES);
+const TRANSITIONS = Object.freeze({
+    pending: new Set(['in_progress', 'waiting', 'completed', 'cancelled']),
+    in_progress: new Set(['waiting', 'completed', 'cancelled']),
+    waiting: new Set(['in_progress', 'completed', 'cancelled']),
+    completed: new Set(),
+    cancelled: new Set(['pending']),
+});
+export function isCanonicalTaskStatus(value) {
+    return typeof value === 'string' && STATUS_SET.has(value);
+}
+export function isCanonicalTaskPriority(value) {
+    return typeof value === 'string' && PRIORITY_SET.has(value);
+}
+export function normalizeCanonicalTaskProjectCodes(value) {
+    const values = Array.isArray(value) ? value : (value == null ? [] : [value]);
+    return [...new Set(values.flatMap((item) => String(item).split(','))
+            .map((item) => item.trim())
+            .filter(Boolean))];
+}
+export function hasInvalidCanonicalTaskProjectCode(value) {
+    const values = Array.isArray(value) ? value : (value == null ? [] : [value]);
+    return values.some((item) => typeof item !== 'string'
+        || item.split(',').some((code) => !code.trim() || code.trim().length > 100));
+}
+export function canTransitionCanonicalTaskStatus(from, to) {
+    return isCanonicalTaskStatus(from)
+        && isCanonicalTaskStatus(to)
+        && TRANSITIONS[from].has(to);
+}

package/dist/canonical-task-principal.d.ts

@@ -0,0 +1,16 @@
+export type CanonicalTaskPrincipalType = 'person' | 'service' | 'internal';
+export type CanonicalTaskPrincipal = Readonly<{
+    type: CanonicalTaskPrincipalType;
+    id: string;
+}>;
+export declare function normalizeCanonicalTaskPrincipal(principal: {
+    type?: unknown;
+    id?: unknown;
+} | null | undefined): CanonicalTaskPrincipal;
+export declare function createCanonicalTaskPrincipal({ authSource, personId, serviceId, internalId, }?: {
+    authSource?: string;
+    personId?: string;
+    serviceId?: string;
+    internalId?: string;
+}): CanonicalTaskPrincipal;
+export declare function principalNamespace(principal: CanonicalTaskPrincipal): string;

package/dist/canonical-task-principal.js

@@ -0,0 +1,36 @@
+const ALLOWED_TYPES = new Set(['person', 'service', 'internal']);
+const TRUSTED_AUTH_SOURCES = new Set(['bearer', 'service-token', 'internal']);
+function normalizePart(value, label) {
+    const normalized = String(value || '').normalize('NFC');
+    if (!normalized)
+        throw new Error(`Canonical Task principal ${label} is required`);
+    if (/\p{Cc}/u.test(normalized))
+        throw new Error(`Canonical Task principal ${label} contains control characters`);
+    return normalized;
+}
+export function normalizeCanonicalTaskPrincipal(principal) {
+    const type = String(principal?.type || '').toLowerCase();
+    if (!ALLOWED_TYPES.has(type))
+        throw new Error('Canonical Task principal type is invalid');
+    return Object.freeze({ type, id: normalizePart(principal?.id, 'id') });
+}
+export function createCanonicalTaskPrincipal({ authSource, personId, serviceId, internalId, } = {}) {
+    if (personId && ['bearer', 'session'].includes(authSource ?? '')) {
+        return normalizeCanonicalTaskPrincipal({ type: 'person', id: personId });
+    }
+    if (!TRUSTED_AUTH_SOURCES.has(authSource ?? '')) {
+        throw new Error('Canonical Task principal requires trusted authentication');
+    }
+    if (authSource === 'service-token') {
+        return normalizeCanonicalTaskPrincipal({ type: 'service', id: serviceId });
+    }
+    if (authSource === 'internal') {
+        return normalizeCanonicalTaskPrincipal({ type: 'internal', id: internalId });
+    }
+    return normalizeCanonicalTaskPrincipal({ type: 'person', id: personId });
+}
+export function principalNamespace(principal) {
+    const normalized = normalizeCanonicalTaskPrincipal(principal);
+    const payload = JSON.stringify({ type: normalized.type, id: normalized.id });
+    return `v1.${Buffer.from(payload, 'utf8').toString('base64url')}`;
+}

package/dist/canonical-task-service.d.ts

@@ -0,0 +1,251 @@
+import { type CanonicalTaskPriority, type CanonicalTaskStatus } from './canonical-task-contract.js';
+import { type CanonicalTaskPrincipal } from './canonical-task-principal.js';
+type JsonRecord = Record<string, unknown>;
+export type CanonicalTaskAction = 'list' | 'search' | 'read' | 'create' | 'update' | 'transition' | 'delete';
+export type CanonicalTaskAuditAction = 'canonical_task.created' | 'canonical_task.updated' | 'canonical_task.transitioned' | 'canonical_task.deleted';
+export interface CanonicalTaskContext extends JsonRecord {
+    principal: CanonicalTaskPrincipal;
+    authSource?: string | null;
+    auditPrincipal?: CanonicalTaskPrincipal | null;
+    auditAuthSource?: string | null;
+    idempotencyKey?: string | null;
+}
+export interface CanonicalTaskRecord extends JsonRecord {
+    id: string;
+    version: number;
+    title: string;
+    description?: string | null;
+    status: CanonicalTaskStatus;
+    priority: CanonicalTaskPriority;
+    assignee_person_id?: string | null;
+    assignee_display_name?: string | null;
+    due_at?: string | null;
+    waiting_on?: string | null;
+    review_at?: string | null;
+    completed_at?: string | null;
+    source_refs?: unknown[];
+    project_codes?: string[];
+    created_at?: string | null;
+    updated_at?: string | null;
+    web_url?: string | null;
+}
+export interface CanonicalTaskCreateInput extends JsonRecord {
+    title: string;
+    description?: string | null;
+    priority?: CanonicalTaskPriority | string | null;
+    assignee_person_id?: string | null;
+    due_at?: string | null;
+    waiting_on?: string | null;
+    review_at?: string | null;
+    source_refs?: unknown[];
+    project_codes?: unknown;
+}
+export interface CanonicalTaskUpdateInput extends JsonRecord {
+    title?: string;
+    description?: string | null;
+    priority?: CanonicalTaskPriority | string | null;
+    assignee_person_id?: string | null;
+    due_at?: string | null;
+    waiting_on?: string | null;
+    review_at?: string | null;
+    source_refs?: unknown[];
+    project_codes?: unknown;
+}
+export interface CanonicalTaskListFilters extends JsonRecord {
+    statuses?: unknown;
+    status?: unknown;
+    priorities?: unknown;
+    priority?: unknown;
+    projectCodes?: unknown;
+    projectCode?: unknown;
+    project_code?: unknown;
+    assigneePersonId?: string | null;
+    dueAfter?: string | null;
+    dueBefore?: string | null;
+    limit?: number | string | null;
+    cursor?: string | null;
+}
+export interface CanonicalTaskSearchFilters extends CanonicalTaskListFilters {
+    q?: string | null;
+    query?: string | null;
+}
+export interface CanonicalTaskPage {
+    items: CanonicalTaskRecord[];
+    totalCount?: number | null;
+    countStatus?: string | null;
+    nextCursor?: string | null;
+    readStatus?: string | null;
+    total_count?: number | null;
+    count_status?: string | null;
+    next_cursor?: string | null;
+    read_status?: string | null;
+    has_more?: boolean;
+    as_of?: string;
+    warnings?: string[];
+    [key: string]: unknown;
+}
+export interface CanonicalTaskSearchPage extends CanonicalTaskPage {
+    query: string;
+}
+export interface CanonicalTaskAuditEntry extends JsonRecord {
+    id: string;
+    actor: CanonicalTaskPrincipal;
+    actor_id: string;
+    actor_type: CanonicalTaskPrincipal['type'];
+    actor_principal: CanonicalTaskPrincipal;
+    actor_namespace: string;
+    auth_source: string | null;
+    action: CanonicalTaskAuditAction;
+    target_type: 'canonical_task';
+    target_id: string;
+    changes: JsonRecord;
+    source_refs: unknown[];
+}
+export interface CanonicalTaskRepository {
+    list(filters: CanonicalTaskListFilters): Promise<CanonicalTaskPage>;
+    search(filters: CanonicalTaskSearchFilters): Promise<CanonicalTaskPage>;
+    get(taskId: string): Promise<CanonicalTaskRecord | null>;
+    findByIdempotencyKey(key: string): Promise<CanonicalTaskRecord | null>;
+    create(input: JsonRecord): Promise<CanonicalTaskRecord>;
+    update(taskId: string, patch: JsonRecord): Promise<CanonicalTaskRecord>;
+    delete(taskId: string, expectedVersion: number): Promise<void>;
+}
+export interface CanonicalTaskAuditRepository {
+    upsertAuditLog(entry: CanonicalTaskAuditEntry): Promise<void>;
+}
+export interface CanonicalTaskAuthorizationRequest {
+    action: CanonicalTaskAction;
+    context: CanonicalTaskContext;
+    task?: CanonicalTaskRecord | null;
+    input?: unknown;
+}
+export interface CanonicalTaskPolicy {
+    normalizeContext?(context: CanonicalTaskContext): CanonicalTaskContext | Promise<CanonicalTaskContext>;
+    authorize(request: CanonicalTaskAuthorizationRequest): void | Promise<void>;
+    scopeFilters?(input: {
+        operation: 'list' | 'search';
+        context: CanonicalTaskContext;
+        filters: CanonicalTaskListFilters | CanonicalTaskSearchFilters;
+    }): Partial<CanonicalTaskListFilters | CanonicalTaskSearchFilters> | void | Promise<Partial<CanonicalTaskListFilters | CanonicalTaskSearchFilters> | void>;
+}
+export type CanonicalTaskClock = () => Date;
+export type CanonicalTaskBaseUrl = string | (() => string | null | undefined);
+export interface CanonicalTaskOperationRequest<T> {
+    scope: string;
+    operationKey: string;
+    fingerprint: string;
+    /**
+     * Persist only the stable reference needed to resume an operation. The
+     * coordinator must not need to serialize the complete Task payload.
+     */
+    projectResult?: (result: T) => unknown;
+    /**
+     * Inspect durable state after a caller or coordinator restart. A recovery
+     * result is deliberately explicit so a missing record is not mistaken for
+     * a successful replay.
+     */
+    recover?: () => Promise<CanonicalTaskOperationRecovery<T>>;
+    run: () => Promise<T>;
+}
+export interface CanonicalTaskOperationRecovery<T> {
+    recovered: boolean;
+    result?: T;
+}
+export interface CanonicalTaskPreparedDeleteRequest<T> {
+    scope?: string;
+    operationKey: string;
+    fingerprint: string;
+    /** Fingerprint for the task-version claim paired with the delete intent. */
+    versionFingerprint: string;
+    versionClaimKey: string;
+    principalNamespace: string;
+    prepare: () => Promise<{
+        result: T;
+        task?: CanonicalTaskRecord | null;
+        authorizationSnapshot?: JsonRecord;
+    }>;
+    findTask: () => Promise<CanonicalTaskRecord | null>;
+    removeTask: (task?: CanonicalTaskRecord) => Promise<void>;
+    projectResult?: (result: T) => unknown;
+    recover?: () => Promise<CanonicalTaskOperationRecovery<T>>;
+}
+export interface CanonicalTaskOperationRepository {
+    execute<T>(request: CanonicalTaskOperationRequest<T>): Promise<T>;
+    executePreparedDelete?<T>(request: CanonicalTaskPreparedDeleteRequest<T>): Promise<T>;
+}
+export interface CanonicalTaskServiceOptions {
+    repository: CanonicalTaskRepository;
+    auditRepository?: CanonicalTaskAuditRepository;
+    policy?: CanonicalTaskPolicy;
+    operationRepository?: CanonicalTaskOperationRepository;
+    clock?: CanonicalTaskClock;
+    baseUrl?: CanonicalTaskBaseUrl;
+}
+export declare class CanonicalTaskError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details: JsonRecord;
+    readonly fieldErrors: Record<string, string[]>;
+    readonly currentTask?: CanonicalTaskRecord;
+    constructor(code: string, message: string, status?: number, details?: JsonRecord, options?: {
+        fieldErrors?: Record<string, string[]>;
+        currentTask?: CanonicalTaskRecord;
+    });
+}
+export declare class CanonicalTaskService {
+    private readonly repository;
+    private readonly auditRepository?;
+    private readonly policy;
+    private readonly operationRepository?;
+    private readonly clock;
+    private readonly baseUrl?;
+    constructor(options: CanonicalTaskServiceOptions);
+    listTasks(filters: CanonicalTaskListFilters | undefined, context: CanonicalTaskContext): Promise<CanonicalTaskPage>;
+    searchTasks(filters: CanonicalTaskSearchFilters | undefined, context: CanonicalTaskContext): Promise<CanonicalTaskSearchPage>;
+    getTask(taskId: string, context: CanonicalTaskContext): Promise<CanonicalTaskRecord>;
+    createTask(input: CanonicalTaskCreateInput, context: CanonicalTaskContext): Promise<CanonicalTaskRecord>;
+    updateTask(taskId: string, input: CanonicalTaskUpdateInput & {
+        expected_version?: number;
+    }, expectedVersion: number, context: CanonicalTaskContext): Promise<CanonicalTaskRecord>;
+    updateTask(taskId: string, input: CanonicalTaskUpdateInput & {
+        expected_version?: number;
+    }, context: CanonicalTaskContext): Promise<CanonicalTaskRecord>;
+    transitionTask(taskId: string, status: unknown, expectedVersion: number, context: CanonicalTaskContext, input?: {
+        waitingOn?: unknown;
+        reviewAt?: unknown;
+    }): Promise<CanonicalTaskRecord>;
+    transitionTask(taskId: string, input: {
+        to_status?: unknown;
+        expected_version?: number;
+        waiting_on?: unknown;
+        review_at?: unknown;
+    }, context: CanonicalTaskContext): Promise<CanonicalTaskRecord>;
+    deleteTask(taskId: string, expectedVersion: number, context: CanonicalTaskContext): Promise<{
+        task_id: string;
+        deleted: true;
+        version: number;
+    }>;
+    deleteTask(taskId: string, input: {
+        expected_version?: number;
+    }, context: CanonicalTaskContext): Promise<{
+        task_id: string;
+        deleted: true;
+        version: number;
+    }>;
+    private versionedMutation;
+    private normalizeCreateInput;
+    private normalizeUpdateInput;
+    private normalizeListFilters;
+    private normalizeSearchFilters;
+    private normalizeContext;
+    private authorize;
+    private scopeFilters;
+    private requireIdempotencyKey;
+    private requireExpectedVersion;
+    private assertVersion;
+    private executeOperation;
+    private audit;
+    private read;
+    private normalizeResponse;
+}
+export {};