@flue/sdk 0.3.11 → 0.4.0

package/dist/config.mjs

@@ -0,0 +1,195 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as v from "valibot";
+import { pathToFileURL } from "node:url";
+
+//#region src/config.ts
+/**
+* Flue config file support — `flue.config.{ts,mts,mjs,js,cjs,cts}`.
+*
+* Modeled on Vite/Astro:
+*
+*   - The config file lives at the project root. Its directory IS the root for
+*     the purposes of resolving any relative paths it sets (`root`, `output`).
+*   - Discovery: `--config <path>` (resolved vs. cwd) wins; otherwise we search
+*     a starting directory (`--root` if given, else cwd) for any of the
+*     supported extensions, in order.
+*   - Loading: plain Node dynamic `import()`. We rely on Node's native
+*     TypeScript type-stripping (Node ≥ 22.18 / ≥ 23.6 by default) to handle
+*     `.ts` configs. We deliberately do NOT bundle the config — `flue.config`
+*     is a flat declarative surface, and "what valid TS works" should match
+*     the same rules the user already absorbed for the rest of the runtime.
+*     The CLI bin pre-checks the Node version before we ever get here, so
+*     `ERR_UNKNOWN_FILE_EXTENSION` shouldn't surface in practice.
+*   - Validation: valibot schema on the user-facing shape.
+*   - Resolution: CLI inline > config file > built-in defaults. CLI flags
+*     always win on a per-field basis — only the fields the user actually
+*     passed get to override the file.
+*
+* The two public types mirror Astro's `AstroUserConfig` / `AstroConfig`
+* split: `UserFlueConfig` is what users author (everything optional);
+* `FlueConfig` is the resolved shape with required defaults filled in.
+*
+* Provider/model configuration lives in `app.ts`, where runtime env is
+* available.
+*/
+/**
+* Identity helper for type inference and editor intellisense, à la Vite's
+* `defineConfig`. Returns its argument unchanged.
+*
+* ```ts
+* import { defineConfig } from '@flue/sdk/config';
+* export default defineConfig({ target: 'node' });
+* ```
+*/
+function defineConfig(config) {
+	return config;
+}
+const TargetSchema = v.picklist(["node", "cloudflare"]);
+const UserFlueConfigSchema = v.strictObject({
+	target: v.optional(TargetSchema),
+	root: v.optional(v.string()),
+	output: v.optional(v.string())
+});
+/**
+* Config file basenames searched, in priority order. TypeScript first because
+* Flue's audience writes TS agents; the rest mirror Vite's supported set.
+*/
+const CONFIG_BASENAMES = Object.freeze([
+	"flue.config.ts",
+	"flue.config.mts",
+	"flue.config.mjs",
+	"flue.config.js",
+	"flue.config.cjs",
+	"flue.config.cts"
+]);
+/**
+* Resolve the absolute path of the user's `flue.config.*` file, or
+* `undefined` if none is found and the user didn't ask for one.
+*
+* Throws if `configFile` is an explicit path that doesn't exist on disk —
+* that's a typo, not a "config not configured" situation.
+*/
+function resolveConfigPath(opts) {
+	if (opts.configFile === false) return void 0;
+	if (opts.configFile) {
+		const explicit = path.isAbsolute(opts.configFile) ? opts.configFile : path.resolve(opts.cwd, opts.configFile);
+		if (!fs.existsSync(explicit)) throw new Error(`[flue] Config file not found: ${opts.configFile}`);
+		return explicit;
+	}
+	for (const basename of CONFIG_BASENAMES) {
+		const candidate = path.join(opts.cwd, basename);
+		if (fs.existsSync(candidate)) return candidate;
+	}
+}
+/**
+* Load a config file's `default` export. We rely on Node's native dynamic
+* `import()` for everything: plain JS, ESM, and TypeScript via type-stripping
+* (Node ≥ 22.18 / ≥ 23.6 enable this by default). The CLI's bin entrypoint
+* pre-validates the Node version, so by the time we reach this function the
+* runtime is known to support the formats we accept.
+*
+* Cache-bust via a query param so repeated loads (e.g. a future dev-server
+* config-watcher) get a fresh module instead of the cached one.
+*
+* Errors that come out of strip-mode (`ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`)
+* are repackaged with a hint pointing at the constraint, since the original
+* Node message is terse.
+*
+* Returns the raw module default — caller is responsible for validation.
+*/
+async function loadConfigModule(absConfigPath) {
+	const fileUrl = pathToFileURL(absConfigPath).href + `?t=${Date.now()}`;
+	try {
+		const mod = await import(fileUrl);
+		return mod.default ?? mod;
+	} catch (err) {
+		const code = err.code;
+		if (code === "ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX") throw new Error(`[flue] ${path.basename(absConfigPath)} uses TypeScript syntax that Node's type-stripping loader doesn't support (e.g. \`enum\`, \`namespace\` with runtime code, parameter properties, decorators). Rewrite using only erasable types (or move the config to plain JS).\n  Original: ${err.message}`);
+		if (code === "ERR_UNKNOWN_FILE_EXTENSION") throw new Error(`[flue] Cannot load ${path.basename(absConfigPath)}: this Node (v${process.versions.node}) does not support TypeScript natively. Upgrade to Node ≥ 22.18 or ≥ 23.6.`);
+		throw err;
+	}
+}
+/**
+* Discover, load, validate, merge, and resolve a Flue config. The single
+* entry point CLIs and embedders call.
+*
+* Precedence (highest first):
+*   1. CLI inline values (`opts.inline.*`)
+*   2. `flue.config.ts`
+*   3. Built-in defaults
+*
+* Throws if validation fails or if no `target` is supplied anywhere.
+*/
+async function resolveConfig(opts) {
+	const cwd = path.resolve(opts.cwd);
+	const searchFrom = path.resolve(opts.searchFrom ?? cwd);
+	const configPath = resolveConfigPath({
+		cwd: searchFrom,
+		configFile: opts.configFile
+	});
+	let fileConfig = {};
+	if (configPath) {
+		const raw = await loadConfigModule(configPath);
+		if (raw == null || typeof raw !== "object") throw new Error(`[flue] ${path.relative(cwd, configPath) || configPath} must export a config object as the default export.`);
+		const result = v.safeParse(UserFlueConfigSchema, raw);
+		if (!result.success) throw new Error(formatValidationError(configPath, result.issues));
+		fileConfig = result.output;
+	}
+	const configDir = configPath ? path.dirname(configPath) : searchFrom;
+	const inline = opts.inline ?? {};
+	const merged = {
+		target: inline.target ?? fileConfig.target,
+		root: inline.root ?? fileConfig.root,
+		output: inline.output ?? fileConfig.output
+	};
+	if (!merged.target) throw new Error("[flue] Missing required `target`. Set it via `--target <node|cloudflare>` or in `flue.config.ts` as `target: \"node\"` (or `\"cloudflare\"`).");
+	const root = resolvePath(merged.root, {
+		fromConfig: !!fileConfig.root && inline.root === void 0,
+		configDir,
+		fallback: configDir
+	});
+	const output = resolvePath(merged.output, {
+		fromConfig: !!fileConfig.output && inline.output === void 0,
+		configDir,
+		fallback: path.join(root, "dist")
+	});
+	return {
+		configPath,
+		userConfig: merged,
+		flueConfig: {
+			target: merged.target,
+			root,
+			output
+		}
+	};
+}
+/**
+* Resolve a possibly-relative path to an absolute one.
+*
+* - If `value` is undefined, returns `fallback`.
+* - If `value` is absolute, returns it as-is.
+* - If `value` is relative AND came from the config file, resolves vs. the
+*   config dir.
+* - If `value` is relative AND came from the CLI, the CLI is responsible for
+*   already having absolutized it (`path.resolve` against cwd at parse time)
+*   — this branch is defensive and resolves against `process.cwd()`.
+*/
+function resolvePath(value, opts) {
+	if (!value) return opts.fallback;
+	if (path.isAbsolute(value)) return value;
+	if (opts.fromConfig) return path.resolve(opts.configDir, value);
+	return path.resolve(value);
+}
+function formatValidationError(configPath, issues) {
+	const lines = [`[flue] Invalid config in ${configPath}:`];
+	for (const issue of issues) {
+		const dotPath = v.getDotPath(issue);
+		const where = dotPath ? `  • ${dotPath}: ` : "  • ";
+		lines.push(`${where}${issue.message}`);
+	}
+	return lines.join("\n");
+}
+
+//#endregion
+export { defineConfig, resolveConfig, resolveConfigPath };

package/dist/flue-app-CG8i4wNG.d.mts

@@ -0,0 +1,184 @@
+import { FlueContextInternal } from "./client.mjs";
+import { Hono } from "hono";
+
+//#region src/runtime/handle-agent.d.ts
+/**
+ * Agent handler signature — the default export of a `.flue/agents/<name>.ts`
+ * file. Receives a context, may return any JSON-serializable value (or
+ * undefined for fire-and-forget agents).
+ */
+type AgentHandler = (ctx: FlueContextInternal) => unknown | Promise<unknown>;
+/**
+ * Caller-provided context factory. Differs per-target:
+ *   - Node: env=process.env, defaultStore=in-memory, no resolveSandbox.
+ *   - Cloudflare: env=DO env, defaultStore=DO SQLite, resolveSandbox=cfSandboxToSessionEnv.
+ */
+type CreateContextFn = (id: string, payload: unknown, request: Request) => FlueContextInternal;
+/**
+ * Webhook execution wrapper. Receives the prepared run callback and returns
+ * a promise that resolves with the handler's return value. Implementations:
+ *
+ *   - Node: just `run()` — no fiber, no DO.
+ *   - Cloudflare: `doInstance.runFiber('flue:webhook:<requestId>', run)`.
+ *
+ * The caller is responsible for any logging on completion/error; this routine
+ * just kicks it off and returns the 202.
+ */
+type StartWebhookFn = (requestId: string, run: () => Promise<unknown>) => Promise<unknown>;
+/**
+ * Foreground handler execution wrapper. Wraps the call to `handler(ctx)` so
+ * targets can layer in keepalive / context propagation. Defaults to direct
+ * invocation when omitted.
+ */
+type RunHandlerFn = (ctx: FlueContextInternal, handler: AgentHandler) => unknown | Promise<unknown>;
+interface HandleAgentOptions {
+  /** Standard Fetch Request. */
+  request: Request;
+  /**
+   * The agent name (URL segment). Used only in webhook completion / error
+   * log lines — routing has already happened by the time we get here.
+   */
+  agentName: string;
+  /** Agent id (URL segment / DO room name). */
+  id: string;
+  /** The agent's default-export handler. */
+  handler: AgentHandler;
+  /** Per-target context factory. */
+  createContext: CreateContextFn;
+  /**
+   * Per-target webhook runner. If omitted, fire-and-forget executes the
+   * prepared `run` callback directly (Node default — handler runs in the
+   * same process as the request handler). On Cloudflare the caller MUST
+   * provide this with a `runFiber` wrapper so the handler survives DO
+   * hibernation between the 202 ack and the actual completion.
+   */
+  startWebhook?: StartWebhookFn;
+  /**
+   * Per-target foreground handler wrapper. If omitted, the handler is
+   * invoked directly (Node default). On Cloudflare this is a
+   * `runWithCloudflareContext` + `keepAliveWhile` wrapper that propagates
+   * `env` via AsyncLocalStorage and prevents the DO from hibernating
+   * mid-stream.
+   */
+  runHandler?: RunHandlerFn;
+}
+/**
+ * Dispatch a single `/agents/:name/:id` request. The mode is chosen by
+ * inspecting headers:
+ *
+ *   - `X-Webhook: true` → fire-and-forget. Returns 202 immediately; the
+ *     handler runs in the background. Errors are logged server-side.
+ *   - `Accept: text/event-stream` (and not webhook) → SSE streaming. Returns
+ *     200 + text/event-stream. Events come from the FlueContext's event
+ *     callback; final result is appended as `event: result`. Per-event errors
+ *     surface as `event: error` envelopes.
+ *   - Otherwise → sync. Returns 200 + JSON `{ result }`.
+ *
+ * Errors thrown BEFORE streaming starts (body parse, agent lookup) bubble
+ * out as a `Response` via {@link toHttpResponse} — headers haven't been sent
+ * yet, so a regular HTTP error is still possible. Errors thrown AFTER the
+ * 200 + text/event-stream headers are on the wire (i.e. inside the agent
+ * handler) get framed as in-stream `error` events instead.
+ *
+ * Caller is responsible for routing — this function assumes the request has
+ * already been validated as a POST against a registered agent.
+ */
+declare function handleAgentRequest(opts: HandleAgentOptions): Promise<Response>;
+//#endregion
+//#region src/runtime/flue-app.d.ts
+/**
+ * Runtime configuration for {@link flue}, seeded by the generated server
+ * entry before the user's `app.ts` is imported. The shape is internal —
+ * users never construct this directly.
+ *
+ * The Node/Cloudflare branches use different fields. Splitting via a
+ * discriminated union would type-check more cleanly, but since the only
+ * caller of `configureFlueRuntime` is the build's own generated code,
+ * a flat optional-fields shape is simpler to maintain.
+ */
+interface FlueRuntime {
+  target: 'node' | 'cloudflare';
+  /**
+   * Names of agents reachable over HTTP when not in local mode.
+   * Trigger-less agents are excluded from this list and gate access
+   * via {@link FlueRuntime.allowNonWebhook}.
+   */
+  webhookAgents: ReadonlyArray<string>;
+  /**
+   * If true, the agent route accepts any registered agent — including
+   * trigger-less ones. Used by the Node target when `FLUE_MODE=local`
+   * (set by `flue run` and `flue dev --target node`). Always false on
+   * Cloudflare today.
+   */
+  allowNonWebhook: boolean;
+  /**
+   * Map of agent name → handler function. Includes ALL agents (webhook
+   * and trigger-less); {@link webhookAgents} gates HTTP exposure when
+   * not in local mode. Required when {@link target} is `'node'`.
+   */
+  handlers?: Record<string, AgentHandler>;
+  /**
+   * Per-target context factory. Required when {@link target} is `'node'`.
+   */
+  createContext?: CreateContextFn;
+  /** Optional Node webhook execution wrapper. Defaults to direct invocation. */
+  startWebhook?: StartWebhookFn;
+  /** Optional Node foreground handler wrapper. Defaults to direct invocation. */
+  runHandler?: RunHandlerFn;
+  /**
+   * Forward an incoming request to the per-agent Durable Object via
+   * Cloudflare's Agents SDK. Required when {@link target} is `'cloudflare'`.
+   *
+   * Returning `null` means "no DO matched" — the caller renders a
+   * `RouteNotFoundError` envelope so the response shape stays
+   * consistent with every other miss.
+   */
+  routeAgentRequest?: (request: Request, env: unknown) => Promise<Response | null>;
+}
+/**
+ * Seed the runtime config consumed by {@link flue}. Called exactly
+ * once at module load by the generated server entry. The Hono routes
+ * returned by `flue()` read this config lazily — see the comment on
+ * {@link runtimeConfig} for why timing relative to user `app.ts`
+ * evaluation is fine.
+ *
+ * Not part of the public API — exposed via `@flue/sdk/internal` only
+ * because the generated entry imports it from a stable bare specifier.
+ */
+declare function configureFlueRuntime(cfg: FlueRuntime): void;
+/**
+ * Public Hono sub-app mounting Flue's built-in agent route. Users
+ * compose this into their own Hono via Hono's `app.route(path, subApp)`:
+ *
+ *     import { Hono } from 'hono';
+ *     import { flue } from '@flue/sdk/app';
+ *
+ *     const app = new Hono();
+ *     app.use('*', logger());
+ *     app.get('/api/ping', (c) => c.json({ pong: true }));
+ *     app.route('/', flue());
+ *
+ *     export default app;
+ *
+ * Each call to `flue()` returns a fresh Hono. Mounting it twice is
+ * legal but pointless — both sub-apps read from the same seeded
+ * runtime and produce identical responses.
+ *
+ * Importable from `@flue/sdk/app`.
+ */
+declare function flue(): Hono;
+/**
+ * Build the default outer Hono app used when no user `app.ts` is
+ * present. Mounts `flue()` at root, renders canonical Flue envelopes
+ * for unmatched paths and any thrown errors.
+ *
+ * Lives in the SDK rather than the generated entry so that user
+ * projects on the Cloudflare target — whose `node_modules` does not
+ * declare `hono` directly — don't have to add it themselves just to
+ * keep the no-`app.ts` default behavior working. When a user does
+ * write an `app.ts`, they own this composition and must `pnpm add
+ * hono` (or equivalent) themselves.
+ */
+declare function createDefaultFlueApp(): Hono;
+//#endregion
+export { AgentHandler as a, RunHandlerFn as c, flue as i, StartWebhookFn as l, configureFlueRuntime as n, CreateContextFn as o, createDefaultFlueApp as r, HandleAgentOptions as s, FlueRuntime as t, handleAgentRequest as u };