Typescript SDK Integration

[lornakelly]

Closes: #43

Summary

This PR integrates the @serverlessworkflow/sdk package into the diagram editor and creates an abstraction layer that isolates SDK dependencies and provides type-safe workflow parsing and validation.

Changes

• Added @serverlessworkflow/sdk and js-yaml dependencies to the project
• Created workflowSdk.ts abstraction layer with validateWorkflow() and parseWorkflow() functions
• Implemented type-safe error handling using WorkflowParseResult
• Added integration tests to cover valid, invalid, and edge-case inputs in both YAML and JSON formats
• Created test fixtures with valid/invalid workflows in YAML and JSON formats
• Updated core module documentation explaining the abstraction layer's purpose
• Added __snapshots__ to .rat-excludes to exclude generated snapshot files from license header checks

[Copilot]

Pull request overview

This PR integrates the @serverlessworkflow/sdk package into the diagram editor as specified in issue #43. The integration creates a lightweight abstraction layer that isolates SDK dependencies and provides type-safe workflow parsing and validation capabilities. This decouples the diagram editor from SDK-specific implementation details, making it easier to adapt as the specification evolves.

Changes:

• Added @serverlessworkflow/sdk (v1.0.1) as a production dependency with a thin abstraction layer
• Implemented three core functions: deserializeWorkflow(), validateWorkflow(), and parseWorkflow() for workflow processing
• Introduced WorkflowParseResult discriminated union type for type-safe error handling
• Added comprehensive unit tests covering success and error scenarios for all functions
• Created test fixtures with valid and invalid workflow examples in both YAML and JSON formats
• Updated core module documentation to explain the abstraction layer's purpose

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
pnpm-workspace.yaml	Added @serverlessworkflow/sdk v1.0.1 to the shared catalog
pnpm-lock.yaml	Updated lock file with SDK and its dependencies (ajv, js-yaml, etc.)
src/core/workflowSdk.ts	New abstraction layer providing SDK-independent workflow operations
src/core/index.ts	Updated to export the new SDK abstraction functions
src/core/README.md	Added documentation for the workflowSdk module
tests/core/workflowSdk.test.ts	Comprehensive unit tests for all three functions with mocked SDK
tests/fixtures/workflows.ts	Test fixtures containing valid and invalid workflow definitions
package.json	Added @serverlessworkflow/sdk as a production dependency

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 8 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

Comments suppressed due to low confidence (1)

pnpm-workspace.yaml:10

• The PR description states "Added lint config to ignore lock yaml file as oxlint doesnt support it", but no changes to lint configuration files are visible in the provided diffs. Verify whether this change was intended or if the description is inaccurate.

packages:
  - packages/*
catalog:
  "@chromatic-com/storybook": ^5.0.1
  "@serverlessworkflow/sdk": ^1.0.1
  "@storybook/addon-a11y": ^10.2.19
  "@storybook/addon-docs": ^10.2.19
  "@storybook/addon-vitest": ^10.2.19
  "@storybook/react-vite": ^10.2.19
  "@testing-library/dom": ^10.4.1

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[fantonangeli]

Thanks a lot @lornakelly , I wrote a few comments regarding the tests

[fantonangeli]

These are unit tests, and the mocks are useful to verify that we call the SDK correctly
However there is the mock and, if the SDK introduces a bug, we don't have a failing test.
Do you agree to also add a couple of tests, using the real SDK without the mock, but also keeping the mocked tests?

[lornakelly]

Was thinking of this but ultimately decided that calling the sdk directly is more of an integration test than unit so stuck with simple unit tests for a start. I agree though, ill add a few tests that call the sdk directly as well

[lornakelly]

As part of refactor, replaced unit tests with integration tests

[fantonangeli]

result.success is already checked by the expect.
The same for the tests below.

[lornakelly]

The if block is for typescript, not the test itself, i cant access result.workflow without it. Is there a better way you know of? Otherwise, I can add a comment to make it clearer though?

[fantonangeli]

Totally true, I was trying locally.
But I'm worried that if someone accidentally remove:

expect(result.success).toBe(true);

There is a possibility that the test doesn't enter the if.
As a solution, I just tried:

    expect(result).toMatchObject({
      success: true,
      workflow: JSON.parse(BASIC_VALID_WORKFLOW_JSON)
    });

Also using snapshots, which helps with big objects for other tests, and vitest will automatically maintain them:

    expect(result).toMatchSnapshot();

[lornakelly]

Used snapshots in integration tests, thanks for the suggestion!

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.