@lovable.dev/workflows-sdk 0.0.0-dev → 0.0.0-dev.2

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,43 @@ 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
+
107
+ Graph inference reads the app's own `typescript`, an optional peer. Apps built
108
+ from a Lovable template already have it. Without it — or with a copy exposing no
109
+ stable JS API, as TypeScript 7 does before 7.1 — the build still succeeds and
110
+ every graph carries one `unknown` node and the diagnostic
111
+ `Install typescript to infer step graphs`.
112
+ Sequential awaited `ctx.step("name", callback)` calls produce order edges;
113
+ `await Promise.all([ctx.step(...), ctx.step(...)])` produces parallel branches
114
+ that join at the next step. Returned step promises work too. Keep step IDs literal.
115
+
116
+ | Field | Meaning |
117
+ | --- | --- |
118
+ | `nodes[].id` | Unique occurrence ID within this graph; use as the UI node key |
119
+ | `nodes[].kind` | `step` or `unknown` |
120
+ | `nodes[].stepId` | Literal step name, present for known steps |
121
+ | `nodes[].label` | Step name or explanation of unsupported code |
122
+ | `edges[]` | `{ source, target, kind: "order" }`, referencing node IDs |
123
+ | `complete` | Whether the handler uses only supported syntax |
124
+ | `diagnostics` | Reasons the graph is partial |
125
+
126
+ For example, `read` followed by parallel `transform-a` and `transform-b`, then
127
+ `save`, produces `read → transform-a → save` and `read → transform-b → save`.
128
+ Repeated step names remain separate nodes. Node IDs are deterministic for the
129
+ same source, but may change when the handler is edited.
130
+
131
+ Graphs have `source: "inferred"` and `scope: "handler"`. They describe source
132
+ structure, not run history or data dependencies, and exclude middleware and
133
+ initialization. Branches, loops, helper calls, dynamic step IDs, nested steps,
134
+ and unawaited steps produce `unknown` nodes and `complete: false`; steps inside
135
+ unsupported code are not expanded. The UI should show these unknown nodes and
136
+ mark partial graphs. Transforms that rewrite the handler may also produce a
137
+ partial graph. A handler with no steps can have an empty graph.
138
+
102
139
  ## Next PRs
103
140
 
104
141
  Connect the manifest and app code to Lovable deployment and runtime execution.
@@ -0,0 +1,119 @@
1
+ //#region src/graph-extract.ts
2
+ let loaded;
3
+ async function loadTypeScript() {
4
+ if (loaded !== void 0) return loaded;
5
+ try {
6
+ const module = await import("typescript");
7
+ const api = module.default ?? module;
8
+ loaded = typeof api?.createSourceFile === "function" ? api : null;
9
+ } catch {
10
+ loaded = null;
11
+ }
12
+ return loaded;
13
+ }
14
+ async function extractWorkflowGraph(handler) {
15
+ const graph = {
16
+ source: "inferred",
17
+ scope: "handler",
18
+ complete: true,
19
+ nodes: [],
20
+ edges: [],
21
+ diagnostics: []
22
+ };
23
+ function addNode(node, parents) {
24
+ const id = `node-${graph.nodes.length}`;
25
+ graph.nodes.push({
26
+ id,
27
+ ...node
28
+ });
29
+ for (const parent of new Set(parents)) graph.edges.push({
30
+ source: parent,
31
+ target: id,
32
+ kind: "order"
33
+ });
34
+ return [id];
35
+ }
36
+ function unknown(reason, parents) {
37
+ graph.complete = false;
38
+ if (!graph.diagnostics.includes(reason)) graph.diagnostics.push(reason);
39
+ return addNode({
40
+ kind: "unknown",
41
+ label: reason
42
+ }, parents);
43
+ }
44
+ const api = await loadTypeScript();
45
+ if (!api) {
46
+ unknown("Install typescript to infer step graphs", []);
47
+ return graph;
48
+ }
49
+ const ts = api;
50
+ const source = ts.createSourceFile("handler.js", `const handler = ${Function.prototype.toString.call(handler)};`, ts.ScriptTarget.ESNext, true, ts.ScriptKind.JS);
51
+ const declaration = source.statements[0];
52
+ const fn = declaration && ts.isVariableStatement(declaration) ? declaration.declarationList.declarations[0]?.initializer : void 0;
53
+ if (!fn || !ts.isArrowFunction(fn) && !ts.isFunctionExpression(fn) || source.text.includes("[native code]")) {
54
+ unknown("Handler source is unavailable", []);
55
+ return graph;
56
+ }
57
+ const parameter = fn.parameters[0]?.name;
58
+ if (parameter && !ts.isIdentifier(parameter)) {
59
+ unknown("Destructured workflow context is not supported yet", []);
60
+ return graph;
61
+ }
62
+ const context = parameter?.text;
63
+ function contains(node, predicate, skipFunctions = false) {
64
+ if (skipFunctions && ts.isFunctionLike(node)) return false;
65
+ return predicate(node) || Boolean(ts.forEachChild(node, (child) => contains(child, predicate, skipFunctions) || void 0));
66
+ }
67
+ function contextStep(node) {
68
+ return ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === context && node.expression.name.text === "step";
69
+ }
70
+ function expression(node, parents, awaited = false) {
71
+ if (ts.isParenthesizedExpression(node)) return expression(node.expression, parents, awaited);
72
+ if (ts.isAwaitExpression(node)) return expression(node.expression, parents, true);
73
+ if (contextStep(node)) {
74
+ if (!awaited) return unknown("Unawaited steps are not supported yet", parents);
75
+ const stepId = node.arguments[0];
76
+ if (!stepId || !ts.isStringLiteral(stepId) && !ts.isNoSubstitutionTemplateLiteral(stepId)) return unknown("Dynamic step IDs are not supported yet", parents);
77
+ const tails = addNode({
78
+ kind: "step",
79
+ stepId: stepId.text,
80
+ label: stepId.text
81
+ }, parents);
82
+ if (node.arguments.slice(1).some((argument) => contains(argument, contextStep))) return unknown("Nested steps are not supported yet", tails);
83
+ return tails;
84
+ }
85
+ 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])) {
86
+ const elements = node.arguments[0].elements;
87
+ if (elements.some((element) => contains(element, ts.isAwaitExpression, true))) return unknown("Await expressions inside Promise.all are not supported yet", parents);
88
+ return elements.length > 0 ? elements.flatMap((element) => {
89
+ while (ts.isParenthesizedExpression(element)) element = element.expression;
90
+ return ts.isCallExpression(element) ? expression(element, parents, true) : unknown("Dynamic Promise.all entries are not followed", parents);
91
+ }) : parents;
92
+ }
93
+ if (contains(node, (child) => ts.isCallExpression(child) || ts.isAwaitExpression(child) || ts.isNewExpression(child))) return unknown("Helper calls and dynamic expressions are not followed", parents);
94
+ if (ts.isIdentifier(node) && node.text === context) return unknown("Workflow context aliases are not followed", parents);
95
+ return parents;
96
+ }
97
+ let tails = [];
98
+ if (!ts.isBlock(fn.body)) {
99
+ expression(fn.body, tails, true);
100
+ return graph;
101
+ }
102
+ for (const statement of fn.body.statements) {
103
+ if (ts.isReturnStatement(statement)) {
104
+ if (statement.expression) expression(statement.expression, tails, true);
105
+ break;
106
+ }
107
+ if (ts.isVariableStatement(statement)) {
108
+ if (statement.declarationList.declarations.some((item) => contains(item.name, (child) => ts.isIdentifier(child) && (child.text === "Promise" || child.text === context)))) {
109
+ tails = unknown("Shadowed context or Promise bindings are not supported yet", tails);
110
+ break;
111
+ }
112
+ for (const item of statement.declarationList.declarations) if (item.initializer) tails = expression(item.initializer, tails);
113
+ } else if (ts.isExpressionStatement(statement)) tails = expression(statement.expression, tails);
114
+ else tails = unknown("Branches, loops, and other control flow are not supported yet", tails);
115
+ }
116
+ return graph;
117
+ }
118
+ //#endregion
119
+ 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-DIeHMgS8.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-CGLWzaln.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: await 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-DIeHMgS8.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.2",
4
4
  "publishConfig": {
5
5
  "access": "public",
6
6
  "tag": "dev",
@@ -35,19 +35,25 @@
35
35
  "@types/node": "22.13.13",
36
36
  "vite": "^7.3.1",
37
37
  "zod": "^4.1.13",
38
- "tsdown": "^0.22.5"
38
+ "tsdown": "^0.22.5",
39
+ "typescript": "npm:@typescript/typescript6@6.0.2"
39
40
  },
40
41
  "peerDependencies": {
41
- "vite": ">=7.3.1 <9"
42
+ "vite": ">=7.3.1 <9",
43
+ "typescript": ">=5.4"
42
44
  },
43
45
  "peerDependenciesMeta": {
44
46
  "vite": {
45
47
  "optional": true
48
+ },
49
+ "typescript": {
50
+ "optional": true
46
51
  }
47
52
  },
48
53
  "scripts": {
49
54
  "build": "tsdown",
50
- "typecheck": "tsgo -p tsconfig.typecheck.json",
51
- "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\""
55
+ "test": "node --test src/graph.test.mjs",
56
+ "typecheck": "tsc -p tsconfig.typecheck.json",
57
+ "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\" && node scripts/check-deps.mjs \"$tmp/package/package.json\""
52
58
  }
53
59
  }