@flue/sdk 0.3.2 → 0.3.4

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;
 }
@@ -319,6 +399,7 @@ var CloudflarePlugin = class {
 		return `
 // Auto-generated by @flue/sdk build (cloudflare)
 import { Agent, routeAgentRequest } from 'agents';
+import { DurableObject } from 'cloudflare:workers';
 import { Bash, InMemoryFs } from 'just-bash';
 import {
   createFlueContext,
@@ -371,17 +452,28 @@ 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 looks like a Durable Object
+ * RPC stub, null otherwise.
+ *
+ * NOTE on detection: The value returned by \`getSandbox()\` is a workerd RPC
+ * Proxy. \`in\` and \`typeof\` against it return \`true\`/\`'function'\` for any
+ * property name, so structural duck-typing is unreliable.
+ *
+ * \`instanceof <UserSandboxClass>\` ALSO does not work: the RPC stub's
+ * prototype chain is workerd's internal \`DurableObject\` runtime class, not
+ * the user-defined \`Sandbox\` class (the user's class only exists on the
+ * in-DO side; the caller side gets a generic stub). Empirically:
+ *   typeof stub === 'object'
+ *   Object.getPrototypeOf(stub).constructor.name === 'DurableObject'
+ *
+ * \`instanceof DurableObject\` (imported from \`cloudflare:workers\`) is the
+ * one signal that holds: it walks the prototype chain via the runtime and
+ * matches any DO RPC stub. We treat any DO stub passed to \`init({ sandbox })\`
+ * as intended for \`@cloudflare/sandbox\`, since that's the only documented
+ * use case for that argument shape on the Cloudflare target.
  */
 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)
-  ) {
+  if (sandbox instanceof DurableObject) {
     return cfSandboxToSessionEnv(sandbox);
   }
   return null;
@@ -652,18 +744,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.4",
   "type": "module",
   "license": "Apache-2.0",
   "exports": {