@flue/sdk 0.3.1 → 0.3.2

package/README.md

@@ -318,6 +318,17 @@ Defaults to port `3583` ("FLUE" on a phone keypad). Override with `--port`.
 
 `flue dev --target cloudflare` requires `wrangler` as a peer dependency in your project (`npm install --save-dev wrangler`).
 
+#### Loading environment variables
+
+Pass `--env <path>` to load a `.env`-format file. Works for both targets:
+
+```bash
+flue dev --target node --env .env
+flue dev --target cloudflare --env .env
+```
+
+Repeatable; later files override earlier ones on key collision. Shell-set env vars win over file values. Edits to the file trigger a reload. Same flag works for `flue run`.
+
 ### Trigger From the CLI (`flue run`)
 
 Build and run any agent locally, perfect for running in CI or for one-shot scripted invocations. Production-shaped — builds the deployable artifact and starts it once.

package/dist/index.d.mts

@@ -43,6 +43,24 @@ interface DevOptions {
   target: 'node' | 'cloudflare';
   /** Defaults to 3583 ("FLUE" on a phone keypad). */
   port?: number;
+  /**
+   * Absolute paths to env files (`.env`-format) to load before starting the
+   * dev server. Repeatable; later files override earlier ones on key
+   * collision (matching wrangler's `envFiles` semantics and standard
+   * dotenv composition patterns).
+   *
+   * - Node: parsed with `node:util.parseEnv` and merged into the child
+   *   server process's env. Shell-set env vars win over file values.
+   * - Cloudflare: passed through to wrangler's `unstable_startWorker` as
+   *   `envFiles`, which loads them as `secret_text` bindings.
+   *
+   * If empty/undefined, no env loading happens. Cloudflare's auto-discovery
+   * of `.dev.vars` is disabled in either case (we always pass an explicit
+   * `envFiles` array to wrangler so its default search is suppressed).
+   *
+   * Each path must exist; otherwise dev fails fast with a clear error.
+   */
+  envFiles?: string[];
 }
 /** Default port for `flue dev`. F=3, L=5, U=8, E=3 on a phone keypad. */
 declare const DEFAULT_DEV_PORT = 3583;
@@ -53,6 +71,26 @@ declare const DEFAULT_DEV_PORT = 3583;
  * — the user is editing code, after all, and we want to recover when they fix it.
  */
 declare function dev(options: DevOptions): Promise<void>;
+/**
+ * Resolve and validate a list of env-file paths. Returns absolute paths.
+ *
+ * Throws a friendly `[flue]`-prefixed error if any path doesn't exist. The
+ * goal of `--env` is explicitness — silent skip on a typo would defeat
+ * the purpose.
+ */
+declare function resolveEnvFiles(envFiles: string[] | undefined, cwd: string): string[];
+/**
+ * Parse one or more `.env`-format files and return their merged contents.
+ * Later files override earlier files on key collision.
+ *
+ * Uses Node's built-in `util.parseEnv` (Node 20.6+; Flue requires Node 22+).
+ * No `dotenv` package needed.
+ *
+ * Parse-only — doesn't touch `process.env`. Caller composes with
+ * `process.env` as needed (typical pattern: spread file vars first, then
+ * `process.env`, so shell-set values win).
+ */
+declare function parseEnvFiles(absolutePaths: string[]): Record<string, string>;
 //#endregion
 //#region src/agent.d.ts
 declare const BUILTIN_TOOL_NAMES: Set<string>;
@@ -75,4 +113,4 @@ interface CreateToolsOptions {
 }
 declare function createTools(env: SessionEnv, options?: CreateToolsOptions): AgentTool<any>[];
 //#endregion
-export { type AgentConfig, type AgentInfo, type AgentInit, BUILTIN_TOOL_NAMES, type BashFactory, type BashLike, type BuildContext, type BuildOptions, type BuildPlugin, type Command, type CommandDef, DEFAULT_DEV_PORT, type DevOptions, type FileStat, type FlueAgent, type FlueContext, type FlueEvent, type FlueEventCallback, type FlueSession, type FlueSessions, type PromptOptions, type PromptResponse, type Role, type SandboxFactory, type SessionData, type SessionEnv, type SessionOptions, type SessionStore, type ShellOptions, type ShellResult, type Skill, type SkillOptions, type TaskOptions, type ToolDef, type ToolParameters, build, createTools, dev, resolveWorkspaceFromCwd };
+export { type AgentConfig, type AgentInfo, type AgentInit, BUILTIN_TOOL_NAMES, type BashFactory, type BashLike, type BuildContext, type BuildOptions, type BuildPlugin, type Command, type CommandDef, DEFAULT_DEV_PORT, type DevOptions, type FileStat, type FlueAgent, type FlueContext, type FlueEvent, type FlueEventCallback, type FlueSession, type FlueSessions, type PromptOptions, type PromptResponse, type Role, type SandboxFactory, type SessionData, type SessionEnv, type SessionOptions, type SessionStore, type ShellOptions, type ShellResult, type Skill, type SkillOptions, type TaskOptions, type ToolDef, type ToolParameters, build, createTools, dev, parseEnvFiles, resolveEnvFiles, resolveWorkspaceFromCwd };

package/dist/index.mjs

@@ -4,6 +4,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { packageUpSync } from "package-up";
 import { spawn } from "node:child_process";
+import { parseEnv } from "node:util";
 
 //#region src/cloudflare-wrangler-merge.ts
 /**
@@ -153,6 +154,38 @@ function mergeFlueAdditions(userConfig, additions) {
 	return merged;
 }
 /**
+* Strip wrangler-normalizer defaults that cause spurious warnings when wrangler
+* re-parses our generated dist/wrangler.jsonc.
+*
+* Background: `unstable_readConfig` returns a fully-normalized `Unstable_Config`
+* with every section populated to a default — including `unsafe: {}`. Wrangler's
+* own validator then emits a `"unsafe" fields are experimental` warning whenever
+* the field is *present*, regardless of whether it's empty. So our merged file,
+* which inherits the empty default, would trip the warning at every dev start
+* and every deploy.
+*
+* We delete `unsafe` only when it's an empty object (the exact shape wrangler's
+* normalizer produces). If a user has actually written `unsafe: {...}` in their
+* own wrangler.jsonc, the value will be non-empty and we leave it alone — the
+* warning in that case is wrangler's intended diagnostic, not noise.
+*
+* Other normalizer-defaulted-empty fields (`vars: {}`, `kv_namespaces: []`,
+* `python_modules: { exclude: ['**\/*.pyc'] }`, etc.) are left in place. They're
+* harmless: wrangler doesn't warn about them, dist/wrangler.jsonc is an
+* internal build artifact, and stripping them only saves bytes. Only `unsafe`
+* has a user-visible side effect we need to fix.
+*
+* If wrangler adds another field to its `experimental()` warning list in a
+* future version (today there are only two: `unsafe` and `secrets`), this
+* function is the place to extend.
+*
+* Mutates `merged` in place to match the shallow-clone pattern in
+* `mergeFlueAdditions`.
+*/
+function stripNoisyWranglerDefaults(merged) {
+	if ("unsafe" in merged && typeof merged.unsafe === "object" && merged.unsafe !== null && !Array.isArray(merged.unsafe) && Object.keys(merged.unsafe).length === 0) delete merged.unsafe;
+}
+/**
 * Return the list of `class_name`s declared in the user's wrangler
 * `durable_objects.bindings` that contain the literal substring `Sandbox`
 * (case-sensitive).
@@ -637,6 +670,7 @@ export default {
 			for (const className of sandboxClassNames) console.log(`[flue] Detected Sandbox-named DO binding "${className}" — re-exporting from @cloudflare/sandbox.`);
 		}
 		const merged = mergeFlueAdditions(userConfig, additions);
+		stripNoisyWranglerDefaults(merged);
 		if (typeof merged.$schema !== "string") merged.$schema = "https://workers.cloudflare.com/schema/wrangler.json";
 		outputs["wrangler.jsonc"] = JSON.stringify(merged, null, 2);
 		writeDeployRedirectIfMissing(ctx.outputDir);
@@ -1155,6 +1189,8 @@ async function dev(options) {
 	const workspaceDir = path.resolve(options.workspaceDir);
 	const outputDir = path.resolve(options.outputDir);
 	const port = options.port ?? DEFAULT_DEV_PORT;
+	const envFiles = resolveEnvFiles(options.envFiles, outputDir);
+	for (const f of envFiles) console.error(`[flue] Loading env from: ${f}`);
 	const buildOptions = {
 		workspaceDir,
 		outputDir,
@@ -1172,10 +1208,12 @@ async function dev(options) {
 	console.error(`[flue] Built in ${Date.now() - initialStart}ms`);
 	const reloader = options.target === "node" ? new NodeReloader({
 		outputDir,
-		port
+		port,
+		envFiles
 	}) : await createCloudflareReloader({
 		outputDir,
-		port
+		port,
+		envFiles
 	});
 	await reloader.start();
 	if (reloader.url) {
@@ -1188,14 +1226,17 @@ async function dev(options) {
 	}
 	console.error(`[flue] Press Ctrl+C to stop\n`);
 	const rebuilder = createRebuilder(buildOptions, reloader);
+	const envFileSet = new Set(envFiles);
 	const watcher = createWatcher({
 		workspaceDir,
 		outputDir,
 		target: options.target,
+		envFiles,
 		onChange: (relPath) => {
 			if (!reloader.shouldRebuildOn(relPath)) return;
+			const isEnvFile = envFileSet.has(relPath);
 			console.error(`[flue] Change detected: ${relPath}`);
-			rebuilder.schedule();
+			rebuilder.schedule(isEnvFile);
 		}
 	});
 	let shuttingDown = false;
@@ -1224,31 +1265,40 @@ async function dev(options) {
 function createRebuilder(buildOptions, reloader) {
 	let running = false;
 	let queued = false;
+	let queuedForce = false;
+	let pendingForce = false;
 	let debounceTimer = null;
-	const runOnce = async () => {
+	const runOnce = async (force) => {
 		running = true;
 		const start = Date.now();
 		console.error(`[flue] Rebuilding...`);
 		try {
 			const { changed } = await build(buildOptions);
-			await reloader.reload(changed);
+			await reloader.reload(changed || force);
 			console.error(`[flue] Reloaded in ${Date.now() - start}ms\n`);
 		} catch (err) {
 			console.error(`[flue] Rebuild failed: ${err instanceof Error ? err.message : String(err)}\n`);
 		} finally {
 			running = false;
 			if (queued) {
+				const nextForce = queuedForce;
 				queued = false;
-				runOnce();
+				queuedForce = false;
+				runOnce(nextForce);
 			}
 		}
 	};
-	return { schedule() {
+	return { schedule(forceReload = false) {
+		if (forceReload) pendingForce = true;
 		if (debounceTimer) clearTimeout(debounceTimer);
 		debounceTimer = setTimeout(() => {
 			debounceTimer = null;
-			if (running) queued = true;
-			else runOnce();
+			const force = pendingForce;
+			pendingForce = false;
+			if (running) {
+				queued = true;
+				if (force) queuedForce = true;
+			} else runOnce(force);
 		}, 150);
 	} };
 }
@@ -1267,7 +1317,7 @@ function createRebuilder(buildOptions, reloader) {
 *   - editor backup/swap suffixes
 */
 function createWatcher(options) {
-	const { workspaceDir, outputDir, target, onChange } = options;
+	const { workspaceDir, outputDir, target, envFiles, onChange } = options;
 	const watchers = [];
 	const isIgnoredPath = (relPath) => {
 		const parts = relPath.replace(/\\/g, "/").split("/");
@@ -1307,6 +1357,10 @@ function createWatcher(options) {
 			watchers.push(w);
 		} catch {}
 	}
+	for (const envPath of envFiles) try {
+		const w = fs.watch(envPath, () => onChange(envPath));
+		watchers.push(w);
+	} catch {}
 	return { close() {
 		for (const w of watchers) try {
 			w.close();
@@ -1318,10 +1372,12 @@ var NodeReloader = class {
 	serverPath;
 	outputDir;
 	port;
+	envFiles;
 	url;
 	constructor(opts) {
 		this.outputDir = opts.outputDir;
 		this.port = opts.port;
+		this.envFiles = opts.envFiles;
 		this.serverPath = path.join(this.outputDir, "dist", "server.mjs");
 		this.url = `http://localhost:${this.port}`;
 	}
@@ -1346,6 +1402,7 @@ var NodeReloader = class {
 		} catch {}
 	}
 	async spawnAndWait() {
+		const fromFiles = parseEnvFiles(this.envFiles);
 		const child = spawn("node", [this.serverPath], {
 			stdio: [
 				"ignore",
@@ -1354,6 +1411,7 @@ var NodeReloader = class {
 			],
 			cwd: this.outputDir,
 			env: {
+				...fromFiles,
 				...process.env,
 				PORT: String(this.port),
 				FLUE_MODE: "local"
@@ -1436,11 +1494,13 @@ var CloudflareReloader = class {
 	outputDir;
 	port;
 	configPath;
+	envFiles;
 	url;
 	constructor(wrangler, opts) {
 		this.wrangler = wrangler;
 		this.outputDir = opts.outputDir;
 		this.port = opts.port;
+		this.envFiles = opts.envFiles;
 		this.configPath = path.join(this.outputDir, "dist", "wrangler.jsonc");
 	}
 	async start() {
@@ -1467,6 +1527,7 @@ var CloudflareReloader = class {
 	* baked into the entry).
 	*/
 	shouldRebuildOn(relPath) {
+		if (this.envFiles.includes(relPath)) return true;
 		const normalized = relPath.replace(/\\/g, "/");
 		if (normalized === "wrangler.jsonc" || normalized === "wrangler.json" || normalized === "wrangler.toml") return true;
 		if (normalized.startsWith("agents/")) return true;
@@ -1491,6 +1552,7 @@ var CloudflareReloader = class {
 		if (!fs.existsSync(this.configPath)) throw new Error(`[flue] Expected ${this.configPath} after build, but it doesn't exist. Did the Cloudflare build succeed?`);
 		this.worker = await this.wrangler.unstable_startWorker({
 			config: this.configPath,
+			envFiles: this.envFiles,
 			build: { nodejsCompatMode: "v2" },
 			dev: {
 				server: {
@@ -1518,6 +1580,40 @@ var CloudflareReloader = class {
 		}
 	}
 };
+/**
+* Resolve and validate a list of env-file paths. Returns absolute paths.
+*
+* Throws a friendly `[flue]`-prefixed error if any path doesn't exist. The
+* goal of `--env` is explicitness — silent skip on a typo would defeat
+* the purpose.
+*/
+function resolveEnvFiles(envFiles, cwd) {
+	if (!envFiles || envFiles.length === 0) return [];
+	return envFiles.map((p) => {
+		const abs = path.isAbsolute(p) ? p : path.resolve(cwd, p);
+		if (!fs.existsSync(abs)) throw new Error(`[flue] --env points at a path that doesn't exist: ${p}`);
+		return abs;
+	});
+}
+/**
+* Parse one or more `.env`-format files and return their merged contents.
+* Later files override earlier files on key collision.
+*
+* Uses Node's built-in `util.parseEnv` (Node 20.6+; Flue requires Node 22+).
+* No `dotenv` package needed.
+*
+* Parse-only — doesn't touch `process.env`. Caller composes with
+* `process.env` as needed (typical pattern: spread file vars first, then
+* `process.env`, so shell-set values win).
+*/
+function parseEnvFiles(absolutePaths) {
+	const merged = {};
+	for (const p of absolutePaths) {
+		const parsed = parseEnv(fs.readFileSync(p, "utf-8"));
+		Object.assign(merged, parsed);
+	}
+	return merged;
+}
 async function waitForHealth(baseUrl, timeoutMs) {
 	const start = Date.now();
 	while (Date.now() - start < timeoutMs) {
@@ -1565,4 +1661,4 @@ function pickExampleAgentName(outputDir, workspaceDir) {
 }
 
 //#endregion
-export { BUILTIN_TOOL_NAMES, DEFAULT_DEV_PORT, build, createTools, dev, resolveWorkspaceFromCwd };
+export { BUILTIN_TOOL_NAMES, DEFAULT_DEV_PORT, build, createTools, dev, parseEnvFiles, resolveEnvFiles, resolveWorkspaceFromCwd };

package/package.json

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