@decaf-ts/as-graph 0.4.0 → 0.5.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.
Files changed (39) hide show
  1. package/README.md +116 -0
  2. package/lib/cjs/dagster/DagsterGraphQLClient.cjs +738 -0
  3. package/lib/cjs/dagster/DagsterGraphQLClient.cjs.map +1 -0
  4. package/lib/cjs/dagster/index.cjs +1 -0
  5. package/lib/cjs/dagster/index.cjs.map +1 -1
  6. package/lib/cjs/nest/graph/GraphBackendHost.cjs +146 -0
  7. package/lib/cjs/nest/graph/GraphBackendHost.cjs.map +1 -0
  8. package/lib/cjs/nest/graph/GraphExecutionModule.cjs +1 -0
  9. package/lib/cjs/nest/graph/GraphExecutionModule.cjs.map +1 -1
  10. package/lib/cjs/nest/graph/index.cjs +1 -0
  11. package/lib/cjs/nest/graph/index.cjs.map +1 -1
  12. package/lib/cjs/nest/graph/main.cjs +97 -12
  13. package/lib/cjs/nest/graph/main.cjs.map +1 -1
  14. package/lib/esm/dagster/DagsterGraphQLClient.js +733 -0
  15. package/lib/esm/dagster/DagsterGraphQLClient.js.map +1 -0
  16. package/lib/esm/dagster/index.js +1 -0
  17. package/lib/esm/dagster/index.js.map +1 -1
  18. package/lib/esm/mastra/MastraCapabilities.js.map +1 -1
  19. package/lib/esm/nest/graph/GraphBackendHost.js +138 -0
  20. package/lib/esm/nest/graph/GraphBackendHost.js.map +1 -0
  21. package/lib/esm/nest/graph/GraphExecutionModule.js +1 -0
  22. package/lib/esm/nest/graph/GraphExecutionModule.js.map +1 -1
  23. package/lib/esm/nest/graph/index.js +1 -0
  24. package/lib/esm/nest/graph/index.js.map +1 -1
  25. package/lib/esm/nest/graph/main.js +64 -12
  26. package/lib/esm/nest/graph/main.js.map +1 -1
  27. package/lib/types/dagster/DagsterGraphQLClient.d.cts +231 -0
  28. package/lib/types/dagster/DagsterGraphQLClient.d.mts +231 -0
  29. package/lib/types/dagster/index.d.cts +1 -0
  30. package/lib/types/dagster/index.d.mts +1 -0
  31. package/lib/types/mastra/MastraCapabilities.d.cts +0 -5
  32. package/lib/types/mastra/MastraCapabilities.d.mts +0 -5
  33. package/lib/types/nest/graph/GraphBackendHost.d.cts +100 -0
  34. package/lib/types/nest/graph/GraphBackendHost.d.mts +100 -0
  35. package/lib/types/nest/graph/GraphExecutionModule.d.cts +12 -0
  36. package/lib/types/nest/graph/GraphExecutionModule.d.mts +12 -0
  37. package/lib/types/nest/graph/index.d.cts +1 -0
  38. package/lib/types/nest/graph/index.d.mts +1 -0
  39. package/package.json +7 -1
package/README.md CHANGED
@@ -620,11 +620,127 @@ import { KeycloakAuthHandler } from "@decaf-ts/integrations/nest";
620
620
  export class AppModule {}
621
621
  ```
622
622
 
623
+ #### Running each backend + UI combination
624
+
625
+ The standalone host (`bin.as-graph-server`, `lib/cjs/nest/graph/main.cjs`) boots exactly one engine
626
+ variant, selected by `GRAPH_BACKEND_ENGINE`, and serves the C20 capability manifest
627
+ (`GET /graph/engines`) plus the per-engine workflow catalogue
628
+ (`GET /graph/engines/{engineId}/workflows`). The for-angular graph page talks to it over
629
+ `http://localhost:3000` (`GRAPH_BACKEND_URL`) and needs no code change when the variant changes — it
630
+ lists whatever the backend advertises and gates its actions on the served capabilities.
631
+
632
+ **Build first.** The scripts run the compiled entrypoint, so `npm run build` (or `build:prod`) must
633
+ have produced `lib/cjs/nest/graph/main.cjs`.
634
+
635
+ | Combination | Boot the backend | Run the UI | Backend port | Extra prerequisites |
636
+ | --- | --- | --- | --- | --- |
637
+ | standard (local engine) | `npm run start:backend` / `start:backend:local` | `npm run start` (for-angular, `:8110`) | `3000` | none — built-in reference interpreter |
638
+ | mastra | `npm run start:backend:mastra` | `npm run start` (for-angular, `:8110`) | `3000` | `@mastra/core` peer installed (`^1.77.0`) |
639
+ | dagster | `npm run start:backend:dagster` | `npm run start` (for-angular, `:8110`) | `3000` | a Dagster gateway + `DAGSTER_GRAPHQL_URL` (see below) |
640
+
641
+ From `for-angular`, `npm run start:dev` (local), `start:dev:mastra`, and `start:dev:dagster` boot
642
+ the backend and the UI together with `concurrently`.
643
+
644
+ | Variable | Default | Meaning |
645
+ | --- | --- | --- |
646
+ | `GRAPH_BACKEND_ENGINE` | `local` | `local` \| `mastra` \| `dagster`; an unknown value fails closed with `GRAPH_BACKEND_ENGINE_UNKNOWN` |
647
+ | `GRAPH_BACKEND_PORT` | `3000` | Backend HTTP port (the standalone binary also accepts the port as its first argument) |
648
+ | `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`) |
649
+ | `DAGSTER_EXECUTION_ENABLED` | `false` | Opt-in gate for launching/replaying existing Dagster runs |
650
+ | `GRAPH_BACKEND_URL` | `http://localhost:3000` | for-angular injection token for the backend base URL (a provider override, not an env var) |
651
+
652
+ The host binds to `127.0.0.1` and only admits `http://localhost`/`http://127.0.0.1` CORS origins
653
+ (development posture, SAA-595 F5).
654
+
655
+ ##### Standard (local engine)
656
+
657
+ No backing service. Build the backend, boot it, and run the UI in a second terminal:
658
+
659
+ ```bash
660
+ # as-graph
661
+ npm run build && npm run start:backend # http://127.0.0.1:3000 (engine: local)
662
+ # for-angular
663
+ npm run start # http://localhost:8110
664
+ ```
665
+
666
+ Verify the backend advertises the local engine:
667
+
668
+ ```bash
669
+ curl -s http://127.0.0.1:3000/graph/engines # .defaultEngineId == "local"
670
+ ```
671
+
672
+ Open the graph route (`http://localhost:8110/graph`); the workflow table lists the workflows
673
+ persisted in the backend's local engine store.
674
+
675
+ ##### Mastra
676
+
677
+ In-process; the only prerequisite is the `@mastra/core` peer dependency (pinned `^1.77.0`),
678
+ resolved by `npm install` in `as-graph`. The host lazily builds a real `@mastra/core` runtime.
679
+
680
+ ```bash
681
+ npm run start:backend:mastra # engine: mastra, still on :3000
682
+ ```
683
+
684
+ The Mastra catalogue lists workflows already compiled/executed in the process (its
685
+ `workflowList`/`workflowLookup` capability), so `GET /graph/engines/mastra/workflows` returns `[]`
686
+ until a workflow is run. The manifest advertises the mastra engine and its per-feature verdicts.
687
+
688
+ ##### Dagster
689
+
690
+ Dagster is Python-side and has no JavaScript runtime, so the backend lists/executes through a
691
+ host-injected `DagsterClient` built from `DAGSTER_GRAPHQL_URL`. Provision the pinned gateway fixture
692
+ (Docker; Dagster `1.13.25`) with the integration harness:
693
+
694
+ ```bash
695
+ # as-graph: boot + seed the pinned gateway and persist its GraphQL URL
696
+ npm run prepare-it-tests # publishes the gateway at http://127.0.0.1:3300/graphql
697
+ DAGSTER_GRAPHQL_URL=http://127.0.0.1:3300/graphql npm run start:backend:dagster
698
+ npm run teardown-it-tests # when done
699
+ ```
700
+
701
+ Without `DAGSTER_GRAPHQL_URL` the dagster host still boots and serves the manifest; its catalogue
702
+ answers `501` (`NOT_SUPPORTED`). To run against an already-running Dagster, set
703
+ `DAGSTER_GRAPHQL_URL` yourself and skip `prepare-it-tests`.
704
+
705
+ > **Environment note (CI sandbox):** inside a container (`/.dockerenv`), the fixture joins the
706
+ > runner's network namespace and binds `127.0.0.1:3000`, which collides with the graph backend's
707
+ > default port. On a normal host the fixture is published at `127.0.0.1:3300`, so there is no
708
+ > collision. Because the for-angular UI is wired to `http://localhost:3000`, run the Dagster gateway
709
+ > on a host (or another namespace) and keep the graph backend on `3000` when exercising the UI +
710
+ > dagster combination.
711
+
712
+ ##### Verifying the UI lists a backend's scenarios
713
+
714
+ 1. `GET /graph/engines` returns the manifest with `defaultEngineId` equal to the booted variant.
715
+ 2. `GET /graph/engines/{engineId}/workflows` returns that engine's catalogue (`200`), or `501` when
716
+ the engine declares no listing support (dagster without a client).
717
+ 3. In the UI the workflow table shows the catalogue rows and gates create/run/save per the manifest
718
+ verdicts; switching variants requires no UI code change.
719
+
720
+ ##### Running each variant's test suite
721
+
722
+ | Variant | Command |
723
+ | --- | --- |
724
+ | standard (local) | `npm run test:integration:standard` |
725
+ | mastra | `npm run test:integration:mastra` |
726
+ | dagster | `npm run prepare-it-tests` then `npm run test:integration:dagster` (or `npm run teardown-it-tests` after) |
727
+ | backend host boot (all variants + standalone binary) | `npm run test:integration:backend` |
728
+
729
+ The dagster suite needs the gateway fixture (`prepare-it-tests`) and Docker; it skips honestly when
730
+ no gateway is prepared. The standalone-binary boot test needs the `lib/cjs` build and skips when it
731
+ is absent.
732
+
623
733
  #### Scripts
624
734
 
625
735
  | Script | Purpose |
626
736
  | --- | --- |
627
737
  | `npm run build` / `build:prod` | Compile ESM + CJS + types |
738
+ | `npm run start:backend` / `start:backend:local` | Boot the standalone host with the built-in local engine (`:3000`) |
739
+ | `npm run start:backend:mastra` | Boot the standalone host with the Mastra engine (`GRAPH_BACKEND_ENGINE=mastra`) |
740
+ | `npm run start:backend:dagster` | Boot the standalone host with the Dagster engine (`GRAPH_BACKEND_ENGINE=dagster`) |
741
+ | `npm run test:integration:standard` / `:mastra` / `:dagster` | Run one engine variant's integration suite |
742
+ | `npm run test:integration:backend` | Run the host-boot integration suite (all variants + standalone binary) |
743
+ | `npm run prepare-it-tests` / `teardown-it-tests` | Provision / stop the pinned Dagster gateway fixture |
628
744
  | `npm run test:unit` / `test:integration` / `test:e2e` | Run the Jest unit / integration / e2e suites |
629
745
  | `npm run test:all` | Run the entire Jest suite (unit, integration, e2e) |
630
746
  | `npm run test:dist` | Re-run the full suite against the compiled `lib` and `dist` outputs |