@flue/sdk 0.3.2 → 0.3.3

package/dist/index.mjs

@@ -127,6 +127,83 @@ function validateUserWranglerConfig(config) {
 	}
 }
 /**
+* Compute Flue's migration contributions for a build.
+*
+* Algorithm:
+*
+* 1. Walk every existing migration entry in the user's config and union the
+*    SQLite-backed classes it declares — across `new_sqlite_classes` and
+*    the `to` side of `renamed_classes` / `transferred_classes`. The
+*    resulting set is "already-declared": every SQLite-backed class
+*    Cloudflare's runtime currently knows about for this Worker.
+*    `deleted_classes` and the `from` side of renames are subtracted, since
+*    they've been explicitly removed.
+*
+*    KV-backed classes (`new_classes`) are deliberately NOT added to the
+*    "declared" set. Flue agents always need a SQLite-backed class for
+*    session storage; if a user happens to have a KV-backed DO with the
+*    same name as a Flue agent, we still need to emit our SQLite migration.
+*    The deploy itself will then surface a clear "class already defined"
+*    error from Cloudflare rather than silently shipping a broken worker
+*    where the agent has no working session store.
+* 2. For each class in `currentClasses` that isn't already-declared, emit a
+*    deterministic per-class migration: one tag, one class. Per-class tags
+*    are essential because Cloudflare migration tags are immutable once
+*    deployed — packing all classes under a single shared tag (the original
+*    bug in issue #15) means new classes added on a redeploy are silently
+*    ignored. With per-class tags, every redeploy is a no-op except for
+*    the truly net-new classes.
+*
+* Renames and deletes are not auto-detected. If an agent file disappears,
+* Flue silently emits no migration for it — Cloudflare's runtime keeps the
+* orphaned class data alive but unbound, and the user can clean up (or
+* rename to recover) by adding a manual `renamed_classes` / `deleted_classes`
+* migration to their own wrangler.jsonc. Auto-emitting `deleted_classes`
+* would destroy stored DO data on every accidental file removal, which is
+* never the right default.
+*
+* Returned in alphabetical order so a regenerated `dist/wrangler.jsonc` is
+* byte-identical across machines and CI runs.
+*
+* Pure function: takes the current class list + the user's existing
+* migrations array (typically `userConfig.migrations` straight from
+* wrangler's reader) and returns the migrations to append. Doesn't read or
+* write any files.
+*/
+function computeFlueMigrations(currentClasses, userMigrations) {
+	const migrationsArray = Array.isArray(userMigrations) ? userMigrations : [];
+	const declared = /* @__PURE__ */ new Set();
+	for (const raw of migrationsArray) {
+		if (typeof raw !== "object" || raw === null) continue;
+		const m = raw;
+		const collectClassList = (key) => {
+			const v = m[key];
+			return Array.isArray(v) ? v.filter((c) => typeof c === "string") : [];
+		};
+		for (const c of collectClassList("new_sqlite_classes")) declared.add(c);
+		for (const c of collectClassList("deleted_classes")) declared.delete(c);
+		const renamed = Array.isArray(m.renamed_classes) ? m.renamed_classes : [];
+		for (const r of renamed) {
+			if (typeof r !== "object" || r === null) continue;
+			const obj = r;
+			if (typeof obj.from === "string") declared.delete(obj.from);
+			if (typeof obj.to === "string") declared.add(obj.to);
+		}
+		const transferred = Array.isArray(m.transferred_classes) ? m.transferred_classes : [];
+		for (const t of transferred) {
+			if (typeof t !== "object" || t === null) continue;
+			const obj = t;
+			if (typeof obj.to === "string") declared.add(obj.to);
+		}
+	}
+	const additions = [];
+	for (const c of [...currentClasses].sort()) if (!declared.has(c)) additions.push({
+		tag: `flue-class-${c}`,
+		new_sqlite_classes: [c]
+	});
+	return additions;
+}
+/**
 * Produce the merged wrangler config: start from the user's, layer Flue's
 * contributions on top. Pure function — caller handles reading and writing.
 */
@@ -149,7 +226,10 @@ function mergeFlueAdditions(userConfig, additions) {
 	const existingMigrations = Array.isArray(merged.migrations) ? merged.migrations : [];
 	const existingMigrationTags = new Set(existingMigrations.filter((m) => typeof m === "object" && m !== null).map((m) => m.tag).filter((t) => typeof t === "string"));
 	const migrationsOut = [...existingMigrations];
-	if (!existingMigrationTags.has(additions.migration.tag)) migrationsOut.push(additions.migration);
+	for (const migration of additions.migrations) if (!existingMigrationTags.has(migration.tag)) {
+		migrationsOut.push(migration);
+		existingMigrationTags.add(migration.tag);
+	}
 	merged.migrations = migrationsOut;
 	return merged;
 }
@@ -316,6 +396,9 @@ var CloudflarePlugin = class {
 }`;
 		}).join("\n\n");
 		const { config: userConfig } = await this.getUserConfig(ctx.outputDir);
+		const sandboxClassNames = detectSandboxBindings(userConfig);
+		const sandboxReExports = sandboxClassNames.map((name) => `export { Sandbox as ${name} } from '@cloudflare/sandbox';`).join("\n");
+		const sandboxClassImport = sandboxClassNames.length > 0 ? `import { Sandbox as __FlueCfSandbox } from '@cloudflare/sandbox';` : "";
 		return `
 // Auto-generated by @flue/sdk build (cloudflare)
 import { Agent, routeAgentRequest } from 'agents';
@@ -327,7 +410,7 @@ import {
   resolveModel,
 } from '@flue/sdk/internal';
 import { runWithCloudflareContext, cfSandboxToSessionEnv } from '@flue/sdk/cloudflare';
-
+${sandboxClassImport ? "\n" + sandboxClassImport : ""}
 ${agentImports}
 
 // ─── Config ─────────────────────────────────────────────────────────────────
@@ -371,19 +454,19 @@ async function createLocalEnv() {
 
 /**
  * Detect and wrap external sandbox instances (e.g. from @cloudflare/sandbox's
- * getSandbox()). Returns SessionEnv if the object quacks like a container
- * sandbox, null otherwise.
+ * getSandbox()). Returns SessionEnv if the value is a @cloudflare/sandbox
+ * RPC stub, null otherwise.
+ *
+ * NOTE: We must use \`instanceof\` here, not structural duck-typing. The value
+ * returned by \`getSandbox()\` is a workerd RPC Proxy that returns \`true\` for
+ * any \`in\` check and \`'function'\` for \`typeof <anything>\`, so structural
+ * checks (positive or negative) are unreliable against it. \`instanceof\` walks
+ * the prototype chain via the runtime, which the proxy can't fake.
  */
 function resolveSandbox(sandbox) {
-  if (
-    sandbox && typeof sandbox === 'object' &&
-    typeof sandbox.exec === 'function' &&
-    typeof sandbox.readFile === 'function' &&
-    typeof sandbox.destroy === 'function' &&
-    !('getCwd' in sandbox) && !('fs' in sandbox)
-  ) {
+  ${sandboxClassNames.length > 0 ? `if (sandbox instanceof __FlueCfSandbox) {
     return cfSandboxToSessionEnv(sandbox);
-  }
+  }` : "/* no @cloudflare/sandbox bindings declared in wrangler config */"}
   return null;
 }
 
@@ -613,7 +696,7 @@ ${agentClasses}
 // \`@cloudflare/sandbox\` so each user-chosen class_name resolves at the
 // bundle's top level. The binding + container image configuration is owned
 // by the user's wrangler.jsonc.
-${detectSandboxBindings(userConfig).map((name) => `export { Sandbox as ${name} } from '@cloudflare/sandbox';`).join("\n")}
+${sandboxReExports}
 
 // ─── Worker Fetch Handler ───────────────────────────────────────────────────
 
@@ -652,18 +735,16 @@ export default {
 			name: agentClassName(a.name)
 		}));
 		const flueSqliteClasses = flueBindings.map((b) => b.class_name);
+		const { config: userConfig, path: userConfigPath } = await this.getUserConfig(ctx.outputDir);
+		if (userConfigPath) console.log(`[flue] Merging with user wrangler config: ${userConfigPath}`);
+		validateUserWranglerConfig(userConfig);
+		const flueMigrations = computeFlueMigrations(flueSqliteClasses, userConfig.migrations);
 		const additions = {
 			defaultName: path.basename(ctx.outputDir) || "flue-agents",
 			main: "_entry.ts",
 			doBindings: flueBindings,
-			migration: {
-				tag: "flue-v1",
-				new_sqlite_classes: flueSqliteClasses
-			}
+			migrations: flueMigrations
 		};
-		const { config: userConfig, path: userConfigPath } = await this.getUserConfig(ctx.outputDir);
-		if (userConfigPath) console.log(`[flue] Merging with user wrangler config: ${userConfigPath}`);
-		validateUserWranglerConfig(userConfig);
 		const sandboxClassNames = detectSandboxBindings(userConfig);
 		if (sandboxClassNames.length > 0) {
 			assertSandboxPackageInstalled(sandboxClassNames, [ctx.outputDir, ctx.workspaceDir]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flue/sdk",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "type": "module",
   "license": "Apache-2.0",
   "exports": {