@decaf-ts/as-graph 0.4.0 → 0.6.0
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 +167 -5
- package/dist/as-graph.cjs +1 -1
- package/dist/as-graph.cjs.map +1 -1
- package/dist/as-graph.js +1 -1
- package/dist/as-graph.js.map +1 -1
- package/lib/cjs/dagster/DagsterGraphExecutionBackend.cjs +102 -11
- package/lib/cjs/dagster/DagsterGraphExecutionBackend.cjs.map +1 -1
- package/lib/cjs/dagster/DagsterGraphQLClient.cjs +738 -0
- package/lib/cjs/dagster/DagsterGraphQLClient.cjs.map +1 -0
- package/lib/cjs/dagster/index.cjs +1 -0
- package/lib/cjs/dagster/index.cjs.map +1 -1
- package/lib/cjs/engine/execution/GraphExecutionEngine.cjs +7 -0
- package/lib/cjs/engine/execution/GraphExecutionEngine.cjs.map +1 -1
- package/lib/cjs/engine/execution/LocalGraphExecutionBackend.cjs +39 -0
- package/lib/cjs/engine/execution/LocalGraphExecutionBackend.cjs.map +1 -1
- package/lib/cjs/engine/index.cjs +1 -0
- package/lib/cjs/engine/index.cjs.map +1 -1
- package/lib/cjs/engine/services/GraphNodeModelService.cjs +129 -0
- package/lib/cjs/engine/services/GraphNodeModelService.cjs.map +1 -0
- package/lib/cjs/engine/services/GraphWorkflowService.cjs +33 -0
- package/lib/cjs/engine/services/GraphWorkflowService.cjs.map +1 -1
- package/lib/cjs/mastra/MastraDefaultStepHandlers.cjs +217 -0
- package/lib/cjs/mastra/MastraDefaultStepHandlers.cjs.map +1 -0
- package/lib/cjs/mastra/MastraEventBridge.cjs +10 -3
- package/lib/cjs/mastra/MastraEventBridge.cjs.map +1 -1
- package/lib/cjs/mastra/MastraGraphExecutionBackend.cjs +111 -13
- package/lib/cjs/mastra/MastraGraphExecutionBackend.cjs.map +1 -1
- package/lib/cjs/mastra/MastraWorkflowCompiler.cjs +3 -3
- package/lib/cjs/mastra/MastraWorkflowCompiler.cjs.map +1 -1
- package/lib/cjs/mastra/index.cjs +1 -0
- package/lib/cjs/mastra/index.cjs.map +1 -1
- package/lib/cjs/mastra/types.cjs +5 -1
- package/lib/cjs/mastra/types.cjs.map +1 -1
- package/lib/cjs/nest/graph/GraphBackendHost.cjs +232 -0
- package/lib/cjs/nest/graph/GraphBackendHost.cjs.map +1 -0
- package/lib/cjs/nest/graph/GraphExecutionModule.cjs +38 -1
- package/lib/cjs/nest/graph/GraphExecutionModule.cjs.map +1 -1
- package/lib/cjs/nest/graph/index.cjs +1 -0
- package/lib/cjs/nest/graph/index.cjs.map +1 -1
- package/lib/cjs/nest/graph/main.cjs +112 -12
- package/lib/cjs/nest/graph/main.cjs.map +1 -1
- package/lib/cjs/ram/GraphNodeRepository.cjs +40 -0
- package/lib/cjs/ram/GraphNodeRepository.cjs.map +1 -0
- package/lib/cjs/ram/index.cjs +1 -0
- package/lib/cjs/ram/index.cjs.map +1 -1
- package/lib/cjs/shared/graph/GraphNodeConverters.cjs +43 -0
- package/lib/cjs/shared/graph/GraphNodeConverters.cjs.map +1 -0
- package/lib/cjs/shared/graph/GraphNodeModel.cjs +74 -0
- package/lib/cjs/shared/graph/GraphNodeModel.cjs.map +1 -0
- package/lib/cjs/shared/graph/index.cjs +2 -0
- package/lib/cjs/shared/graph/index.cjs.map +1 -1
- package/lib/esm/dagster/DagsterGraphExecutionBackend.js +102 -11
- package/lib/esm/dagster/DagsterGraphExecutionBackend.js.map +1 -1
- package/lib/esm/dagster/DagsterGraphQLClient.js +733 -0
- package/lib/esm/dagster/DagsterGraphQLClient.js.map +1 -0
- package/lib/esm/dagster/index.js +1 -0
- package/lib/esm/dagster/index.js.map +1 -1
- package/lib/esm/engine/execution/GraphExecutionBackend.js.map +1 -1
- package/lib/esm/engine/execution/GraphExecutionEngine.js +7 -0
- package/lib/esm/engine/execution/GraphExecutionEngine.js.map +1 -1
- package/lib/esm/engine/execution/LocalGraphExecutionBackend.js +39 -0
- package/lib/esm/engine/execution/LocalGraphExecutionBackend.js.map +1 -1
- package/lib/esm/engine/index.js +1 -0
- package/lib/esm/engine/index.js.map +1 -1
- package/lib/esm/engine/services/GraphNodeModelService.js +120 -0
- package/lib/esm/engine/services/GraphNodeModelService.js.map +1 -0
- package/lib/esm/engine/services/GraphWorkflowService.js +34 -1
- package/lib/esm/engine/services/GraphWorkflowService.js.map +1 -1
- package/lib/esm/mastra/MastraCapabilities.js.map +1 -1
- package/lib/esm/mastra/MastraDefaultStepHandlers.js +212 -0
- package/lib/esm/mastra/MastraDefaultStepHandlers.js.map +1 -0
- package/lib/esm/mastra/MastraEventBridge.js +10 -3
- package/lib/esm/mastra/MastraEventBridge.js.map +1 -1
- package/lib/esm/mastra/MastraGraphExecutionBackend.js +112 -14
- package/lib/esm/mastra/MastraGraphExecutionBackend.js.map +1 -1
- package/lib/esm/mastra/MastraWorkflowCompiler.js +3 -3
- package/lib/esm/mastra/MastraWorkflowCompiler.js.map +1 -1
- package/lib/esm/mastra/index.js +1 -0
- package/lib/esm/mastra/index.js.map +1 -1
- package/lib/esm/mastra/types.js +4 -0
- package/lib/esm/mastra/types.js.map +1 -1
- package/lib/esm/nest/graph/GraphBackendHost.js +189 -0
- package/lib/esm/nest/graph/GraphBackendHost.js.map +1 -0
- package/lib/esm/nest/graph/GraphExecutionModule.js +39 -2
- package/lib/esm/nest/graph/GraphExecutionModule.js.map +1 -1
- package/lib/esm/nest/graph/index.js +1 -0
- package/lib/esm/nest/graph/index.js.map +1 -1
- package/lib/esm/nest/graph/main.js +79 -12
- package/lib/esm/nest/graph/main.js.map +1 -1
- package/lib/esm/ram/GraphNodeRepository.js +31 -0
- package/lib/esm/ram/GraphNodeRepository.js.map +1 -0
- package/lib/esm/ram/index.js +1 -0
- package/lib/esm/ram/index.js.map +1 -1
- package/lib/esm/shared/graph/GraphNodeConverters.js +38 -0
- package/lib/esm/shared/graph/GraphNodeConverters.js.map +1 -0
- package/lib/esm/shared/graph/GraphNodeModel.js +65 -0
- package/lib/esm/shared/graph/GraphNodeModel.js.map +1 -0
- package/lib/esm/shared/graph/index.js +2 -0
- package/lib/esm/shared/graph/index.js.map +1 -1
- package/lib/types/dagster/DagsterGraphExecutionBackend.d.cts +40 -4
- package/lib/types/dagster/DagsterGraphExecutionBackend.d.mts +40 -4
- package/lib/types/dagster/DagsterGraphQLClient.d.cts +231 -0
- package/lib/types/dagster/DagsterGraphQLClient.d.mts +231 -0
- package/lib/types/dagster/index.d.cts +1 -0
- package/lib/types/dagster/index.d.mts +1 -0
- package/lib/types/engine/execution/GraphExecutionBackend.d.cts +27 -0
- package/lib/types/engine/execution/GraphExecutionBackend.d.mts +27 -0
- package/lib/types/engine/execution/GraphExecutionEngine.d.cts +9 -0
- package/lib/types/engine/execution/GraphExecutionEngine.d.mts +9 -0
- package/lib/types/engine/execution/LocalGraphExecutionBackend.d.cts +14 -0
- package/lib/types/engine/execution/LocalGraphExecutionBackend.d.mts +14 -0
- package/lib/types/engine/index.d.cts +1 -0
- package/lib/types/engine/index.d.mts +1 -0
- package/lib/types/engine/services/GraphNodeModelService.d.cts +54 -0
- package/lib/types/engine/services/GraphNodeModelService.d.mts +54 -0
- package/lib/types/engine/services/GraphWorkflowService.d.cts +21 -0
- package/lib/types/engine/services/GraphWorkflowService.d.mts +21 -0
- package/lib/types/mastra/MastraCapabilities.d.cts +0 -5
- package/lib/types/mastra/MastraCapabilities.d.mts +0 -5
- package/lib/types/mastra/MastraDefaultStepHandlers.d.cts +74 -0
- package/lib/types/mastra/MastraDefaultStepHandlers.d.mts +74 -0
- package/lib/types/mastra/MastraGraphExecutionBackend.d.cts +29 -0
- package/lib/types/mastra/MastraGraphExecutionBackend.d.mts +29 -0
- package/lib/types/mastra/MastraWorkflowCompiler.d.cts +3 -3
- package/lib/types/mastra/MastraWorkflowCompiler.d.mts +3 -3
- package/lib/types/mastra/index.d.cts +1 -0
- package/lib/types/mastra/index.d.mts +1 -0
- package/lib/types/mastra/types.d.cts +12 -0
- package/lib/types/mastra/types.d.mts +12 -0
- package/lib/types/nest/graph/GraphBackendHost.d.cts +152 -0
- package/lib/types/nest/graph/GraphBackendHost.d.mts +152 -0
- package/lib/types/nest/graph/GraphExecutionModule.d.cts +23 -0
- package/lib/types/nest/graph/GraphExecutionModule.d.mts +23 -0
- package/lib/types/nest/graph/index.d.cts +1 -0
- package/lib/types/nest/graph/index.d.mts +1 -0
- package/lib/types/ram/GraphNodeRepository.d.cts +13 -0
- package/lib/types/ram/GraphNodeRepository.d.mts +13 -0
- package/lib/types/ram/index.d.cts +1 -0
- package/lib/types/ram/index.d.mts +1 -0
- package/lib/types/shared/graph/GraphNodeConverters.d.cts +15 -0
- package/lib/types/shared/graph/GraphNodeConverters.d.mts +15 -0
- package/lib/types/shared/graph/GraphNodeModel.d.cts +24 -0
- package/lib/types/shared/graph/GraphNodeModel.d.mts +24 -0
- package/lib/types/shared/graph/index.d.cts +2 -0
- package/lib/types/shared/graph/index.d.mts +2 -0
- package/package.json +15 -3
package/README.md
CHANGED
|
@@ -144,10 +144,10 @@ npm install @decaf-ts/as-graph
|
|
|
144
144
|
|
|
145
145
|
| Import | Contains |
|
|
146
146
|
| --- | --- |
|
|
147
|
-
| `@decaf-ts/as-graph` | Backend engine: `GraphExecutionEngine`, planning, validation, auth, loops, pinning, run lifecycle, value store,
|
|
148
|
-
| `@decaf-ts/as-graph/shared` | UI-known contracts: `@node`/`@graph`/`@port` decorators, the canonical `GraphWorkflowDocument` and its builder/reader/serializer, manifest catalogue types, constants, and frontend-safe execution-state projections |
|
|
147
|
+
| `@decaf-ts/as-graph` | Backend engine: `GraphExecutionEngine`, planning, validation, auth, loops, pinning, run lifecycle, value store, the built-in node classes, and the node-kind persistence service (`GraphNodeModelService`) |
|
|
148
|
+
| `@decaf-ts/as-graph/shared` | UI-known contracts: `@node`/`@graph`/`@port` decorators, the canonical `GraphWorkflowDocument` and its builder/reader/serializer, manifest catalogue types, the persistable `GraphNodeModel` catalogue row with its manifest converters, constants, and frontend-safe execution-state projections |
|
|
149
149
|
| `@decaf-ts/as-graph/nest` | NestJS HTTP/SSE wiring: catalogue, workflow persistence and run-lifecycle controllers |
|
|
150
|
-
| `@decaf-ts/as-graph/ram` | Adapter-backed persistence: `GraphRunModel`/`GraphRunEventModel`/`GraphValueModel` and their `@repository()` classes, the `RamGraphRunStore`/`RamGraphRunEventStore` stores, and the `createRamGraphAdapter` helper |
|
|
150
|
+
| `@decaf-ts/as-graph/ram` | Adapter-backed persistence: `GraphRunModel`/`GraphRunEventModel`/`GraphValueModel` and their `@repository()` classes, the `GraphNodeRepository` node-kind rows, the `RamGraphRunStore`/`RamGraphRunEventStore` stores, and the `createRamGraphAdapter` helper |
|
|
151
151
|
| `@decaf-ts/as-graph/mastra` | Mastra execution backend: `MastraGraphExecutionBackend`, the workflow compiler, condition/event bridges, schema converter, resume guard, and the Mastra capability table. Runs canonical documents on a host-injected `@mastra/core` runtime (pinned `1.74.0`) |
|
|
152
152
|
| `@decaf-ts/as-graph/dagster` | Dagster execution backend: `DagsterGraphExecutionBackend`, the workflow translator, event bridge, result mapper, capability table (`DAGSTER_CAPABILITY_TABLE`), and Dagster identifier/condition-grammar helpers. Driven through a host-injected `DagsterClient` port against the pinned engine contract (`1.13.25`; Dagster is Python-side, there is no JavaScript runtime dependency) |
|
|
153
153
|
|
|
@@ -407,7 +407,7 @@ A backend declares its contract to the facade:
|
|
|
407
407
|
| `local` | Whether the backend executes in-process. |
|
|
408
408
|
| `codeMode` | `"hostSide"` (code-mode surfaces run through the facade-owned sandbox evaluator) or `"unsupported"`. The facade fails closed with `GRAPH_CODE_MODE_UNSUPPORTED_BACKEND` before delegating a code-mode workflow to any backend that is not local and not `"hostSide"`. |
|
|
409
409
|
| `capabilities` | Optional `GraphBackendCapabilities` (`codeMode` plus `workflows: { list, get }`). When omitted, the facade derives them from the declared `codeMode` and the presence of the optional `listWorkflows`/`getWorkflow` methods (`resolveGraphBackendCapabilities`), so an unsupported operation is reported as `not_supported` instead of silently returning an empty result. |
|
|
410
|
-
| optional methods | `listWorkflows` / `getWorkflow` (workflow catalogue seam), `cancel`, `resume`, `release`, `dispose`. |
|
|
410
|
+
| optional methods | `listWorkflows` / `getWorkflow` (workflow catalogue seam), `seedWorkflows` (workflow seeding seam), `cancel`, `resume`, `release`, `dispose`. |
|
|
411
411
|
|
|
412
412
|
Engine-level reads of the active backend: `engine.backend`,
|
|
413
413
|
`engine.backendCapabilities`, `engine.listWorkflows()` (active backend),
|
|
@@ -416,6 +416,30 @@ and the flavour-scoped `engine.listEngineWorkflows(flavour)` /
|
|
|
416
416
|
with `GRAPH_EXECUTION_BACKEND_NOT_REGISTERED` (unknown flavour) or
|
|
417
417
|
`GRAPH_BACKEND_WORKFLOWS_NOT_SUPPORTED` (no listing/lookup support).
|
|
418
418
|
|
|
419
|
+
##### Workflow seeding
|
|
420
|
+
|
|
421
|
+
Every backend exposes an optional `seedWorkflows(documents)` seam so a host can
|
|
422
|
+
register canonical `GraphWorkflowDocument`s into the driver's own persistence at
|
|
423
|
+
boot — each driver seeds into its own storage and serves the seeded entries
|
|
424
|
+
through its normal `listWorkflows`/`getWorkflow` path:
|
|
425
|
+
|
|
426
|
+
- `local` persists each document through the wired `workflowStore` write path
|
|
427
|
+
(`saveDocument`), so seeding honours the same boundary validation and
|
|
428
|
+
ownership rules as any other write, and fails closed with
|
|
429
|
+
`GRAPH_BACKEND_SEED_NOT_SUPPORTED` when no writable store is configured.
|
|
430
|
+
- `mastra` registers the documents in its compiled-workflow cache, so seeded
|
|
431
|
+
entries are served exactly like a workflow recorded by `execute`; seeded
|
|
432
|
+
entries are owner-less and therefore visible to every caller.
|
|
433
|
+
- `dagster` adds the documents to its read-only catalogue map alongside the
|
|
434
|
+
deployment's jobs — a host boot action, never an authoring surface: authoring
|
|
435
|
+
capabilities stay `not_supported`.
|
|
436
|
+
|
|
437
|
+
The engine facade wires it at boot: passing
|
|
438
|
+
`seedWorkflows: GraphWorkflowDocument[]` in the `GraphExecutionEngineConfig`
|
|
439
|
+
(or `GraphExecutionModuleOptions.seedWorkflows` for the NestJS module) makes the
|
|
440
|
+
engine call the active backend's `seedWorkflows` during `boot()`, failing closed
|
|
441
|
+
with `GRAPH_BACKEND_SEED_NOT_SUPPORTED` when the backend does not implement it.
|
|
442
|
+
|
|
419
443
|
##### Mastra backend (`@decaf-ts/as-graph/mastra`)
|
|
420
444
|
|
|
421
445
|
`MastraGraphExecutionBackend` translates the canonical document into a Mastra
|
|
@@ -492,6 +516,7 @@ Run lifecycle and cached/pinned-value persistence always flows through Decaf rep
|
|
|
492
516
|
| `GraphRunModel` / `GraphRunRepository` | Run lifecycle records (durable run history), persisted as `graph_run` rows |
|
|
493
517
|
| `GraphRunEventModel` / `GraphRunEventRepository` | Run event envelopes (SSE replay/audit), persisted as `graph_run_event` rows; live subscribers stay in-process |
|
|
494
518
|
| `GraphValueModel` / `GraphValueRepository` | Cached/pinned graph values (must survive restarts for pinning), persisted as `graph_value` rows; per-execution runtime values are not persisted |
|
|
519
|
+
| `GraphNodeRepository` | Node-kind catalogue rows (one row per registered kind, persisted as `graph_node`); the `GraphNodeModel` row class lives in `./shared` so backend stores and UI listing/forms share it |
|
|
495
520
|
| `RamGraphRunStore` / `RamGraphRunEventStore` | Adapter-backed `GraphRunStore`/`GraphRunEventStore` implementations; construct with an initialized adapter |
|
|
496
521
|
| `createRamGraphAdapter(alias?)` | Creates and initializes a `RamAdapter` (tests); production passes a durable adapter (e.g. TypeORM) |
|
|
497
522
|
| `createGraphValueRepository(adapter)` | Factory for a fresh `GraphValueRepository` instance over the provided adapter |
|
|
@@ -549,6 +574,12 @@ summaries, `POST /graph/workflows/validate`), the asynchronous run lifecycle (`P
|
|
|
549
574
|
The engine provider is a Decaf `ClientBasedService`: the module constructs `new GraphExecutionEngine()`
|
|
550
575
|
and initializes it with `await engine.boot(config)`.
|
|
551
576
|
|
|
577
|
+
The module also mirrors the populated node catalogue into repository-backed rows at boot: a
|
|
578
|
+
`GraphNodeModelService` provider upserts every registered node-kind manifest as a `GraphNodeModel`
|
|
579
|
+
row (`syncFromCatalogue`), so node kinds are exposed through repository/adapter CRUD and listing
|
|
580
|
+
(`GraphNodeRepository`) for whichever engine the host booted — mirroring the
|
|
581
|
+
`GraphWorkflowService`/`GraphRunModelService` persistence pattern.
|
|
582
|
+
|
|
552
583
|
The engine capability API serves a statically-derived, boot-time capability manifest
|
|
553
584
|
(`GraphEngineCapabilityService`): it is built once from the backends registered in the
|
|
554
585
|
`GraphExecutionBackendRegistry`, only allowlisted flavours (`local`, `mastra`, `dagster`) are advertised,
|
|
@@ -590,6 +621,7 @@ an authenticated owner user is rejected with `401`) and can be relaxed to `"opti
|
|
|
590
621
|
| `initAdapter` / `adapterUser` | Secure-default adapter bootstrap: only `initAdapter: true` installs a standalone `RamAdapter`; otherwise the host must have configured a Decaf adapter via `DecafModule.forRoot(...)`, and construction fails closed with a `GraphStoreError` when none is current |
|
|
591
622
|
| `valueAdapter` | Adapter backing cached/pinned value persistence; falls back to the globally configured adapter (`Adapter.current`) |
|
|
592
623
|
| `runAdapter` | Adapter backing run and run-event persistence; falls back to `valueAdapter`, then to `Adapter.current`. Runs and run events always persist through the adapter-backed `@repository()` stores (`RamGraphRunStore` / `RamGraphRunEventStore`) — never a process-local map |
|
|
624
|
+
| `seedWorkflows` | Canonical workflow documents seeded into the active backend at boot through the backend's `seedWorkflows` seam (see [Workflow seeding](#workflow-seeding)) |
|
|
593
625
|
| `credentialAuthorizer` | Stage-8 credential existence/authorization hook wired into the engine's document validator; without it, credential checks are shape/type-only |
|
|
594
626
|
| `authHandler` | `AuthHandler` class installed via `DecafAuthModule.forRoot` (the for-nest pattern; typical values: `KeycloakAuthHandler` / `KeycloakNamespaceAuthHandler` from `@decaf-ts/integrations/nest`). It primes every request context with the authenticated `user` / `roles` / `namespaces` / `organization`, which `GraphAuthValidator` authorizes each workflow and node against |
|
|
595
627
|
| `authGlobal` | When `true` (default when `authHandler` is set), the auth interceptor is registered globally; `false` installs the handler without a global interceptor (routes opt in with `@Auth()`) |
|
|
@@ -620,11 +652,141 @@ import { KeycloakAuthHandler } from "@decaf-ts/integrations/nest";
|
|
|
620
652
|
export class AppModule {}
|
|
621
653
|
```
|
|
622
654
|
|
|
655
|
+
#### Running each backend + UI combination
|
|
656
|
+
|
|
657
|
+
The standalone host (`bin.as-graph-server`, `lib/cjs/nest/graph/main.cjs`) boots exactly one engine
|
|
658
|
+
variant, selected by `GRAPH_BACKEND_ENGINE`, and serves the C20 capability manifest
|
|
659
|
+
(`GET /graph/engines`) plus the per-engine workflow catalogue
|
|
660
|
+
(`GET /graph/engines/{engineId}/workflows`). The for-angular graph page talks to it over
|
|
661
|
+
`http://localhost:3000` (`GRAPH_BACKEND_URL`) and needs no code change when the variant changes — it
|
|
662
|
+
lists whatever the backend advertises and gates its actions on the served capabilities.
|
|
663
|
+
|
|
664
|
+
**Build first.** The scripts run the compiled entrypoint, so `npm run build` (or `build:prod`) must
|
|
665
|
+
have produced `lib/cjs/nest/graph/main.cjs`.
|
|
666
|
+
|
|
667
|
+
| Combination | Boot the backend | Run the UI | Backend port | Extra prerequisites |
|
|
668
|
+
| --- | --- | --- | --- | --- |
|
|
669
|
+
| standard (local engine) | `npm run start:backend` / `start:backend:local` | `npm run start` (for-angular, `:8110`) | `3000` | none — built-in reference interpreter |
|
|
670
|
+
| mastra | `npm run start:backend:mastra` | `npm run start` (for-angular, `:8110`) | `3000` | `@mastra/core` peer installed (`^1.77.0`) |
|
|
671
|
+
| dagster | `npm run start:backend:dagster` | `npm run start` (for-angular, `:8110`) | `3000` | a Dagster gateway + `DAGSTER_GRAPHQL_URL` (see below) |
|
|
672
|
+
|
|
673
|
+
From `for-angular`, `npm run start:dev` (local), `start:dev:mastra`, and `start:dev:dagster` boot
|
|
674
|
+
the backend and the UI together with `concurrently`.
|
|
675
|
+
|
|
676
|
+
| Variable | Default | Meaning |
|
|
677
|
+
| --- | --- | --- |
|
|
678
|
+
| `GRAPH_BACKEND_ENGINE` | `local` | `local` \| `mastra` \| `dagster`; an unknown value fails closed with `GRAPH_BACKEND_ENGINE_UNKNOWN` |
|
|
679
|
+
| `GRAPH_BACKEND_PORT` | `3000` | Backend HTTP port (the standalone binary also accepts the port as its first argument) |
|
|
680
|
+
| `DAGSTER_GRAPHQL_URL` | unset | Read-only Dagster client target. Without it the dagster backend still boots and serves the manifest, but the catalogue reports `NOT_SUPPORTED` (`501`) |
|
|
681
|
+
| `DAGSTER_EXECUTION_ENABLED` | `false` | Opt-in gate for launching/replaying existing Dagster runs |
|
|
682
|
+
| `GRAPH_BACKEND_URL` | `http://localhost:3000` | for-angular injection token for the backend base URL (a provider override, not an env var) |
|
|
683
|
+
|
|
684
|
+
The host binds to `127.0.0.1` and only admits `http://localhost`/`http://127.0.0.1` CORS origins
|
|
685
|
+
(development posture, SAA-595 F5).
|
|
686
|
+
|
|
687
|
+
##### Demo workflow seeding
|
|
688
|
+
|
|
689
|
+
The standalone host seeds the demo workflow fixture registry into whichever
|
|
690
|
+
engine it boots: `loadGraphDemoWorkflows()` (exported from
|
|
691
|
+
`@decaf-ts/as-graph/nest`) imports the `graphWorkflowFixtures` registry from
|
|
692
|
+
`src/workflows` and passes its canonical documents as `seedWorkflows`, so each
|
|
693
|
+
driver's catalogue lists the full fixture set out of the box. The registry is
|
|
694
|
+
test-only content — `npm pack` excludes `lib/**/workflows` — so a
|
|
695
|
+
release-packaged host boots with an empty seed set and its catalogues behave
|
|
696
|
+
exactly as before (the mastra catalogue starts empty; the dagster catalogue
|
|
697
|
+
needs a wired client).
|
|
698
|
+
|
|
699
|
+
##### Standard (local engine)
|
|
700
|
+
|
|
701
|
+
No backing service. Build the backend, boot it, and run the UI in a second terminal:
|
|
702
|
+
|
|
703
|
+
```bash
|
|
704
|
+
# as-graph
|
|
705
|
+
npm run build && npm run start:backend # http://127.0.0.1:3000 (engine: local)
|
|
706
|
+
# for-angular
|
|
707
|
+
npm run start # http://localhost:8110
|
|
708
|
+
```
|
|
709
|
+
|
|
710
|
+
Verify the backend advertises the local engine:
|
|
711
|
+
|
|
712
|
+
```bash
|
|
713
|
+
curl -s http://127.0.0.1:3000/graph/engines # .defaultEngineId == "local"
|
|
714
|
+
```
|
|
715
|
+
|
|
716
|
+
Open the workflow catalog (`http://localhost:8110/workflows`); the workflow table lists the
|
|
717
|
+
workflows persisted in the backend's local engine store, including the seeded demo fixture set.
|
|
718
|
+
|
|
719
|
+
##### Mastra
|
|
720
|
+
|
|
721
|
+
In-process; the only prerequisite is the `@mastra/core` peer dependency (pinned `^1.77.0`),
|
|
722
|
+
resolved by `npm install` in `as-graph`. The host lazily builds a real `@mastra/core` runtime.
|
|
723
|
+
|
|
724
|
+
```bash
|
|
725
|
+
npm run start:backend:mastra # engine: mastra, still on :3000
|
|
726
|
+
```
|
|
727
|
+
|
|
728
|
+
The Mastra catalogue lists the workflows registered in the process: the seeded demo fixture set
|
|
729
|
+
(see [Demo workflow seeding](#demo-workflow-seeding)) plus every workflow already compiled/executed
|
|
730
|
+
in the process (its `workflowList`/`workflowLookup` capability). The manifest advertises the mastra
|
|
731
|
+
engine and its per-feature verdicts.
|
|
732
|
+
|
|
733
|
+
##### Dagster
|
|
734
|
+
|
|
735
|
+
Dagster is Python-side and has no JavaScript runtime, so the backend lists/executes through a
|
|
736
|
+
host-injected `DagsterClient` built from `DAGSTER_GRAPHQL_URL`. Provision the pinned gateway fixture
|
|
737
|
+
(Docker; Dagster `1.13.25`) with the integration harness:
|
|
738
|
+
|
|
739
|
+
```bash
|
|
740
|
+
# as-graph: boot + seed the pinned gateway and persist its GraphQL URL
|
|
741
|
+
npm run prepare-it-tests # publishes the gateway at http://127.0.0.1:3300/graphql
|
|
742
|
+
DAGSTER_GRAPHQL_URL=http://127.0.0.1:3300/graphql npm run start:backend:dagster
|
|
743
|
+
npm run teardown-it-tests # when done
|
|
744
|
+
```
|
|
745
|
+
|
|
746
|
+
Without `DAGSTER_GRAPHQL_URL` the dagster host still boots and serves the manifest; with the
|
|
747
|
+
seeded fixture set its catalogue lists those fixtures read-only, while a release-packaged host
|
|
748
|
+
with an empty seed set answers `501` (`NOT_SUPPORTED`). To run against an already-running Dagster, set
|
|
749
|
+
`DAGSTER_GRAPHQL_URL` yourself and skip `prepare-it-tests`.
|
|
750
|
+
|
|
751
|
+
> **Environment note (CI sandbox):** inside a container (`/.dockerenv`), the fixture joins the
|
|
752
|
+
> runner's network namespace and binds `127.0.0.1:3000`, which collides with the graph backend's
|
|
753
|
+
> default port. On a normal host the fixture is published at `127.0.0.1:3300`, so there is no
|
|
754
|
+
> collision. Because the for-angular UI is wired to `http://localhost:3000`, run the Dagster gateway
|
|
755
|
+
> on a host (or another namespace) and keep the graph backend on `3000` when exercising the UI +
|
|
756
|
+
> dagster combination.
|
|
757
|
+
|
|
758
|
+
##### Verifying the UI lists a backend's scenarios
|
|
759
|
+
|
|
760
|
+
1. `GET /graph/engines` returns the manifest with `defaultEngineId` equal to the booted variant.
|
|
761
|
+
2. `GET /graph/engines/{engineId}/workflows` returns that engine's catalogue (`200`), or `501` when
|
|
762
|
+
the engine declares no listing support (dagster without a client and without seeded fixtures).
|
|
763
|
+
3. In the UI the workflow table shows the catalogue rows and gates create/run/save per the manifest
|
|
764
|
+
verdicts; switching variants requires no UI code change.
|
|
765
|
+
|
|
766
|
+
##### Running each variant's test suite
|
|
767
|
+
|
|
768
|
+
| Variant | Command |
|
|
769
|
+
| --- | --- |
|
|
770
|
+
| standard (local) | `npm run test:integration:standard` |
|
|
771
|
+
| mastra | `npm run test:integration:mastra` |
|
|
772
|
+
| dagster | `npm run prepare-it-tests` then `npm run test:integration:dagster` (or `npm run teardown-it-tests` after) |
|
|
773
|
+
| backend host boot (all variants + standalone binary) | `npm run test:integration:backend` |
|
|
774
|
+
|
|
775
|
+
The dagster suite needs the gateway fixture (`prepare-it-tests`) and Docker; it skips honestly when
|
|
776
|
+
no gateway is prepared. The standalone-binary boot test needs the `lib/cjs` build and skips when it
|
|
777
|
+
is absent.
|
|
778
|
+
|
|
623
779
|
#### Scripts
|
|
624
780
|
|
|
625
781
|
| Script | Purpose |
|
|
626
782
|
| --- | --- |
|
|
627
|
-
| `npm run build` / `build:prod` | Compile ESM + CJS + types |
|
|
783
|
+
| `npm run build` / `build:prod` | Compile ESM + CJS + types; `postbuild`/`postbuild:prod` run the `check:emitted-specifiers` guard, which fails the build when any relative module specifier in the emitted `lib/cjs`/`lib/esm` output does not resolve |
|
|
784
|
+
| `npm run start:backend` / `start:backend:local` | Boot the standalone host with the built-in local engine (`:3000`) |
|
|
785
|
+
| `npm run start:backend:mastra` | Boot the standalone host with the Mastra engine (`GRAPH_BACKEND_ENGINE=mastra`) |
|
|
786
|
+
| `npm run start:backend:dagster` | Boot the standalone host with the Dagster engine (`GRAPH_BACKEND_ENGINE=dagster`) |
|
|
787
|
+
| `npm run test:integration:standard` / `:mastra` / `:dagster` | Run one engine variant's integration suite |
|
|
788
|
+
| `npm run test:integration:backend` | Run the host-boot integration suite (all variants + standalone binary) |
|
|
789
|
+
| `npm run prepare-it-tests` / `teardown-it-tests` | Provision / stop the pinned Dagster gateway fixture |
|
|
628
790
|
| `npm run test:unit` / `test:integration` / `test:e2e` | Run the Jest unit / integration / e2e suites |
|
|
629
791
|
| `npm run test:all` | Run the entire Jest suite (unit, integration, e2e) |
|
|
630
792
|
| `npm run test:dist` | Re-run the full suite against the compiled `lib` and `dist` outputs |
|