@auersperg/flare 0.0.0-stage → 0.3.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Auer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# Flare 0.3 — SDK and CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Applications install one `@auersperg/flare` package, including the portable SDK and lazy Bun CLI. No internal package archives, ORM, Agents, Wrangler or workerd are installed into an application.
+
+- `@auersperg/flare`: `createClient({url,getToken})`, references, errors, file upload helpers.
+- `@auersperg/flare/react`: `FlareProvider`, `useFlare`, `useQuery(api.tasks.list,args)` → data or loading `undefined`.
+- `@auersperg/flare/server`: `defineSchema`, `defineTable`, `z`, function declarations and contracts.
+- `@auersperg/flare/cloudflare`: native facet/action factories, backend only.
+- `@auersperg/flare/protocol`: transport types and limits.
+
+```ts
+// flare/schema.ts
+import { defineSchema, defineTable, z } from "@auersperg/flare/server";
+export default defineSchema({
+  tasks: defineTable(
+    z.object({ title: z.string(), done: z.boolean().default(false) }),
+  ).index("by_done", ["done"]),
+});
+```
+
+Functions import typed declarations from `./_generated/server`; `bunx --bun --package @auersperg/flare@next flare dev` generates this module before compilation. Read: `db.get(table,id)`, `db.query(table).withIndex(name,q=>q.eq(field,value)).order("desc").paginate({limit,cursor})`, `take(100)` and `first()`. Write: `insert`, `patch`, `replace`, `delete`; IDs and creation timestamps are automatic. Insert/replace accept validator input types, including omitted defaults. Queries expose no SQL, writes, session or storage capability.
+
+Standard Schema / Standard JSON Schema validators define one contract for CLI, documents, function arguments/results and dashboard forms. All writes and schema activation validate data; reads decode already validated records, without running the same table validator again on each row. Output validation still applies to every function call. Mutations are transactional and capabilities expire when the invocation finishes. Unawaited database work and scheduled jobs must settle before commit.
+
+0.3 is intentionally incompatible with the SQL/Drizzle API and release ABI 1–3. No compatibility adapters or historical app SQL journals remain. Use a fresh environment; local builds do not erase existing cloud data. Browser/server-JS clients remain portable; only CLI/build tooling requires Bun. No automatic retry of ambiguous mutations.
+
+MIT-licensed; npm preview package `@auersperg/flare`. See the root architecture and maintenance documents for cloud acceptance and remaining product gates.
+
+Scheduling: mutation `jobs.schedule(path,args,{delaySeconds})` and `jobs.cancel(id)` share the transaction. Cancel only removes a not-yet-enqueued outbox entry; it never aborts a running action. `paginate` adapts record count to its byte budget; `take` fails instead of silently truncating bulky results.
+
+## Function model
+
+Exactly three kinds: `query`, `mutation`, `action`. Declare each query once. JS: `client.onUpdate(ref,args,next,onError?)` delivers the first snapshot and later updates; `client.query(ref,args)` is the one-off alternative. Writes use `client.mutation`, external work uses `client.action`. The old `live`, `useLive`, `call` and `subscribe` APIs have been removed, not aliased. Regenerate references and redeploy applications with the updated CLI.
+
+React uses one `useQuery(ref,args)` inside `FlareProvider`; `"skip"` makes no request. It returns values directly (not a custom result wrapper), handles cleanup and reconnect, and clears values for identity/auth changes. Function/auth errors reach the React error boundary. HTTP one-off reads do not require a persistent socket. Transport names such as `/v1/live` describe WebSockets, not another function type.
+
+## Scoped files and background work
+
+Actions use native scoped capabilities, not account-wide R2/Queue bindings. `ctx.files.list({limit:50,cursor})` returns `{page,isDone,continueCursor}`; pass the returned cursor to read the next page. No array alias or silent last-100 truncation remains. Upload/download grants expire, uploads stream to R2, and deletion invalidates outstanding download links.
+
+Mutation outbox entries and data commit together. Native Queues batches confirm enqueue before removing outbox rows; retries remain per-message and at-least-once. Application external effects must use idempotency keys. Receipts have a bounded 30-day window, not perpetual exactly-once delivery.
+
+## CLI
+
+The CLI is compiled separately from the portable SDK in this package. Bun 1.4.3+; no local dashboard or emulator.
+
+```sh
+bun add @auersperg/flare@next       # npm preview, next tag
+bunx --bun --package @auersperg/flare@next flare dev     # browser approval → project → native schema/types → cloud-dev watch
+bunx --bun --package @auersperg/flare@next flare deploy  # build and confirm production deployment
+```
+
+Schema and functions live in `flare/`. `_generated/server.ts` supplies schema-typed query/mutation declarations; `_generated/api.ts` supplies browser-safe references. SQL journals and db-generation commands are not needed. Compilation/checksums happen locally, not on an application request. Frontend changes do not trigger backend deployment; framework-prefixed public URL env entries preserve other variables.
+
+Advanced explicit commands:
+
+```sh
+flare build --entry app.ts --outdir release
+flare link --platform https://api.example.com/control --project PROJECT_UUID
+flare dev --entry app.ts
+flare deploy --env dev --release release
+```
+
+Immutable output contains facet/action modules, `schema.json`, manifest, checksums, generated TypeScript API and OpenAPI 3.1. Only ABI 4 is accepted. No old `tables` declarations, `--migrations` flag or Drizzle pipeline.
+
+Browser approval is protected by online Access/owner authorization and same-origin CSRF. Project-scoped credentials stay outside source/frontend env. Dev publishes to an already provisioned platform; general `platform init` is not implemented. No npm publication or cloud provisioning occurs during local verification.
+
+## Immutable releases
+
+```sh
+bunx --bun --package @auersperg/flare@next flare releases --env dev
+bunx --bun --package @auersperg/flare@next flare deploy --env prod --cmd "bun run build"
+bunx --bun --package @auersperg/flare@next flare promote --env prod --hash DEV_BUILD_HASH --cmd "bun run build"
+bunx --bun --package @auersperg/flare@next flare rollback --env prod --hash PREVIOUS_BUILD_HASH
+```
+
+History keeps the last five **distinct successful backend builds**, with their first publication date. Failed candidates are not promotable. Active builds and job/outbox references are protected from garbage collection. Repeating an unchanged build is not a new version.
+
+Promote copies the selected immutable dev bundle to prod without recompiling or copying development data. Rollback activates compatible historical code against current data; it does not rewind the database. Both require explicit confirmation (`--confirm PROJECT_UUID` in CI), validate schema/job compatibility and compare the target's expected active hash. A changed target returns a conflict, never an automatic write retry.
+
+`--cmd` generates client references for the exact selected bundle and builds the frontend **before** activating the backend. The child receives the selected environment URL via `FLARE_URL`, `PUBLIC_FLARE_URL`, `VITE_FLARE_URL`, `NEXT_PUBLIC_FLARE_URL` and `EXPO_PUBLIC_FLARE_URL`; local dev env files remain unchanged. A failed build does not publish backend code. Framework build variables must be public URLs, not credentials.
+
+Frontend hosting stays with native Wrangler or another hosting tool. An application release script can sequence Flare + build + Wrangler. Frontend publication failure after backend activation is an explicit partial release, not an atomic transaction. Dashboard Health → Development/Production releases offers contract inspection, backend promotion and rollback on demand, with no polling. It does not publish the frontend.
+
+Isolated historical preview environments and a paired frontend/backend version catalogue are not implemented. A saved backend hash is not a preview URL or a Git commit. Use additive contracts when old clients may remain active.
+
+## On-demand backups
+
+```sh
+bunx --bun --package @auersperg/flare@next flare backup list --env dev
+bunx --bun --package @auersperg/flare@next flare backup create --env dev --confirm PROJECT_UUID
+bunx --bun --package @auersperg/flare@next flare backup restore --from dev --env prod --id BACKUP_UUID --confirm PROJECT_UUID
+bunx --bun --package @auersperg/flare@next flare backup status --env prod
+bunx --bun --package @auersperg/flare@next flare backup delete --env dev --id BACKUP_UUID --confirm PROJECT_UUID
+```
+
+Writes require owner access and explicit confirmation (interactive `yes`, or the project UUID in CI). Creation prints its ID before sending the request; after an uncertain response retry explicitly with `--id` and that same ID. No automatic write retry. Restore copies data, IDs, creation timestamps, files and the exact backend build into the **other, empty environment of the same project**. It does not promote a release or overwrite an occupied production database.
+
+Pause cron and drain jobs/actions/uploads first. Limits: 10,000 documents / 4 MiB logical data, 100 files / 100 MiB. Secrets, environment settings, schedules and job history are not copied. Interrupted restores stay closed to application calls and deployments; retry the same backup ID. The source backup cannot be deleted while a restore references it. Private R2 backups occupy storage until explicitly deleted; no periodic backup timer or extra service is installed. See the maintenance guide for recovery limitations.
+
+## Built-in application login
+
+Owner enables authentication/public registration per environment in dashboard → Auth. No external provider is required for native passwords. Applications explicitly decide which functions are public; required remains the default. User role/ownership checks still belong in handlers.
+
+```ts
+import { createClient, createPasswordAuth } from "@auersperg/flare";
+const url = import.meta.env.PUBLIC_FLARE_URL;
+const auth = createPasswordAuth({ url });
+const client = createClient({ url, getToken: auth.getToken });
+const stopAuth = auth.onChange(() => client.refreshAuth());
+await auth.register("my-login", "a long unique passphrase");
+// Later: await auth.login(login, password), auth.me(), auth.changePassword(old, next).
+await auth.logout();
+stopAuth();
+client.dispose();
+```
+
+Sessions are memory-only and expire after at most 12 hours. Reload requires login again. Password reset/block/revoke in Auth disconnects affected live users. Owner/Access manages accounts; application users and project CLI credentials do not gain dashboard privileges. Public login/registration have bounded rate limits; public registration is not equivalent to public access to private rows. Passwords require 6–128 characters. There is no email verification/recovery or MFA in this minimal version; owner reset is available. Existing short-lived R2 download grants remain valid for their explicit TTL, not until session logout.
+
+## License and distribution
+
+SDK and CLI are MIT-licensed; see LICENSE. npm name: `@auersperg/flare`.
+The `flare` binary remains unchanged. Preview releases are published under the `next` tag. Core/dashboard are separate non-published
+components and are not included in this package.

package/dist/cli/chunk-5cq8wgte.js

@@ -0,0 +1,327 @@
+// @bun
+// packages/flare/src/cli/cloud.mjs
+import { randomUUID } from "crypto";
+import {
+  readFile,
+  mkdir,
+  writeFile,
+  access,
+  mkdtemp,
+  watch,
+  rm
+} from "fs/promises";
+import { resolve, join } from "path";
+var allowedUrl = (value) => {
+  const u = new URL(value);
+  if (u.protocol !== "https:" || u.username || u.password || u.search || u.hash)
+    throw Error("Platform must be an HTTPS management URL");
+  return u.href.replace(/\/$/, "");
+};
+async function request(platform, path, body) {
+  let token = process.env.FLARE_DEPLOY_TOKEN;
+  if (!token) {
+    const config = JSON.parse(await readFile(".flare/project.json", "utf8").catch((e) => {
+      if (e.code !== "ENOENT")
+        throw e;
+      return "null";
+    }));
+    if (config) {
+      const { storedToken } = await import("./chunk-x14smx1y.js");
+      token = await storedToken(platform, config.project);
+    }
+  }
+  if (!token)
+    throw Error("Sign in with flare dev; CI can set FLARE_DEPLOY_TOKEN");
+  const r = await fetch(allowedUrl(platform) + path, {
+    method: body === undefined ? "GET" : "POST",
+    headers: {
+      authorization: `Bearer ${token}`,
+      ...body === undefined ? {} : { "content-type": "application/json" }
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+    redirect: "error",
+    signal: AbortSignal.timeout(60000)
+  });
+  const result = await r.json();
+  if (!r.ok) {
+    const error = Error(`${result.error ?? "Deployment failed"} (HTTP ${r.status}); writes are not automatically retried`);
+    error.status = r.status;
+    throw error;
+  }
+  return result;
+}
+async function link(options) {
+  if (!options.platform || !options.project || !/^[0-9a-f-]{36}$/.test(options.project))
+    throw Error("Required: --platform <management URL> --project <ID>");
+  const platform = allowedUrl(options.platform);
+  const data = await request(platform, `/api/projects/${options.project}`);
+  await mkdir(".flare", { recursive: true });
+  await writeFile(".flare/project.json", JSON.stringify({
+    platform,
+    project: options.project,
+    runtime: data.runtime,
+    urls: data.urls
+  }, null, 2) + `
+`, { mode: 384 });
+  return { project: options.project, runtime: data.runtime, urls: data.urls };
+}
+async function deploy(options = {}) {
+  if (!options.release) {
+    const config = JSON.parse(await readFile(".flare/project.json", "utf8"));
+    const { prepare, generateApi } = await import("./chunk-786w6vrj.js");
+    const { buildApplication } = await import("./chunk-vx7kmczm.js");
+    const source = await prepare(), directory = resolve(".flare/releases/" + randomUUID());
+    const env = options.env ?? "prod";
+    if (!["dev", "prod"].includes(env))
+      throw Error("Environment must be dev or prod");
+    if (env === "prod" && options.confirm !== config.project) {
+      if (!process.stdin.isTTY)
+        throw Error("Production requires --confirm <project ID> in CI");
+      const { createInterface } = await import("readline/promises");
+      const prompt = createInterface({
+        input: process.stdin,
+        output: process.stdout
+      });
+      try {
+        if (await prompt.question(`Deploy to production ${config.project}? Type yes: `) !== "yes")
+          throw Error("Deployment cancelled");
+      } finally {
+        prompt.close();
+      }
+    }
+    try {
+      await buildApplication({ ...source, outdir: directory });
+      const result = await deploy({
+        env,
+        release: directory,
+        confirm: env === "prod" ? config.project : undefined,
+        cmd: options.cmd
+      });
+      await generateApi(directory);
+      return result;
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+    }
+  }
+  const config = JSON.parse(await readFile(".flare/project.json", "utf8"));
+  const env = options.env ?? "dev";
+  if (!["dev", "prod"].includes(env) || !options.release)
+    throw Error("Required: --env dev|prod --release <built directory>");
+  if (env === "prod" && options.confirm !== config.project)
+    throw Error("Production requires --confirm <project ID>");
+  const directory = resolve(options.release);
+  const read = async (file) => readFile(join(directory, file), "utf8");
+  const bundle = {
+    release: JSON.parse(await read("release.json")),
+    manifest: JSON.parse(await read("manifest.json")),
+    schema: JSON.parse(await read("schema.json")),
+    facet: await read("facet.js"),
+    action: await read("action.js")
+  };
+  let expected;
+  if (options.cmd) {
+    const health = await request(config.platform, `/api/projects/${config.project}/${env}/health`);
+    expected = health.active;
+    const { generateApi } = await import("./chunk-786w6vrj.js");
+    await generateApi(directory);
+    await frontendBuild(config, env, options.cmd);
+  }
+  return request(config.platform, `/api/projects/${config.project}/${env}/deploy`, { bundle, confirm: options.confirm, expected });
+}
+async function dev(options = {}) {
+  if (options.env && options.env !== "dev")
+    throw Error("Watch publishes only to dev; use deploy for production");
+  const simple = !options.entry;
+  if (simple) {
+    const { scaffold } = await import("./chunk-786w6vrj.js");
+    await scaffold();
+    try {
+      await access(".flare/project.json");
+    } catch (e) {
+      if (e.code !== "ENOENT")
+        throw e;
+      const { connect } = await import("./chunk-x14smx1y.js");
+      await connect();
+    }
+  }
+  await access(".flare/project.json");
+  if (simple) {
+    const config = JSON.parse(await readFile(".flare/project.json", "utf8"));
+    try {
+      await request(config.platform, `/api/projects/${config.project}`);
+    } catch (e) {
+      if (process.env.FLARE_DEPLOY_TOKEN || e.status !== 401 && !e.message.startsWith("Sign in"))
+        throw e;
+      const { connect } = await import("./chunk-x14smx1y.js");
+      await connect();
+    }
+  }
+  const { buildApplication } = await import("./chunk-vx7kmczm.js");
+  let busy = false, pending = false, timer, hash;
+  const publish = async (initial = false) => {
+    if (busy) {
+      pending = true;
+      return;
+    }
+    busy = true;
+    try {
+      const outdir = resolve(".flare/releases/" + randomUUID());
+      try {
+        const { prepare, generateApi, frontendEnvironment } = await import("./chunk-786w6vrj.js");
+        const source = simple ? await prepare() : { entry: options.entry };
+        const release = await buildApplication({ ...source, outdir });
+        if (release.hash !== hash) {
+          const data = await deploy({ env: "dev", release: outdir });
+          if (simple) {
+            await generateApi(outdir);
+            await frontendEnvironment(data.url);
+          }
+          hash = release.hash;
+          console.log(`Dev release ${hash}
+${data.url}`);
+        }
+      } finally {
+        await rm(outdir, { recursive: true, force: true });
+      }
+    } catch (e) {
+      if (initial)
+        throw e;
+      console.error(e.message);
+    } finally {
+      busy = false;
+      if (pending) {
+        pending = false;
+        publish();
+      }
+    }
+  };
+  await publish(true);
+  console.log("Watching application code; backend runs in Cloudflare dev. Start your frontend with its own dev server.");
+  for await (const event of watch(simple ? resolve("flare") : process.cwd(), {
+    recursive: true
+  })) {
+    const file = event.filename?.toString() ?? "";
+    if (/(^|\/)(node_modules|\.flare|\.git|dist|_generated)(\/|$)/.test(file) || !/\.(ts|tsx|js|mjs|sql|json)$/.test(file))
+      continue;
+    clearTimeout(timer);
+    timer = setTimeout(() => void publish(), 400);
+  }
+}
+async function backup(options = {}) {
+  const config = JSON.parse(await readFile(".flare/project.json", "utf8"));
+  const operation = options.operation ?? "list", env = options.env ?? "prod";
+  if (!["dev", "prod"].includes(env) || !["create", "list", "restore", "delete", "status"].includes(operation))
+    throw Error("Use backup create|list|restore|delete|status --env dev|prod");
+  const path = `/api/projects/${config.project}/${env}/`;
+  if (operation === "list")
+    return request(config.platform, path + "backups" + (options.cursor ? `?cursor=${encodeURIComponent(options.cursor)}` : ""));
+  if (operation === "status")
+    return request(config.platform, path + "backup-status");
+  const id = options.id ?? (operation === "create" ? randomUUID() : null);
+  if (!id || !/^[0-9a-f-]{36}$/.test(id))
+    throw Error("Required: --id <backup ID>");
+  if (operation === "restore" && (!["dev", "prod"].includes(options.from) || options.from === env))
+    throw Error("Restore requires --from dev|prod to a different empty environment of this project");
+  if (options.confirm !== config.project) {
+    if (!process.stdin.isTTY)
+      throw Error("Backup writes require --confirm <project ID> in CI");
+    const { createInterface } = await import("readline/promises");
+    const prompt = createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    try {
+      if (await prompt.question(`${operation} backup ${id} \xB7 ${config.project}/${env}? Type yes: `) !== "yes")
+        throw Error("Cancelled");
+    } finally {
+      prompt.close();
+    }
+  }
+  console.error(`Backup operation ${operation}: ${id}`);
+  return request(config.platform, path + "backup-" + operation, {
+    id,
+    sourceEnv: options.from,
+    confirm: config.project
+  });
+}
+async function frontendBuild(config, env, command) {
+  if (typeof command !== "string" || !command.trim())
+    throw Error("Empty build command");
+  const settings = await request(config.platform, `/api/projects/${config.project}/${env}/settings`);
+  const url = allowedUrl(settings.url);
+  const { $ } = await Promise.resolve(globalThis.Bun);
+  await $`${{ raw: command }}`.env({
+    ...process.env,
+    FLARE_URL: url,
+    PUBLIC_FLARE_URL: url,
+    VITE_FLARE_URL: url,
+    NEXT_PUBLIC_FLARE_URL: url,
+    EXPO_PUBLIC_FLARE_URL: url
+  });
+}
+async function releaseOperation(options, operation) {
+  const config = JSON.parse(await readFile(".flare/project.json", "utf8"));
+  const env = options.env ?? "prod";
+  if (!["dev", "prod"].includes(env) || !/^[a-f0-9]{64}$/.test(options.hash ?? ""))
+    throw Error("Required: --hash <64-character release hash> and --env dev|prod");
+  if (operation === "promote" && env !== "prod")
+    throw Error("Promote targets production only");
+  if (options.confirm !== config.project) {
+    if (!process.stdin.isTTY)
+      throw Error("Release switch requires --confirm <project ID> in CI");
+    const { createInterface } = await import("readline/promises");
+    const prompt = createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    try {
+      if (await prompt.question(`${operation} ${options.hash} into ${env}? Type yes: `) !== "yes")
+        throw Error("Cancelled");
+    } finally {
+      prompt.close();
+    }
+  }
+  const path = `/api/projects/${config.project}/${env}/`;
+  const health = await request(config.platform, path + "health");
+  if (options.cmd) {
+    const source = operation === "promote" ? "dev" : env;
+    const bundle = await request(config.platform, `/api/projects/${config.project}/${source}/release-bundle?hash=${options.hash}`);
+    if (bundle.release.hash !== options.hash)
+      throw Error("Release hash mismatch");
+    const { generateReferences } = await import("./chunk-vx7kmczm.js");
+    const { generateApi } = await import("./chunk-786w6vrj.js");
+    await mkdir(".flare", { recursive: true });
+    const directory = await mkdtemp(resolve(".flare/release-contract-"));
+    try {
+      await writeFile(join(directory, "api.ts"), await generateReferences(bundle.manifest));
+      await writeFile(join(directory, "manifest.json"), JSON.stringify(bundle.manifest));
+      await generateApi(directory);
+      await frontendBuild(config, env, options.cmd);
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+    }
+  }
+  return request(config.platform, path + "release-" + operation, {
+    hash: options.hash,
+    expected: health.active,
+    confirm: config.project
+  });
+}
+var promote = (options = {}) => releaseOperation(options, "promote");
+var rollback = (options = {}) => releaseOperation(options, "rollback");
+async function releases(options = {}) {
+  const config = JSON.parse(await readFile(".flare/project.json", "utf8"));
+  const env = options.env ?? "dev";
+  if (!["dev", "prod"].includes(env))
+    throw Error("Environment must be dev or prod");
+  return request(config.platform, `/api/projects/${config.project}/${env}/history`);
+}
+export {
+  backup,
+  deploy,
+  dev,
+  link,
+  promote,
+  releases,
+  rollback
+};

package/dist/cli/chunk-786w6vrj.js

@@ -0,0 +1,169 @@
+// @bun
+import {
+  bundle
+} from "./chunk-xff4b01y.js";
+
+// packages/flare/src/cli/project.mjs
+import {
+  mkdir,
+  readFile,
+  writeFile,
+  readdir,
+  access,
+  rm
+} from "fs/promises";
+import { resolve, join } from "path";
+import { pathToFileURL } from "url";
+import { randomUUID } from "crypto";
+async function scaffold() {
+  await access("package.json");
+  await mkdir("flare", { recursive: true });
+  try {
+    await writeFile("flare/schema.ts", `import {defineSchema} from "@auersperg/flare/server";
+export default defineSchema({});
+`, { flag: "wx" });
+  } catch (e) {
+    if (e.code !== "EEXIST")
+      throw e;
+  }
+  for (const [file, text] of [
+    [".gitignore", `
+.flare/
+flare/_generated/
+.env.local
+`],
+    [".prettierignore", `
+.flare/
+flare/_generated/
+`]
+  ]) {
+    const previous = await readFile(file, "utf8").catch((e) => {
+      if (e.code !== "ENOENT")
+        throw e;
+      return "";
+    });
+    if (!previous.includes("flare/_generated/"))
+      await writeFile(file, previous + text);
+  }
+}
+async function modules(directory, prefix = "") {
+  const result = [];
+  for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (entry.name.startsWith("_") || entry.name.startsWith("."))
+      continue;
+    const path = join(directory, entry.name), name = prefix + entry.name;
+    if (entry.isDirectory())
+      result.push(...await modules(path, name + "/"));
+    else if (entry.isFile() && entry.name.endsWith(".ts") && name !== "schema.ts" && !name.endsWith(".d.ts"))
+      result.push({ path: resolve(path), name: name.slice(0, -3) });
+  }
+  return result;
+}
+async function prepare() {
+  await scaffold();
+  await mkdir(".flare/build", { recursive: true });
+  await mkdir("flare/_generated", { recursive: true });
+  await writeFile("flare/_generated/server.ts", `import type schema from "../schema";
+import {createFunctions} from "@auersperg/flare/server";
+export const {query,mutation,action}=createFunctions<typeof schema>();
+`);
+  const files = await modules("flare");
+  const schema = resolve("flare/schema.ts"), entry = resolve(".flare/build/app.ts");
+  const imports = files.map((file, i) => `import * as f${i} from ${JSON.stringify(file.path)};`).join(`
+`);
+  const source = `import {defineApp} from "@auersperg/flare/server";
+import schema from ${JSON.stringify(schema)};
+${imports}
+const functions={};
+${files.map((file, i) => `functions[${JSON.stringify(file.name)}]=Object.fromEntries(Object.entries(f${i}).filter(([,fn])=>fn && typeof fn === "object" && ["query","mutation","action"].includes(fn.kind)));`).join(`
+`)}
+const tree=Object.create(null);
+for(const [path,exports] of Object.entries(functions)) {
+  const parts=path.split("/");let node=tree;
+  for(const part of parts.slice(0,-1))node=node[part]??=Object.create(null);
+  const key=parts.at(-1); if(key in node)throw Error("Function namespace conflict: "+path);
+  node[key]=exports;
+}
+export default defineApp({schema,functions:tree});
+`;
+  await writeFile(entry, source);
+  const metadata = resolve(`.flare/build/metadata-${randomUUID()}.mjs`);
+  try {
+    await bundle({
+      entrypoints: [entry],
+      outdir: resolve(".flare/build"),
+      naming: { entry: metadata.split("/").at(-1) },
+      packages: "external",
+      target: "bun",
+      format: "esm"
+    });
+    const app = await import(pathToFileURL(metadata).href);
+    if (!app.default?.schema)
+      throw Error("Schema must export defineSchema(...)");
+    const imports = [], declarations = [];
+    for (const file of files) {
+      const node = file.name.split("/").reduce((tree, name) => tree?.[name], app.default.functions);
+      for (const [name, fn] of Object.entries(node ?? {})) {
+        if (fn?.kind !== "action")
+          continue;
+        const symbol = `action${imports.length}`;
+        imports.push(`import {${name} as ${symbol}} from ${JSON.stringify(file.path)};`);
+        declarations.push(`${JSON.stringify(file.name + "/" + name)}:${symbol}`);
+      }
+    }
+    const actionEntry = resolve(".flare/build/actions.ts");
+    await writeFile(actionEntry, `${imports.join(`
+`)}
+export default {functions:{${declarations.join(",")}}};
+`);
+    return { entry, actionEntry };
+  } finally {
+    await rm(metadata, { force: true });
+  }
+}
+async function generateApi(directory) {
+  await mkdir("flare/_generated", { recursive: true });
+  const flat = await readFile(join(directory, "api.ts"), "utf8");
+  const manifest = JSON.parse(await readFile(join(directory, "manifest.json"), "utf8"));
+  const paths = Object.keys(manifest.functions);
+  const tree = Object.create(null);
+  for (const path of paths) {
+    let node = tree;
+    const parts = path.split("/");
+    for (const part of parts.slice(0, -1))
+      node = node[part] ??= Object.create(null);
+    node[parts.at(-1)] = path;
+  }
+  const serialize = (value) => typeof value === "string" ? `references[${JSON.stringify(value)}]` : `{${Object.entries(value).map(([key, child]) => `${JSON.stringify(key)}:${serialize(child)}`).join(",")}}`;
+  await writeFile("flare/_generated/references.ts", flat);
+  await writeFile("flare/_generated/api.ts", `import {api as references} from "./references";
+export const api = ${serialize(tree)} as const;
+`);
+}
+async function frontendEnvironment(url) {
+  const pkg = JSON.parse(await readFile("package.json", "utf8"));
+  const dependencies = { ...pkg.dependencies, ...pkg.devDependencies };
+  const variable = dependencies.astro ? "PUBLIC_FLARE_URL" : dependencies.expo ? "EXPO_PUBLIC_FLARE_URL" : "VITE_FLARE_URL";
+  const parsed = new URL(url);
+  if (parsed.protocol !== "https:" || parsed.username || parsed.password || parsed.search || parsed.hash)
+    throw Error("Invalid environment URL");
+  let previous = await readFile(".env.local", "utf8").catch((e) => {
+    if (e.code !== "ENOENT")
+      throw e;
+    return "";
+  });
+  const line = variable + "=" + JSON.stringify(parsed.href);
+  const pattern = new RegExp("^" + variable + "=.*$", "m");
+  const next = pattern.test(previous) ? previous.replace(pattern, () => line) : previous + (previous.endsWith(`
+`) || !previous ? "" : `
+`) + line + `
+`;
+  if (next !== previous)
+    await writeFile(".env.local", next, { mode: 384 });
+}
+export {
+  frontendEnvironment,
+  generateApi,
+  prepare,
+  scaffold
+};