@invect/version-control 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,78 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="../../../.github/assets/logo-light.svg">
+    <img alt="Invect" src="../../../.github/assets/logo-dark.svg" width="50">
+  </picture>
+</p>
+
+<h1 align="center">@invect/version-control</h1>
+
+<p align="center">
+  Version control plugin for Invect.
+  <br />
+  <a href="https://invect.dev/docs/plugins"><strong>Docs</strong></a>
+</p>
+
+---
+
+Sync Invect flows to GitHub (and other Git providers) as readable `.flow.ts` TypeScript files. Supports push, pull, PR-based publishing, and bidirectional sync.
+
+## Install
+
+```bash
+pnpm add @invect/version-control
+```
+
+## Backend
+
+```ts
+import { versionControl } from '@invect/version-control';
+import { githubProvider } from '@invect/version-control/providers/github';
+
+const invectRouter = await createInvectRouter({
+  database: { type: 'sqlite', connectionString: 'file:./dev.db' },
+  encryptionKey: process.env.INVECT_ENCRYPTION_KEY!,
+  plugins: [
+    versionControl({
+      provider: githubProvider({ auth: process.env.GITHUB_TOKEN! }),
+      repo: 'org/my-flows',
+    }),
+  ],
+});
+
+app.use('/invect', invectRouter);
+```
+
+### Options
+
+```ts
+versionControl({
+  provider: githubProvider({ auth: '...' }), // Git hosting provider
+  repo: 'owner/repo', // Default repository (owner/name)
+  defaultBranch: 'main', // Target branch
+  path: 'flows/', // Directory in the repo for flow files
+  mode: 'pr-per-publish', // "pr-per-publish" | "auto-sync" | "manual-only"
+  syncDirection: 'push', // "push" | "pull" | "bidirectional"
+  webhookSecret: '...', // Webhook secret for PR merge events
+});
+```
+
+## Features
+
+- **Push/pull** — Sync flows to and from a Git repository.
+- **PR-based publishing** — Create pull requests for flow changes, merge to deploy.
+- **Bidirectional sync** — Keep flows in sync between Invect and Git.
+- **Readable exports** — Flows are serialized as `.flow.ts` TypeScript files.
+- **Sync history** — Full audit trail of sync operations with commit SHAs.
+
+## Exports
+
+| Entry Point                                | Content                  |
+| ------------------------------------------ | ------------------------ |
+| `@invect/version-control`                  | Backend plugin (Node.js) |
+| `@invect/version-control/providers/github` | GitHub provider          |
+| `@invect/version-control/types`            | Shared types             |
+
+## License
+
+[MIT](../../../LICENSE)

package/dist/backend/flow-serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flow-serializer.d.ts","sourceRoot":"","sources":["../../src/backend/flow-serializer.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,kBAAkB,EAC9B,QAAQ,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAChE,MAAM,CA0ER;AAMD,UAAU,kBAAkB;IAC1B,KAAK,EAAE,KAAK,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAClC,CAAC,CAAC;IACH,KAAK,EAAE,KAAK,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC,CAAC;CACJ"}
+{"version":3,"file":"flow-serializer.d.ts","sourceRoot":"","sources":["../../src/backend/flow-serializer.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,kBAAkB,EAC9B,QAAQ,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAChE,MAAM,CAiFR;AAMD,UAAU,kBAAkB;IAC1B,KAAK,EAAE,KAAK,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAClC,CAAC,CAAC;IACH,KAAK,EAAE,KAAK,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC,CAAC;CACJ"}

package/dist/backend/index.cjs

@@ -1,5 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_shared_types = require("../shared/types.cjs");
 let node_crypto = require("node:crypto");
+let zod_v4 = require("zod/v4");
 //#region src/backend/schema.ts
 const SYNC_MODES = [
 	"direct-commit",
@@ -208,6 +210,10 @@ function serializeFlowToTs(definition, metadata) {
 	lines.push("  ],");
 	lines.push("});");
 	lines.push("");
+	lines.push("/* @invect-definition");
+	lines.push(JSON.stringify(definition));
+	lines.push("*/");
+	lines.push("");
 	return lines.join("\n");
 }
 /** Map action IDs to SDK helper function names */
@@ -345,6 +351,11 @@ var VcSyncService = class {
 	}
 	async pushFlow(db, flowId, identity) {
 		const config = await this.requireConfig(db, flowId);
+		if (config.syncDirection === "pull") return {
+			success: false,
+			error: "Push is not allowed — this flow is configured for pull-only sync.",
+			action: "push"
+		};
 		const { content, version } = await this.exportFlow(db, flowId);
 		try {
 			if (config.mode === "direct-commit") return await this.directCommit(db, config, content, version, identity);
@@ -390,6 +401,11 @@ var VcSyncService = class {
 	}
 	async pullFlow(db, flowId, identity) {
 		const config = await this.requireConfig(db, flowId);
+		if (config.syncDirection === "push") return {
+			success: false,
+			error: "Pull is not allowed — this flow is configured for push-only sync.",
+			action: "pull"
+		};
 		const remote = await this.provider.getFileContent(config.repo, config.filePath, config.branch);
 		if (!remote) return {
 			success: false,
@@ -624,7 +640,7 @@ var VcSyncService = class {
 		const versions = await db.query("SELECT flow_id, version, invect_definition FROM flow_versions WHERE flow_id = ? ORDER BY version DESC LIMIT 1", [flowId]);
 		if (versions.length === 0) throw new Error(`No versions found for flow: ${flowId}`);
 		const fv = versions[0];
-		const definition = typeof fv.invectDefinition === "string" ? JSON.parse(fv.invectDefinition) : fv.invectDefinition;
+		const definition = typeof fv.invect_definition === "string" ? JSON.parse(fv.invect_definition) : fv.invect_definition;
 		let tags;
 		if (flow.tags) try {
 			tags = typeof flow.tags === "string" ? JSON.parse(flow.tags) : flow.tags;
@@ -641,43 +657,27 @@ var VcSyncService = class {
 		};
 	}
 	async importFlowContent(db, flowId, content, identity) {
-		const { writeFileSync, unlinkSync, mkdtempSync } = await import("node:fs");
-		const { join } = await import("node:path");
-		const { tmpdir } = await import("node:os");
-		const tmpDir = mkdtempSync(join(tmpdir(), "invect-vc-"));
-		const tmpFile = join(tmpDir, "import.flow.ts");
-		try {
-			writeFileSync(tmpFile, content, "utf-8");
-			const { createJiti } = await import("jiti");
-			const result = await createJiti(require("url").pathToFileURL(__filename).href, { interopDefault: true }).import(tmpFile);
-			const definition = result.default ?? result;
-			if (!definition || typeof definition !== "object" || !("nodes" in definition) || !("edges" in definition)) throw new Error("Imported .flow.ts file did not produce a valid InvectDefinition. Expected an object with \"nodes\" and \"edges\" arrays.");
-			const nextVersion = ((await db.query("SELECT MAX(version) as version FROM flow_versions WHERE flow_id = ?", [flowId]))[0]?.version ?? 0) + 1;
-			const defJson = typeof definition === "string" ? definition : JSON.stringify(definition);
-			await db.execute(`INSERT INTO flow_versions (flow_id, version, invect_definition, created_at, created_by)
-         VALUES (?, ?, ?, ?, ?)`, [
-				flowId,
-				nextVersion,
-				defJson,
-				(/* @__PURE__ */ new Date()).toISOString(),
-				identity ?? null
-			]);
-			await db.execute("UPDATE flows SET live_version_number = ?, updated_at = ? WHERE id = ?", [
-				nextVersion,
-				(/* @__PURE__ */ new Date()).toISOString(),
-				flowId
-			]);
-			this.logger.info("Flow imported from remote", {
-				flowId,
-				version: nextVersion
-			});
-		} finally {
-			try {
-				unlinkSync(tmpFile);
-				const { rmdirSync } = await import("node:fs");
-				rmdirSync(tmpDir);
-			} catch {}
-		}
+		const definition = parseFlowTsContent(content);
+		if (!definition || typeof definition !== "object" || !Array.isArray(definition.nodes) || !Array.isArray(definition.edges)) throw new Error("Imported .flow.ts file did not produce a valid InvectDefinition. Expected an object with \"nodes\" and \"edges\" arrays.");
+		const nextVersion = ((await db.query("SELECT MAX(version) as version FROM flow_versions WHERE flow_id = ?", [flowId]))[0]?.version ?? 0) + 1;
+		const defJson = JSON.stringify(definition);
+		await db.execute(`INSERT INTO flow_versions (flow_id, version, invect_definition, created_at, created_by)
+       VALUES (?, ?, ?, ?, ?)`, [
+			flowId,
+			nextVersion,
+			defJson,
+			(/* @__PURE__ */ new Date()).toISOString(),
+			identity ?? null
+		]);
+		await db.execute("UPDATE flows SET live_version_number = ?, updated_at = ? WHERE id = ?", [
+			nextVersion,
+			(/* @__PURE__ */ new Date()).toISOString(),
+			flowId
+		]);
+		this.logger.info("Flow imported from remote", {
+			flowId,
+			version: nextVersion
+		});
 	}
 	buildFilePath(flowName) {
 		return `${this.options.path ?? "workflows/"}${flowName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "")}.flow.ts`;
@@ -757,6 +757,153 @@ function mapHistoryRow(r) {
 		createdBy: r.created_by
 	};
 }
+/**
+* Parse a .flow.ts file content to extract the InvectDefinition.
+*
+* This is a static parser that does NOT evaluate the TypeScript file.
+* It works by extracting the `defineFlow({ ... })` call's argument as a
+* JS object literal string and parsing it with a safe JSON5-like approach.
+*
+* Falls back to extracting raw `nodes` and `edges` arrays if defineFlow
+* wrapper is not found.
+*/
+function parseFlowTsContent(content) {
+	const jsonCommentMatch = content.match(/\/\*\s*@invect-definition\s+([\s\S]*?)\s*\*\//);
+	if (jsonCommentMatch) try {
+		return JSON.parse(jsonCommentMatch[1]);
+	} catch {}
+	const defineFlowMatch = content.match(/defineFlow\s*\(\s*\{/);
+	if (defineFlowMatch && defineFlowMatch.index !== void 0) {
+		const objStr = extractBalancedBraces(content, defineFlowMatch.index + defineFlowMatch[0].length - 1);
+		if (objStr) try {
+			const parsed = parseObjectLiteral(objStr);
+			if (parsed && Array.isArray(parsed.nodes) && Array.isArray(parsed.edges)) return {
+				nodes: parsed.nodes,
+				edges: parsed.edges
+			};
+		} catch {}
+	}
+	return null;
+}
+/** Extract a balanced {} block from a string starting at the given { index */
+function extractBalancedBraces(str, startIdx) {
+	let depth = 0;
+	let inString = false;
+	let escaped = false;
+	for (let i = startIdx; i < str.length; i++) {
+		const ch = str[i];
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+		if (ch === "\\") {
+			escaped = true;
+			continue;
+		}
+		if (inString) {
+			if (ch === inString) inString = false;
+			continue;
+		}
+		if (ch === "\"" || ch === "'" || ch === "`") {
+			inString = ch;
+			continue;
+		}
+		if (ch === "{" || ch === "[") depth++;
+		else if (ch === "}" || ch === "]") {
+			depth--;
+			if (depth === 0) return str.slice(startIdx, i + 1);
+		}
+	}
+	return null;
+}
+/**
+* Parse a JS object literal string into a JSON-compatible value.
+*
+* Handles: unquoted keys, single-quoted strings, trailing commas,
+* template literals (simplified), and function calls by converting
+* them to strings.
+*/
+function parseObjectLiteral(objStr) {
+	try {
+		let normalized = objStr.replace(/\/\/.*$/gm, "");
+		normalized = normalized.replace(/\/\*[\s\S]*?\*\//g, "");
+		normalized = replaceQuotes(normalized);
+		normalized = normalized.replace(/(?<=[{,]\s*)([a-zA-Z_$][a-zA-Z0-9_$]*)(?=\s*:)/g, "\"$1\"");
+		normalized = normalized.replace(/,\s*([}\]])/g, "$1");
+		normalized = replaceFunctionCalls(normalized);
+		return JSON.parse(normalized);
+	} catch {
+		return null;
+	}
+}
+/** Replace single-quoted strings with double-quoted */
+function replaceQuotes(str) {
+	let result = "";
+	let inDouble = false;
+	let inSingle = false;
+	let escaped = false;
+	for (let i = 0; i < str.length; i++) {
+		const ch = str[i];
+		if (escaped) {
+			result += ch;
+			escaped = false;
+			continue;
+		}
+		if (ch === "\\") {
+			result += ch;
+			escaped = true;
+			continue;
+		}
+		if (!inSingle && ch === "\"") {
+			inDouble = !inDouble;
+			result += ch;
+		} else if (!inDouble && ch === "'") {
+			inSingle = !inSingle;
+			result += "\"";
+		} else result += ch;
+	}
+	return result;
+}
+/**
+* Replace function calls like `input("ref", { ... })` with a JSON object
+* that captures the node structure. This handles the SDK helper calls
+* in the serialized .flow.ts nodes array.
+*
+* Pattern: `helperName("refId", { params })` → `{ "type": "helperName", "referenceId": "refId", "params": { ... } }`
+* Also handles namespaced: `ns.helperName("refId", { ... })`
+*/
+function replaceFunctionCalls(str) {
+	const callPattern = /([a-zA-Z_$][\w$]*\.[a-zA-Z_$][\w$]*|[a-zA-Z_$][\w$]*)\s*\(\s*"([^"]*)"\s*,\s*(\{)/g;
+	let result = str;
+	let match;
+	let offset = 0;
+	callPattern.lastIndex = 0;
+	while ((match = callPattern.exec(str)) !== null) {
+		const fnName = match[1];
+		const refId = match[2];
+		const braceStart = match.index + match[0].length - 1;
+		const paramsBlock = extractBalancedBraces(str, braceStart);
+		if (!paramsBlock) continue;
+		let closeParen = braceStart + paramsBlock.length;
+		while (closeParen < str.length && str[closeParen] !== ")") closeParen++;
+		const fullCall = str.slice(match.index, closeParen + 1);
+		const replacement = `{ "__type": "${fnName}", "referenceId": "${refId}", "params": ${paramsBlock} }`;
+		result = result.slice(0, match.index + offset) + replacement + result.slice(match.index + offset + fullCall.length);
+		offset += replacement.length - fullCall.length;
+	}
+	return result;
+}
+//#endregion
+//#region src/backend/validation.ts
+const configureSyncInputSchema = zod_v4.z.object({
+	repo: zod_v4.z.string().regex(/^[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+$/, "Invalid repo format. Expected \"owner/name\".").optional(),
+	branch: zod_v4.z.string().max(256).regex(/^[a-zA-Z0-9._/-]+$/, "Invalid branch name.").optional(),
+	filePath: zod_v4.z.string().max(1024).regex(/^[a-zA-Z0-9._/-]+\.flow\.ts$/, "File path must end with .flow.ts").optional(),
+	mode: zod_v4.z.enum(require_shared_types.VC_SYNC_MODES).optional(),
+	syncDirection: zod_v4.z.enum(require_shared_types.VC_SYNC_DIRECTIONS).optional(),
+	enabled: zod_v4.z.boolean().optional()
+});
+const historyLimitSchema = zod_v4.z.coerce.number().int().min(1).max(100).default(20);
 //#endregion
 //#region src/backend/plugin.ts
 /**
@@ -780,6 +927,15 @@ function mapHistoryRow(r) {
 * ```
 */
 function versionControl(options) {
+	const { frontend, ...backendOptions } = options;
+	return {
+		id: "version-control",
+		name: "Version Control",
+		backend: _vcBackendPlugin(backendOptions),
+		frontend
+	};
+}
+function _vcBackendPlugin(options) {
 	let syncService;
 	let pluginLogger = console;
 	return {
@@ -798,10 +954,17 @@ function versionControl(options) {
 				path: "/vc/flows/:flowId/configure",
 				handler: async (ctx) => {
 					const { flowId } = ctx.params;
-					const input = ctx.body;
+					const parsed = configureSyncInputSchema.safeParse(ctx.body);
+					if (!parsed.success) return {
+						status: 400,
+						body: {
+							error: "Invalid input",
+							details: parsed.error.issues
+						}
+					};
 					return {
 						status: 200,
-						body: await syncService.configureSyncForFlow(ctx.database, flowId, input)
+						body: await syncService.configureSyncForFlow(ctx.database, flowId, parsed.data)
 					};
 				}
 			},
@@ -998,7 +1161,7 @@ function versionControl(options) {
 				path: "/vc/flows/:flowId/history",
 				handler: async (ctx) => {
 					const { flowId } = ctx.params;
-					const limit = ctx.query.limit ? parseInt(ctx.query.limit, 10) : 20;
+					const limit = historyLimitSchema.parse(ctx.query.limit);
 					return {
 						status: 200,
 						body: {
@@ -1012,25 +1175,23 @@ function versionControl(options) {
 		hooks: {}
 	};
 	async function handlePrMerged(db, prNumber) {
-		const rows = await db.query("SELECT flow_id FROM vc_sync_config WHERE active_pr_number = ?", [prNumber]);
+		const rows = await db.query("SELECT flow_id, draft_branch, repo FROM vc_sync_config WHERE active_pr_number = ?", [prNumber]);
 		for (const row of rows) {
+			if (row.draft_branch) try {
+				await options.provider.deleteBranch(row.repo, row.draft_branch);
+			} catch {}
 			await db.execute(`UPDATE vc_sync_config
          SET active_pr_number = NULL, active_pr_url = NULL, draft_branch = NULL, updated_at = ?
          WHERE flow_id = ?`, [(/* @__PURE__ */ new Date()).toISOString(), row.flow_id]);
-			const { randomUUID } = await import("node:crypto");
 			await db.execute(`INSERT INTO vc_sync_history (id, flow_id, action, pr_number, message, created_at)
          VALUES (?, ?, ?, ?, ?, ?)`, [
-				randomUUID(),
+				(0, node_crypto.randomUUID)(),
 				row.flow_id,
 				"pr-merged",
 				prNumber,
 				`PR #${prNumber} merged`,
 				(/* @__PURE__ */ new Date()).toISOString()
 			]);
-			const configs = await db.query("SELECT draft_branch, repo FROM vc_sync_config WHERE flow_id = ?", [row.flow_id]);
-			if (configs[0]?.draft_branch) try {
-				await options.provider.deleteBranch(configs[0].repo, configs[0].draft_branch);
-			} catch {}
 			pluginLogger.info("PR merged — sync updated", {
 				flowId: row.flow_id,
 				prNumber