@auersperg/flare 0.0.0-stage → 0.3.1

package/dist/cli/chunk-vx7kmczm.js

@@ -0,0 +1,379 @@
+// @bun
+import {
+  bundle
+} from "./chunk-xff4b01y.js";
+
+// packages/flare/src/cli/build.mjs
+import { compile } from "json-schema-to-typescript";
+
+// packages/flare/src/sdk/server.ts
+import { z } from "zod";
+
+// packages/flare/src/sdk/protocol.ts
+var LIMITS = Object.freeze({
+  inputBytes: 65536,
+  outputBytes: 262144,
+  frameBytes: 8192,
+  subscriptions: 64,
+  fileBytes: 10485760
+});
+
+class FlareError extends Error {
+  code;
+  ambiguous;
+  constructor(code, message, ambiguous = false) {
+    super(message);
+    this.code = code;
+    this.ambiguous = ambiguous;
+    this.name = "FlareError";
+  }
+}
+function assertPath(path) {
+  if (path.length > 256 || !/^[A-Za-z][A-Za-z0-9_]*(\/[A-Za-z][A-Za-z0-9_]*)*$/.test(path) || path.split("/").some((p) => ["__proto__", "prototype", "constructor"].includes(p))) {
+    throw new FlareError("INVALID_PATH", "Invalid function path");
+  }
+}
+function stableJson(value) {
+  const ancestors = new Set;
+  function visit(v, depth) {
+    if (depth > 40)
+      throw new FlareError("INVALID_JSON", "JSON nesting limit exceeded");
+    if (v === null || typeof v === "string" || typeof v === "boolean")
+      return v;
+    if (typeof v === "number" && Number.isFinite(v))
+      return v;
+    if (typeof v !== "object" || v === null || ancestors.has(v))
+      throw new FlareError("INVALID_JSON", "Expected lossless JSON");
+    if (!Array.isArray(v) && Object.getPrototypeOf(v) !== Object.prototype && Object.getPrototypeOf(v) !== null) {
+      throw new FlareError("INVALID_JSON", "Expected plain JSON object");
+    }
+    if (Object.getOwnPropertySymbols(v).length)
+      throw new FlareError("INVALID_JSON", "Symbol keys are unsupported");
+    ancestors.add(v);
+    let result;
+    if (Array.isArray(v)) {
+      result = Array.from(v, (item) => visit(item, depth + 1));
+    } else {
+      const out = Object.create(null);
+      for (const key of Object.keys(v).sort()) {
+        const descriptor = Object.getOwnPropertyDescriptor(v, key);
+        if (!("value" in descriptor))
+          throw new FlareError("INVALID_JSON", "Getters are unsupported");
+        out[key] = visit(descriptor.value, depth + 1);
+      }
+      result = out;
+    }
+    ancestors.delete(v);
+    return result;
+  }
+  return JSON.stringify(visit(value, 0));
+}
+function boundedJson(value, maxBytes) {
+  const json = stableJson(value);
+  if (new TextEncoder().encode(json).byteLength > maxBytes)
+    throw new FlareError("TOO_LARGE", "JSON payload exceeds limit");
+  return json;
+}
+
+// packages/flare/src/sdk/schema.ts
+function identifier(name) {
+  if (!/^[a-zA-Z][a-zA-Z0-9_]{0,47}$/.test(name) || name.toLowerCase().startsWith("sqlite_"))
+    throw new FlareError("INVALID_SCHEMA", "Invalid table, index or field name");
+  return name;
+}
+function schemaContract(schema) {
+  const out = Object.create(null);
+  if (Object.keys(schema).length > 100)
+    throw new FlareError("INVALID_SCHEMA", "Maximum 100 tables");
+  for (const [name, table] of Object.entries(schema)) {
+    identifier(name);
+    const document = table.validator["~standard"].jsonSchema.output({
+      target: "draft-2020-12"
+    });
+    out[name] = { document, indexes: table.indexes };
+  }
+  assertSchemaContract(out);
+  return out;
+}
+function assertSchemaContract(contract) {
+  boundedJson(contract, 1048576);
+  if (!contract || Array.isArray(contract) || typeof contract !== "object" || Object.keys(contract).length > 100)
+    throw new FlareError("INVALID_SCHEMA", "Invalid schema");
+  const names = new Set;
+  for (const [name, table] of Object.entries(contract)) {
+    if (names.has(name.toLowerCase()))
+      throw new FlareError("INVALID_SCHEMA", "SQLite table names are case-insensitive");
+    names.add(name.toLowerCase());
+    identifier(name);
+    const doc = table?.document;
+    if (!doc || doc.type !== "object" || !doc.properties || doc.additionalProperties !== false)
+      throw new FlareError("INVALID_SCHEMA", "Tables require a closed object validator");
+    for (const field of Object.keys(doc.properties))
+      identifier(field);
+    if (Object.keys(doc.properties).length > 64 || !table.indexes || Object.keys(table.indexes).length > 20)
+      throw new FlareError("INVALID_SCHEMA", "Schema exceeds limits");
+    const indexes = new Set;
+    for (const [index, fields] of Object.entries(table.indexes)) {
+      if (indexes.has(index.toLowerCase()))
+        throw new FlareError("INVALID_SCHEMA", "SQLite index names are case-insensitive");
+      indexes.add(index.toLowerCase());
+      identifier(index);
+      if (!Array.isArray(fields) || fields.length < 1 || fields.length > 4 || new Set(fields).size !== fields.length)
+        throw new FlareError("INVALID_SCHEMA", "Invalid index fields");
+      for (const field of fields) {
+        identifier(field);
+        const p = doc.properties[field];
+        const scalar = (s) => Array.isArray(s?.type) && s.type.every((type) => ["string", "number", "integer", "boolean", "null"].includes(type)) || ["string", "number", "integer", "boolean", "null"].includes(s?.type) || Array.isArray(s?.anyOf) && s.anyOf.every(scalar);
+        if (!p || !scalar(p))
+          throw new FlareError("INVALID_SCHEMA", "Indexes require declared scalar fields");
+      }
+    }
+  }
+}
+var documents = new WeakMap;
+// packages/flare/src/sdk/server.ts
+function declare(kind) {
+  return (options) => Object.freeze({ ...options, kind, auth: options.auth ?? "required" });
+}
+var query = declare("query");
+var mutation = declare("mutation");
+var action = declare("action");
+function flatten(tree) {
+  const out = Object.create(null);
+  const ancestors = new Set;
+  function walk(node, prefix, depth) {
+    if (depth > 20 || ancestors.has(node))
+      throw new FlareError("INVALID_CONTRACT", "Invalid function tree");
+    ancestors.add(node);
+    for (const [name, value] of Object.entries(node)) {
+      const path = prefix ? `${prefix}/${name}` : name;
+      assertPath(path);
+      if (value && typeof value === "object" && "handler" in value && typeof value.handler === "function") {
+        const definition = value;
+        if (!["query", "mutation", "action"].includes(definition.kind))
+          throw new FlareError("INVALID_CONTRACT", "Invalid function kind");
+        if (out[path])
+          throw new FlareError("INVALID_CONTRACT", "Duplicate function path");
+        out[path] = definition;
+      } else if (value && typeof value === "object")
+        walk(value, path, depth + 1);
+      else
+        throw new FlareError("INVALID_CONTRACT", "Invalid function definition");
+    }
+    ancestors.delete(node);
+  }
+  walk(tree, "", 0);
+  return out;
+}
+function manifest(app) {
+  const functions = Object.create(null);
+  for (const [path, fn] of Object.entries(flatten(app.functions))) {
+    const input = fn.input["~standard"].jsonSchema?.input({
+      target: "draft-2020-12"
+    });
+    const output = fn.output["~standard"].jsonSchema?.output({
+      target: "draft-2020-12"
+    });
+    if (!input || !output)
+      throw new FlareError("INVALID_CONTRACT", `${path} requires JSON Schema converters`);
+    functions[path] = { kind: fn.kind, auth: fn.auth, input, output };
+  }
+  boundedJson(functions, 1048576);
+  return { protocol: 1, runtimeAbi: 4, functions };
+}
+
+// packages/flare/src/cli/build.mjs
+import { createHash } from "crypto";
+import {
+  access,
+  mkdir,
+  mkdtemp,
+  readFile,
+  rename,
+  rm,
+  writeFile
+} from "fs/promises";
+import { dirname, join, resolve } from "path";
+import { pathToFileURL } from "url";
+var digest = (data) => createHash("sha256").update(data).digest("hex");
+async function buildApplication(options) {
+  const entry = resolve(options.entry), outdir = resolve(options.outdir), working = dirname(entry);
+  try {
+    await access(outdir);
+    throw new Error("Output directory already exists; builds never overwrite an existing release");
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
+  }
+  await access(entry);
+  await mkdir(join(working, ".flare/tmp"), { recursive: true });
+  const temporary = await mkdtemp(join(working, ".flare/tmp/build-"));
+  try {
+    const metadataPath = join(temporary, "metadata.mjs");
+    await bundle({
+      entrypoints: [entry],
+      outdir: temporary,
+      naming: { entry: "metadata.mjs" },
+      packages: "external",
+      target: "bun",
+      format: "esm"
+    });
+    const module = await import(pathToFileURL(metadataPath).href);
+    if (!module.default)
+      throw new Error("Application entry must default-export defineApp(...)");
+    const contract = manifest(module.default);
+    const schema = schemaContract(module.default.schema);
+    const facet = await compileRole("facet", entry, working);
+    const action = await compileRole("action", options.actionEntry ? resolve(options.actionEntry) : entry, working);
+    const checksums = {
+      facet: digest(facet),
+      action: digest(action),
+      schema: digest(stableJson(schema)),
+      manifest: digest(stableJson(contract))
+    };
+    const artifact = {
+      protocol: 1,
+      compatibilityDate: "2026-10-10",
+      checksums
+    };
+    const hash = digest(stableJson(artifact));
+    const staging = join(temporary, "release");
+    await mkdir(staging);
+    await writeFile(join(staging, "facet.js"), facet);
+    await writeFile(join(staging, "action.js"), action);
+    await writeFile(join(staging, "manifest.json"), JSON.stringify(contract, null, 2));
+    await writeFile(join(staging, "schema.json"), JSON.stringify(schema, null, 2));
+    await writeFile(join(staging, "release.json"), JSON.stringify({ ...artifact, hash }, null, 2));
+    await writeFile(join(staging, "api.ts"), await generateReferences(contract));
+    const calls = Object.entries(contract.functions).filter(([, fn]) => fn.auth !== "internal");
+    const schemas = Object.create(null);
+    const refSchema = (schema, name) => {
+      const rewrite = (value) => {
+        if (Array.isArray(value))
+          return value.map(rewrite);
+        if (!value || typeof value !== "object")
+          return value;
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+          key,
+          key === "$ref" && typeof item === "string" && item.startsWith("#/") ? `#/components/schemas/${name}/${item.slice(2)}` : rewrite(item)
+        ]));
+      };
+      schemas[name] = rewrite(schema);
+      return { $ref: `#/components/schemas/${name}` };
+    };
+    const callSchemas = calls.map(([path, fn], index) => ({
+      path,
+      fn,
+      input: refSchema(fn.input, `Input${index}`),
+      output: refSchema(fn.output, `Output${index}`)
+    }));
+    const openapi = {
+      openapi: "3.1.0",
+      info: { title: "Flare application contract", version: hash },
+      components: {
+        schemas,
+        securitySchemes: {
+          bearer: { type: "http", scheme: "bearer", bearerFormat: "JWT" }
+        }
+      },
+      paths: calls.length ? {
+        "/v1/call": {
+          post: {
+            operationId: "callFunction",
+            security: calls.some(([, fn]) => fn.auth === "public") ? [{}, { bearer: [] }] : [{ bearer: [] }],
+            requestBody: {
+              required: true,
+              content: {
+                "application/json": {
+                  schema: {
+                    oneOf: callSchemas.map(({ path, fn, input }) => ({
+                      type: "object",
+                      additionalProperties: false,
+                      required: ["path", "kind", "args"],
+                      properties: {
+                        path: { const: path },
+                        kind: { const: fn.kind },
+                        args: input
+                      }
+                    }))
+                  }
+                }
+              }
+            },
+            responses: {
+              200: {
+                description: "Validated function result",
+                content: {
+                  "application/json": {
+                    schema: {
+                      type: "object",
+                      required: ["result"],
+                      properties: {
+                        result: {
+                          anyOf: callSchemas.map(({ output }) => output)
+                        }
+                      }
+                    }
+                  }
+                }
+              },
+              401: { description: "Unauthorized" },
+              500: {
+                description: "Execution failed; write outcome may be ambiguous"
+              }
+            }
+          }
+        }
+      } : {}
+    };
+    await writeFile(join(staging, "openapi.json"), JSON.stringify(openapi, null, 2));
+    await mkdir(dirname(outdir), { recursive: true });
+    await rename(staging, outdir);
+    return { hash, outdir, checksums };
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+  }
+}
+async function compileRole(role, entry, working) {
+  const code = role === "facet" ? `import app from ${JSON.stringify(entry)}; import {createFacet} from "@auersperg/flare/cloudflare"; export class AppFacet extends createFacet(app) {}` : `import app from ${JSON.stringify(entry)}; import {createAction} from "@auersperg/flare/cloudflare"; export class Action extends createAction(app) {}`;
+  const virtualEntry = join(working, `${role}-entry.ts`);
+  const result = await bundle({
+    entrypoints: [virtualEntry],
+    files: { [virtualEntry]: code },
+    external: ["cloudflare:workers"],
+    metafile: true
+  });
+  if (Object.keys(result.metafile.inputs).some((path) => /modelcontextprotocol|agents\//.test(path)))
+    throw new Error("Full Agents/MCP code entered application bundle");
+  if (result.outputs.length !== 1 || result.outputs[0].kind !== "entry-point")
+    throw new Error("Application runtime must compile to one JavaScript module");
+  const output = await result.outputs[0].text();
+  if (Buffer.byteLength(output) > 1048576)
+    throw new Error("Application bundle exceeds the preview 1 MiB limit");
+  return output;
+}
+async function generateReferences(contract) {
+  let generated = `import {reference} from "@auersperg/flare";
+`;
+  const refs = [];
+  for (const [index, [path, fn]] of Object.entries(contract.functions).entries()) {
+    generated += await compile(fn.input, `Input${index}`, {
+      bannerComment: ""
+    });
+    generated += await compile(fn.output, `Output${index}`, {
+      bannerComment: ""
+    });
+    refs.push(`${JSON.stringify(path)}: reference<Input${index}, Output${index}>(${JSON.stringify(path)}, ${JSON.stringify(fn.kind)})`);
+  }
+  generated += `
+export const api = {
+${refs.join(`,
+`)}
+} as const;
+`;
+  return generated;
+}
+export {
+  buildApplication,
+  generateReferences
+};

package/dist/cli/chunk-x14smx1y.js

@@ -0,0 +1,113 @@
+// @bun
+// packages/flare/src/cli/login.mjs
+import { readFile, mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+import { homedir } from "os";
+import {
+  randomBytes,
+  createHash,
+  generateKeyPairSync,
+  privateDecrypt,
+  constants
+} from "crypto";
+import { createInterface } from "readline/promises";
+import { spawn } from "child_process";
+import { setTimeout as sleep } from "timers/promises";
+var credentialDirectory = () => join(process.env.FLARE_CONFIG_HOME ?? join(homedir(), ".config", "flare"));
+async function storedToken(platform, project) {
+  const key = createHash("sha256").update(platform + "/" + project).digest("hex");
+  const record = JSON.parse(await readFile(join(credentialDirectory(), key + ".json"), "utf8").catch((e) => {
+    if (e.code !== "ENOENT")
+      throw e;
+    return "null";
+  }));
+  if (record && record.expiresAt > Date.now())
+    return record.token;
+  return null;
+}
+async function connect() {
+  if (!process.stdin.isTTY)
+    throw Error("First run needs an interactive terminal: run flare dev to sign in. CI can use FLARE_DEPLOY_TOKEN with a linked project.");
+  let dashboard, platform;
+  const existing = JSON.parse(await readFile(".flare/project.json", "utf8").catch((e) => {
+    if (e.code !== "ENOENT")
+      throw e;
+    return "null";
+  }));
+  if (existing)
+    platform = new URL(new URL(existing.platform).origin);
+  else {
+    const prompt = createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    try {
+      platform = new URL(await prompt.question("Runtime URL (shown in dashboard Health): "));
+    } finally {
+      prompt.close();
+    }
+  }
+  if (platform.protocol !== "https:" || platform.username || platform.password || platform.search || platform.hash || platform.pathname !== "/")
+    throw Error("Enter a plain HTTPS origin without a path or credentials.");
+  platform = platform.origin + "/control";
+  const secret = randomBytes(32).toString("hex"), secretHash = createHash("sha256").update(secret).digest("hex");
+  const { publicKey, privateKey } = generateKeyPairSync("rsa", {
+    modulusLength: 2048
+  });
+  async function post(path, body) {
+    const response = await fetch(platform + "/api/cli/" + path, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      redirect: "error",
+      signal: AbortSignal.timeout(15000)
+    });
+    const data = await response.json();
+    if (!response.ok)
+      throw Error(`CLI login ${data.error ?? response.status}. The platform must have the CLI login update installed.`);
+    return data;
+  }
+  const session = await post("start", {
+    secretHash,
+    publicKey: publicKey.export({ format: "jwk" })
+  });
+  dashboard = new URL(session.dashboard);
+  if (dashboard.protocol !== "https:" || dashboard.username || dashboard.password || dashboard.pathname !== "/" || dashboard.search || dashboard.hash)
+    throw Error("Invalid dashboard URL returned by installation");
+  const url = dashboard.origin + "/?cli=" + encodeURIComponent(session.id);
+  console.log(`Confirm code ${session.code} in your dashboard:
+${url}`);
+  const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? null : "xdg-open";
+  if (opener) {
+    const child = spawn(opener, [url], { stdio: "ignore" });
+    child.on("error", () => {});
+    child.unref();
+  }
+  const end = Date.now() + Math.min(session.expiresIn, 600) * 1000;
+  while (Date.now() < end) {
+    await sleep(3000);
+    const result = await post("poll", { id: session.id, secret });
+    if (result.pending)
+      continue;
+    if (result.platform !== platform || !/^[a-f0-9-]{36}$/.test(result.project))
+      throw Error("Unexpected platform/project in login response");
+    const token = privateDecrypt({
+      key: privateKey,
+      oaepHash: "sha256",
+      padding: constants.RSA_PKCS1_OAEP_PADDING
+    }, Buffer.from(result.encrypted, "base64")).toString();
+    const directory = credentialDirectory();
+    await mkdir(directory, { recursive: true, mode: 448 });
+    const key = createHash("sha256").update(platform + "/" + result.project).digest("hex");
+    await writeFile(join(directory, key + ".json"), JSON.stringify({ token, expiresAt: result.expiresAt }) + `
+`, { mode: 384 });
+    process.env.FLARE_DEPLOY_TOKEN = token;
+    const { link } = await import("./chunk-5cq8wgte.js");
+    return link({ platform, project: result.project });
+  }
+  throw Error("Login expired. Run flare dev again.");
+}
+export {
+  connect,
+  storedToken
+};

package/dist/cli/chunk-xff4b01y.js

@@ -0,0 +1,18 @@
+// @bun
+// packages/flare/src/cli/bundle.mjs
+async function bundle(options) {
+  const result = await Bun.build({
+    format: "esm",
+    target: "browser",
+    env: "disable",
+    metafile: true,
+    ...options
+  });
+  if (!result.success)
+    throw new AggregateError(result.logs, "Build failed");
+  if (!result.metafile)
+    throw new Error("Compiler dependency graph is missing");
+  return result;
+}
+
+export { bundle };

package/dist/cli/flare.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env bun
+// @bun
+
+// packages/flare/src/cli/main.mjs
+if (typeof Bun === "undefined" || !Bun.semver.satisfies(Bun.version, ">=1.4.3")) {
+  console.error("Flare CLI requires Bun 1.4.3 or newer.");
+  process.exit(1);
+}
+var [command, ...args] = process.argv.slice(2);
+if (!command || ["--help", "help"].includes(command))
+  console.log(`Flare 0.3 private minimum
+
+flare dev                  Browser login, setup and cloud dev watch
+flare deploy               Confirmed production build and deploy
+
+Advanced commands:
+flare releases --env dev|prod
+flare promote --hash <dev release hash> [--cmd "bun run build"]
+flare rollback --hash <retained release hash> --env dev|prod
+flare build --entry <app.ts> --outdir <new directory>
+flare link --platform <management URL> --project <ID>
+flare deploy --env dev|prod --release <directory> [--confirm <project ID>]
+flare dev --entry <app.ts>
+flare backup create|list|restore|delete|status --env dev|prod
+  restore --from dev|prod --id <backup ID> (empty target only)
+
+Dashboard is Cloudflare-only. Local tooling does not run a dashboard or backend. CLI authentication uses FLARE_DEPLOY_TOKEN from the online dashboard. Run flare dev with no flags for browser login, project selection and automatic schema/API generation. Run flare deploy with no flags for a confirmed production release. Platform installation is separate.`);
+else if ([
+  "build",
+  "link",
+  "deploy",
+  "dev",
+  "backup",
+  "promote",
+  "rollback",
+  "releases"
+].includes(command)) {
+  try {
+    const options = {};
+    if (command === "backup")
+      options.operation = args.shift() ?? "list";
+    const permitted = {
+      build: ["entry", "outdir"],
+      link: ["platform", "project"],
+      deploy: ["env", "release", "confirm", "cmd"],
+      promote: ["env", "hash", "confirm", "cmd"],
+      rollback: ["env", "hash", "confirm", "cmd"],
+      releases: ["env"],
+      dev: ["entry", "env"],
+      backup: ["env", "id", "from", "confirm", "cursor"]
+    }[command];
+    for (let i = 0;i < args.length; i += 2) {
+      const key = args[i]?.replace(/^--/, "");
+      if (!args[i]?.startsWith("--") || !permitted.includes(key) || !args[i + 1] || args[i + 1].startsWith("--") || key in options)
+        throw Error("Expected supported unique named options");
+      options[key] = args[i + 1];
+    }
+    if (command === "build") {
+      if (!options.entry || !options.outdir)
+        throw Error("Required: --entry, --outdir");
+      const { buildApplication } = await import("./chunk-vx7kmczm.js");
+      const x = await buildApplication(options);
+      console.log(`Built immutable release ${x.hash}
+${x.outdir}`);
+    } else {
+      const cloud = await import("./chunk-5cq8wgte.js");
+      const x = await cloud[command](options);
+      if (x)
+        console.log(JSON.stringify(x, null, 2));
+    }
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : "Command failed");
+    process.exitCode = 1;
+  }
+} else {
+  console.error(`Unsupported command: ${command}; no deployment has occurred.`);
+  process.exitCode = 1;
+}

package/dist/sdk/backup.d.ts

@@ -0,0 +1,22 @@
+import { type Json } from "./protocol.js";
+import { type NativeStorage, type Schema, type SchemaContract } from "./schema.js";
+export declare const SNAPSHOT_BYTES: number;
+export declare const SNAPSHOT_ROWS = 10000;
+export type DataSnapshot = {
+    format: 1;
+    schema: SchemaContract;
+    revision: number;
+    tables: Record<string, {
+        _id: string;
+        _creationTime: number;
+        value: Record<string, Json>;
+    }[]>;
+};
+export declare function emptyData(storage: NativeStorage, schema: Schema): boolean;
+/** Caller holds the facet's serial gate; all pages belong to one revision. */
+export declare function exportData(storage: NativeStorage, schema: Schema): DataSnapshot;
+/** Native transaction preserves IDs, references and timestamps; never merges into existing data. */
+export declare function restoreData(storage: NativeStorage, schema: Schema, id: string, snapshot: DataSnapshot): Promise<{
+    restored: boolean;
+    revision: number;
+}>;