@lovable.dev/workflows-sdk 0.0.0-dev.16 → 0.0.0-dev.17

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
@@ -46,9 +46,17 @@ definitions as immutable after registration.
46
46
  See [the authoring example](examples/src/lib/workflows/greet/index.ts) for schemas,
47
47
  typed middleware, and a durable step. The package typecheck includes this example.
48
48
 
49
- Every `ctx.step()` needs a static, user-facing description. Lovable's agent
50
- supplies this text so the workflow UI can explain what the step does before and
51
- during a run:
49
+ Every durable operation needs a static, user-facing description. Lovable's
50
+ agent supplies this text so the workflow UI can explain each operation before
51
+ and during a run. Put it in the operation's options:
52
+
53
+ | Operation | Description field |
54
+ | --- | --- |
55
+ | `ctx.step` | Third argument: `meta.description` |
56
+ | `ctx.sleep`, `ctx.sleepUntil` | Second argument: `meta.description` |
57
+ | `ctx.waitForEvent` | Second argument: `meta.description` |
58
+ | `ctx.now`, `ctx.uuid` | First argument: `meta.description` |
59
+ | `ctx.approve` | First argument: `description` |
52
60
 
53
61
  ```ts
54
62
  await ctx.step("load-customer", () => loadCustomer(ctx.input.customerId), {
@@ -314,7 +322,7 @@ outside this mapped form.
314
322
  | `nodes[].id` | Unique occurrence ID within this graph; use as the UI node key |
315
323
  | `nodes[].kind` | Durable operation, `parallel`, or `unknown` |
316
324
  | `nodes[].stepId` | Runtime durable ID for every statically known operation |
317
- | `nodes[].description` | User-facing description for a static step |
325
+ | `nodes[].description` | User-facing description for every known durable operation |
318
326
  | `nodes[].groupId` | Stable callsite ID for a dynamic parallel node |
319
327
  | `nodes[].cardinality` | `dynamic` for a runtime-sized parallel fan-out |
320
328
  | `nodes[].operation.kind` | Durable operation repeated by a parallel node |
@@ -578,8 +586,10 @@ inside the step and return the key.
578
586
  Each call re-runs the handler from the top. Step bodies run only in their
579
587
  selected request, so side effects belong inside a step.
580
588
 
581
- `next` reports a step's `stepId`, `kind`, and author-supplied `meta`, including
582
- its description and group. It does not report the step input:
589
+ `next` reports an operation's `stepId`, `kind`, and author-supplied `meta`,
590
+ including its description and group. An approval's top-level authoring
591
+ description is copied into runtime metadata for the same response shape. `next`
592
+ does not report a step's input:
583
593
  `ctx.step(id, fn, options)` closes over its arguments rather than declaring
584
594
  them, so the input is not knowable without running `fn`. Deterministic values
585
595
  (`ctx.now`, `ctx.uuid`) are pinned into `memoDelta`, so concurrent calls replay
@@ -593,14 +603,16 @@ a caller needs to resolve them:
593
603
 
594
604
  ```json
595
605
  { "seq": 1, "stepId": "approve:Approve refund", "kind": "approve",
596
- "config": { "title": "Approve refund", "description": "refund of $40" } }
606
+ "meta": { "description": "Ask a reviewer to approve the refund" },
607
+ "config": { "title": "Approve refund", "description": "Ask a reviewer to approve the refund" } }
597
608
  ```
598
609
 
599
610
  The endpoint returns `waiting` with that list in `next`. Resume by appending the
600
- decision to the memo and calling `advance`:
611
+ decision to the memo, preserving its `meta`, and calling `advance`:
601
612
 
602
613
  ```jsonc
603
614
  { "seq": 1, "stepId": "approve:Approve refund", "kind": "approve",
615
+ "meta": { "description": "Ask a reviewer to approve the refund" },
604
616
  "status": "completed", "result": { "approved": true, "approvalId": "apr_1" } }
605
617
  ```
606
618
 
@@ -1,5 +1,5 @@
1
1
  import { t as defaultDurableId } from "./durable-ids-LsygHSZC.js";
2
- import { loadTypeScript } from "./graph-BEfFBC6v.js";
2
+ import { loadTypeScript } from "./graph-DW4JTyGa.js";
3
3
  //#region src/manifests/duplicate-ids.ts
4
4
  /** Where an explicit `{ id }` would sit for each operation. */
5
5
  const optionsArgument = {
@@ -183,10 +183,11 @@ function serializeSchema(schema, direction, label) {
183
183
  }
184
184
  }
185
185
  async function generateManifests(definition) {
186
- const { extractWorkflowGraph } = await import("./graph-BEfFBC6v.js");
187
- const { findDuplicateOperationIds } = await import("./duplicate-ids-CosMS6qZ.js");
188
- const { findNestedDurableOperations } = await import("./nested-operations-hWj5wt1m.js");
189
- const { findStepMetadataIssues } = await import("./step-metadata-Cly35okS.js");
186
+ const { extractWorkflowGraph } = await import("./graph-DW4JTyGa.js");
187
+ const { findDuplicateOperationIds } = await import("./duplicate-ids-DeCwJVrP.js");
188
+ const { findNestedDurableOperations } = await import("./nested-operations-CPCNe0xy.js");
189
+ const { findOperationDescriptionIssues } = await import("./operation-descriptions-BalrfRnU.js");
190
+ const { findStepMetadataIssues } = await import("./step-metadata-CIGA9vth.js");
190
191
  const collection = registerWorkflows(definition);
191
192
  const manifests = [];
192
193
  for (const workflow of collection.workflows) {
@@ -214,6 +215,12 @@ async function generateManifests(definition) {
214
215
  throw new Error(`@lovable.dev/workflows-sdk: workflow "${workflow.id}" ${step} is declared in a loop or callback and must include a static { meta: { group: { id: "...", label: "..." } } }`);
215
216
  }
216
217
  if (metadataIssue?.kind === "duplicate-group") throw new Error(`@lovable.dev/workflows-sdk: workflow "${workflow.id}" uses group id ${JSON.stringify(metadataIssue.groupId)} at more than one repeated step callsite; every group id must identify one callsite`);
218
+ const operationDescriptionIssue = (await findOperationDescriptionIssues(workflow.handler))[0];
219
+ if (operationDescriptionIssue) {
220
+ const { method } = operationDescriptionIssue;
221
+ const description = method === "approve" ? "{ description: \"...\" }" : "{ meta: { description: \"...\" } }";
222
+ throw new Error(`@lovable.dev/workflows-sdk: workflow "${workflow.id}" ctx.${method}() must include a static ${description}`);
223
+ }
217
224
  const metadata = {
218
225
  id: workflow.id,
219
226
  ...workflow.description === void 0 ? {} : { description: workflow.description },
@@ -5,7 +5,9 @@ const durableMethods = {
5
5
  approve: 0,
6
6
  waitForEvent: 0,
7
7
  sleep: 0,
8
- sleepUntil: 0
8
+ sleepUntil: 0,
9
+ now: 0,
10
+ uuid: 0
9
11
  };
10
12
  let loaded;
11
13
  async function loadTypeScript() {
@@ -140,7 +142,7 @@ async function extractWorkflowGraph(handler) {
140
142
  if (!groupOptions) return { description };
141
143
  const id = stringLiteral(option(groupOptions, "id"));
142
144
  const label = stringLiteral(option(groupOptions, "label"));
143
- return id === void 0 || label === void 0 ? void 0 : {
145
+ return id === void 0 || label === void 0 ? { description } : {
144
146
  description,
145
147
  group: {
146
148
  id,
@@ -148,6 +150,9 @@ async function extractWorkflowGraph(handler) {
148
150
  }
149
151
  };
150
152
  }
153
+ function operationDescription(options) {
154
+ return stringLiteral(option(readableOptions(option(options, "meta")), "description"));
155
+ }
151
156
  function durableStepId(argument, options, fallback) {
152
157
  if (argument && !options) return void 0;
153
158
  const given = option(options, "id");
@@ -176,15 +181,15 @@ async function extractWorkflowGraph(handler) {
176
181
  title
177
182
  }));
178
183
  if (stepId === void 0) return unknown("Dynamic approval IDs are not supported yet", parents);
179
- const given = option(options, "description");
180
- const description = stringLiteral(given);
181
- if (given && description === void 0) degrade("Dynamic approval descriptions are not recorded");
184
+ const description = stringLiteral(option(options, "description"));
185
+ if (description === void 0) return unknown("Approval descriptions must be static strings", parents);
182
186
  return addNode({
183
187
  kind: "approve",
184
188
  stepId,
189
+ description,
185
190
  config: {
186
191
  title,
187
- ...description === void 0 ? {} : { description }
192
+ description
188
193
  },
189
194
  label: title
190
195
  }, parents);
@@ -198,12 +203,15 @@ async function extractWorkflowGraph(handler) {
198
203
  name: event
199
204
  }));
200
205
  if (stepId === void 0) return unknown("Dynamic waitForEvent IDs are not supported yet", parents);
206
+ const description = operationDescription(options);
207
+ if (description === void 0) return unknown("Wait descriptions must be static strings", parents);
201
208
  const given = option(options, "deadline");
202
209
  const deadline = numberLiteral(given);
203
210
  if (given && deadline === void 0) degrade("Dynamic waitForEvent deadlines are not recorded");
204
211
  return addNode({
205
212
  kind: "wait-for-event",
206
213
  stepId,
214
+ description,
207
215
  config: {
208
216
  event,
209
217
  ...deadline === void 0 ? {} : { deadline }
@@ -220,26 +228,45 @@ async function extractWorkflowGraph(handler) {
220
228
  ms
221
229
  }));
222
230
  if (stepId === void 0) return unknown("Dynamic sleep IDs are not supported yet", parents);
231
+ const description = operationDescription(options);
232
+ if (description === void 0) return unknown("Sleep descriptions must be static strings", parents);
223
233
  return addNode({
224
234
  kind: "sleep",
225
235
  stepId,
236
+ description,
226
237
  config: { ms },
227
238
  label: `sleep ${ms}ms`
228
239
  }, parents);
229
240
  }
230
- const timestamp = numberLiteral(call.arguments[0]);
231
- if (timestamp === void 0) return unknown("Dynamic sleepUntil timestamps are not supported yet", parents);
232
- const options = readableOptions(call.arguments[1]);
233
- const stepId = durableStepId(call.arguments[1], options, defaultDurableId({
234
- kind: "sleepUntil",
235
- timestamp
236
- }));
237
- if (stepId === void 0) return unknown("Dynamic sleepUntil IDs are not supported yet", parents);
241
+ if (method === "sleepUntil") {
242
+ const timestamp = numberLiteral(call.arguments[0]);
243
+ if (timestamp === void 0) return unknown("Dynamic sleepUntil timestamps are not supported yet", parents);
244
+ const options = readableOptions(call.arguments[1]);
245
+ const stepId = durableStepId(call.arguments[1], options, defaultDurableId({
246
+ kind: "sleepUntil",
247
+ timestamp
248
+ }));
249
+ if (stepId === void 0) return unknown("Dynamic sleepUntil IDs are not supported yet", parents);
250
+ const description = operationDescription(options);
251
+ if (description === void 0) return unknown("Sleep descriptions must be static strings", parents);
252
+ return addNode({
253
+ kind: "sleep-until",
254
+ stepId,
255
+ description,
256
+ config: { timestamp },
257
+ label: `sleep until ${timestamp}`
258
+ }, parents);
259
+ }
260
+ const options = readableOptions(call.arguments[0]);
261
+ const stepId = durableStepId(call.arguments[0], options, defaultDurableId({ kind: method }));
262
+ if (stepId === void 0) return unknown(`Dynamic ${method} IDs are not supported yet`, parents);
263
+ const description = operationDescription(options);
264
+ if (description === void 0) return unknown(`${method} descriptions must be static strings`, parents);
238
265
  return addNode({
239
- kind: "sleep-until",
266
+ kind: method,
240
267
  stepId,
241
- config: { timestamp },
242
- label: `sleep until ${timestamp}`
268
+ description,
269
+ label: stepId
243
270
  }, parents);
244
271
  }
245
272
  function expression(node, parents, awaited = false) {
package/dist/index.d.ts CHANGED
@@ -56,8 +56,10 @@ interface WorkflowStepGroup {
56
56
  id: string;
57
57
  label: string;
58
58
  }
59
- type WorkflowStepMetadata = Record<string, unknown> & {
59
+ type WorkflowOperationMetadata = Record<string, unknown> & {
60
60
  description: string;
61
+ };
62
+ type WorkflowStepMetadata = WorkflowOperationMetadata & {
61
63
  group?: WorkflowStepGroup;
62
64
  };
63
65
  //#endregion
@@ -78,13 +80,15 @@ type WorkflowGraphNodeDetails = {
78
80
  } | {
79
81
  kind: "approve";
80
82
  stepId: string;
83
+ description: string;
81
84
  config: {
82
85
  title: string;
83
- description?: string;
86
+ description: string;
84
87
  };
85
88
  } | {
86
89
  kind: "wait-for-event";
87
90
  stepId: string;
91
+ description: string;
88
92
  config: {
89
93
  event: string;
90
94
  deadline?: number;
@@ -92,15 +96,25 @@ type WorkflowGraphNodeDetails = {
92
96
  } | {
93
97
  kind: "sleep";
94
98
  stepId: string;
99
+ description: string;
95
100
  config: {
96
101
  ms: number;
97
102
  };
98
103
  } | {
99
104
  kind: "sleep-until";
100
105
  stepId: string;
106
+ description: string;
101
107
  config: {
102
108
  timestamp: number;
103
109
  };
110
+ } | {
111
+ kind: "now";
112
+ stepId: string;
113
+ description: string;
114
+ } | {
115
+ kind: "uuid";
116
+ stepId: string;
117
+ description: string;
104
118
  } | {
105
119
  kind: "unknown";
106
120
  };
@@ -288,4 +302,4 @@ declare function createStepsHandler(collection: WorkflowCollection, options?: St
288
302
  */
289
303
  declare function toServerSentEventsResponse(events: AsyncIterable<WorkflowEvent>): Response;
290
304
  //#endregion
291
- export { type AnyWorkflowDefinition, type Cadence, type Ctx, type MemoEntry, type OverlapPolicy, type ReplayOutcome, type ResolvedSchedule, type ResolvedTrigger, type ScheduleDefinition, type StepContext, type StepIntent, type StepKind, type StepOptions, type StepReference, type StepResult, type StepsDisposition, type StepsHandler, type StepsHandlerOptions, type StepsRequest, type StepsResponse, type TanStackWorkflowHandler, type TanStackWorkflowHandlerOptions, type TriggerDefinition, type Weekday, type WorkflowCollection, type WorkflowDefinition, type WorkflowGraph, type WorkflowGraphNode, type WorkflowGraphNodeDetails, type WorkflowInput, type WorkflowManifest, type WorkflowOutput, type WorkflowState, type WorkflowStepGroup, type WorkflowStepMetadata, type WorkflowsDefinition, createMiddleware, createStepsHandler, createTanStackWorkflowHandler, createWorkflow, daily, defineSchedule, generateManifests, hourly, registerWorkflows, toServerSentEventsResponse, weekly };
305
+ export { type AnyWorkflowDefinition, type Cadence, type Ctx, type MemoEntry, type OverlapPolicy, type ReplayOutcome, type ResolvedSchedule, type ResolvedTrigger, type ScheduleDefinition, type StepContext, type StepIntent, type StepKind, type StepOptions, type StepReference, type StepResult, type StepsDisposition, type StepsHandler, type StepsHandlerOptions, type StepsRequest, type StepsResponse, type TanStackWorkflowHandler, type TanStackWorkflowHandlerOptions, type TriggerDefinition, type Weekday, type WorkflowCollection, type WorkflowDefinition, type WorkflowGraph, type WorkflowGraphNode, type WorkflowGraphNodeDetails, type WorkflowInput, type WorkflowManifest, type WorkflowOperationMetadata, type WorkflowOutput, type WorkflowState, type WorkflowStepGroup, type WorkflowStepMetadata, type WorkflowsDefinition, createMiddleware, createStepsHandler, createTanStackWorkflowHandler, createWorkflow, daily, defineSchedule, generateManifests, hourly, registerWorkflows, toServerSentEventsResponse, weekly };
package/dist/index.js CHANGED
@@ -1,4 +1,4 @@
1
- import { a as defineSchedule, c as weekly, i as registerWorkflows, n as createMiddleware, o as daily, r as createWorkflow, s as hourly, t as generateManifests } from "./generate-DTzFAh96.js";
1
+ import { a as defineSchedule, c as weekly, i as registerWorkflows, n as createMiddleware, o as daily, r as createWorkflow, s as hourly, t as generateManifests } from "./generate-B-owFpem.js";
2
2
  import { t as defaultDurableId } from "./durable-ids-LsygHSZC.js";
3
3
  import { WorkflowRequestParseError, inMemoryRunStore, parseWorkflowRequest, runWorkflow } from "@tanstack/workflow-core";
4
4
  //#region src/stacks/tanstack/sse.ts
@@ -288,24 +288,27 @@ async function replay(options) {
288
288
  sleep: (ms, opts) => durable("sleep", opts?.id ?? defaultDurableId({
289
289
  kind: "sleep",
290
290
  ms
291
- }), void 0, { ms }, opts?.id === void 0),
291
+ }), void 0, { ms }, opts?.id === void 0, opts?.meta),
292
292
  sleepUntil: (timestamp, opts) => durable("sleep", opts?.id ?? defaultDurableId({
293
293
  kind: "sleepUntil",
294
294
  timestamp
295
- }), void 0, { timestamp }, opts?.id === void 0),
295
+ }), void 0, { timestamp }, opts?.id === void 0, opts?.meta),
296
296
  waitForEvent: (name, opts) => durable("waitForEvent", opts?.id ?? defaultDurableId({
297
297
  kind: "waitForEvent",
298
298
  name
299
- }), void 0, { name }, opts?.id === void 0),
299
+ }), void 0, { name }, opts?.id === void 0, opts?.meta),
300
300
  approve: (opts) => durable("approve", opts.id ?? defaultDurableId({
301
301
  kind: "approve",
302
302
  title: opts.title
303
303
  }), void 0, {
304
304
  title: opts.title,
305
305
  ...opts.description === void 0 ? {} : { description: opts.description }
306
- }, opts.id === void 0),
307
- now: (opts) => durable("now", opts?.id ?? defaultDurableId({ kind: "now" }), async () => Date.now(), void 0, opts?.id === void 0),
308
- uuid: (opts) => durable("uuid", opts?.id ?? defaultDurableId({ kind: "uuid" }), async () => crypto.randomUUID(), void 0, opts?.id === void 0),
306
+ }, opts.id === void 0, {
307
+ ...opts.meta,
308
+ ...opts.description === void 0 ? {} : { description: opts.description }
309
+ }),
310
+ now: (opts) => durable("now", opts?.id ?? defaultDurableId({ kind: "now" }), async () => Date.now(), void 0, opts?.id === void 0, opts?.meta),
311
+ uuid: (opts) => durable("uuid", opts?.id ?? defaultDurableId({ kind: "uuid" }), async () => crypto.randomUUID(), void 0, opts?.id === void 0, opts?.meta),
309
312
  emit: (name, value) => {
310
313
  emitted.push({
311
314
  name,
@@ -1,4 +1,4 @@
1
- import { loadTypeScript } from "./graph-BEfFBC6v.js";
1
+ import { loadTypeScript } from "./graph-DW4JTyGa.js";
2
2
  //#region src/manifests/nested-operations.ts
3
3
  const durableMethods = [
4
4
  "step",
@@ -0,0 +1,45 @@
1
+ import { loadTypeScript } from "./graph-DW4JTyGa.js";
2
+ //#region src/manifests/operation-descriptions.ts
3
+ const optionsArgument = {
4
+ approve: 0,
5
+ sleep: 1,
6
+ sleepUntil: 1,
7
+ waitForEvent: 1,
8
+ now: 0,
9
+ uuid: 0
10
+ };
11
+ async function findOperationDescriptionIssues(handler) {
12
+ const api = await loadTypeScript();
13
+ if (!api) return [];
14
+ const ts = api;
15
+ const source = ts.createSourceFile("handler.js", `const handler = ${Function.prototype.toString.call(handler)};`, ts.ScriptTarget.ESNext, true, ts.ScriptKind.JS);
16
+ const declaration = source.statements[0];
17
+ const fn = declaration && ts.isVariableStatement(declaration) ? declaration.declarationList.declarations[0]?.initializer : void 0;
18
+ if (!fn || !ts.isArrowFunction(fn) && !ts.isFunctionExpression(fn) || source.text.includes("[native code]")) return [];
19
+ const parameter = fn.parameters[0]?.name;
20
+ if (!parameter || !ts.isIdentifier(parameter)) return [];
21
+ const context = parameter.text;
22
+ function literalString(node) {
23
+ return node && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) ? node.text : void 0;
24
+ }
25
+ function property(node, name) {
26
+ if (!node || !ts.isObjectLiteralExpression(node)) return void 0;
27
+ for (const entry of node.properties) {
28
+ if (!ts.isPropertyAssignment(entry)) continue;
29
+ if ((ts.isIdentifier(entry.name) || ts.isStringLiteral(entry.name) ? entry.name.text : void 0) === name) return entry.initializer;
30
+ }
31
+ }
32
+ const issues = [];
33
+ const visit = (node) => {
34
+ if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === context && node.expression.name.text in optionsArgument) {
35
+ const method = node.expression.name.text;
36
+ const options = node.arguments[optionsArgument[method]];
37
+ if ((method === "approve" ? literalString(property(options, "description")) : literalString(property(property(options, "meta"), "description"))) === void 0) issues.push({ method });
38
+ }
39
+ ts.forEachChild(node, visit);
40
+ };
41
+ visit(fn);
42
+ return issues;
43
+ }
44
+ //#endregion
45
+ export { findOperationDescriptionIssues };
@@ -1,4 +1,4 @@
1
- import { loadTypeScript } from "./graph-BEfFBC6v.js";
1
+ import { loadTypeScript } from "./graph-DW4JTyGa.js";
2
2
  //#region src/manifests/step-metadata.ts
3
3
  async function findStepMetadataIssues(handler) {
4
4
  const api = await loadTypeScript();
package/dist/vite.js CHANGED
@@ -1,4 +1,4 @@
1
- import { t as generateManifests } from "./generate-DTzFAh96.js";
1
+ import { t as generateManifests } from "./generate-B-owFpem.js";
2
2
  import { dirname, isAbsolute, join, relative, resolve, sep } 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.16",
3
+ "version": "0.0.0-dev.17",
4
4
  "publishConfig": {
5
5
  "access": "public",
6
6
  "tag": "dev",