@lovable.dev/workflows-sdk 0.0.0-dev → 0.0.0-dev.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 CHANGED
@@ -73,8 +73,8 @@ to the app root. For example, `greet` produces `.lovable/workflows/greet.json`.
73
73
  Generation errors fail the build. See [the Vite example](examples/vite.config.ts).
74
74
 
75
75
  Each version-1 manifest contains a single `workflow` with its ID, description,
76
- version, and input/output/state JSON Schemas, plus a `schedules` array containing
77
- only that workflow's schedules and static inputs. It is an SDK discovery format,
76
+ version, and input/output/state JSON Schemas, a `graph` for visualization, and a
77
+ `schedules` array containing only that workflow's schedules and static inputs. It is an SDK discovery format,
78
78
  not the engine's deployment or execution contract. Handlers and middleware stay
79
79
  in app code. Schedule IDs and JSON object keys are sorted for stable output.
80
80
 
@@ -99,6 +99,37 @@ Custom app transform plugins and virtual modules are not loaded by this loader.
99
99
  For another build system, call `await generateManifests(collection)` and make
100
100
  synchronizing the returned manifests to `.lovable/workflows/` a required build step.
101
101
 
102
+ ### Step graph
103
+
104
+ Each manifest's `graph` contains `nodes` and directed `edges`. The SDK parses the
105
+ handler's function source without executing it. No additional registration is needed.
106
+ Sequential awaited `ctx.step("name", callback)` calls produce order edges;
107
+ `await Promise.all([ctx.step(...), ctx.step(...)])` produces parallel branches
108
+ that join at the next step. Returned step promises work too. Keep step IDs literal.
109
+
110
+ | Field | Meaning |
111
+ | --- | --- |
112
+ | `nodes[].id` | Unique occurrence ID within this graph; use as the UI node key |
113
+ | `nodes[].kind` | `step` or `unknown` |
114
+ | `nodes[].stepId` | Literal step name, present for known steps |
115
+ | `nodes[].label` | Step name or explanation of unsupported code |
116
+ | `edges[]` | `{ source, target, kind: "order" }`, referencing node IDs |
117
+ | `complete` | Whether the handler uses only supported syntax |
118
+ | `diagnostics` | Reasons the graph is partial |
119
+
120
+ For example, `read` followed by parallel `transform-a` and `transform-b`, then
121
+ `save`, produces `read → transform-a → save` and `read → transform-b → save`.
122
+ Repeated step names remain separate nodes. Node IDs are deterministic for the
123
+ same source, but may change when the handler is edited.
124
+
125
+ Graphs have `source: "inferred"` and `scope: "handler"`. They describe source
126
+ structure, not run history or data dependencies, and exclude middleware and
127
+ initialization. Branches, loops, helper calls, dynamic step IDs, nested steps,
128
+ and unawaited steps produce `unknown` nodes and `complete: false`; steps inside
129
+ unsupported code are not expanded. The UI should show these unknown nodes and
130
+ mark partial graphs. Transforms that rewrite the handler may also produce a
131
+ partial graph. A handler with no steps can have an empty graph.
132
+
102
133
  ## Next PRs
103
134
 
104
135
  Connect the manifest and app code to Lovable deployment and runtime execution.
@@ -0,0 +1,102 @@
1
+ import * as ts from "typescript";
2
+ //#region src/graph-extract.ts
3
+ function extractWorkflowGraph(handler) {
4
+ const graph = {
5
+ source: "inferred",
6
+ scope: "handler",
7
+ complete: true,
8
+ nodes: [],
9
+ edges: [],
10
+ diagnostics: []
11
+ };
12
+ const source = ts.createSourceFile("handler.js", `const handler = ${Function.prototype.toString.call(handler)};`, ts.ScriptTarget.ESNext, true, ts.ScriptKind.JS);
13
+ function addNode(node, parents) {
14
+ const id = `node-${graph.nodes.length}`;
15
+ graph.nodes.push({
16
+ id,
17
+ ...node
18
+ });
19
+ for (const parent of new Set(parents)) graph.edges.push({
20
+ source: parent,
21
+ target: id,
22
+ kind: "order"
23
+ });
24
+ return [id];
25
+ }
26
+ function unknown(reason, parents) {
27
+ graph.complete = false;
28
+ if (!graph.diagnostics.includes(reason)) graph.diagnostics.push(reason);
29
+ return addNode({
30
+ kind: "unknown",
31
+ label: reason
32
+ }, parents);
33
+ }
34
+ const declaration = source.statements[0];
35
+ const fn = declaration && ts.isVariableStatement(declaration) ? declaration.declarationList.declarations[0]?.initializer : void 0;
36
+ if (!fn || !ts.isArrowFunction(fn) && !ts.isFunctionExpression(fn) || source.text.includes("[native code]")) {
37
+ unknown("Handler source is unavailable", []);
38
+ return graph;
39
+ }
40
+ const parameter = fn.parameters[0]?.name;
41
+ if (parameter && !ts.isIdentifier(parameter)) {
42
+ unknown("Destructured workflow context is not supported yet", []);
43
+ return graph;
44
+ }
45
+ const context = parameter?.text;
46
+ function contains(node, predicate, skipFunctions = false) {
47
+ if (skipFunctions && ts.isFunctionLike(node)) return false;
48
+ return predicate(node) || Boolean(ts.forEachChild(node, (child) => contains(child, predicate, skipFunctions) || void 0));
49
+ }
50
+ function contextStep(node) {
51
+ return ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === context && node.expression.name.text === "step";
52
+ }
53
+ function expression(node, parents, awaited = false) {
54
+ if (ts.isParenthesizedExpression(node)) return expression(node.expression, parents, awaited);
55
+ if (ts.isAwaitExpression(node)) return expression(node.expression, parents, true);
56
+ if (contextStep(node)) {
57
+ if (!awaited) return unknown("Unawaited steps are not supported yet", parents);
58
+ const stepId = node.arguments[0];
59
+ if (!stepId || !ts.isStringLiteral(stepId) && !ts.isNoSubstitutionTemplateLiteral(stepId)) return unknown("Dynamic step IDs are not supported yet", parents);
60
+ const tails = addNode({
61
+ kind: "step",
62
+ stepId: stepId.text,
63
+ label: stepId.text
64
+ }, parents);
65
+ if (node.arguments.slice(1).some((argument) => contains(argument, contextStep))) return unknown("Nested steps are not supported yet", tails);
66
+ return tails;
67
+ }
68
+ if (awaited && ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === "Promise" && node.expression.name.text === "all" && node.arguments.length === 1 && ts.isArrayLiteralExpression(node.arguments[0])) {
69
+ const elements = node.arguments[0].elements;
70
+ if (elements.some((element) => contains(element, ts.isAwaitExpression, true))) return unknown("Await expressions inside Promise.all are not supported yet", parents);
71
+ return elements.length > 0 ? elements.flatMap((element) => {
72
+ while (ts.isParenthesizedExpression(element)) element = element.expression;
73
+ return ts.isCallExpression(element) ? expression(element, parents, true) : unknown("Dynamic Promise.all entries are not followed", parents);
74
+ }) : parents;
75
+ }
76
+ if (contains(node, (child) => ts.isCallExpression(child) || ts.isAwaitExpression(child) || ts.isNewExpression(child))) return unknown("Helper calls and dynamic expressions are not followed", parents);
77
+ if (ts.isIdentifier(node) && node.text === context) return unknown("Workflow context aliases are not followed", parents);
78
+ return parents;
79
+ }
80
+ let tails = [];
81
+ if (!ts.isBlock(fn.body)) {
82
+ expression(fn.body, tails, true);
83
+ return graph;
84
+ }
85
+ for (const statement of fn.body.statements) {
86
+ if (ts.isReturnStatement(statement)) {
87
+ if (statement.expression) expression(statement.expression, tails, true);
88
+ break;
89
+ }
90
+ if (ts.isVariableStatement(statement)) {
91
+ if (statement.declarationList.declarations.some((item) => contains(item.name, (child) => ts.isIdentifier(child) && (child.text === "Promise" || child.text === context)))) {
92
+ tails = unknown("Shadowed context or Promise bindings are not supported yet", tails);
93
+ break;
94
+ }
95
+ for (const item of statement.declarationList.declarations) if (item.initializer) tails = expression(item.initializer, tails);
96
+ } else if (ts.isExpressionStatement(statement)) tails = expression(statement.expression, tails);
97
+ else tails = unknown("Branches, loops, and other control flow are not supported yet", tails);
98
+ }
99
+ return graph;
100
+ }
101
+ //#endregion
102
+ export { extractWorkflowGraph };
package/dist/index.d.ts CHANGED
@@ -19,6 +19,25 @@ declare function registerWorkflows<const TWorkflows extends readonly AnyWorkflow
19
19
  schedules?: readonly ScheduleDefinition[];
20
20
  }): WorkflowsDefinition<TWorkflows[number]>;
21
21
  //#endregion
22
+ //#region src/graph.d.ts
23
+ interface WorkflowGraph {
24
+ source: "inferred";
25
+ scope: "handler";
26
+ complete: boolean;
27
+ nodes: {
28
+ id: string;
29
+ kind: "step" | "unknown";
30
+ label: string;
31
+ stepId?: string;
32
+ }[];
33
+ edges: {
34
+ source: string;
35
+ target: string;
36
+ kind: "order";
37
+ }[];
38
+ diagnostics: string[];
39
+ }
40
+ //#endregion
22
41
  //#region src/json.d.ts
23
42
  type JsonValue = null | boolean | number | string | JsonValue[] | {
24
43
  [key: string]: JsonValue;
@@ -41,7 +60,8 @@ interface WorkflowManifest {
41
60
  timeZone: string;
42
61
  input: JsonValue;
43
62
  }[];
63
+ graph: WorkflowGraph;
44
64
  }
45
65
  declare function generateManifests(definition: WorkflowsDefinition): Promise<WorkflowManifest[]>;
46
66
  //#endregion
47
- export { type AnyWorkflowDefinition, type Ctx, type ScheduleDefinition, type StepContext, type StepOptions, type WorkflowDefinition, type WorkflowInput, type WorkflowManifest, type WorkflowOutput, type WorkflowState, type WorkflowsDefinition, createMiddleware, createWorkflow, defineSchedule, generateManifests, registerWorkflows };
67
+ export { type AnyWorkflowDefinition, type Ctx, type ScheduleDefinition, type StepContext, type StepOptions, type WorkflowDefinition, type WorkflowGraph, type WorkflowInput, type WorkflowManifest, type WorkflowOutput, type WorkflowState, type WorkflowsDefinition, createMiddleware, createWorkflow, defineSchedule, generateManifests, registerWorkflows };
package/dist/index.js CHANGED
@@ -1,3 +1,3 @@
1
- import { n as registerWorkflows, r as defineSchedule, t as generateManifests } from "./manifest-jkqqGByV.js";
1
+ import { n as registerWorkflows, r as defineSchedule, t as generateManifests } from "./manifest-DYEhsHr3.js";
2
2
  import { createMiddleware, createWorkflow } from "@tanstack/workflow-core";
3
3
  export { createMiddleware, createWorkflow, defineSchedule, generateManifests, registerWorkflows };
@@ -70,6 +70,7 @@ function jsonSchema(schema, direction, label) {
70
70
  }
71
71
  }
72
72
  async function generateManifests(definition) {
73
+ const { extractWorkflowGraph } = await import("./graph-extract-SXSdcip0.js");
73
74
  const collection = registerWorkflows(definition);
74
75
  const manifests = [];
75
76
  for (const workflow of collection.workflows) {
@@ -101,7 +102,8 @@ async function generateManifests(definition) {
101
102
  const manifest = {
102
103
  version: 1,
103
104
  workflow: metadata,
104
- schedules
105
+ schedules,
106
+ graph: extractWorkflowGraph(workflow.handler)
105
107
  };
106
108
  toJson(manifest, "manifest");
107
109
  manifests.push(manifest);
package/dist/vite.js CHANGED
@@ -1,4 +1,4 @@
1
- import { t as generateManifests } from "./manifest-jkqqGByV.js";
1
+ import { t as generateManifests } from "./manifest-DYEhsHr3.js";
2
2
  import { join, resolve } from "node:path";
3
3
  import { createServer } from "vite";
4
4
  import { lstat, mkdir, mkdtemp, readdir, rename, rm, writeFile } from "node:fs/promises";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lovable.dev/workflows-sdk",
3
- "version": "0.0.0-dev",
3
+ "version": "0.0.0-dev.1",
4
4
  "publishConfig": {
5
5
  "access": "public",
6
6
  "tag": "dev",
@@ -28,6 +28,7 @@
28
28
  "dist"
29
29
  ],
30
30
  "dependencies": {
31
+ "typescript": "npm:@typescript/typescript6@6.0.2",
31
32
  "@standard-schema/spec": "^1.1.0",
32
33
  "@tanstack/workflow-core": "0.0.4"
33
34
  },
@@ -47,6 +48,7 @@
47
48
  },
48
49
  "scripts": {
49
50
  "build": "tsdown",
51
+ "test": "node --test src/graph.test.mjs",
50
52
  "typecheck": "tsgo -p tsconfig.typecheck.json",
51
53
  "check:package": "tmp=$(mktemp -d) && pnpm pack --out \"$tmp/pkg.tgz\" && tar -xzf \"$tmp/pkg.tgz\" -C \"$tmp\" && publint \"$tmp/package\" --strict && attw \"$tmp/pkg.tgz\""
52
54
  }