@nocobase/app-plugin-projects 0.0.0-stage → 0.1.0-beta.10

package/dist/server/kernel/tx.js

@@ -0,0 +1,109 @@
+/**
+ * Units of work. A transaction collects the domain events its writes emit and publishes them only after it commits, so
+ * a listener never sees a change that was rolled back.
+ *
+ * Hooks registered with `beforeCommit` see those events while the transaction is still open and may write in it: what
+ * they write commits or rolls back with the change that caused it (the inbox, for example, turns events into items
+ * this way). Events a hook emits are handed to the hooks again, for a bounded number of rounds.
+ *
+ * A unit (`unit`) makes every service call inside it join one transaction without passing it along: the plan engine
+ * runs several services' writes as one change that commits or rolls back together. Inside a unit, `run` without
+ * `outer` joins the unit (or the savepoint `savepoint` opened), and `read` answers its connection. A rehearsing unit
+ * (`rehearse: true`) always rolls back, drops the events its writes emit, runs no commit hooks, and says so on its
+ * `Tx` (`rehearsal`), so a trigger can answer what it would start without queuing anything.
+ *
+ * Thin stand-in: the database layer's `transaction()` has no commit hooks of its own. Use them once it does.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** Thrown inside a rehearsing unit to roll it back. */
+class Rollback extends Error {
+    value;
+    constructor(value) {
+        super('Rehearsal rolled back.');
+        this.value = value;
+    }
+}
+const MAX_HOOK_ROUNDS = 5;
+export function createTxRunner(database, bus) {
+    const hooks = new Set();
+    // The unit (or its savepoint) the current call runs in, if any.
+    const ambient = new AsyncLocalStorage();
+    async function runHooks(tx, pending) {
+        let handled = 0;
+        for (let round = 0; hooks.size > 0 && handled < pending.length && round < MAX_HOOK_ROUNDS; round += 1) {
+            const batch = pending.slice(handled);
+            handled = pending.length;
+            for (const hook of hooks)
+                await hook(tx, batch);
+        }
+    }
+    return {
+        async run(fn, outer) {
+            if (outer)
+                return fn(outer);
+            const joined = ambient.getStore();
+            if (joined)
+                return fn(joined);
+            const pending = [];
+            const result = await database.transaction(async (conn) => {
+                const tx = { conn, emit: (event) => pending.push(event) };
+                const value = await fn(tx);
+                await runHooks(tx, pending);
+                return value;
+            });
+            for (const event of pending)
+                bus.emit(event);
+            return result;
+        },
+        read: () => ambient.getStore()?.conn ?? database.connection(),
+        beforeCommit(hook) {
+            hooks.add(hook);
+            return () => {
+                hooks.delete(hook);
+            };
+        },
+        async unit(fn, options = {}) {
+            if (ambient.getStore())
+                throw new Error('Units of work do not nest.');
+            if (options.rehearse) {
+                try {
+                    await database.transaction(async (conn) => {
+                        const tx = { conn, emit: () => undefined, rehearsal: true };
+                        throw new Rollback(await ambient.run(tx, () => fn(tx)));
+                    });
+                }
+                catch (error) {
+                    if (error instanceof Rollback)
+                        return error.value;
+                    throw error;
+                }
+                throw new Error('A rehearsal did not roll back.');
+            }
+            const pending = [];
+            const result = await database.transaction(async (conn) => {
+                const tx = { conn, emit: (event) => pending.push(event) };
+                const value = await ambient.run(tx, () => fn(tx));
+                await runHooks(tx, pending);
+                return value;
+            });
+            for (const event of pending)
+                bus.emit(event);
+            return result;
+        },
+        async savepoint(tx, fn) {
+            const buffered = [];
+            const result = await tx.conn.transaction((conn) => {
+                const inner = {
+                    conn,
+                    emit: (event) => buffered.push(event),
+                    ...(tx.rehearsal ? { rehearsal: true } : {}),
+                };
+                return ambient.run(inner, () => fn(inner));
+            });
+            for (const event of buffered)
+                tx.emit(event);
+            return result;
+        },
+    };
+}
+//# sourceMappingURL=tx.js.map

package/dist/server/kernel/tx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tx.js","sourceRoot":"","sources":["../../../server/kernel/tx.ts"],"names":[],"mappings":"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"}

package/dist/server/kernel/users.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The accounts of the authentication plugin, as this plugin needs them: display names and existence.
+ *
+ * Thin stand-in: the authentication plugin's `UserAdministrationService` reads one user at a time, so batches read its
+ * `user` collection directly. Keep every such read in this file.
+ */
+import type { DatabaseConnection } from '@nocobase/db';
+export interface UserSummary {
+    readonly id: string;
+    readonly name: string;
+    readonly email: string | null;
+}
+/** A service account, the identity of an organization's API key, as the actor display names it. */
+export interface ApiKeyActorSummary {
+    readonly id: string;
+    readonly name: string;
+    readonly disabled: boolean;
+}
+export interface UserDirectory {
+    /** Display names by id; unknown ids are left out. */
+    names(conn: DatabaseConnection, ids: Iterable<string | null | undefined>): Promise<Map<string, string>>;
+    /** One account, active or not; undefined when it does not exist. */
+    find(conn: DatabaseConnection, id: string): Promise<(UserSummary & {
+        readonly active: boolean;
+    }) | undefined>;
+    /** An account that exists and is neither disabled nor deleted. */
+    isActive(conn: DatabaseConnection, id: string): Promise<boolean>;
+    /** Account ids by address; addresses are compared lower-cased, as the authentication plugin stores them. */
+    idsByEmail(conn: DatabaseConnection, emails: readonly string[]): Promise<Map<string, string>>;
+    /** Every active person, by name: service accounts are not people and are never offered in a picker. */
+    listActive(conn: DatabaseConnection): Promise<UserSummary[]>;
+    /** An active account that is a person, not a service account: someone who may be admitted, own or be notified. */
+    isPerson(conn: DatabaseConnection, id: string): Promise<boolean>;
+    /** Of `ids`, the ones that are people (not service accounts), in any state. */
+    people(conn: DatabaseConnection, ids: Iterable<string | null | undefined>): Promise<Set<string>>;
+    /** Every service account (an API key identity), deleted ones included, by name. */
+    apiKeyActors(conn: DatabaseConnection): Promise<ApiKeyActorSummary[]>;
+}
+export declare function createUserDirectory(): UserDirectory;
+//# sourceMappingURL=users.d.ts.map

package/dist/server/kernel/users.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../../server/kernel/users.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAMvD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAaD,mGAAmG;AACnG,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAYD,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,KAAK,CACH,IAAI,EAAE,kBAAkB,EACxB,GAAG,EAAE,QAAQ,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,GACvC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChC,oEAAoE;IACpE,IAAI,CACF,IAAI,EAAE,kBAAkB,EACxB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,CAAC,WAAW,GAAG;QAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC,GAAG,SAAS,CAAC,CAAC;IACrE,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE,4GAA4G;IAC5G,UAAU,CACR,IAAI,EAAE,kBAAkB,EACxB,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChC,uGAAuG;IACvG,UAAU,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC7D,kHAAkH;IAClH,QAAQ,CAAC,IAAI,EAAE,kBAAkB,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE,+EAA+E;IAC/E,MAAM,CACJ,IAAI,EAAE,kBAAkB,EACxB,GAAG,EAAE,QAAQ,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,GACvC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACxB,mFAAmF;IACnF,YAAY,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;CACvE;AAED,wBAAgB,mBAAmB,IAAI,aAAa,CAyEnD"}

package/dist/server/kernel/users.js

@@ -0,0 +1,84 @@
+import { oneOf, unique } from './db.js';
+const USERS = 'user';
+const isService = (row) => row.kind === 'service';
+function summaryOf(row) {
+    return {
+        id: row.id,
+        name: row.name || row.username || row.email || row.id,
+        email: row.email,
+    };
+}
+export function createUserDirectory() {
+    const users = (conn) => conn.repository(USERS);
+    const find = async (conn, id) => {
+        const row = await users(conn).findOne({ filter: { id } });
+        return row
+            ? { ...summaryOf(row), active: !row.disabledAt && !row.deletedAt }
+            : undefined;
+    };
+    return {
+        async names(conn, ids) {
+            const wanted = unique(ids);
+            if (wanted.length === 0)
+                return new Map();
+            const rows = await users(conn).findMany({
+                filter: (f) => oneOf(f, 'id', wanted),
+            });
+            return new Map(rows.map((row) => [row.id, summaryOf(row).name]));
+        },
+        find,
+        async isActive(conn, id) {
+            return (await find(conn, id))?.active ?? false;
+        },
+        async idsByEmail(conn, emails) {
+            const result = new Map();
+            if (emails.length === 0)
+                return result;
+            const rows = await users(conn).findMany({
+                filter: (f) => oneOf(f, 'email', emails),
+            });
+            for (const row of rows) {
+                const email = row.email?.toLowerCase();
+                if (email && !result.has(email))
+                    result.set(email, row.id);
+            }
+            return result;
+        },
+        async listActive(conn) {
+            const rows = await users(conn).findMany({
+                filter: (f) => f.and([f.date('disabledAt').empty(), f.date('deletedAt').empty()]),
+            });
+            return rows
+                .filter((row) => !isService(row))
+                .map(summaryOf)
+                .sort((a, b) => a.name.localeCompare(b.name));
+        },
+        async isPerson(conn, id) {
+            const row = await users(conn).findOne({ filter: { id } });
+            return Boolean(row && !row.disabledAt && !row.deletedAt && !isService(row));
+        },
+        async people(conn, ids) {
+            const wanted = unique(ids);
+            if (wanted.length === 0)
+                return new Set();
+            const rows = await users(conn).findMany({
+                filter: (f) => oneOf(f, 'id', wanted),
+            });
+            return new Set(rows.filter((row) => !isService(row)).map((row) => row.id));
+        },
+        async apiKeyActors(conn) {
+            // Deleted keys included: what they did keeps their name.
+            const rows = await users(conn).findMany({
+                filter: (f) => f.string('kind').eq('service'),
+            });
+            return rows
+                .map((row) => ({
+                id: row.id,
+                name: summaryOf(row).name,
+                disabled: Boolean(row.disabledAt),
+            }))
+                .sort((a, b) => a.name.localeCompare(b.name));
+        },
+    };
+}
+//# sourceMappingURL=users.js.map

package/dist/server/kernel/users.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"users.js","sourceRoot":"","sources":["../../../server/kernel/users.ts"],"names":[],"mappings":"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"}

package/dist/server/kernel/validate.d.ts

@@ -0,0 +1,14 @@
+/** `YYYY-MM-DD` of a real calendar date; null or `''` clears it. */
+export declare function validDate(value: unknown, field: string): string | null;
+/** A trimmed, non-empty string of at most `maxLength` characters. */
+export declare function requiredText(value: unknown, field: string, maxLength: number, code?: string): string;
+/** A string of at most `maxLength` characters, or null. */
+export declare function optionalText(value: unknown, field: string, maxLength: number): string | null;
+export declare function validBoolean(value: unknown, field: string): boolean;
+/** One of `values`. */
+export declare function validChoice<T extends string>(value: unknown, values: readonly T[], field: string, code?: string): T;
+/** An array of non-empty strings, trimmed and deduplicated in order. */
+export declare function stringList(value: unknown, field: string): string[];
+/** An id-like string, or null. */
+export declare function optionalId(value: unknown, field: string): string | null;
+//# sourceMappingURL=validate.d.ts.map

package/dist/server/kernel/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../server/kernel/validate.ts"],"names":[],"mappings":"AAQA,oEAAoE;AACpE,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQtE;AAED,qEAAqE;AACrE,wBAAgB,YAAY,CAC1B,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,IAAI,SAAkB,GACrB,MAAM,CAQR;AAED,2DAA2D;AAC3D,wBAAgB,YAAY,CAC1B,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAOf;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAInE;AAED,uBAAuB;AACvB,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAC1C,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,SAAS,CAAC,EAAE,EACpB,KAAK,EAAE,MAAM,EACb,IAAI,SAAkB,GACrB,CAAC,CAOH;AAED,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAUlE;AAED,kCAAkC;AAClC,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKvE"}

package/dist/server/kernel/validate.js

@@ -0,0 +1,68 @@
+/**
+ * Validation of request fields. Each helper throws a 400 naming the field; `undefined` means "not provided" and is left
+ * to the caller.
+ */
+import { invalid } from './errors.js';
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/u;
+/** `YYYY-MM-DD` of a real calendar date; null or `''` clears it. */
+export function validDate(value, field) {
+    if (value === null || value === '')
+        return null;
+    if (typeof value !== 'string' || !DATE_PATTERN.test(value))
+        throw invalid('INVALID_DATE', `${field} must be YYYY-MM-DD.`);
+    const date = new Date(`${value}T00:00:00Z`);
+    if (Number.isNaN(date.getTime()) || date.toISOString().slice(0, 10) !== value)
+        throw invalid('INVALID_DATE', `${field} is not a valid date.`);
+    return value;
+}
+/** A trimmed, non-empty string of at most `maxLength` characters. */
+export function requiredText(value, field, maxLength, code = 'INVALID_FIELD') {
+    const text = typeof value === 'string' ? value.trim() : '';
+    if (!text || text.length > maxLength)
+        throw invalid(code, `${field} is required (at most ${maxLength} characters).`);
+    return text;
+}
+/** A string of at most `maxLength` characters, or null. */
+export function optionalText(value, field, maxLength) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value !== 'string')
+        throw invalid('INVALID_FIELD', `${field} must be a string.`);
+    if (value.length > maxLength)
+        throw invalid('INVALID_FIELD', `${field} is too long.`);
+    return value;
+}
+export function validBoolean(value, field) {
+    if (typeof value !== 'boolean')
+        throw invalid('INVALID_FIELD', `${field} must be a boolean.`);
+    return value;
+}
+/** One of `values`. */
+export function validChoice(value, values, field, code = 'INVALID_FIELD') {
+    if (typeof value !== 'string' ||
+        !values.includes(value))
+        throw invalid(code, `${field} must be one of ${values.join(', ')}.`);
+    return value;
+}
+/** An array of non-empty strings, trimmed and deduplicated in order. */
+export function stringList(value, field) {
+    if (!Array.isArray(value))
+        throw invalid('INVALID_FIELD', `${field} must be an array of strings.`);
+    const result = [];
+    for (const item of value) {
+        if (typeof item !== 'string' || item.trim() === '')
+            throw invalid('INVALID_FIELD', `${field} must be an array of strings.`);
+        if (!result.includes(item.trim()))
+            result.push(item.trim());
+    }
+    return result;
+}
+/** An id-like string, or null. */
+export function optionalId(value, field) {
+    if (value === null)
+        return null;
+    if (typeof value !== 'string' || value === '')
+        throw invalid('INVALID_FIELD', `${field} must be a string or null.`);
+    return value;
+}
+//# sourceMappingURL=validate.js.map

package/dist/server/kernel/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../server/kernel/validate.ts"],"names":[],"mappings":"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"}

package/dist/server/kernel/work.d.ts

@@ -0,0 +1,107 @@
+import type { DatabaseConnection } from '@nocobase/db';
+import type { Issue } from '../../shared/issues.js';
+import type { Blocker } from '../../shared/subtasks.js';
+import type { CommentChange, IssueChange, IssueTriggers } from '../domains/issues/ports.js';
+import type { ActivityRecorder } from './activity.js';
+import type { KindRegistry } from './kinds.js';
+import type { Tx } from './tx.js';
+import type { Actor } from './actor.js';
+declare module './events.js' {
+    interface DomainEventMap {
+        /** Something a kind's work handler did in the transaction, for that kind's plugin to hear after commit. */
+        'work.announced': {
+            readonly kind: string;
+            readonly payload: unknown;
+        };
+    }
+}
+/**
+ * Why a handler started nothing for a principal: `deferred`, the person asked not to start now; `blocked`, the issue
+ * waits for unfinished issues; `dormant`, the issue is where work does not start (`BACKLOG_STATUS`); `limited`,
+ * principals' comments started as many runs on the issue as the kind allows.
+ */
+export type RunAttemptSkip = 'waitingOwner' | 'deferred' | 'limited' | 'denied' | 'blocked' | 'dormant' | 'duplicate' | 'archived' | 'noRunner' | 'unavailable';
+/** One principal a change concerned, and whether work started for it. */
+export interface RunAttempt {
+    /** The kind of the principal (`agent`). */
+    readonly kind: string;
+    readonly principalId: string;
+    readonly subjectId: string;
+    /** What caused it: `assigned`, `comment`, `mention`, `statusChange`, `unblocked`… */
+    readonly triggerType: string;
+    readonly started: boolean;
+    readonly skipped?: RunAttemptSkip;
+    /** The kind's own reference to the work, such as a run id. */
+    readonly runId?: string;
+}
+/** Queued work a handler withdrew because of a change. */
+export interface WorkWithdrawal {
+    readonly kind: string;
+    readonly principalId: string;
+    readonly subjectId: string;
+    /** The kind's own reference to the work, such as a run id. */
+    readonly runId: string;
+    /** `blocked`: the issue waits for unfinished issues now. */
+    readonly reason: 'blocked';
+}
+/**
+ * A kind's answer to changes of the issues it executes or is named in. Each call joins the change's transaction; when
+ * that transaction is a rehearsal (`tx.rehearsal`), it only answers what it would start.
+ */
+export interface IssueWorkHandler {
+    /** Receives comments even when the executor was cleared, for issue-wide pause policies. */
+    readonly observesComments?: boolean;
+    /** Receives trusted owner claims even when the executor is cleared. */
+    readonly observesOwnerClaims?: boolean;
+    /** A new issue, or an update (including a status moved by a status event). */
+    onIssueChanged(tx: Tx, change: IssueChange): Promise<readonly RunAttempt[]>;
+    /**
+     * A comment that is not a note, of a person or another principal (never the system's), on an issue the kind executes
+     * or in which it is mentioned or answered. The attempts that started become the comment's `triggered` mentions.
+     * Throwing refuses the comment.
+     */
+    onCommentCreated?(tx: Tx, change: CommentChange): Promise<readonly RunAttempt[]>;
+    /** The issue's owner changed. Every work kind hears this before ordinary triggers, including unassigned issues. */
+    onOwnerChanged?(tx: Tx, input: {
+        readonly issue: Issue;
+        readonly from: string;
+        readonly to: string;
+        readonly actor?: Actor;
+    }): Promise<readonly RunAttempt[]>;
+    /**
+     * A `blockedBy` was added and the issue is held now: work not yet taken up should wait. Answers what it withdrew.
+     */
+    onBlocked?(tx: Tx, input: {
+        readonly issue: Issue;
+        readonly blockers: readonly Blocker[];
+    }): Promise<readonly WorkWithdrawal[]>;
+    /** Nothing holds the issue any more. */
+    onUnblocked?(tx: Tx, input: {
+        readonly issue: Issue;
+        readonly releasedBy: Issue;
+        readonly actor?: Actor;
+    }): Promise<readonly RunAttempt[]>;
+    /** Every sub-issue (`stage` null), or every sub-issue of one stage, of an issue the kind executes is finished. */
+    onSubtasksFinished?(tx: Tx, input: {
+        readonly parent: Issue;
+        readonly stage: number | null;
+        readonly childIssueIds: readonly string[];
+        readonly actor?: Actor;
+    }): Promise<readonly RunAttempt[]>;
+}
+/** Reports attempts to the innermost `collectRunAttempts` around the caller, if any. */
+export declare function recordRunAttempts(attempts: readonly RunAttempt[]): void;
+/** Runs `fn` and collects the attempts the triggers reported while it ran. */
+export declare function collectRunAttempts<T>(fn: () => Promise<T>): Promise<{
+    readonly value: T;
+    readonly attempts: readonly RunAttempt[];
+}>;
+export interface KindTriggersDeps {
+    /** Writes the skips and withdrawals on the issue's activity; without it they are only reported. */
+    readonly activity?: ActivityRecorder;
+    /** What holds an issue now, for the activity's words (`SubtaskService.blockersOf`). */
+    readonly blockers?: (conn: DatabaseConnection, issue: Issue) => Promise<readonly Blocker[]>;
+}
+/** The default triggers: each change to the work handlers of the kinds it concerns. */
+export declare function kindTriggers(kinds: KindRegistry, deps?: KindTriggersDeps): IssueTriggers;
+//# sourceMappingURL=work.d.ts.map

package/dist/server/kernel/work.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"work.d.ts","sourceRoot":"","sources":["../../../server/kernel/work.ts"],"names":[],"mappings":"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"}

package/dist/server/kernel/work.js

@@ -0,0 +1,173 @@
+/**
+ * Work for executors of other kinds: what a change, a comment or a release starts, as the kind that executes it decides
+ * (`PrincipalKind.work`). The plugin never knows what "work" is; it tells the kind's handler, in the transaction of the
+ * change, and the handler answers what it started and what it did not start and why (`RunAttempt[]`).
+ *
+ * `kindTriggers` is the default of the triggers (`domains/issues/ports.ts`): it hands each change to the work handler of
+ * every kind concerned (the issue's executor before and after, the kinds a comment mentions or answers), and turns the
+ * attempts that started into the `triggered` mentions a comment returns. A plugin that binds `projectsTriggersToken`
+ * replaces it.
+ *
+ * `collectRunAttempts` runs a service call and collects every attempt its triggers reported, for a preview or a test,
+ * without changing what the call returns.
+ *
+ * A handler may announce something to run after the change commits (`work.announced`): it is delivered on the plugin's
+ * event bus like any other event, and only the plugin that owns `kind` reads its `payload`.
+ *
+ * What a handler did not start because the issue is held (`blocked`), waits where nothing starts (`dormant`), or had
+ * as many runs from principals' comments as the kind allows (`limited`), and the queued work it
+ * withdrew when the issue became held (`onBlocked`), is recorded on the issue's activity, as the principal's:
+ * `work_skipped { reason, trigger, blockers | status }` and `work_withdrawn { reason, runId, blockers }`.
+ * Whether an issue is held is the plugin's to say (`SubtaskService.blockersOf`); the handler asks it and answers
+ * `skipped: 'blocked'`.
+ *
+ * Collect only: a plan's rehearsal (`Tx.rehearsal`, `kernel/tx.ts`) runs the same triggers in a transaction that
+ * always rolls back and drops every event. A handler then answers the attempts it would make (`started: true` for work
+ * it would start, `skipped` with the reason otherwise) and queues, cancels or announces nothing; the rehearsal turns the
+ * attempts into the plan row's `wakes`.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+const collector = new AsyncLocalStorage();
+/** Reports attempts to the innermost `collectRunAttempts` around the caller, if any. */
+export function recordRunAttempts(attempts) {
+    collector.getStore()?.push(...attempts);
+}
+/** Runs `fn` and collects the attempts the triggers reported while it ran. */
+export async function collectRunAttempts(fn) {
+    const attempts = [];
+    const value = await collector.run(attempts, fn);
+    return { value, attempts };
+}
+function handlerOf(kinds, key) {
+    return key ? kinds.get(key)?.work : undefined;
+}
+/** The distinct kinds with a work handler among `keys`, in order. */
+function handlersOf(kinds, keys) {
+    const seen = new Map();
+    for (const key of keys) {
+        const work = handlerOf(kinds, key);
+        if (key && work && !seen.has(key))
+            seen.set(key, work);
+    }
+    return [...seen];
+}
+const blockerRefs = (blockers) => blockers.map((blocker) => ({
+    issueId: blocker.issueId,
+    identifier: blocker.identifier,
+}));
+/** The skips recorded on the issue's activity. */
+const RECORDED_SKIPS = new Set([
+    'waitingOwner',
+    'blocked',
+    'dormant',
+    'limited',
+]);
+/** The default triggers: each change to the work handlers of the kinds it concerns. */
+export function kindTriggers(kinds, deps = {}) {
+    /** Reports the attempts, and records on `issue` the ones held back or dormant. */
+    async function report(tx, issue, attempts) {
+        const result = (await attempts) ?? [];
+        recordRunAttempts(result);
+        if (tx.rehearsal || !deps.activity)
+            return result;
+        let blockers;
+        for (const attempt of result) {
+            if (!RECORDED_SKIPS.has(attempt.skipped ?? ''))
+                continue;
+            let details = {};
+            if (attempt.skipped === 'blocked') {
+                blockers ??= (await deps.blockers?.(tx.conn, issue)) ?? [];
+                details = { blockers: blockerRefs(blockers) };
+            }
+            else if (attempt.skipped === 'dormant')
+                details = { status: issue.statusKey };
+            await deps.activity.record(tx.conn, {
+                issueId: issue.id,
+                actor: { type: attempt.kind, id: attempt.principalId },
+                action: 'work_skipped',
+                details: {
+                    reason: attempt.skipped,
+                    trigger: attempt.triggerType,
+                    ...details,
+                },
+            });
+            tx.emit({ type: 'issue.changed', issueId: issue.id });
+        }
+        return result;
+    }
+    return {
+        async onIssueChanged(tx, change) {
+            const { before, after } = change;
+            // Transfers reach every work kind before ordinary triggers, even when the executor is cleared.
+            if (before && before.ownerUserId !== after.ownerUserId)
+                for (const [, work] of handlersOf(kinds, kinds.list().map((kind) => kind.key)))
+                    await report(tx, after, work.onOwnerChanged?.(tx, {
+                        issue: after,
+                        from: before.ownerUserId,
+                        to: after.ownerUserId,
+                        actor: change.actor,
+                    }));
+            for (const [, work] of handlersOf(kinds, [
+                before?.executor?.type,
+                after.executor?.type,
+                ...(change.ownerClaimed
+                    ? kinds
+                        .list()
+                        .filter((kind) => kind.work?.observesOwnerClaims)
+                        .map((kind) => kind.key)
+                    : []),
+            ]))
+                await report(tx, after, work.onIssueChanged(tx, change));
+        },
+        async onCommentCreated(tx, change) {
+            const concerned = handlersOf(kinds, [
+                ...kinds
+                    .list()
+                    .filter((kind) => kind.work?.observesComments)
+                    .map((kind) => kind.key),
+                change.issue.executor?.type,
+                change.parent?.authorType,
+                ...change.mentions.map((ref) => ref.kind),
+            ]);
+            const triggered = [];
+            for (const [, work] of concerned)
+                for (const attempt of await report(tx, change.issue, work.onCommentCreated?.(tx, change)))
+                    if (attempt.started &&
+                        !triggered.some((ref) => ref.kind === attempt.kind && ref.id === attempt.principalId))
+                        triggered.push({ kind: attempt.kind, id: attempt.principalId });
+            return triggered;
+        },
+        async onBlocked(tx, input) {
+            const { issue, blockers } = input;
+            // Every kind: queued work may be for a principal a comment woke, not only for the executor.
+            const concerned = handlersOf(kinds, kinds.list().map((kind) => kind.key));
+            for (const [, work] of concerned) {
+                if (!work.onBlocked)
+                    continue;
+                const withdrawn = await work.onBlocked(tx, input);
+                if (tx.rehearsal || !deps.activity)
+                    continue;
+                for (const item of withdrawn) {
+                    await deps.activity.record(tx.conn, {
+                        issueId: issue.id,
+                        actor: { type: item.kind, id: item.principalId },
+                        action: 'work_withdrawn',
+                        details: {
+                            reason: item.reason,
+                            runId: item.runId,
+                            blockers: blockerRefs(blockers),
+                        },
+                    });
+                    tx.emit({ type: 'issue.changed', issueId: issue.id });
+                }
+            }
+        },
+        async onUnblocked(tx, input) {
+            await report(tx, input.issue, handlerOf(kinds, input.issue.executor?.type)?.onUnblocked?.(tx, input));
+        },
+        async onSubtasksFinished(tx, input) {
+            await report(tx, input.parent, handlerOf(kinds, input.parent.executor?.type)?.onSubtasksFinished?.(tx, input));
+        },
+    };
+}
+//# sourceMappingURL=work.js.map