@mastra/factory 0.28.0-alpha.0 → 0.28.0-alpha.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +210 -42
- package/dist/boards/board-events.d.ts +34 -0
- package/dist/boards/board-events.d.ts.map +1 -0
- package/dist/boards/board-events.js +50 -0
- package/dist/boards/board-events.js.map +1 -0
- package/dist/boards/board-writes.d.ts +86 -0
- package/dist/boards/board-writes.d.ts.map +1 -0
- package/dist/boards/board-writes.js +252 -0
- package/dist/boards/board-writes.js.map +1 -0
- package/dist/boards/define-board.d.ts +16 -5
- package/dist/boards/define-board.d.ts.map +1 -1
- package/dist/boards/define-board.js +30 -8
- package/dist/boards/define-board.js.map +1 -1
- package/dist/boards/intake-routing.d.ts +30 -6
- package/dist/boards/intake-routing.d.ts.map +1 -1
- package/dist/boards/intake-routing.js +43 -5
- package/dist/boards/intake-routing.js.map +1 -1
- package/dist/boards/legacy-plan-role.d.ts.map +1 -1
- package/dist/boards/legacy-plan-role.js +8 -4
- package/dist/boards/legacy-plan-role.js.map +1 -1
- package/dist/boards/phase-automation.d.ts.map +1 -1
- package/dist/boards/phase-automation.js +7 -2
- package/dist/boards/phase-automation.js.map +1 -1
- package/dist/boards/project-boards.d.ts +18 -7
- package/dist/boards/project-boards.d.ts.map +1 -1
- package/dist/boards/project-boards.js +78 -14
- package/dist/boards/project-boards.js.map +1 -1
- package/dist/boards/stored-board.d.ts +59 -1
- package/dist/boards/stored-board.d.ts.map +1 -1
- package/dist/boards/stored-board.js +219 -7
- package/dist/boards/stored-board.js.map +1 -1
- package/dist/factory.d.ts +63 -9
- package/dist/factory.d.ts.map +1 -1
- package/dist/factory.js +187 -22
- package/dist/factory.js.map +1 -1
- package/dist/index.d.ts +3 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4 -3
- package/dist/integrations/base.d.ts +6 -0
- package/dist/integrations/base.d.ts.map +1 -1
- package/dist/integrations/github/acceptance-labels.d.ts +4 -0
- package/dist/integrations/github/acceptance-labels.d.ts.map +1 -1
- package/dist/integrations/github/acceptance-labels.js +1 -1
- package/dist/integrations/github/acceptance-labels.js.map +1 -1
- package/dist/integrations/github/default-rules.d.ts +2 -9
- package/dist/integrations/github/default-rules.d.ts.map +1 -1
- package/dist/integrations/github/default-rules.js +7 -6
- package/dist/integrations/github/default-rules.js.map +1 -1
- package/dist/integrations/github/issue-reconciler.d.ts.map +1 -1
- package/dist/integrations/github/issue-reconciler.js +17 -1
- package/dist/integrations/github/issue-reconciler.js.map +1 -1
- package/dist/integrations/github/review-status-comment.d.ts +61 -0
- package/dist/integrations/github/review-status-comment.d.ts.map +1 -0
- package/dist/integrations/github/review-status-comment.js +217 -0
- package/dist/integrations/github/review-status-comment.js.map +1 -0
- package/dist/integrations/github/review-status-reporter.d.ts +42 -0
- package/dist/integrations/github/review-status-reporter.d.ts.map +1 -0
- package/dist/integrations/github/review-status-reporter.js +100 -0
- package/dist/integrations/github/review-status-reporter.js.map +1 -0
- package/dist/integrations/github/review-status.d.ts +28 -0
- package/dist/integrations/github/review-status.d.ts.map +1 -0
- package/dist/integrations/github/review-status.js +95 -0
- package/dist/integrations/github/review-status.js.map +1 -0
- package/dist/integrations/github/routes.d.ts.map +1 -1
- package/dist/integrations/github/routes.js +2 -5
- package/dist/integrations/github/routes.js.map +1 -1
- package/dist/integrations/github/rules.d.ts +13 -1
- package/dist/integrations/github/rules.d.ts.map +1 -1
- package/dist/integrations/github/rules.js +77 -6
- package/dist/integrations/github/rules.js.map +1 -1
- package/dist/integrations/gitlab/default-rules.d.ts +24 -9
- package/dist/integrations/gitlab/default-rules.d.ts.map +1 -1
- package/dist/integrations/gitlab/default-rules.js +4 -4
- package/dist/integrations/gitlab/default-rules.js.map +1 -1
- package/dist/integrations/gitlab/merge-request-reconciler.js +1 -1
- package/dist/integrations/gitlab/routes.d.ts.map +1 -1
- package/dist/integrations/gitlab/routes.js +1 -3
- package/dist/integrations/gitlab/routes.js.map +1 -1
- package/dist/integrations/gitlab/rules.d.ts +16 -0
- package/dist/integrations/gitlab/rules.d.ts.map +1 -1
- package/dist/integrations/gitlab/rules.js +69 -4
- package/dist/integrations/gitlab/rules.js.map +1 -1
- package/dist/integrations/incidentio/default-rules.d.ts +1 -9
- package/dist/integrations/incidentio/default-rules.d.ts.map +1 -1
- package/dist/integrations/incidentio/default-rules.js +3 -4
- package/dist/integrations/incidentio/default-rules.js.map +1 -1
- package/dist/integrations/incidentio/routes.d.ts.map +1 -1
- package/dist/integrations/incidentio/routes.js +1 -4
- package/dist/integrations/incidentio/routes.js.map +1 -1
- package/dist/integrations/incidentio/rules.d.ts +7 -0
- package/dist/integrations/incidentio/rules.d.ts.map +1 -1
- package/dist/integrations/incidentio/rules.js +35 -3
- package/dist/integrations/incidentio/rules.js.map +1 -1
- package/dist/integrations/jira/default-rules.d.ts +1 -9
- package/dist/integrations/jira/default-rules.d.ts.map +1 -1
- package/dist/integrations/jira/default-rules.js +3 -4
- package/dist/integrations/jira/default-rules.js.map +1 -1
- package/dist/integrations/jira/routes.d.ts.map +1 -1
- package/dist/integrations/jira/routes.js +1 -4
- package/dist/integrations/jira/routes.js.map +1 -1
- package/dist/integrations/jira/rules.d.ts +7 -0
- package/dist/integrations/jira/rules.d.ts.map +1 -1
- package/dist/integrations/jira/rules.js +35 -3
- package/dist/integrations/jira/rules.js.map +1 -1
- package/dist/integrations/linear/default-rules.d.ts +1 -9
- package/dist/integrations/linear/default-rules.d.ts.map +1 -1
- package/dist/integrations/linear/default-rules.js +3 -4
- package/dist/integrations/linear/default-rules.js.map +1 -1
- package/dist/integrations/linear/routes.d.ts.map +1 -1
- package/dist/integrations/linear/routes.js +1 -4
- package/dist/integrations/linear/routes.js.map +1 -1
- package/dist/integrations/linear/rules.d.ts +7 -0
- package/dist/integrations/linear/rules.d.ts.map +1 -1
- package/dist/integrations/linear/rules.js +35 -3
- package/dist/integrations/linear/rules.js.map +1 -1
- package/dist/integrations/platform/connect/routes.d.ts +7 -1
- package/dist/integrations/platform/connect/routes.d.ts.map +1 -1
- package/dist/integrations/platform/connect/routes.js +42 -5
- package/dist/integrations/platform/connect/routes.js.map +1 -1
- package/dist/integrations/platform/connect/session-tools.d.ts +7 -0
- package/dist/integrations/platform/connect/session-tools.d.ts.map +1 -0
- package/dist/integrations/platform/connect/session-tools.js +30 -0
- package/dist/integrations/platform/connect/session-tools.js.map +1 -0
- package/dist/integrations/platform/github/integration.d.ts.map +1 -1
- package/dist/integrations/platform/github/integration.js +1 -3
- package/dist/integrations/platform/github/integration.js.map +1 -1
- package/dist/integrations/platform/jira/routes.d.ts.map +1 -1
- package/dist/integrations/platform/jira/routes.js +1 -4
- package/dist/integrations/platform/jira/routes.js.map +1 -1
- package/dist/integrations/platform/linear/event-worker.d.ts +1 -1
- package/dist/integrations/platform/linear/event-worker.d.ts.map +1 -1
- package/dist/integrations/platform/linear/event-worker.js +9 -0
- package/dist/integrations/platform/linear/event-worker.js.map +1 -1
- package/dist/integrations/platform/linear/integration.d.ts.map +1 -1
- package/dist/integrations/platform/linear/integration.js +1 -3
- package/dist/integrations/platform/linear/integration.js.map +1 -1
- package/dist/integrations/slack/channel-reply-processor.d.ts +2 -0
- package/dist/integrations/slack/channel-reply-processor.d.ts.map +1 -1
- package/dist/integrations/slack/channel-reply-processor.js +6 -1
- package/dist/integrations/slack/channel-reply-processor.js.map +1 -1
- package/dist/integrations/slack/connect-route.d.ts.map +1 -1
- package/dist/integrations/slack/connect-route.js +1 -1
- package/dist/integrations/slack/connect-route.js.map +1 -1
- package/dist/integrations/slack/integration.d.ts.map +1 -1
- package/dist/integrations/slack/integration.js +2 -0
- package/dist/integrations/slack/integration.js.map +1 -1
- package/dist/integrations/slack/slack.d.ts +12 -10
- package/dist/integrations/slack/slack.d.ts.map +1 -1
- package/dist/integrations/slack/slack.js +110 -43
- package/dist/integrations/slack/slack.js.map +1 -1
- package/dist/integrations/slack/voice-clips.d.ts +32 -0
- package/dist/integrations/slack/voice-clips.d.ts.map +1 -0
- package/dist/integrations/slack/voice-clips.js +201 -0
- package/dist/integrations/slack/voice-clips.js.map +1 -0
- package/dist/integrations/workos/integration.d.ts.map +1 -1
- package/dist/integrations/workos/integration.js +1 -3
- package/dist/integrations/workos/integration.js.map +1 -1
- package/dist/mcp/routes.js +1 -1
- package/dist/packages/_internals/workspace/dist/index.js +1 -1
- package/dist/routes/attention-activity.js +1 -1
- package/dist/routes/attention-providers.js +1 -1
- package/dist/routes/automation-runs.d.ts.map +1 -1
- package/dist/routes/automation-runs.js +1 -4
- package/dist/routes/automation-runs.js.map +1 -1
- package/dist/routes/boards.d.ts +8 -6
- package/dist/routes/boards.d.ts.map +1 -1
- package/dist/routes/boards.js +73 -143
- package/dist/routes/boards.js.map +1 -1
- package/dist/routes/config.d.ts.map +1 -1
- package/dist/routes/config.js +3 -8
- package/dist/routes/config.js.map +1 -1
- package/dist/routes/contracts.d.ts +132 -0
- package/dist/routes/contracts.d.ts.map +1 -1
- package/dist/routes/contracts.js +77 -29
- package/dist/routes/contracts.js.map +1 -1
- package/dist/routes/fs.d.ts.map +1 -1
- package/dist/routes/fs.js +1 -4
- package/dist/routes/fs.js.map +1 -1
- package/dist/routes/intake-routes.d.ts.map +1 -1
- package/dist/routes/intake-routes.js +19 -12
- package/dist/routes/intake-routes.js.map +1 -1
- package/dist/routes/intake.d.ts.map +1 -1
- package/dist/routes/intake.js +3 -5
- package/dist/routes/intake.js.map +1 -1
- package/dist/routes/knowledge.d.ts.map +1 -1
- package/dist/routes/knowledge.js +1 -4
- package/dist/routes/knowledge.js.map +1 -1
- package/dist/routes/oauth.d.ts.map +1 -1
- package/dist/routes/oauth.js +1 -4
- package/dist/routes/oauth.js.map +1 -1
- package/dist/routes/projects.d.ts +3 -0
- package/dist/routes/projects.d.ts.map +1 -1
- package/dist/routes/projects.js +7 -4
- package/dist/routes/projects.js.map +1 -1
- package/dist/routes/provider-credentials.d.ts.map +1 -1
- package/dist/routes/provider-credentials.js +6 -0
- package/dist/routes/provider-credentials.js.map +1 -1
- package/dist/routes/route.d.ts +2 -0
- package/dist/routes/route.d.ts.map +1 -1
- package/dist/routes/route.js +5 -1
- package/dist/routes/route.js.map +1 -1
- package/dist/routes/skills.d.ts.map +1 -1
- package/dist/routes/skills.js +1 -4
- package/dist/routes/skills.js.map +1 -1
- package/dist/routes/source-control-sessions.d.ts.map +1 -1
- package/dist/routes/source-control-sessions.js +1 -3
- package/dist/routes/source-control-sessions.js.map +1 -1
- package/dist/routes/source-control-settings.d.ts.map +1 -1
- package/dist/routes/source-control-settings.js +3 -2
- package/dist/routes/source-control-settings.js.map +1 -1
- package/dist/routes/surface.d.ts +3 -1
- package/dist/routes/surface.d.ts.map +1 -1
- package/dist/routes/surface.js +11 -1
- package/dist/routes/surface.js.map +1 -1
- package/dist/routes/voice.d.ts +48 -0
- package/dist/routes/voice.d.ts.map +1 -0
- package/dist/routes/voice.js +248 -0
- package/dist/routes/voice.js.map +1 -0
- package/dist/routes/work-items.d.ts.map +1 -1
- package/dist/routes/work-items.js +1 -4
- package/dist/routes/work-items.js.map +1 -1
- package/dist/rules/decision-applicability.js +1 -1
- package/dist/rules/dispatcher.d.ts +28 -0
- package/dist/rules/dispatcher.d.ts.map +1 -1
- package/dist/rules/dispatcher.js +391 -93
- package/dist/rules/dispatcher.js.map +1 -1
- package/dist/rules/event-rules.d.ts +40 -1
- package/dist/rules/event-rules.d.ts.map +1 -1
- package/dist/rules/event-rules.js +59 -1
- package/dist/rules/event-rules.js.map +1 -1
- package/dist/rules/processor.js +1 -1
- package/dist/rules/processor.js.map +1 -1
- package/dist/rules/transition-service.d.ts +9 -0
- package/dist/rules/transition-service.d.ts.map +1 -1
- package/dist/rules/transition-service.js +4 -2
- package/dist/rules/transition-service.js.map +1 -1
- package/dist/rules/types.d.ts +54 -3
- package/dist/rules/types.d.ts.map +1 -1
- package/dist/rules/types.js +2 -0
- package/dist/rules/types.js.map +1 -1
- package/dist/rules/validation.d.ts.map +1 -1
- package/dist/rules/validation.js +57 -2
- package/dist/rules/validation.js.map +1 -1
- package/dist/session/credential-policy.d.ts +2 -2
- package/dist/session/credential-policy.d.ts.map +1 -1
- package/dist/session/credential-policy.js +3 -3
- package/dist/session/credential-policy.js.map +1 -1
- package/dist/session/default-model-hydration.d.ts +2 -2
- package/dist/session/default-model-hydration.d.ts.map +1 -1
- package/dist/session/default-model-hydration.js +4 -4
- package/dist/session/default-model-hydration.js.map +1 -1
- package/dist/session/session-threads.d.ts +8 -0
- package/dist/session/session-threads.d.ts.map +1 -1
- package/dist/session/session-threads.js +11 -1
- package/dist/session/session-threads.js.map +1 -1
- package/dist/skills/catalog.js +1 -1
- package/dist/storage/domains/audit/actions.d.ts +1 -1
- package/dist/storage/domains/audit/actions.d.ts.map +1 -1
- package/dist/storage/domains/audit/actions.js +2 -1
- package/dist/storage/domains/audit/actions.js.map +1 -1
- package/dist/storage/domains/audit/domain.d.ts.map +1 -1
- package/dist/storage/domains/audit/domain.js +1 -3
- package/dist/storage/domains/audit/domain.js.map +1 -1
- package/dist/storage/domains/boards/base.d.ts +32 -1
- package/dist/storage/domains/boards/base.d.ts.map +1 -1
- package/dist/storage/domains/boards/base.js +155 -8
- package/dist/storage/domains/boards/base.js.map +1 -1
- package/dist/storage/domains/boards/schemas.d.ts.map +1 -1
- package/dist/storage/domains/boards/schemas.js +13 -1
- package/dist/storage/domains/boards/schemas.js.map +1 -1
- package/dist/storage/domains/comments/routes.d.ts.map +1 -1
- package/dist/storage/domains/comments/routes.js +1 -3
- package/dist/storage/domains/comments/routes.js.map +1 -1
- package/dist/storage/domains/memory-settings/base.d.ts +0 -8
- package/dist/storage/domains/memory-settings/base.d.ts.map +1 -1
- package/dist/storage/domains/memory-settings/base.js +1 -11
- package/dist/storage/domains/memory-settings/base.js.map +1 -1
- package/dist/storage/domains/projects/base.d.ts +6 -0
- package/dist/storage/domains/projects/base.d.ts.map +1 -1
- package/dist/storage/domains/projects/base.js +9 -1
- package/dist/storage/domains/projects/base.js.map +1 -1
- package/dist/storage/domains/voice-settings/base.d.ts +31 -0
- package/dist/storage/domains/voice-settings/base.d.ts.map +1 -0
- package/dist/storage/domains/voice-settings/base.js +81 -0
- package/dist/storage/domains/voice-settings/base.js.map +1 -0
- package/dist/storage/domains/work-items/base.d.ts +31 -2
- package/dist/storage/domains/work-items/base.d.ts.map +1 -1
- package/dist/storage/domains/work-items/base.js +197 -44
- package/dist/storage/domains/work-items/base.js.map +1 -1
- package/dist/storage/domains/work-items/cards.d.ts +6 -1
- package/dist/storage/domains/work-items/cards.d.ts.map +1 -1
- package/dist/storage/domains/work-items/cards.js +54 -4
- package/dist/storage/domains/work-items/cards.js.map +1 -1
- package/dist/storage/domains/work-items/work-item-schema.d.ts +2 -0
- package/dist/storage/domains/work-items/work-item-schema.d.ts.map +1 -1
- package/dist/storage/domains/work-items/work-item-schema.js +24 -1
- package/dist/storage/domains/work-items/work-item-schema.js.map +1 -1
- package/dist/timing.d.ts +1 -0
- package/dist/timing.d.ts.map +1 -1
- package/dist/timing.js +1 -1
- package/dist/timing.js.map +1 -1
- package/dist/tools/read-tools.d.ts +2 -2
- package/dist/tools/read-tools.d.ts.map +1 -1
- package/dist/tools/read-tools.js +7 -6
- package/dist/tools/read-tools.js.map +1 -1
- package/dist/tools/session-tools.d.ts +1 -1
- package/dist/tools/session-tools.d.ts.map +1 -1
- package/dist/tools/session-tools.js.map +1 -1
- package/dist/tools/sessions-state-processor.d.ts +1 -1
- package/dist/tools/sessions-state-processor.d.ts.map +1 -1
- package/dist/tools/sessions-state-processor.js +9 -2
- package/dist/tools/sessions-state-processor.js.map +1 -1
- package/dist/tools/work-item-tools.js +2 -2
- package/dist/voice/rate-limit.d.ts +13 -0
- package/dist/voice/rate-limit.d.ts.map +1 -0
- package/dist/voice/rate-limit.js +36 -0
- package/dist/voice/rate-limit.js.map +1 -0
- package/dist/voice/realtime.d.ts +13 -0
- package/dist/voice/realtime.d.ts.map +1 -0
- package/dist/voice/realtime.js +56 -0
- package/dist/voice/realtime.js.map +1 -0
- package/dist/voice/transcription.d.ts +51 -0
- package/dist/voice/transcription.d.ts.map +1 -0
- package/dist/voice/transcription.js +112 -0
- package/dist/voice/transcription.js.map +1 -0
- package/dist/work-items/split-backfill.d.ts +13 -0
- package/dist/work-items/split-backfill.d.ts.map +1 -0
- package/dist/work-items/split-backfill.js +32 -0
- package/dist/work-items/split-backfill.js.map +1 -0
- package/dist/work-items/split-migration.d.ts +39 -2
- package/dist/work-items/split-migration.d.ts.map +1 -1
- package/dist/work-items/split-migration.js +170 -62
- package/dist/work-items/split-migration.js.map +1 -1
- package/dist/workspace.js +2 -2
- package/package.json +9 -8
package/README.md
CHANGED
|
@@ -60,7 +60,11 @@ Each work item has one board item. Factory's card-to-card parent link is `parent
|
|
|
60
60
|
|
|
61
61
|
#### Migration and dry run
|
|
62
62
|
|
|
63
|
-
Factory
|
|
63
|
+
Factory keeps the legacy `work_items` table and copies each card into the new tables. Before it starts serving, it copies only open cards. Done and canceled cards are copied in the background afterwards and appear on the board shortly after startup. While that runs, opening a card, or receiving a Linear, Jira, GitHub, GitLab, or incident.io event for it, copies that card on demand, so a reopened issue keeps its original card. Board lists, such as the Done column, fill in as the background copy progresses.
|
|
64
|
+
|
|
65
|
+
Once the background copy finishes, Factory records it, and later startups skip the copy. A card that an older Factory version changes in the legacy table afterwards is recopied at the next startup. Unchanged legacy rows are no-ops. Deleted board items have tombstones so a later startup doesn't resurrect them. A legacy row whose source conflicts with another card ID, or that was edited on both sides, is skipped rather than preventing startup; the copy still counts as finished.
|
|
66
|
+
|
|
67
|
+
Each copy pass logs one summary line with its counts and up to ten skipped card IDs with their reasons, for example `[factory] work item split (background pass): 9,837 cards checked, 0 copied, 106 recopied, 9,581 unchanged, 0 deferred, 150 skipped — <id> (Split board item changed after migration); … and 140 more`. A pass that runs longer than ten seconds also logs a progress line every ten seconds. When startup completes, Factory writes `[factory:timing] boot <n>ms` to stderr, regardless of the log level. Reconcile skipped card IDs before retiring the legacy data; comments and subscriptions linked to a skipped ID won't have a visible card until the conflict is resolved.
|
|
64
68
|
|
|
65
69
|
For a database that has not cut over yet, inspect the migration without switching storage by setting this environment variable before starting Factory:
|
|
66
70
|
|
|
@@ -110,18 +114,55 @@ There is no dual-write rollback: an older Factory version sees the legacy snapsh
|
|
|
110
114
|
|
|
111
115
|
### Stored boards
|
|
112
116
|
|
|
113
|
-
Each project
|
|
117
|
+
Each project's boards live in its database, and the stored row is the board.
|
|
114
118
|
|
|
115
|
-
- **
|
|
116
|
-
- **
|
|
119
|
+
- **Factory's boards**: the built-in Work board and the boards you pass to `new MastraFactory({ boards })` (app boards). Factory stores each in a project once: when the project is created, and in existing projects the first time a process loads them, which includes the preload at startup. The project keeps a key's board from then on. A Factory release or an app change never rewrites it, and a board the project deleted is not stored again. A key you add later is stored once in every project that hasn't had it. The legacy Review board is never stored and stays read-only.
|
|
120
|
+
- **The project's own boards**: boards an admin created through the boards API, or that an app wrote with [`factory.upsertBoard()`](#writing-a-board-into-projects).
|
|
117
121
|
|
|
118
|
-
A project's boards are
|
|
122
|
+
A project's boards are the Work and app boards in code order, followed by the others. The catalog, card creation through the API and Factory tools, transitions, the dispatcher, phase runs and the attention views all read that list. Existing apps need no change.
|
|
119
123
|
|
|
120
|
-
**Data model.** A stored board has a `key` (the ID cards reference as `board`), `name`, optional `description`, and ordered phases. A phase has a `key` (the stage ID), `name`, optional `description`, `kind`, and for working phases `runner` (`{ skill?, context?, instructions? }`), `autoStart`, `autoStartWhen` and `exitTool`, plus `nextPhases` on any phase. The first phase is the initial phase and must be `resting`. Saved boards pass the same checks `defineBoard()` applies, with the same messages. A
|
|
124
|
+
**Data model.** A stored board has a `key` (the ID cards reference as `board`), `name`, optional `description`, and ordered phases. A phase has a `key` (the stage ID), `name`, optional `description`, `kind`, and for working phases `runner` (`{ skill?, context?, instructions? }`), `autoStart`, `autoStartWhen` and `exitTool`, plus `nextPhases` on any phase. The first phase is the initial phase and must be `resting`. Saved boards pass the same checks `defineBoard()` applies, with the same messages. A board under a key no code board uses has no code behaviors: no handlers, transition policy, `sourceClosed`, or tool and event rules. Its working phases start their `runner` on entry.
|
|
121
125
|
|
|
122
126
|
`nextPhases` on a stored board: leaving it out (or `null`) on a resting or working phase allows moves to every other phase, `[]` allows none, and a terminal phase allows none unless it lists some.
|
|
123
127
|
|
|
124
|
-
**
|
|
128
|
+
**Editing the Work board and app boards.** The catalog and `GET …/boards/:boardKey` report each board's `source` (`builtin`, `app` or `stored`) and `editable` (`false` only for the legacy Review board). `PATCH` replaces the project's board. Factory serves the stored fields with the code behaviour of the board and of each phase key still attached: entry and exit handlers, outcomes, tool and event rules, `sourceClosed` and the transition policy. A runner's instructions reach the runs the code handlers start.
|
|
129
|
+
|
|
130
|
+
What code behaviour depends on stays fixed, and an edit that changes it is refused with `422 code_behaviour`, listing every conflict:
|
|
131
|
+
|
|
132
|
+
- Every phase the code declares stays, with the same `kind`, and the code's initial phase stays first.
|
|
133
|
+
- On a phase whose work runs in code handlers (Triage, Planning, Building, Review and PR review on Work), `runner.context` stays as declared and `runner.skill` stays unset: the handlers choose the skill.
|
|
134
|
+
- A declared exit tool (`submit_plan` on Planning) keeps its `id`. Its `autoApprove` and `autoApproveWhen` are yours. A phase whose code handlers move cards on without an exit tool can't get one: it would hold those moves back.
|
|
135
|
+
- Every move the code board allows from a phase stays in its `nextPhases`. Code makes those moves itself: an approved plan moves Planning to Building, a merged or closed pull request moves its card to Done or Canceled, and integration rules move cards between phases. You can add moves.
|
|
136
|
+
|
|
137
|
+
Everything else can change: names and descriptions, added `nextPhases`, `autoStart` and `autoStartWhen`, exit-tool approval, runner instructions, the runner of working phases without code handlers, the order of phases after the first, and new phases (which behave like stored-board phases).
|
|
138
|
+
|
|
139
|
+
**When Factory's definition changes.** A project keeps the board it stored, so a newer Work default or a changed app board doesn't reach it on its own. `POST …/boards/:boardKey/reset` with `expectedRevision` rewrites the board to Factory's current definition for its key (Work or an app board) at the next revision; revisions never go back, so a client holding an older revision is refused.
|
|
140
|
+
|
|
141
|
+
**Boards that no longer fit the code.** A Work or app board is served even when it has fallen out of step with a newer release's code, with the code behaviour that still fits it. A phase the code declares keeps its handlers only while it is on the board with the same `kind`, `runner.context`, `runner.skill` and exit tool; an outcome is dropped when its target phase is gone or the board no longer allows the move; the board's tool rules always stay (they hold exit-tool approvals, such as Planning's `submit_plan`), and its event rules and transition policy need every phase the code declares, and `sourceClosed` needs both its phases, still terminal. A move Factory's code makes that the board's `nextPhases` don't allow is reported too; when code makes it, the move is refused (and retried until its attempts run out), and the card stays where it is. Each dropped behaviour is reported in the board's `problems`, for example `Phase "testing" isn't on stored board "release", so its code behaviour doesn't run.` or `Phase "triage" runs without its code behaviour: <conflict>`. A board stored under an app board's key that the app stopped defining is served as one of the project's own boards.
|
|
142
|
+
|
|
143
|
+
Creating a board under a built-in or app board's key is refused with `409 code_board`, and so is deleting the Work board, whose code handlers run by its key; reset it instead. App boards can be deleted like the project's own; Factory doesn't store them again, and `factory.upsertBoard()` brings one back. A stored `review` board stays hidden by the Review board.
|
|
144
|
+
|
|
145
|
+
**When a board isn't stored.** If storing Factory's boards in a project fails, the boards it couldn't store aren't served, the catalog reports `Board "<key>" isn't stored in this project yet; Factory stores it on the next load.`, and `GET …/boards/:boardKey` answers `404 board_not_found`; the project's next load tries again. Factory serves code boards itself only for the legacy Review board, for every project when the boards storage could not start, and on a replica that has not loaded a project yet, until its first load.
|
|
146
|
+
|
|
147
|
+
#### Writing a board into projects
|
|
148
|
+
|
|
149
|
+
`factory.upsertBoard()` writes a board definition into projects after `prepare()`: each named project (or all of them) that has no board under its key gets it, and each one that has it, edited or not, has it replaced at the next revision. Factory doesn't run it for you, so projects created later don't get the board until you run it again; run it from an admin script, or after `prepare()` when you want every project to have the definition you ship. The board is checked once, as the boards API checks it, each replacement passes the checks an edit does (cards in a removed phase refuse it with `phase_in_use` there), and each write is audited as `factory.board.created` or `factory.board.updated` by `system:factory`. It returns the projects it stored the board in, the ones it replaced it in, and the ones that already had it unchanged. A refused board throws `BoardWriteError`, whose `code` is the boards API's error code (`invalid_board`, `unknown_skill`, `code_behaviour`, `phase_in_use`, `project_not_found`, or `code_board` for the legacy Review board's key). A board under a new key has no code behaviour; an app board's key keeps the app board's, so it also brings back an app board a project deleted.
|
|
150
|
+
|
|
151
|
+
```ts
|
|
152
|
+
const bugs = {
|
|
153
|
+
key: 'bugs',
|
|
154
|
+
name: 'Bugs',
|
|
155
|
+
phases: [
|
|
156
|
+
{ key: 'reported', name: 'Reported', kind: 'resting', nextPhases: ['fixing'] },
|
|
157
|
+
{ key: 'fixing', name: 'Fixing', kind: 'working', runner: { context: 'work' }, nextPhases: ['fixed'] },
|
|
158
|
+
{ key: 'fixed', name: 'Fixed', kind: 'terminal' },
|
|
159
|
+
],
|
|
160
|
+
} satisfies StoredBoardInput;
|
|
161
|
+
|
|
162
|
+
const factory = new MastraFactory({ storage });
|
|
163
|
+
await factory.prepare();
|
|
164
|
+
const { inserted, updated, unchanged } = await factory.upsertBoard(bugs, { projects: 'all' });
|
|
165
|
+
```
|
|
125
166
|
|
|
126
167
|
**Editing rules for stored boards.**
|
|
127
168
|
|
|
@@ -131,17 +172,18 @@ A project's boards are its code boards followed by its stored boards. The catalo
|
|
|
131
172
|
|
|
132
173
|
**Replicas.** Each board write replaces the project's board version. The replica that wrote it sees the change at once; other replicas notice within a second, the next time they touch that project.
|
|
133
174
|
|
|
134
|
-
**Integrations.** Integration event rules and reconcilers read only the code boards. Intake bindings and label routes can target only code boards. A project's [intake routes](#intake-routes) can also send new cards to its stored boards. Every card move goes through the transition service, which checks it against the project's boards.
|
|
175
|
+
**Integrations.** Integration event rules and reconcilers read only the code boards, which edits can't break: the initial phase and every phase with code behaviour are kept. Integration messages use the code names of phases. Intake bindings and label routes can target only code boards. A project's [intake routes](#intake-routes) can also send new cards to its stored boards. Every card move goes through the transition service, which checks it against the project's boards.
|
|
135
176
|
|
|
136
|
-
**Routes.** All need project membership; changes need an organization admin when auth is enabled, and are recorded in the audit log as `factory.board.created`, `updated` and `
|
|
177
|
+
**Routes.** All need project membership; changes need an organization admin when auth is enabled, and are recorded in the audit log as `factory.board.created`, `updated`, `deleted` and `reset`.
|
|
137
178
|
|
|
138
|
-
| Method | Path | Body | Result
|
|
139
|
-
| -------- | --------------------------------------------------------------- | ------------------------------------------------------- |
|
|
140
|
-
| `GET` | `/web/factory/projects/:id/boards` | — | The catalog, with each board's `source`, `editable` and `problems`.
|
|
141
|
-
| `GET` | `/web/factory/projects/:id/boards/:boardKey` | — | The definition, `revision` (`null` for
|
|
142
|
-
| `POST` | `/web/factory/projects/:id/boards` | The board, with `key`. | `201` and the board. `409 code_board` for a code board's key, `409 board_exists` for a stored board's.
|
|
143
|
-
| `PATCH` | `/web/factory/projects/:id/boards/:boardKey` | The whole board without `key`, plus `expectedRevision`. | The board. Replaces every field. `409 code_board` for
|
|
144
|
-
| `
|
|
179
|
+
| Method | Path | Body | Result |
|
|
180
|
+
| -------- | --------------------------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
181
|
+
| `GET` | `/web/factory/projects/:id/boards` | — | The catalog, with each board's `source`, `editable` and `problems`. |
|
|
182
|
+
| `GET` | `/web/factory/projects/:id/boards/:boardKey` | — | The definition, `revision` (`null` for the Review board), `source`, `editable`, `problems`, `codeBehaviour` (per phase: whether code handlers run it, its fixed exit tool and required next phases) and `canEdit` (whether you may change it). |
|
|
183
|
+
| `POST` | `/web/factory/projects/:id/boards` | The board, with `key`. | `201` and the board. `409 code_board` for a code board's key, `409 board_exists` for a stored board's. |
|
|
184
|
+
| `PATCH` | `/web/factory/projects/:id/boards/:boardKey` | The whole board without `key`, plus `expectedRevision`. | The board. Replaces every field. `422 code_behaviour` for an edit code behaviour can't honour, `409 code_board` for the Review board. |
|
|
185
|
+
| `POST` | `/web/factory/projects/:id/boards/:boardKey/reset` | `{ expectedRevision }` | The board, rewritten to Factory's current definition at the next revision. `409 not_code_board` for the project's own boards, `409 code_board` for the Review board. |
|
|
186
|
+
| `DELETE` | `/web/factory/projects/:id/boards/:boardKey?expectedRevision=n` | — | `204`. `409 code_board` for the Work and Review boards. |
|
|
145
187
|
|
|
146
188
|
A stale `expectedRevision` is refused with `409 revision_mismatch`; reload the board and try again.
|
|
147
189
|
|
|
@@ -161,23 +203,40 @@ curl -X POST "$FACTORY_URL/web/factory/projects/$PROJECT/boards" -H 'content-typ
|
|
|
161
203
|
curl "$FACTORY_URL/web/factory/projects/$PROJECT/boards/bugs" > bugs.json
|
|
162
204
|
jq '.board | { name, description, phases: (.phases | map(if .key == "fixing" then .name = "Patching" else . end)), expectedRevision: .revision }' bugs.json \
|
|
163
205
|
| curl -X PATCH "$FACTORY_URL/web/factory/projects/$PROJECT/boards/bugs" -H 'content-type: application/json' -d @-
|
|
206
|
+
|
|
207
|
+
# Let Work's Planning start, and approve its plan, on its own for cards labelled effort:low.
|
|
208
|
+
curl "$FACTORY_URL/web/factory/projects/$PROJECT/boards/work" > work.json
|
|
209
|
+
jq '.board | { name, description, expectedRevision: .revision, phases: (.phases | map(if .key == "planning" then
|
|
210
|
+
.autoStart = true
|
|
211
|
+
| .autoStartWhen = { operator: "AND", conditions: [{ field: "item.labels", operator: "contains", value: "effort:low" }] }
|
|
212
|
+
| .exitTool = { id: "submit_plan", autoApprove: true, autoApproveWhen: .autoStartWhen }
|
|
213
|
+
else . end)) }' work.json \
|
|
214
|
+
| curl -X PATCH "$FACTORY_URL/web/factory/projects/$PROJECT/boards/work" -H 'content-type: application/json' -d @-
|
|
215
|
+
|
|
216
|
+
# Put Work back to Factory's default.
|
|
217
|
+
curl -X POST "$FACTORY_URL/web/factory/projects/$PROJECT/boards/work/reset" -H 'content-type: application/json' \
|
|
218
|
+
-d "{\"expectedRevision\": $(curl -s "$FACTORY_URL/web/factory/projects/$PROJECT/boards/work" | jq .board.revision)}"
|
|
164
219
|
```
|
|
165
220
|
|
|
221
|
+
Admins can make the same edits in the Factory UI under **Settings → Work board**.
|
|
222
|
+
|
|
166
223
|
### Migrating from `defineBoard()`
|
|
167
224
|
|
|
168
|
-
`defineBoard()
|
|
225
|
+
`defineBoard()` and the `boards` option of `MastraFactory` are deprecated: write board definitions into projects with [`factory.upsertBoard()`](#writing-a-board-into-projects), or manage them through the boards API. Nothing breaks: each project stores the boards you pass once, Factory serves them from its rows with the code behaviour the board declares, and a later code change reaches a project only through reset. Factory logs once per process:
|
|
169
226
|
|
|
170
227
|
```text
|
|
171
|
-
[Mastra Factory] MastraFactory({ boards }) and defineBoard() are deprecated: boards
|
|
228
|
+
[Mastra Factory] MastraFactory({ boards }) and defineBoard() are deprecated: boards live in the database, and each project stores these definitions once. Write board definitions into projects with factory.upsertBoard(), or manage them through the boards API; see the README "Stored boards" section and mastra-ai/mastra#28920.
|
|
172
229
|
```
|
|
173
230
|
|
|
174
|
-
|
|
231
|
+
`includeDefaultBoards` decides whether projects get the built-in Work board (and the legacy Review board).
|
|
175
232
|
|
|
176
|
-
|
|
233
|
+
Using only the built-in boards logs nothing. A board that cards reach only through the API, the Factory UI or Factory tools, and that needs no handlers, policies or rules, can move off code: write its definition under a new key into projects with `factory.upsertBoard()`, move its cards, then stop passing the code board. Keep passing a board while integrations file cards onto it, intake bindings or label routes target it, or it needs code behaviors.
|
|
234
|
+
|
|
235
|
+
Removing `defineBoard()` still needs code behaviour that stored boards can reference by name, and integrations that read each project's boards. That work is tracked in [mastra-ai/mastra#28920](https://github.com/mastra-ai/mastra/issues/28920).
|
|
177
236
|
|
|
178
237
|
### Board lifecycle rules
|
|
179
238
|
|
|
180
|
-
Code boards own phase entry and exit handlers; stored boards have none (see [Stored boards](#stored-boards)). Work and Review are installed automatically with Mastra's preferred defaults; no rule configuration is needed. Custom boards declare source-specific `onEnter` and `onExit` handlers through `defineBoard()`, which is deprecated but still works:
|
|
239
|
+
Code boards own phase entry and exit handlers; stored boards have none, and a project's copy of a code board keeps its code's handlers (see [Stored boards](#stored-boards)). Work and Review are installed automatically with Mastra's preferred defaults; no rule configuration is needed. Custom boards declare source-specific `onEnter` and `onExit` handlers through `defineBoard()`, which is deprecated but still works:
|
|
181
240
|
|
|
182
241
|
```typescript
|
|
183
242
|
import { MastraFactory } from '@mastra/factory';
|
|
@@ -205,7 +264,7 @@ export function createFactory(storage: MastraFactoryConfig['storage']) {
|
|
|
205
264
|
}
|
|
206
265
|
```
|
|
207
266
|
|
|
208
|
-
Handlers return one typed decision or `undefined`. Supported sources are `issue`, `pullRequest`, `linearIssue`, and `manual`. Each Factory instance resolves handlers from its installed definitions. To replace Work or Review, disable both default boards and install a board with the same ID. You can reinstall the exported `workBoard` and `reviewBoard` definitions unchanged, or use their phases as the starting point for a customized definition:
|
|
267
|
+
Handlers return one typed decision or `undefined`. Supported sources are `issue`, `pullRequest`, `linearIssue`, and `manual`. Each Factory instance resolves handlers from its installed definitions. To replace Work or Review, disable both default boards and install a board with the same ID. Projects created after that store your board. Existing projects keep the Work board they already stored until an admin resets it or you write yours into them with `factory.upsertBoard()`. You can reinstall the exported `workBoard` and `reviewBoard` definitions unchanged, or use their phases as the starting point for a customized definition:
|
|
209
268
|
|
|
210
269
|
```typescript
|
|
211
270
|
import { MastraFactory, workBoard } from '@mastra/factory';
|
|
@@ -257,7 +316,7 @@ const releaseBoard = defineBoard({
|
|
|
257
316
|
});
|
|
258
317
|
```
|
|
259
318
|
|
|
260
|
-
Work declares `{ completed: 'done', canceled: 'canceled' }`. A board without `sourceClosed` leaves its cards where they are, and cards already in a terminal phase are never moved. The move is an ordinary transition, so the board must allow it from the card's current phase. Integration rule overrides receive the same targets as `context.boardClosure`.
|
|
319
|
+
Work declares `{ completed: 'done', canceled: 'canceled' }`. A board without `sourceClosed` leaves its cards where they are, and cards already in a terminal phase are never moved. The move is an ordinary transition, so the board must allow it from the card's current phase. Integration rule overrides receive the same targets as `context.boardClosure`. When a project [intake route](#status-events-move-existing-cards) on the card's board handles `work_item.closed`, as the default close routes do on Work, the routes decide the move instead and `sourceClosed` is only the fallback.
|
|
261
320
|
|
|
262
321
|
### Board tool-result rules
|
|
263
322
|
|
|
@@ -661,9 +720,9 @@ A project's [intake routes](#intake-routes) are checked before these bindings an
|
|
|
661
720
|
|
|
662
721
|
### Intake routes
|
|
663
722
|
|
|
664
|
-
Each project has an ordered list of intake routes, managed through the API (there is no UI yet). A route decides where a new card lands: the first enabled route whose `when` matches the card names its board and phase.
|
|
723
|
+
Each project has an ordered list of intake routes, managed through the API (there is no UI yet). A route names the board events it handles in `on`. A route on `work_item.created`, the default, decides where a new card lands: the first enabled route whose `when` matches the card names its board and phase. A route on `work_item.closed` or `work_item.reopened` decides where an existing card moves when its source closes or reopens (see [Status events](#status-events-move-existing-cards)).
|
|
665
724
|
|
|
666
|
-
**The default routes.** Every project starts with two
|
|
725
|
+
**The default routes.** Every project starts with five routes: two that place new cards, and three that move cards when their issue closes or reopens. The first, `Outside authors wait in Intake`:
|
|
667
726
|
|
|
668
727
|
```json
|
|
669
728
|
{
|
|
@@ -680,18 +739,30 @@ Each project has an ordered list of intake routes, managed through the API (ther
|
|
|
680
739
|
|
|
681
740
|
It files GitHub and GitLab issues and pull requests from authors outside the write-access circle in Work › Intake, ahead of any label route or binding. Intake is a resting phase, so nothing starts there on its own. Any session, a person's or an agent's, can move the card on, and that move starts the next phase's run. Pushes to a pull request resting in Intake don't re-review it, and comments and edits on an issue never re-run Triage (see GitHub event rules). Trusted authors' cards, and Linear, Jira and incident.io cards (which carry no trust stamp), land where they did before. The second, `Pull requests go to PR review`, sends every other pull request and merge request (`source.kind equals pull_request`) to Work › PR review, where the reviewer runs once a person or the project's auto-run lets it start. Because it comes second, an outside author's pull request still waits in Intake. A pull request Factory opened for one of its own cards is filed by that card's rule, which no route re-places: it waits in Intake while the authoring card goes out for review.
|
|
682
741
|
|
|
683
|
-
The
|
|
742
|
+
The other three move Work cards when their issue's status changes:
|
|
743
|
+
|
|
744
|
+
| Route | `on` | `when` | Target |
|
|
745
|
+
| --------------------------------------------- | ------------------------ | ------------------------------- | --------------- |
|
|
746
|
+
| `Closed issues go to Done` | `["work_item.closed"]` | `event.reason equals completed` | Work › Done |
|
|
747
|
+
| `Issues closed as not planned go to Canceled` | `["work_item.closed"]` | `event.reason equals canceled` | Work › Canceled |
|
|
748
|
+
| `Reopened issues go back to Intake` | `["work_item.reopened"]` | none | Work › Intake |
|
|
749
|
+
|
|
750
|
+
They replace the close handlers each integration used to apply on its own, so a closed GitHub, GitLab, Linear, Jira or incident.io issue lands where it did before, but you can now edit or disable that move. To stop closes from moving Work cards, disable both close routes. Deleting them does not stop the move: with no route left that handles closes, Work's `sourceClosed` mapping moves closed cards to Done or Canceled again.
|
|
751
|
+
|
|
752
|
+
The default routes are stored routes like any other: list them, edit them, disable them, reorder them or delete them through the API. Factory adds each one once, the first time the project's routes are read or written, appending it after the project's existing routes, and doesn't add it back after an admin deletes it. Deleting a default is permanent: recreate it by hand to get it back. A project set up before the pull request route or the close and reopen routes existed gets them this way too.
|
|
684
753
|
|
|
685
754
|
**Trust only decides where a card arrives.** Once a card is moved out of Intake, later input on it runs like on any card: a maintainer's push re-reviews an outside author's pull request. A phase that should only auto-start for trusted authors says so in its `autoStartWhen` (`author.trusted equals true`). Runs on untrusted cards still use their own isolated memory.
|
|
686
755
|
|
|
687
756
|
**Route shape.**
|
|
688
757
|
|
|
689
|
-
| Field
|
|
690
|
-
|
|
|
691
|
-
| `name`
|
|
692
|
-
| `enabled`
|
|
693
|
-
| `
|
|
694
|
-
| `
|
|
758
|
+
| Field | Meaning |
|
|
759
|
+
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
760
|
+
| `name` | Up to 120 characters. |
|
|
761
|
+
| `enabled` | Defaults to `true`. Disabled routes are skipped. |
|
|
762
|
+
| `on` | The board events the route handles: `work_item.created` (the default), `work_item.closed` and `work_item.reopened`. Each at most once. `work_item.commented` and `work_item.edited` are activity, which never moves a card, so a route can't name them. |
|
|
763
|
+
| `when` | A rule over the card's facts (the same format as `autoStartWhen`). `null`, the default, matches every card. A route that handles more than `work_item.created` can also test `event.type` and `event.reason`. |
|
|
764
|
+
| `target` | Required. `{ boardKey, phaseKey? }` sets where matching cards land; without `phaseKey` they land in the board's first phase. The board must be installed in the project (code or stored). For a route on `work_item.created`, the phase can't be terminal and must be reachable from the board's first phase; a route that only moves existing cards can target any phase, terminal ones included. |
|
|
765
|
+
| `allowWorkingPhase` | Defaults to `false`. A status move into a working phase (one that starts runs, such as Triage) is refused unless this is `true`, so a reopened card doesn't re-run Triage by accident. |
|
|
695
766
|
|
|
696
767
|
Routes are evaluated in `position` order (0 first). Rules can test these card facts: `item.labels`, `item.title`, `item.author`, `source.kind` (`issue`, `pull_request`, …), `source.integration` (`github`, `gitlab`, `linear`, `jira`, `incidentio`, …) and `author.trusted`. `author.trusted` is `true` when the card carries an `authorTrusted: true` or `factoryAuthored: true` stamp. GitHub and GitLab stamp `authorTrusted` from the author's repository permission, and a stamp that is missing counts as untrusted.
|
|
697
768
|
|
|
@@ -706,16 +777,46 @@ A card a route placed records the route's id in its `intakeRouteId` metadata and
|
|
|
706
777
|
|
|
707
778
|
Not covered: a pull request routed to a board other than Work or Review no longer gets Factory review, because review requests and pushes only act on pull request cards on those boards.
|
|
708
779
|
|
|
780
|
+
#### Status events move existing cards
|
|
781
|
+
|
|
782
|
+
Every integration reports issue status changes with the same names: `work_item.created` when an issue is first seen, `work_item.closed` when it closes, and `work_item.reopened` when it reopens (GitHub and GitLab; Linear, Jira and incident.io report opens and closes only). A close carries `event.reason`: `canceled` for GitHub's "not planned" and "duplicate" and for Linear, Jira and incident.io canceled states, `completed` otherwise (GitLab closes are always `completed`).
|
|
783
|
+
|
|
784
|
+
When one of these arrives for a card that already exists, the first enabled route on the card's board whose `on` names the event and whose `when` matches the card and the event moves the card to the route's phase:
|
|
785
|
+
|
|
786
|
+
- The move is a system move made by the route, recorded in the card's history (`by: intake-route:<routeId>`) and in the audit log (`factory.work_item.stage_moved` with `cause: event_route`, made by actor `intake-route:<routeId>`).
|
|
787
|
+
- The move clears the card's armed autonomy. A provider event is not a person's go-ahead, so a reopened card waits for a person or the project's auto-run before a phase run starts.
|
|
788
|
+
- It skips the board's `nextPhases`, so a reopened card can leave Done. It still checks that the phase exists and that the board's card lanes take the card (an issue never lands in PR review).
|
|
789
|
+
- It is refused with `approval_required` when the target is a working phase and the route doesn't set `allowWorkingPhase`.
|
|
790
|
+
- A move into a working or resting phase waits for a run in flight on the card to end, then moves the card. While it waits it goes back to the queue, so it never holds a dispatch slot.
|
|
791
|
+
- The source's last status wins. When an issue is closed and reopened before Factory applies the close, the close is dropped and the card stays where it was.
|
|
792
|
+
- A move into a terminal phase doesn't wait: it runs terminal cleanup like any other, so a session still running on the card is aborted at once, as a close always has.
|
|
793
|
+
- A close moves only an unfinished card, and a reopen only a finished one. Redelivered or reconciled webhooks move the card once.
|
|
794
|
+
|
|
795
|
+
Only routes targeting the card's own board apply; a route naming another board is skipped. A route on the card's board that names the event owns it even when it is disabled or its `when` doesn't match: the card stays put. Only on a board where no route names the event does the board's `sourceClosed` mapping apply, so custom boards keep closing as before. To stop closes from moving Work cards, disable both close routes: deleting them hands closes back to Work's `sourceClosed` mapping, which moves the card to Done or Canceled.
|
|
796
|
+
|
|
797
|
+
A deployment that answers an event itself keeps routes out of it: a handler or `null` set explicitly on the integration's `rules` for `issueClosed`, `issueReopened`, `issueCommentCreated` and so on, or `null` on the card's board handlers. An override that moves nothing really moves nothing. A board handler that wraps or returns the stock close move is different: that move still goes to the routes, as the stock handler's own would.
|
|
798
|
+
|
|
799
|
+
#### Activity reaches the card's session
|
|
800
|
+
|
|
801
|
+
A new comment on a card's GitHub or GitLab issue, or an edit to its title or description, tells the session working the card, with pointers only:
|
|
802
|
+
|
|
803
|
+
```text
|
|
804
|
+
New comment by @alice on acme/repo#42: https://github.com/acme/repo/issues/42#issuecomment-100
|
|
805
|
+
acme/repo#42 was edited by @bob (untrusted author): https://github.com/acme/repo/issues/42
|
|
806
|
+
```
|
|
807
|
+
|
|
808
|
+
The message never carries the comment's body or the issue's title: the session follows the link to read it. Authors without write access are marked `(untrusted author)`. Factory's own GitHub comments are skipped, and so are edits to an existing GitLab comment. An idle session is woken by GitHub activity from a trusted author. Activity from an untrusted author never wakes a session, and neither does GitLab activity: GitLab deliveries don't say whether Factory wrote a comment, so a session could otherwise wake itself with its own comments. That activity is sent as a `low` priority notification, which never starts a run: it waits in the session's notifications, and the session's next run is told it is there. Otherwise, activity while it is busy waits as one notification per card and kind of activity, counting how many arrived. A card nobody is working drops the message. Nothing starts: Triage still runs once. The card's feed shows the comment either way.
|
|
809
|
+
|
|
709
810
|
**Routes.** Reading needs a signed-in user of the project's organization. Changes need an organization admin when auth is enabled. Deleting or reordering routes renumbers the routes after it and bumps their `revision`, so an update sent with an older `expectedRevision` is refused with 409 and must be retried with the current one. Changes are recorded in the audit log as `factory.intake_route.created`, `updated`, `deleted` and `reordered`.
|
|
710
811
|
|
|
711
|
-
| Method | Path | Body | Result
|
|
712
|
-
| -------- | --------------------------------------------------------------------- | ---------------------------------------------------------- |
|
|
713
|
-
| `GET` | `/web/factory/projects/:id/intake-routes` | — | `intakeRoutes` in order.
|
|
714
|
-
| `GET` | `/web/factory/projects/:id/intake-routes/:routeId` | — | The route.
|
|
715
|
-
| `POST` | `/web/factory/projects/:id/intake-routes` | The route. | `201` and the route, added at the end. `422 unknown_board`, `unknown_phase`, `terminal_phase` or `unreachable_phase` for a target cards can't land on. `409 intake_route_limit` past 100 routes. |
|
|
716
|
-
| `PATCH` | `/web/factory/projects/:id/intake-routes/:routeId` | The fields to change, plus `expectedRevision`. | The route.
|
|
717
|
-
| `DELETE` | `/web/factory/projects/:id/intake-routes/:routeId?expectedRevision=n` | — | `204`.
|
|
718
|
-
| `POST` | `/web/factory/projects/:id/intake-routes/reorder` | `{ "ids": [...] }`: every route of the project, once each. | The routes in their new order. `409 intake_route_set_mismatch` if the list differs from the project's routes.
|
|
812
|
+
| Method | Path | Body | Result |
|
|
813
|
+
| -------- | --------------------------------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
814
|
+
| `GET` | `/web/factory/projects/:id/intake-routes` | — | `intakeRoutes` in order. |
|
|
815
|
+
| `GET` | `/web/factory/projects/:id/intake-routes/:routeId` | — | The route. |
|
|
816
|
+
| `POST` | `/web/factory/projects/:id/intake-routes` | The route. | `201` and the route, added at the end. `422 unknown_board`, `unknown_phase`, `terminal_phase` or `unreachable_phase` for a target cards can't land on; `422 invalid_intake_route` for a bad `on` or a `when` testing `event.*` on a placement-only route. `409 intake_route_limit` past 100 routes. |
|
|
817
|
+
| `PATCH` | `/web/factory/projects/:id/intake-routes/:routeId` | The fields to change, plus `expectedRevision`. | The route. |
|
|
818
|
+
| `DELETE` | `/web/factory/projects/:id/intake-routes/:routeId?expectedRevision=n` | — | `204`. |
|
|
819
|
+
| `POST` | `/web/factory/projects/:id/intake-routes/reorder` | `{ "ids": [...] }`: every route of the project, once each. | The routes in their new order. `409 intake_route_set_mismatch` if the list differs from the project's routes. |
|
|
719
820
|
|
|
720
821
|
A stale `expectedRevision` is refused with `409 revision_mismatch`. Each route reports `problems`, for example when its board has since been deleted. Such a route places no cards.
|
|
721
822
|
|
|
@@ -730,6 +831,25 @@ curl -X POST "$FACTORY_URL/web/factory/projects/$PROJECT/intake-routes" -H 'cont
|
|
|
730
831
|
"target": { "boardKey": "work", "phaseKey": "triage" }
|
|
731
832
|
}'
|
|
732
833
|
|
|
834
|
+
# Send issues closed as not planned to Done, too, instead of Canceled.
|
|
835
|
+
curl -X PATCH "$FACTORY_URL/web/factory/projects/$PROJECT/intake-routes/$CLOSED_CANCELED_ROUTE" -H 'content-type: application/json' -d '{
|
|
836
|
+
"target": { "boardKey": "work", "phaseKey": "done" },
|
|
837
|
+
"expectedRevision": 1
|
|
838
|
+
}'
|
|
839
|
+
|
|
840
|
+
# Send reopened bugs back to Triage to run again. A new route is added at the end, after the
|
|
841
|
+
# default reopen route that matches every reopen, so then move it ahead of that one with
|
|
842
|
+
# POST .../intake-routes/reorder.
|
|
843
|
+
curl -X POST "$FACTORY_URL/web/factory/projects/$PROJECT/intake-routes" -H 'content-type: application/json' -d '{
|
|
844
|
+
"name": "Reopened bugs re-run Triage",
|
|
845
|
+
"on": ["work_item.reopened"],
|
|
846
|
+
"when": { "operator": "AND", "conditions": [
|
|
847
|
+
{ "field": "item.labels", "operator": "contains", "value": "bug" }
|
|
848
|
+
] },
|
|
849
|
+
"target": { "boardKey": "work", "phaseKey": "triage" },
|
|
850
|
+
"allowWorkingPhase": true
|
|
851
|
+
}'
|
|
852
|
+
|
|
733
853
|
# Let outside authors' issues go where label routes send them, instead of Intake.
|
|
734
854
|
curl -X PATCH "$FACTORY_URL/web/factory/projects/$PROJECT/intake-routes/$DEFAULT_ROUTE" -H 'content-type: application/json' -d '{
|
|
735
855
|
"enabled": false,
|
|
@@ -912,7 +1032,7 @@ Both integrations expose incidents and incident follow-ups as separate Intake so
|
|
|
912
1032
|
|
|
913
1033
|
### Linear workspace connections
|
|
914
1034
|
|
|
915
|
-
For Platform-managed Linear connections, Settings →
|
|
1035
|
+
For Platform-managed Linear connections, **Settings → Work Intake** connects and repairs workspaces in place. A disconnected workspace with saved sources shows **Reconnect** on the Linear card; healthy ones need no action. A disconnected workspace without saved sources has nothing paused, so it has no Reconnect; authorize it again with **Connect**. To add another workspace, choose **Connect** next to Linear under **Add a source**. During reconnection, choose the named workspace in Linear. Factory checks that workspace's connection when authorization returns.
|
|
916
1036
|
|
|
917
1037
|
Work Intake keeps disconnected workspaces' saved sources and routing. Their issues remain paused until access is restored. A request failure shows a retry action and does not mark the workspace disconnected. Sources and polling from healthy workspaces remain available when another workspace's source request fails.
|
|
918
1038
|
|
|
@@ -1040,6 +1160,54 @@ Spawned sessions get a one-line signal instead: a side session sees which sessio
|
|
|
1040
1160
|
|
|
1041
1161
|
The tools take their scope as an argument rather than reading the request, so the same tool set can later be mounted elsewhere, such as an MCP server.
|
|
1042
1162
|
|
|
1163
|
+
### Mastra Connect and your own tools in sessions
|
|
1164
|
+
|
|
1165
|
+
With Platform credentials and `MASTRA_PROJECT_ID`, every Factory session gets the [Mastra Connect](https://mastra.ai/docs/mastra-platform/connect) tools of each connection attached to the Platform project. Attach and remove connections in Mastra Platform, on the project's **Connect** page. The organization's other connections reach sessions only once they're attached, and a new project has none. **Settings → Tools** lists what sessions get, read from the same Platform list. Platform deploys get both variables automatically. Anywhere else, including locally, set `MASTRA_PROJECT_ID` and `MASTRA_PLATFORM_SECRET_KEY` or `MASTRA_PLATFORM_ACCESS_TOKEN`. Attach Linear, and a Slack thread, a web chat or a work item can ask about its issues.
|
|
1166
|
+
|
|
1167
|
+
Sessions run these tools without asking while automatic approval is on, so only attach accounts whose actions sessions may take. When a person turns approval off, the tools follow the `mcp` permission category, except in Slack with `adapterOptions.toolDisplay: 'text'`, where every tool call is approved automatically. Tools with `delete` or `archive` anywhere in their name, in any case, are left out. That check goes by name only, so it can't catch every destructive action, such as a SQL tool running a `DROP`. GitHub and GitLab Connect tools are left out too: Factory's own source-control tools enforce repository scope and self-review, and Connect's would skip both. Every user and organization on the Factory shares the project's connections, and a connection attached for another app on the same project reaches Factory sessions too. `GET /web/integrations/platform/connect-tools` backs the settings page.
|
|
1168
|
+
|
|
1169
|
+
Connect caches the connection list for 30 seconds. When a later refresh fails, sessions keep the last list it got, including a connection removed since, until a refresh succeeds. A run with no list yet waits at most 15 seconds for one, then goes on without Connect tools, and Factory logs why. If the Platform stalls instead of failing, later runs also go without them until that listing answers or fails.
|
|
1170
|
+
|
|
1171
|
+
`tools` replaces that default with the tools you choose: a record of tools, such as an MCP server's, or a function that returns them for each run from its `requestContext`. `tools: {}` offers none. Factory doesn't filter the tools you pass: the example below includes `linear_delete_issue`, so narrow it with Connect's `allowTools` or `disallowTools`.
|
|
1172
|
+
|
|
1173
|
+
```typescript
|
|
1174
|
+
import { tools as connectTools } from '@mastra/connect';
|
|
1175
|
+
import { MastraFactory } from '@mastra/factory';
|
|
1176
|
+
|
|
1177
|
+
const factory = new MastraFactory({
|
|
1178
|
+
// ...
|
|
1179
|
+
tools: connectTools({ providers: ['linear'] }),
|
|
1180
|
+
});
|
|
1181
|
+
```
|
|
1182
|
+
|
|
1183
|
+
A tool named like one Factory already gives the session, such as `linear_get_issue` from a connected Linear integration, is not offered, and Factory logs that once per name. When resolving the tools you pass throws, the run fails with that error.
|
|
1184
|
+
|
|
1185
|
+
Factory doesn't read MCP servers from the host's `mcp.json` files, and logs a warning at startup when `~/.mastracode/mcp.json` exists. Pass MCP tools through `tools` instead:
|
|
1186
|
+
|
|
1187
|
+
```typescript
|
|
1188
|
+
import { MCPClient } from '@mastra/mcp';
|
|
1189
|
+
|
|
1190
|
+
const mcp = new MCPClient({ servers: { tickets: { url: new URL('https://tickets.example.com/mcp') } } });
|
|
1191
|
+
|
|
1192
|
+
const factory = new MastraFactory({
|
|
1193
|
+
// ...
|
|
1194
|
+
tools: await mcp.listTools(),
|
|
1195
|
+
});
|
|
1196
|
+
```
|
|
1197
|
+
|
|
1198
|
+
### Voice input
|
|
1199
|
+
|
|
1200
|
+
The composer mic first asks `POST /web/voice/live-session`. When the chosen model has a realtime model (Mistral Voxtral), the server mints a short-lived Mistral `rt_` token with the selected key and the browser streams 16 kHz PCM to Mistral's realtime socket, so words appear in the draft while you speak. Every other provider answers `{ mode: 'batch' }`, and so does Mistral when it won't mint a token for a key that can still transcribe (for example one without the `create_client_session` permission): the browser records a clip and posts it to `POST /web/voice/transcribe`, where the server transcribes it with a provider from the Mastra Code speech-to-text registry (`@mastra/code-sdk/voice/stt-registry`). A rejected or out-of-credit Mistral key answers 502 before anything is recorded; other providers report a bad key only when the clip is transcribed. API keys never reach the browser. Each member can start 20 live sessions or transcriptions a minute on each server process (the counters are in memory); past that both routes answer 429 `voice_rate_limited` with `Retry-After`, before anything is recorded. Only a minted live session or a transcription counts, so when Mistral won't mint a token and the browser records a clip instead, that dictation counts once.
|
|
1201
|
+
|
|
1202
|
+
Voice input resolves its model and key the way an interactive chat in the same Factory does:
|
|
1203
|
+
|
|
1204
|
+
- `factory` model scope: the Factory's voice model with organization keys. Only organization admins change the model.
|
|
1205
|
+
- `user` or `hybrid` model scope: each member's own voice model with personal keys. Organization keys are never used.
|
|
1206
|
+
|
|
1207
|
+
Either side starts on auto, the first registry provider with a key. OAuth subscriptions are never used. With sign-in enabled, keys come only from stored credentials; in local mode the provider env var applies before a stored key. `GET`/`PUT /web/voice/settings` back **Settings → Models → Voice input**.
|
|
1208
|
+
|
|
1209
|
+
Voice clips recorded in Slack and sent to a Factory session (a mention, a DM, or a thread the bot is in) are transcribed the same way under the thread's Factory, with the sender as the member, before the agent sees the message. A thread with no Factory session uses the sender's own voice model and key. The transcript replaces the clip. A clip that can't be transcribed is dropped from the message and the sender gets a card only they can see, with the reason and, for a missing, rejected or out-of-credit key, an **Open voice settings** button; when nothing but mentions is left in the message, the agent doesn't run. Uploaded audio files stay attachments.
|
|
1210
|
+
|
|
1043
1211
|
### MCP server (Claude, ChatGPT and other MCP clients)
|
|
1044
1212
|
|
|
1045
1213
|
A Factory with an auth provider and an OAuth authorization server serves an MCP endpoint over Streamable HTTP:
|
|
@@ -1048,7 +1216,7 @@ A Factory with an auth provider and an OAuth authorization server serves an MCP
|
|
|
1048
1216
|
https://<your-factory>/web/factory/projects/<projectId>/mcp
|
|
1049
1217
|
```
|
|
1050
1218
|
|
|
1051
|
-
|
|
1219
|
+
The Factory UI does not show this URL while the MCP endpoint is being reworked. Build it from your Factory URL and project id as shown above.
|
|
1052
1220
|
|
|
1053
1221
|
It exposes the Factory tools a signed-in web session has (list, inspect, create, update and transition work items, start and signal sessions, decisions, approvals), plus `search` and `fetch` over work items for ChatGPT. Each tool carries MCP annotations (read-only, destructive, idempotent) so clients can ask before changes.
|
|
1054
1222
|
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import type { RuleGroup } from '../rules/rule-group.js';
|
|
2
|
+
/**
|
|
3
|
+
* What happened to a card's source, named the same for every provider. Integrations map their
|
|
4
|
+
* webhooks onto these. Status events change where a card belongs: only these can move a card, so
|
|
5
|
+
* only these may be named in a route's `on`.
|
|
6
|
+
*/
|
|
7
|
+
export declare const STATUS_EVENTS: readonly ['work_item.created', 'work_item.closed', 'work_item.reopened'];
|
|
8
|
+
export type StatusEvent = (typeof STATUS_EVENTS)[number];
|
|
9
|
+
/** Activity on a card: it never moves the card, it only tells the card's session. */
|
|
10
|
+
export declare const ACTIVITY_EVENTS: readonly ['work_item.commented', 'work_item.edited'];
|
|
11
|
+
export type ActivityEvent = (typeof ACTIVITY_EVENTS)[number];
|
|
12
|
+
/** Why a work item closed: `canceled` covers "not planned" and duplicates. */
|
|
13
|
+
export declare const CLOSE_REASONS: readonly ['completed', 'canceled'];
|
|
14
|
+
export type CloseReason = (typeof CLOSE_REASONS)[number];
|
|
15
|
+
/** A status event as routes see it. */
|
|
16
|
+
export interface BoardEventFacts {
|
|
17
|
+
type: StatusEvent;
|
|
18
|
+
reason?: CloseReason;
|
|
19
|
+
}
|
|
20
|
+
/** The close reason for a provider's own closed-state fact. */
|
|
21
|
+
export declare function closeReason(canceled: boolean): CloseReason;
|
|
22
|
+
/** What a route without `on` handles: placing new cards, as routes always have. */
|
|
23
|
+
export declare const DEFAULT_ROUTE_EVENTS: readonly StatusEvent[];
|
|
24
|
+
/** Facts a route's `when` can test about the event, besides the card's own facts. */
|
|
25
|
+
export declare const EVENT_RULE_FIELDS: readonly ['event.type', 'event.reason'];
|
|
26
|
+
/** Every field an intake route's `when` may name. */
|
|
27
|
+
export declare const INTAKE_ROUTE_RULE_FIELDS: readonly ["item.labels", "item.title", "item.author", "author.trusted", "source.kind", "source.integration", "event.type", "event.reason"];
|
|
28
|
+
/**
|
|
29
|
+
* Why a route's `on` and `when` can't be saved together, or null. `on` must name at least one
|
|
30
|
+
* status event, each once; `event.*` conditions need an event besides `work_item.created`, which
|
|
31
|
+
* places new cards and carries no event facts.
|
|
32
|
+
*/
|
|
33
|
+
export declare function routeEventsProblem(on: readonly string[], when: RuleGroup | null): string | null;
|
|
34
|
+
//# sourceMappingURL=board-events.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"board-events.d.ts","sourceRoot":"","sources":["../../src/boards/board-events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGxD;;;;GAIG;AACH,eAAO,MAAM,aAAa,YAAI,mBAAmB,EAAE,kBAAkB,EAAE,oBAAoB,CAAU,CAAC;AACtG,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,qFAAqF;AACrF,eAAO,MAAM,eAAe,YAAI,qBAAqB,EAAE,kBAAkB,CAAU,CAAC;AACpF,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,8EAA8E;AAC9E,eAAO,MAAM,aAAa,YAAI,WAAW,EAAE,UAAU,CAAU,CAAC;AAChE,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,uCAAuC;AACvC,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,QAAQ,EAAE,OAAO,GAAG,WAAW,CAE1D;AAED,mFAAmF;AACnF,eAAO,MAAM,oBAAoB,EAAE,SAAS,WAAW,EAA0B,CAAC;AAElF,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,YAAI,YAAY,EAAE,cAAc,CAAU,CAAC;AAEzE,qDAAqD;AACrD,eAAO,MAAM,wBAAwB,4IAAuD,CAAC;AAc7F;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAa/F"}
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import { CARD_RULE_FIELDS } from "../rules/rule-group.js";
|
|
2
|
+
// src/boards/board-events.ts
|
|
3
|
+
/**
|
|
4
|
+
* What happened to a card's source, named the same for every provider. Integrations map their
|
|
5
|
+
* webhooks onto these. Status events change where a card belongs: only these can move a card, so
|
|
6
|
+
* only these may be named in a route's `on`.
|
|
7
|
+
*/
|
|
8
|
+
const STATUS_EVENTS = [
|
|
9
|
+
"work_item.created",
|
|
10
|
+
"work_item.closed",
|
|
11
|
+
"work_item.reopened"
|
|
12
|
+
];
|
|
13
|
+
/** Activity on a card: it never moves the card, it only tells the card's session. */
|
|
14
|
+
const ACTIVITY_EVENTS = ["work_item.commented", "work_item.edited"];
|
|
15
|
+
/** Why a work item closed: `canceled` covers "not planned" and duplicates. */
|
|
16
|
+
const CLOSE_REASONS = ["completed", "canceled"];
|
|
17
|
+
/** The close reason for a provider's own closed-state fact. */
|
|
18
|
+
function closeReason(canceled) {
|
|
19
|
+
return canceled ? "canceled" : "completed";
|
|
20
|
+
}
|
|
21
|
+
/** What a route without `on` handles: placing new cards, as routes always have. */
|
|
22
|
+
const DEFAULT_ROUTE_EVENTS = ["work_item.created"];
|
|
23
|
+
/** Facts a route's `when` can test about the event, besides the card's own facts. */
|
|
24
|
+
const EVENT_RULE_FIELDS = ["event.type", "event.reason"];
|
|
25
|
+
/** Every field an intake route's `when` may name. */
|
|
26
|
+
const INTAKE_ROUTE_RULE_FIELDS = [...CARD_RULE_FIELDS, ...EVENT_RULE_FIELDS];
|
|
27
|
+
function isStatusEvent(value) {
|
|
28
|
+
return STATUS_EVENTS.includes(value);
|
|
29
|
+
}
|
|
30
|
+
function namesEventField(group) {
|
|
31
|
+
return group.conditions.some((condition) => "conditions" in condition ? namesEventField(condition) : EVENT_RULE_FIELDS.includes(condition.field));
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Why a route's `on` and `when` can't be saved together, or null. `on` must name at least one
|
|
35
|
+
* status event, each once; `event.*` conditions need an event besides `work_item.created`, which
|
|
36
|
+
* places new cards and carries no event facts.
|
|
37
|
+
*/
|
|
38
|
+
function routeEventsProblem(on, when) {
|
|
39
|
+
if (on.length === 0) return "`on` must name at least one event.";
|
|
40
|
+
if (new Set(on).size !== on.length) return "`on` may name each event only once.";
|
|
41
|
+
for (const event of on) {
|
|
42
|
+
if (ACTIVITY_EVENTS.includes(event)) return `"${event}" is activity, not a status change: it notifies the card's session and can't move a card, so a route can't name it.`;
|
|
43
|
+
if (!isStatusEvent(event)) return `"${event}" is not a board event; use one of ${STATUS_EVENTS.join(", ")}.`;
|
|
44
|
+
}
|
|
45
|
+
if (when && on.every((event) => event === "work_item.created") && namesEventField(when)) return "`event.type` and `event.reason` only apply to routes that handle an event besides work_item.created.";
|
|
46
|
+
return null;
|
|
47
|
+
}
|
|
48
|
+
export { ACTIVITY_EVENTS, CLOSE_REASONS, DEFAULT_ROUTE_EVENTS, EVENT_RULE_FIELDS, INTAKE_ROUTE_RULE_FIELDS, STATUS_EVENTS, closeReason, routeEventsProblem };
|
|
49
|
+
|
|
50
|
+
//# sourceMappingURL=board-events.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"board-events.js","names":[],"sources":["../../src/boards/board-events.ts"],"sourcesContent":["import type { RuleGroup } from '../rules/rule-group.js';\nimport { CARD_RULE_FIELDS } from '../rules/rule-group.js';\n\n/**\n * What happened to a card's source, named the same for every provider. Integrations map their\n * webhooks onto these. Status events change where a card belongs: only these can move a card, so\n * only these may be named in a route's `on`.\n */\nexport const STATUS_EVENTS = ['work_item.created', 'work_item.closed', 'work_item.reopened'] as const;\nexport type StatusEvent = (typeof STATUS_EVENTS)[number];\n\n/** Activity on a card: it never moves the card, it only tells the card's session. */\nexport const ACTIVITY_EVENTS = ['work_item.commented', 'work_item.edited'] as const;\nexport type ActivityEvent = (typeof ACTIVITY_EVENTS)[number];\n\n/** Why a work item closed: `canceled` covers \"not planned\" and duplicates. */\nexport const CLOSE_REASONS = ['completed', 'canceled'] as const;\nexport type CloseReason = (typeof CLOSE_REASONS)[number];\n\n/** A status event as routes see it. */\nexport interface BoardEventFacts {\n type: StatusEvent;\n reason?: CloseReason;\n}\n\n/** The close reason for a provider's own closed-state fact. */\nexport function closeReason(canceled: boolean): CloseReason {\n return canceled ? 'canceled' : 'completed';\n}\n\n/** What a route without `on` handles: placing new cards, as routes always have. */\nexport const DEFAULT_ROUTE_EVENTS: readonly StatusEvent[] = ['work_item.created'];\n\n/** Facts a route's `when` can test about the event, besides the card's own facts. */\nexport const EVENT_RULE_FIELDS = ['event.type', 'event.reason'] as const;\n\n/** Every field an intake route's `when` may name. */\nexport const INTAKE_ROUTE_RULE_FIELDS = [...CARD_RULE_FIELDS, ...EVENT_RULE_FIELDS] as const;\n\nfunction isStatusEvent(value: string): value is StatusEvent {\n return (STATUS_EVENTS as readonly string[]).includes(value);\n}\n\nfunction namesEventField(group: RuleGroup): boolean {\n return group.conditions.some(condition =>\n 'conditions' in condition\n ? namesEventField(condition)\n : (EVENT_RULE_FIELDS as readonly string[]).includes(condition.field),\n );\n}\n\n/**\n * Why a route's `on` and `when` can't be saved together, or null. `on` must name at least one\n * status event, each once; `event.*` conditions need an event besides `work_item.created`, which\n * places new cards and carries no event facts.\n */\nexport function routeEventsProblem(on: readonly string[], when: RuleGroup | null): string | null {\n if (on.length === 0) return '`on` must name at least one event.';\n if (new Set(on).size !== on.length) return '`on` may name each event only once.';\n for (const event of on) {\n if ((ACTIVITY_EVENTS as readonly string[]).includes(event)) {\n return `\"${event}\" is activity, not a status change: it notifies the card's session and can't move a card, so a route can't name it.`;\n }\n if (!isStatusEvent(event)) return `\"${event}\" is not a board event; use one of ${STATUS_EVENTS.join(', ')}.`;\n }\n if (when && on.every(event => event === 'work_item.created') && namesEventField(when)) {\n return '`event.type` and `event.reason` only apply to routes that handle an event besides work_item.created.';\n }\n return null;\n}\n"],"mappings":";;;;;;;AAQA,MAAa,gBAAgB;CAAC;CAAqB;CAAoB;AAAoB;;AAI3F,MAAa,kBAAkB,CAAC,uBAAuB,kBAAkB;;AAIzE,MAAa,gBAAgB,CAAC,aAAa,UAAU;;AAUrD,SAAgB,YAAY,UAAgC;CAC1D,OAAO,WAAW,aAAa;AACjC;;AAGA,MAAa,uBAA+C,CAAC,mBAAmB;;AAGhF,MAAa,oBAAoB,CAAC,cAAc,cAAc;;AAG9D,MAAa,2BAA2B,CAAC,GAAG,kBAAkB,GAAG,iBAAiB;AAElF,SAAS,cAAc,OAAqC;CAC1D,OAAQ,cAAoC,SAAS,KAAK;AAC5D;AAEA,SAAS,gBAAgB,OAA2B;CAClD,OAAO,MAAM,WAAW,MAAK,cAC3B,gBAAgB,YACZ,gBAAgB,SAAS,IACxB,kBAAwC,SAAS,UAAU,KAAK,CACvE;AACF;;;;;;AAOA,SAAgB,mBAAmB,IAAuB,MAAuC;CAC/F,IAAI,GAAG,WAAW,GAAG,OAAO;CAC5B,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,SAAS,GAAG,QAAQ,OAAO;CAC3C,KAAK,MAAM,SAAS,IAAI;EACtB,IAAK,gBAAsC,SAAS,KAAK,GACvD,OAAO,IAAI,MAAM;EAEnB,IAAI,CAAC,cAAc,KAAK,GAAG,OAAO,IAAI,MAAM,qCAAqC,cAAc,KAAK,IAAI,EAAE;CAC5G;CACA,IAAI,QAAQ,GAAG,OAAM,UAAS,UAAU,mBAAmB,KAAK,gBAAgB,IAAI,GAClF,OAAO;CAET,OAAO;AACT"}
|