@lovable.dev/workflows-sdk 0.0.0-dev

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 ADDED
@@ -0,0 +1,123 @@
1
+ # @lovable.dev/workflows-sdk
2
+
3
+ Author workflows with TanStack workflow-core and register them in an explicit
4
+ collection for Lovable. This development SDK generates build manifests; execution
5
+ and schedule installation on Lovable are not implemented yet.
6
+
7
+ Experimental: every release stays in the `0.0.0-dev` series. The API may
8
+ change without compatibility guarantees; this SDK is not production-ready.
9
+
10
+ ## Authoring
11
+
12
+ Use `createWorkflow({ id, input, output }).handler(...)` to define a workflow
13
+ and `createMiddleware` to extend its typed context. Both builders come directly
14
+ from [`@tanstack/workflow-core`](https://github.com/TanStack/workflow).
15
+ Schema validation libraries implementing Standard Schema, such as Zod, provide
16
+ input and output inference.
17
+
18
+ Keep the app's workflow collection in `app/workflows/index.ts`. Each workflow
19
+ lives in `app/workflows/{workflow-name}/index.ts`, with its helpers alongside it:
20
+
21
+ ```text
22
+ app/workflows/
23
+ ├── index.ts
24
+ └── greet/
25
+ ├── index.ts
26
+ └── helpers.ts
27
+ ```
28
+
29
+ Each workflow's `index.ts` exports its definition. The collection entry imports
30
+ all workflow definitions and default-exports `registerWorkflows(...)`:
31
+
32
+ ```ts
33
+ import { registerWorkflows } from "@lovable.dev/workflows-sdk";
34
+ import { greet } from "./greet";
35
+
36
+ export default registerWorkflows({ workflows: [greet] });
37
+ ```
38
+
39
+ The `id` passed to `createWorkflow` is its app-wide unique name and should match
40
+ its folder name. Names contain 1–128 lowercase letters, digits, hyphens, or
41
+ underscores, starting with a letter or digit. The app collection rejects duplicate
42
+ names. An empty collection is valid. Registration copies the list, retains the
43
+ definitions, and does not execute handlers or register global state. Treat
44
+ definitions as immutable after registration.
45
+
46
+ See [the authoring example](examples/workflows.ts) for schemas, typed middleware,
47
+ and a durable step. The package typecheck includes this example.
48
+
49
+ ## Schedules
50
+
51
+ Declare a schedule with `defineSchedule({ id, workflow, cron, timeZone, input })`
52
+ and include it in `registerWorkflows({ workflows, schedules })`. `workflow` refers
53
+ to the same definition object included in `workflows`; `input` is required and
54
+ inferred from that workflow. Multiple schedules can target one workflow.
55
+
56
+ Use a five-field cron expression (minute, hour, day, month, weekday) and an IANA
57
+ time zone; the default is UTC. Schedule IDs must be unique within the app's
58
+ collection. Registration checks field count and time zone; cron syntax and
59
+ calendar semantics remain the engine's responsibility. This API declares
60
+ schedules but does not install timers or start runs. Periodic intervals,
61
+ catch-up, and overlap policies remain follow-ups.
62
+
63
+ The [example](examples/workflows.ts) declares a daily greeting at 09:00 in
64
+ Europe/Stockholm with static workflow input.
65
+
66
+ ## Manifest generation
67
+
68
+ Add `workflowsManifest({ entry: "app/workflows/index.ts" })` from
69
+ `@lovable.dev/workflows-sdk/vite` to the app's Vite plugins. The entry must
70
+ default-export its `registerWorkflows()` collection. Each production build writes
71
+ one manifest per workflow to `.lovable/workflows/{workflow-name}.json` relative
72
+ to the app root. For example, `greet` produces `.lovable/workflows/greet.json`.
73
+ Generation errors fail the build. See [the Vite example](examples/vite.config.ts).
74
+
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,
78
+ not the engine's deployment or execution contract. Handlers and middleware stay
79
+ in app code. Schedule IDs and JSON object keys are sorted for stable output.
80
+
81
+ The SDK manages the JSON files in `.lovable/workflows/`. Successful generation
82
+ removes manifests for deleted or renamed workflows; an empty collection removes
83
+ all JSON manifests. Other files and subdirectories are preserved. All definitions
84
+ are validated before writing, and each file is replaced by rename so readers
85
+ never see a partially written JSON document.
86
+
87
+ Schemas must implement [Standard JSON Schema](https://standardschema.dev/json-schema)
88
+ conversion to draft 2020-12, as Zod 4 does. Missing conversion support and
89
+ conversion errors fail generation. Schedule inputs must be plain JSON and pass
90
+ the workflow's input schema; the manifest retains the raw input for validation
91
+ when a run starts. Functions, undefined values, non-finite numbers, class
92
+ instances, and cycles are rejected. `previousVersions` is rejected until version
93
+ routing has a manifest contract.
94
+
95
+ The plugin evaluates the entry using a separate Vite SSR loader with the app's
96
+ aliases, mode, defines, and SSR dependency rules. Module-level code and schema
97
+ validators run during extraction; workflow handlers and middleware do not.
98
+ Custom app transform plugins and virtual modules are not loaded by this loader.
99
+ For another build system, call `await generateManifests(collection)` and make
100
+ synchronizing the returned manifests to `.lovable/workflows/` a required build step.
101
+
102
+ ## Next PRs
103
+
104
+ Connect the manifest and app code to Lovable deployment and runtime execution.
105
+ Define support for TanStack primitives, version routing, and schedule policies.
106
+
107
+ ## Publishing dev builds
108
+
109
+ The [publishing workflow](../../.github/workflows/publish-workflows-sdk.yml)
110
+ publishes the version committed in `package.json` to npm's `dev` tag when SDK
111
+ changes land on `main`. Manage versions manually: `0.0.0-dev`, `0.0.0-dev.1`,
112
+ `0.0.0-dev.2`, and so on. The workflow rejects versions outside this series and
113
+ skips versions already published. Manual runs default to a dry run.
114
+ See [the setup guide](PUBLISHING.md) for the
115
+ one-time bootstrap and npm trusted-publisher configuration.
116
+
117
+ Install a published build with `npm install @lovable.dev/workflows-sdk@dev`,
118
+ or pin the exact version shown in the workflow run's summary.
119
+
120
+ The existing internal [`@lovable/workflow-sdk`](../../packages/workflow-sdk)
121
+ provides the engine contract. Use [`mcp-js`](../lovable-mcp-js) as the reference
122
+ for separating authoring, manifest extraction, and framework integration. The
123
+ workflow prototype's `ts/workflow-sdk` supplies adapter and manifest examples.
@@ -0,0 +1,47 @@
1
+ import { AnyWorkflowDefinition, AnyWorkflowDefinition as AnyWorkflowDefinition$1, Ctx, StepContext, StepOptions, WorkflowDefinition, WorkflowInput, WorkflowInput as WorkflowInput$1, WorkflowOutput, WorkflowState, createMiddleware, createWorkflow } from "@tanstack/workflow-core";
2
+ //#region src/schedule.d.ts
3
+ interface ScheduleDefinition<TWorkflow extends AnyWorkflowDefinition$1 = AnyWorkflowDefinition$1> {
4
+ readonly id: string;
5
+ readonly workflow: TWorkflow;
6
+ readonly cron: string;
7
+ readonly timeZone?: string;
8
+ readonly input: WorkflowInput$1<NoInfer<TWorkflow>>;
9
+ }
10
+ declare function defineSchedule<TWorkflow extends AnyWorkflowDefinition$1>(schedule: ScheduleDefinition<TWorkflow>): ScheduleDefinition<TWorkflow>;
11
+ //#endregion
12
+ //#region src/register.d.ts
13
+ interface WorkflowsDefinition<TWorkflow extends AnyWorkflowDefinition$1 = AnyWorkflowDefinition$1> {
14
+ readonly workflows: readonly TWorkflow[];
15
+ readonly schedules: readonly ScheduleDefinition[];
16
+ }
17
+ declare function registerWorkflows<const TWorkflows extends readonly AnyWorkflowDefinition$1[]>({ workflows, schedules }: {
18
+ workflows: TWorkflows;
19
+ schedules?: readonly ScheduleDefinition[];
20
+ }): WorkflowsDefinition<TWorkflows[number]>;
21
+ //#endregion
22
+ //#region src/json.d.ts
23
+ type JsonValue = null | boolean | number | string | JsonValue[] | {
24
+ [key: string]: JsonValue;
25
+ };
26
+ //#endregion
27
+ //#region src/manifest.d.ts
28
+ interface WorkflowManifest {
29
+ version: 1;
30
+ workflow: {
31
+ id: string;
32
+ description?: string;
33
+ version?: string;
34
+ inputSchema?: JsonValue;
35
+ outputSchema?: JsonValue;
36
+ stateSchema?: JsonValue;
37
+ };
38
+ schedules: {
39
+ id: string;
40
+ cron: string;
41
+ timeZone: string;
42
+ input: JsonValue;
43
+ }[];
44
+ }
45
+ declare function generateManifests(definition: WorkflowsDefinition): Promise<WorkflowManifest[]>;
46
+ //#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 };
package/dist/index.js ADDED
@@ -0,0 +1,3 @@
1
+ import { n as registerWorkflows, r as defineSchedule, t as generateManifests } from "./manifest-jkqqGByV.js";
2
+ import { createMiddleware, createWorkflow } from "@tanstack/workflow-core";
3
+ export { createMiddleware, createWorkflow, defineSchedule, generateManifests, registerWorkflows };
@@ -0,0 +1,112 @@
1
+ //#region src/validation.ts
2
+ function assertIdentifier(kind, id) {
3
+ if (typeof id !== "string" || id.trim() === "" || id !== id.trim()) throw new Error(`@lovable.dev/workflows-sdk: ${kind} IDs must be non-empty and have no surrounding whitespace`);
4
+ }
5
+ //#endregion
6
+ //#region src/schedule.ts
7
+ function defineSchedule(schedule) {
8
+ assertIdentifier("schedule", schedule.id);
9
+ if (typeof schedule.cron !== "string" || schedule.cron.trim().split(/\s+/).length !== 5) throw new Error(`@lovable.dev/workflows-sdk: schedule "${schedule.id}" requires a five-field cron expression`);
10
+ const timeZone = schedule.timeZone ?? "UTC";
11
+ new Intl.DateTimeFormat("en", { timeZone });
12
+ return {
13
+ ...schedule,
14
+ timeZone
15
+ };
16
+ }
17
+ //#endregion
18
+ //#region src/register.ts
19
+ function registerWorkflows({ workflows, schedules = [] }) {
20
+ const ids = /* @__PURE__ */ new Set();
21
+ for (const workflow of workflows) {
22
+ if (workflow.__kind !== "workflow" || typeof workflow.handler !== "function") throw new Error("@lovable.dev/workflows-sdk: expected a completed createWorkflow().handler() definition");
23
+ assertIdentifier("workflow", workflow.id);
24
+ if (!/^[a-z0-9][a-z0-9_-]{0,127}$/.test(workflow.id)) throw new Error("@lovable.dev/workflows-sdk: workflow names must be 1–128 lowercase letters, digits, hyphens or underscores, starting with a letter or digit");
25
+ if (ids.has(workflow.id)) throw new Error(`@lovable.dev/workflows-sdk: duplicate workflow ID "${workflow.id}"`);
26
+ ids.add(workflow.id);
27
+ }
28
+ const scheduleIds = /* @__PURE__ */ new Set();
29
+ const registeredSchedules = schedules.map((schedule) => {
30
+ const definition = defineSchedule(schedule);
31
+ if (scheduleIds.has(definition.id)) throw new Error(`@lovable.dev/workflows-sdk: duplicate schedule ID "${definition.id}"`);
32
+ if (!workflows.includes(definition.workflow)) throw new Error(`@lovable.dev/workflows-sdk: schedule "${definition.id}" references an unregistered workflow`);
33
+ scheduleIds.add(definition.id);
34
+ return definition;
35
+ });
36
+ return {
37
+ workflows: [...workflows],
38
+ schedules: registeredSchedules
39
+ };
40
+ }
41
+ //#endregion
42
+ //#region src/json.ts
43
+ function toJson(value, path, ancestors = /* @__PURE__ */ new Set()) {
44
+ if (value === null || typeof value === "string" || typeof value === "boolean") return value;
45
+ if (typeof value === "number" && Number.isFinite(value)) return value;
46
+ if (typeof value !== "object" || ancestors.has(value)) throw new Error(`@lovable.dev/workflows-sdk: ${path} must contain finite, acyclic JSON values`);
47
+ ancestors.add(value);
48
+ try {
49
+ if (Object.getOwnPropertySymbols(value).length > 0) throw new Error(`@lovable.dev/workflows-sdk: ${path} must not contain symbol keys`);
50
+ if (Array.isArray(value)) {
51
+ if (Object.keys(value).length !== value.length) throw new Error(`@lovable.dev/workflows-sdk: ${path} must be a dense JSON array without extra properties`);
52
+ return Array.from(value, (item, index) => toJson(item, `${path}[${index}]`, ancestors));
53
+ }
54
+ if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) throw new Error(`@lovable.dev/workflows-sdk: ${path} must contain plain JSON objects`);
55
+ return Object.fromEntries(Object.keys(value).sort().map((key) => [key, toJson(value[key], `${path}.${key}`, ancestors)]));
56
+ } finally {
57
+ ancestors.delete(value);
58
+ }
59
+ }
60
+ //#endregion
61
+ //#region src/manifest.ts
62
+ function jsonSchema(schema, direction, label) {
63
+ if (!schema) return void 0;
64
+ const standard = schema["~standard"];
65
+ if (typeof standard.jsonSchema?.[direction] !== "function") throw new Error(`@lovable.dev/workflows-sdk: ${label} must support Standard JSON Schema conversion`);
66
+ try {
67
+ return toJson(standard.jsonSchema[direction]({ target: "draft-2020-12" }), label);
68
+ } catch (cause) {
69
+ throw new Error(`@lovable.dev/workflows-sdk: cannot serialize ${label}`, { cause });
70
+ }
71
+ }
72
+ async function generateManifests(definition) {
73
+ const collection = registerWorkflows(definition);
74
+ const manifests = [];
75
+ for (const workflow of collection.workflows) {
76
+ if (workflow.previousVersions?.length) throw new Error(`@lovable.dev/workflows-sdk: workflow "${workflow.id}" previousVersions are not supported yet`);
77
+ const metadata = {
78
+ id: workflow.id,
79
+ ...workflow.description === void 0 ? {} : { description: workflow.description },
80
+ ...workflow.version === void 0 ? {} : { version: workflow.version },
81
+ ...workflow.inputSchema ? { inputSchema: jsonSchema(workflow.inputSchema, "input", `${workflow.id}.input`) } : {},
82
+ ...workflow.outputSchema ? { outputSchema: jsonSchema(workflow.outputSchema, "output", `${workflow.id}.output`) } : {},
83
+ ...workflow.stateSchema ? { stateSchema: jsonSchema(workflow.stateSchema, "output", `${workflow.id}.state`) } : {}
84
+ };
85
+ const schedules = [];
86
+ for (const schedule of collection.schedules.filter((schedule) => schedule.workflow === workflow)) {
87
+ const input = toJson(schedule.input, `schedule "${schedule.id}" input`);
88
+ const schema = schedule.workflow.inputSchema;
89
+ if (schema) {
90
+ const result = await schema["~standard"].validate(input);
91
+ if (result.issues) throw new Error(`@lovable.dev/workflows-sdk: schedule "${schedule.id}" input is invalid: ${result.issues.map((issue) => issue.message).join("; ")}`);
92
+ }
93
+ schedules.push({
94
+ id: schedule.id,
95
+ cron: schedule.cron,
96
+ timeZone: schedule.timeZone ?? "UTC",
97
+ input
98
+ });
99
+ }
100
+ schedules.sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
101
+ const manifest = {
102
+ version: 1,
103
+ workflow: metadata,
104
+ schedules
105
+ };
106
+ toJson(manifest, "manifest");
107
+ manifests.push(manifest);
108
+ }
109
+ return manifests.sort((a, b) => a.workflow.id < b.workflow.id ? -1 : a.workflow.id > b.workflow.id ? 1 : 0);
110
+ }
111
+ //#endregion
112
+ export { registerWorkflows as n, defineSchedule as r, generateManifests as t };
package/dist/vite.d.ts ADDED
@@ -0,0 +1,7 @@
1
+ import { Plugin } from "vite";
2
+ //#region src/vite.d.ts
3
+ declare function workflowsManifest({ entry }: {
4
+ entry: string;
5
+ }): Plugin;
6
+ //#endregion
7
+ export { workflowsManifest };
package/dist/vite.js ADDED
@@ -0,0 +1,77 @@
1
+ import { t as generateManifests } from "./manifest-jkqqGByV.js";
2
+ import { join, resolve } from "node:path";
3
+ import { createServer } from "vite";
4
+ import { lstat, mkdir, mkdtemp, readdir, rename, rm, writeFile } from "node:fs/promises";
5
+ //#region src/manifest-files.ts
6
+ async function ensureDirectory(path) {
7
+ try {
8
+ await mkdir(path);
9
+ } catch (error) {
10
+ if (error.code !== "EEXIST") throw error;
11
+ }
12
+ if (!(await lstat(path)).isDirectory()) throw new Error(`@lovable.dev/workflows-sdk: ${path} must be a directory, not a file or symlink`);
13
+ }
14
+ async function writeManifests(root, manifests) {
15
+ const lovable = join(root, ".lovable");
16
+ await ensureDirectory(lovable);
17
+ const directory = join(lovable, "workflows");
18
+ await ensureDirectory(directory);
19
+ const staging = await mkdtemp(join(directory, ".tmp-"));
20
+ const names = new Set(manifests.map((manifest) => `${manifest.workflow.id}.json`));
21
+ try {
22
+ for (const manifest of manifests) await writeFile(join(staging, `${manifest.workflow.id}.json`), JSON.stringify(manifest, null, 2) + "\n");
23
+ for (const name of names) await rename(join(staging, name), join(directory, name));
24
+ for (const entry of await readdir(directory, { withFileTypes: true })) if (entry.name.endsWith(".json") && !names.has(entry.name) && !entry.isDirectory()) await rm(join(directory, entry.name), { force: true });
25
+ } finally {
26
+ await rm(staging, {
27
+ recursive: true,
28
+ force: true
29
+ });
30
+ }
31
+ }
32
+ //#endregion
33
+ //#region src/vite.ts
34
+ function workflowsManifest({ entry }) {
35
+ let config;
36
+ return {
37
+ name: "@lovable.dev/workflows-sdk/manifest",
38
+ apply: "build",
39
+ configResolved(resolved) {
40
+ config = resolved;
41
+ },
42
+ async generateBundle() {
43
+ const entryPath = resolve(config.root, entry);
44
+ this.addWatchFile(entryPath);
45
+ const server = await createServer({
46
+ configFile: false,
47
+ root: config.root,
48
+ mode: config.mode,
49
+ envDir: config.envDir,
50
+ define: config.define,
51
+ logLevel: "silent",
52
+ resolve: { alias: config.resolve.alias },
53
+ ssr: {
54
+ external: config.ssr.external,
55
+ noExternal: config.ssr.noExternal
56
+ },
57
+ server: {
58
+ middlewareMode: true,
59
+ hmr: false,
60
+ watch: null
61
+ },
62
+ optimizeDeps: { noDiscovery: true }
63
+ });
64
+ try {
65
+ const module = await server.ssrLoadModule(entryPath);
66
+ if (!module.default || !Array.isArray(module.default.workflows) || !Array.isArray(module.default.schedules)) throw new Error(`@lovable.dev/workflows-sdk: ${entry} must default-export a registerWorkflows() collection`);
67
+ const manifests = await generateManifests(module.default);
68
+ await writeManifests(config.root, manifests);
69
+ } finally {
70
+ for (const file of server.moduleGraph.fileToModulesMap.keys()) this.addWatchFile(file);
71
+ await server.close();
72
+ }
73
+ }
74
+ };
75
+ }
76
+ //#endregion
77
+ export { workflowsManifest };
package/package.json ADDED
@@ -0,0 +1,53 @@
1
+ {
2
+ "name": "@lovable.dev/workflows-sdk",
3
+ "version": "0.0.0-dev",
4
+ "publishConfig": {
5
+ "access": "public",
6
+ "tag": "dev",
7
+ "registry": "https://registry.npmjs.org"
8
+ },
9
+ "description": "Author workflows for Lovable apps.",
10
+ "type": "module",
11
+ "repository": {
12
+ "type": "git",
13
+ "url": "git+https://github.com/lovablelabs/lovable.git",
14
+ "directory": "npm-packages/workflows-sdk"
15
+ },
16
+ "types": "./dist/index.d.ts",
17
+ "exports": {
18
+ ".": {
19
+ "types": "./dist/index.d.ts",
20
+ "import": "./dist/index.js"
21
+ },
22
+ "./vite": {
23
+ "types": "./dist/vite.d.ts",
24
+ "import": "./dist/vite.js"
25
+ }
26
+ },
27
+ "files": [
28
+ "dist"
29
+ ],
30
+ "dependencies": {
31
+ "@standard-schema/spec": "^1.1.0",
32
+ "@tanstack/workflow-core": "0.0.4"
33
+ },
34
+ "devDependencies": {
35
+ "@types/node": "22.13.13",
36
+ "vite": "^7.3.1",
37
+ "zod": "^4.1.13",
38
+ "tsdown": "^0.22.5"
39
+ },
40
+ "peerDependencies": {
41
+ "vite": ">=7.3.1 <9"
42
+ },
43
+ "peerDependenciesMeta": {
44
+ "vite": {
45
+ "optional": true
46
+ }
47
+ },
48
+ "scripts": {
49
+ "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\""
52
+ }
53
+ }