@oalo-ai/cli 0.0.0-stage → 0.1.0

package/src/commands/tokens.js

@@ -0,0 +1,85 @@
+import { OaloChannel } from "../channel.js";
+import { resolve as resolveConfig, controlPlane, HOW_TO_CONNECT } from "../config.js";
+import { dim } from "../events.js";
+
+/**
+ * `oalo tokens`: the workspace's sync tokens (data plane), managed as the
+ * signed-in person.
+ *
+ *   oalo tokens list
+ *   oalo tokens create --name shop-mirror --scope write:orders [--scope read:products] [--days 90]
+ *   oalo tokens revoke <id>
+ *
+ * A sync token is for an app's own server (mirroring rows in, reading them
+ * out). It carries no end-user identity and reads or writes every row of the
+ * tables it covers, so it never goes inside a mobile or web app. Prefer the
+ * narrowest scope: `write:<table>` over `write`.
+ */
+export async function tokens(flags, rest) {
+  const sub = rest[1] || "list";
+  const cfg = resolveConfig(flags);
+  const { url, token } = controlPlane(cfg);
+  if (!url || !token) {
+    console.error(`oalo tokens needs a CLI token.\n\n${HOW_TO_CONNECT}`);
+    process.exitCode = 2;
+    return;
+  }
+
+  const ch = new OaloChannel({ url, token });
+  try {
+    await ch.connect();
+    if (sub === "list") {
+      const r = await ch.call("sync_api:list_tokens", {});
+      const list = r.tokens || [];
+      if (flags.json) return void console.log(JSON.stringify(list, null, 2));
+      if (!list.length) return void console.log(`no sync tokens in ${url}`);
+      for (const t of list) {
+        const when = t.last_used_at ? `last used ${t.last_used_at.slice(0, 10)}` : "never used";
+        const exp = t.expires_at ? `, expires ${t.expires_at.slice(0, 10)}` : "";
+        console.log(`${t.id}  ${t.name}  ${(t.scopes || []).join(" ")}  ${dim(when + exp)}`);
+      }
+      return;
+    }
+
+    if (sub === "create") {
+      const scopes = [].concat(flags.scope || []).flatMap((s) => String(s).split(",")).map((s) => s.trim()).filter(Boolean);
+      if (typeof flags.name !== "string" || !scopes.length) {
+        console.error("usage: oalo tokens create --name <name> --scope write:<table> [--scope ...] [--days N]\n" +
+          "scopes: read, write, read_manifest, read:<table>, write:<table>, events, workflows, chat, env:dev, env:prod");
+        process.exitCode = 2;
+        return;
+      }
+      const days = Number(flags.days || 90);
+      const expires_at = days > 0 ? new Date(Date.now() + days * 86_400_000).toISOString() : undefined;
+      const r = await ch.call("sync_api:create_token", { name: flags.name, scopes, ...(expires_at ? { expires_at } : {}) });
+      if (flags.json) return void console.log(JSON.stringify(r, null, 2));
+      console.log(r.token);
+      // What the server granted, not what was asked for.
+      const granted = (r.scopes || scopes).join(" ");
+      const expiry = expires_at ? `expires ${expires_at.slice(0, 10)} (${days} days; --days 0 for no expiry)` : "never expires";
+      console.error(dim(`${flags.name}: ${granted}, ${expiry}. ` +
+        "Shown once: put it in the app server's secrets now. Never ship it inside a mobile or web app."));
+      return;
+    }
+
+    if (sub === "revoke") {
+      const id = rest[2];
+      if (!id) {
+        console.error("usage: oalo tokens revoke <id>   (ids from `oalo tokens list`)");
+        process.exitCode = 2;
+        return;
+      }
+      await ch.call("sync_api:revoke_token", { id });
+      console.log(`revoked ${id}. Anything still using it gets 401 from now on.`);
+      return;
+    }
+
+    console.error(`unknown tokens command: ${sub} (list, create, revoke)`);
+    process.exitCode = 2;
+  } catch (e) {
+    console.error(e.message);
+    process.exitCode = 1;
+  } finally {
+    ch.close();
+  }
+}

package/src/commands/typegen.js

@@ -0,0 +1,505 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { resolve as resolveConfig, HOW_TO_CONNECT } from "../config.js";
+import { fetchManifest, fetchWorkflows, syncGet } from "../api.js";
+
+const DEFAULT_OUT = "oalo.generated.ts";
+
+/**
+ * Field-type vocabulary is defined by `mix sync.gen.model`, which is what
+ * creates models in the first place. This mirrors its `dart_type/1` exactly so
+ * the two generators cannot drift:
+ *
+ *   string|text|references -> String   (a reference holds the target's id)
+ *   integer|datetime       -> int      (datetime is an epoch int, not a string)
+ *   float                  -> double
+ *   boolean                -> bool
+ *   anything else          -> dynamic  (json lands here)
+ */
+function tsType(type) {
+  switch (type) {
+    case "string":
+    case "text":
+    case "references":
+      return "string";
+    case "integer":
+    case "float":
+    case "datetime":
+      return "number";
+    case "boolean":
+      return "boolean";
+    default:
+      return "unknown";
+  }
+}
+
+const pascal = (table) =>
+  table
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((w) => w[0].toUpperCase() + w.slice(1))
+    .join("");
+
+/**
+ * `<Table>Doc` rather than a singularised `<Table>`. Singularising is a bug
+ * farm (quizzes, measurements, stages all break naive rules) and the suffix
+ * says what the type actually is: the document body, not the whole row.
+ */
+const docTypeName = (table) => `${pascal(table)}Doc`;
+
+/**
+ * Quote a property name only when it is not a plain identifier. Field names come
+ * from user-created models, so they cannot be assumed safe, but quoting
+ * everything makes the common case noisy to read.
+ */
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const propKey = (name) => (IDENT.test(name) ? name : JSON.stringify(name));
+
+function renderModel(table, model) {
+  const fields = model.fields || [];
+  const lines = [];
+
+  lines.push(`/** \`${table}\` — primary key \`${model.primary_key || "id"}\`${
+    model.shared ? ", shared" : ""
+  }${model.owner_field ? `, owned via \`${model.owner_field}\`` : ""} */`);
+  lines.push(`export interface ${docTypeName(table)} {`);
+
+  for (const f of fields) {
+    if (!f?.name) continue;
+    lines.push(`  ${propKey(f.name)}?: ${tsType(f.type)};`);
+  }
+
+  // The manifest is a PARTIAL description, not a closed schema: `clients`
+  // declares only `user_id` while real documents also carry email, name and
+  // phone. Closing the interface would make correct code fail to compile, so
+  // declared fields are typed and the rest stay reachable.
+  lines.push(`  /** The manifest describes the fields above; documents may carry more. */`);
+  lines.push(`  [key: string]: unknown;`);
+  lines.push(`}`);
+  return lines.join("\n");
+}
+
+// A workflow contract's field types (AppBuilder.Loops.ApiCalls) in TypeScript.
+function contractType(type) {
+  switch (type) {
+    case "string":
+      return "string";
+    case "number":
+    case "integer":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "object":
+      return "Record<string, unknown>";
+    case "array":
+      return "unknown[]";
+    default:
+      return "unknown";
+  }
+}
+
+function renderFields(name, fields) {
+  const lines = [`export interface ${name} {`];
+  for (const [field, f] of Object.entries(fields || {}).sort(([a], [b]) => a.localeCompare(b))) {
+    if (f?.description) lines.push(`  /** ${String(f.description).replace(/\*\//g, "* /")} */`);
+    lines.push(`  ${propKey(field)}${f?.required === false ? "?" : ""}: ${contractType(f?.type)};`);
+  }
+  lines.push(`}`);
+  return lines.join("\n");
+}
+
+// The workflows an app can call: their types, and `runWorkflow` to call one
+// from the app's server with the token OALO gives it.
+function renderWorkflows(workflows) {
+  const list = [...workflows].sort((a, b) => a.name.localeCompare(b.name));
+  const type = (w) => pascal(w.name);
+  const out = [
+    ``,
+    `// ── Workflows ─────────────────────────────────────────────────────────────`,
+    `// The workflows this workspace's apps can call: POST /api/workflows/v1/<name>/run.`,
+    ``,
+  ];
+  for (const w of list) {
+    if (w.description) out.push(`/** ${w.name}: ${String(w.description).replace(/\*\//g, "* /")} */`);
+    out.push(renderFields(`${type(w)}Input`, w.input), renderFields(`${type(w)}Output`, w.output), ``);
+  }
+  out.push(
+    `export interface WorkflowTypes {`,
+    ...list.map((w) => `  ${JSON.stringify(w.name)}: { input: ${type(w)}Input; output: ${type(w)}Output };`),
+    `}`,
+    ``,
+    `export type WorkflowName = keyof WorkflowTypes;`,
+    ``,
+    `export interface WorkflowRun<K extends WorkflowName> {`,
+    `  run_id: number;`,
+    `  workflow: K;`,
+    `  /** running: not done within \`wait\`; read it again with getWorkflowRun. */`,
+    `  status: "success" | "running" | "waiting" | "error" | "halted_iterations" | "halted_cost" | "cancelled";`,
+    `  output: WorkflowTypes[K]["output"] | null;`,
+    `  error: string | null;`,
+    `  cost_usd: number | null;`,
+    `  /** A preview's call: dev data, outside actions simulated. */`,
+    `  test: boolean;`,
+    `  poll: string;`,
+    `}`,
+    ``,
+    `export interface WorkflowCallOptions extends OaloServerOptions {`,
+    `  /** The person it's about, so the workflow's sends reach them. */`,
+    `  contact?: { external_ref?: string; email?: string; phone?: string; name?: string };`,
+    `  /** Seconds to wait for the answer (0 to 55, default 30). */`,
+    `  wait?: number;`,
+    `}`,
+    ``,
+    `/** Run a workflow and wait for its output. Check \`status\` before reading \`output\`. */`,
+    `export async function runWorkflow<K extends WorkflowName>(name: K, input: WorkflowTypes[K]["input"], opts: WorkflowCallOptions = {}): Promise<WorkflowRun<K>> {`,
+    `  const body = { input, contact: opts.contact, wait: opts.wait };`,
+    `  return (await oaloFetch(\`/api/workflows/v1/\${encodeURIComponent(name)}/run\`, { method: "POST", body: JSON.stringify(body) }, opts)) as WorkflowRun<K>;`,
+    `}`,
+    ``,
+    `/** A run that answered \`running\`, read again. */`,
+    `export async function getWorkflowRun<K extends WorkflowName>(run: WorkflowRun<K> | number, opts: WorkflowCallOptions = {}): Promise<WorkflowRun<K>> {`,
+    `  const id = typeof run === "number" ? run : run.run_id;`,
+    `  return (await oaloFetch(\`/api/workflows/v1/runs/\${id}\`, { method: "GET" }, opts)) as WorkflowRun<K>;`,
+    `}`,
+    ``,
+  );
+  return out;
+}
+
+// What every generated file gets: the server-side fetch the helpers share, and
+// createChatSession for the chat widget's data-user-url endpoint.
+function renderServerHelpers() {
+  return [
+    ``,
+    `// ── Server-side helpers ───────────────────────────────────────────────────`,
+    `// They use the OALO_URL and OALO_SYNC_TOKEN OALO gives a server app. Never`,
+    `// call them from a browser: the token must stay on the server.`,
+    ``,
+    `export interface OaloServerOptions {`,
+    `  /** Default: OALO_URL and OALO_SYNC_TOKEN from the environment. */`,
+    `  url?: string;`,
+    `  token?: string;`,
+    `}`,
+    ``,
+    `const oaloEnv = (k: string): string | undefined => (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env?.[k];`,
+    ``,
+    `async function oaloFetch(path: string, init: RequestInit, opts: OaloServerOptions): Promise<unknown> {`,
+    `  const url = opts.url ?? oaloEnv("OALO_URL");`,
+    `  const token = opts.token ?? oaloEnv("OALO_SYNC_TOKEN");`,
+    `  if (!url || !token) throw new Error("OALO_URL and OALO_SYNC_TOKEN are not set: call OALO from the app's server");`,
+    `  const res = await fetch(url.replace(/\\/$/, "") + path, { ...init, headers: { Authorization: \`Bearer \${token}\`, "Content-Type": "application/json" } });`,
+    `  const body = (await res.json().catch(() => null)) as { error?: string | { message?: string } } | null;`,
+    `  const message = typeof body?.error === "string" ? body.error : body?.error?.message;`,
+    `  if (!res.ok && res.status !== 202) throw new Error(message ?? \`Oalo call failed: HTTP \${res.status}\`);`,
+    `  return body;`,
+    `}`,
+    ``,
+    `/** One aggregate over a model's rows (oalo docs dashboards). */`,
+    `export interface MetricQuery<K extends ModelName = ModelName> {`,
+    `  table: K;`,
+    `  /** Default count. sum, avg, min and max read \`field\` as a number; distinct counts its values. */`,
+    `  measure?: "count" | "sum" | "avg" | "min" | "max" | "distinct";`,
+    `  field?: string & keyof DocumentOf<K>;`,
+    `  /** Group by a field (top \`limit\` groups, default 12). */`,
+    `  by?: (string & keyof DocumentOf<K>) | "owner_id" | "availability" | "product_id";`,
+    `  every?: "day" | "week" | "month";`,
+    `  /** Which time a row counts at: when it was created (default), last changed, or a date field. */`,
+    `  time?: "created" | "changed" | (string & keyof DocumentOf<K>);`,
+    `  /** The window, ending now. Leave it out for all time. */`,
+    `  days?: number;`,
+    `  /** Also the same measure over the window before (needs days). */`,
+    `  compare?: boolean;`,
+    `  limit?: number;`,
+    `  /** Buckets in this zone, like America/Argentina/Buenos_Aires. Default UTC. */`,
+    `  tz?: string;`,
+    `  where?: { field: string & keyof DocumentOf<K>; op: "eq" | "neq" | "in" | "gt" | "gte" | "lt" | "lte" | "set" | "unset" | "contains"; value?: string | number | (string | number)[] }[];`,
+    `}`,
+    ``,
+    `export interface MetricResult {`,
+    `  rows: { bucket?: string; group?: string; value: number }[];`,
+    `  total: number;`,
+    `  previous: number | null;`,
+    `  /** Every bucket in the window, so a line has its empty days. */`,
+    `  buckets: string[] | null;`,
+    `  groups: string[] | null;`,
+    `  more_groups: boolean;`,
+    `  /** Rows counted by created time that are older than the created stamp. */`,
+    `  untracked: number;`,
+    `}`,
+    ``,
+    `/** A count, sum or average over a model, grouped or over time, for the app's own charts. From the app's server. */`,
+    `export async function queryMetric<K extends ModelName>(query: MetricQuery<K>, opts: OaloServerOptions = {}): Promise<MetricResult> {`,
+    `  return (await oaloFetch("/api/sync/v1/_metrics", { method: "POST", body: JSON.stringify(query) }, opts)) as MetricResult;`,
+    `}`,
+    ``,
+    `export interface ChatSession {`,
+    `  /** Give this to the chat widget: answer it from the endpoint in its data-user-url. */`,
+    `  user_token: string;`,
+    `  expires_at: string;`,
+    `  bot: string;`,
+    `}`,
+    ``,
+    `/**`,
+    ` * The chat widget as your signed-in user. Answer the widget's data-user-url with`,
+    ` * this (JSON), after checking the user is signed in; answer 401 when they aren't.`,
+    ` */`,
+    `export async function createChatSession(`,
+    `  bot: string,`,
+    `  user: { external_ref: string; email?: string; name?: string; phone?: string },`,
+    `  opts: OaloServerOptions & { context?: string } = {},`,
+    `): Promise<ChatSession> {`,
+    `  const body = { bot, user, context: opts.context };`,
+    `  return (await oaloFetch("/api/chat/v1/sessions", { method: "POST", body: JSON.stringify(body) }, opts)) as ChatSession;`,
+    `}`,
+    ``,
+    `/** A bot's call to one of your endpoints, declared in .oalo/app.json. */`,
+    `export interface OaloToolCall {`,
+    `  tool: string;`,
+    `  /** The bot's public id. */`,
+    `  bot: string;`,
+    `  conversation: string | null;`,
+    `  /** Your own id for the signed-in user (from createChatSession), or null when the chat is anonymous. */`,
+    `  user: string | null;`,
+    `}`,
+    ``,
+    `/**`,
+    ` * Check a request to a tool endpoint came from OALO, and for which user. Pass the`,
+    ` * method, the path with its query as received, the headers and the RAW body (before`,
+    ` * JSON parsing). Throws when it isn't OALO's, or is over 5 minutes old.`,
+    ` */`,
+    `export async function verifyOaloToolCall(`,
+    `  req: { method: string; path: string; headers: Headers | Record<string, string | string[] | undefined>; body: string },`,
+    `  opts: { token?: string; maxAgeSeconds?: number } = {},`,
+    `): Promise<OaloToolCall> {`,
+    `  const header = (k: string): string | undefined => {`,
+    `    const v = typeof (req.headers as Headers).get === "function" ? (req.headers as Headers).get(k) ?? undefined : (req.headers as Record<string, string | string[] | undefined>)[k];`,
+    `    return Array.isArray(v) ? v[0] : v;`,
+    `  };`,
+    `  const token = opts.token ?? oaloEnv("OALO_SYNC_TOKEN");`,
+    `  if (!token) throw new Error("OALO_SYNC_TOKEN is not set");`,
+    `  const ts = header("x-oalo-timestamp");`,
+    `  const sig = header("x-oalo-signature");`,
+    `  const user = header("x-oalo-user") ?? "";`,
+    `  if (!ts || !sig || !sig.startsWith("v1=")) throw new Error("not an OALO tool call");`,
+    `  if (!(Math.abs(Date.now() / 1000 - Number(ts)) <= (opts.maxAgeSeconds ?? 300))) throw new Error("the OALO tool call is too old");`,
+    `  const enc = new TextEncoder();`,
+    `  const key = await crypto.subtle.importKey("raw", enc.encode(token), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);`,
+    `  const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, enc.encode([ts, req.method.toUpperCase(), req.path, user, req.body].join("\\n"))));`,
+    `  const want = Array.from(mac, (b) => b.toString(16).padStart(2, "0")).join("");`,
+    `  const got = sig.slice(3);`,
+    `  let diff = want.length ^ got.length;`,
+    `  for (let i = 0; i < want.length; i++) diff |= want.charCodeAt(i) ^ (got.charCodeAt(i) || 0);`,
+    `  if (diff !== 0) throw new Error("the OALO signature doesn't match");`,
+    `  return { tool: header("x-oalo-tool") ?? "", bot: header("x-oalo-bot") ?? "", conversation: header("x-oalo-conversation") || null, user: user || null };`,
+    `}`,
+    ``,
+  ];
+}
+
+/**
+ * The workspace's products by id, so code names `"premium"` as a `ProductId`
+ * the compiler checks (BuyButton, a row's product_id, purchased_products),
+ * not a loose string. Older Bases send no `products`: nothing is emitted.
+ */
+function renderProducts(products) {
+  if (!Array.isArray(products)) return [];
+  const sorted = [...products].sort((a, b) => String(a.id).localeCompare(String(b.id)));
+  return [
+    `/** The workspace's products (\`oalo products\` lists them). Archived ones are left out. */`,
+    `export const PRODUCTS = {`,
+    ...sorted.map((p) => `  ${JSON.stringify(p.id)}: { title: ${JSON.stringify(p.title ?? p.id)}, type: ${JSON.stringify(p.type ?? null)} },`),
+    `} as const;`,
+    ``,
+    `export type ProductId = ${sorted.length ? "keyof typeof PRODUCTS" : "never"};`,
+    ``,
+    `/** Narrow a string (a row's product_id, an entry of purchased_products) to a ProductId. */`,
+    `export const isProductId = (s: unknown): s is ProductId =>`,
+    `  typeof s === "string" && Object.prototype.hasOwnProperty.call(PRODUCTS, s);`,
+    ``,
+  ];
+}
+
+function render(manifest, cfg, workflows = []) {
+  const models = manifest?.models || {};
+  const tables = Object.keys(models).sort();
+
+  const head = [
+    `// Generated by \`oalo typegen\`. DO NOT EDIT.`,
+    `//`,
+    `// workspace      ${cfg.serverUrl}`,
+    `// env            ${cfg.env}`,
+    `// schema version ${manifest?.schema_version ?? "unknown"}`,
+    `// models         ${tables.length}`,
+    `// workflows      ${workflows.length}`,
+    ...(Array.isArray(manifest?.products) ? [`// products       ${manifest.products.length}`] : []),
+    `//`,
+    `// Regenerate after a schema change; \`oalo typegen --check\` fails when stale.`,
+    `// The env is stamped deliberately: dev and prod are separate schemas, and`,
+    `// bindings generated against one are not a promise about the other.`,
+    ``,
+    `export type SyncId = string;`,
+    ``,
+    `/** The envelope every row carries; \`document\` holds the model's own fields. */`,
+    `export interface SyncRow<T> {`,
+    `  id: SyncId;`,
+    `  document: T;`,
+    `  owner_id: string | null;`,
+    `  availability: string | null;`,
+    `  product_id: string | null;`,
+    `  seqnum: number;`,
+    `  row_hash: string;`,
+    `  deleted_at: number | null;`,
+    `  last_modified_ms: number;`,
+    `}`,
+    ``,
+    `/** A page from \`GET /api/sync/v1/<table>\`. */`,
+    `export interface SyncPage<T> {`,
+    `  rows: SyncRow<T>[];`,
+    `  has_more: boolean;`,
+    `  next_since: number;`,
+    `}`,
+    ``,
+  ];
+
+  const bodies = tables.map((t) => renderModel(t, models[t]));
+
+  const registry = [
+    ``,
+    `/** Every table this token can read, with its key and ownership shape. */`,
+    `export const MODELS = {`,
+    ...tables.map((t) => {
+      const m = models[t];
+      return `  ${JSON.stringify(t)}: { primaryKey: ${JSON.stringify(
+        m.primary_key || "id",
+      )}, shared: ${!!m.shared}, ownerField: ${JSON.stringify(m.owner_field ?? null)} },`;
+    }),
+    `} as const;`,
+    ``,
+    `export type ModelName = keyof typeof MODELS;`,
+    ``,
+    `/** Map a table name to its document type: \`DocumentOf<"exercises">\`. */`,
+    `export interface DocumentTypes {`,
+    ...tables.map((t) => `  ${JSON.stringify(t)}: ${docTypeName(t)};`),
+    `}`,
+    ``,
+    `export type DocumentOf<K extends ModelName> = DocumentTypes[K];`,
+    `export type RowOf<K extends ModelName> = SyncRow<DocumentOf<K>>;`,
+    `export type PageOf<K extends ModelName> = SyncPage<DocumentOf<K>>;`,
+    ``,
+  ];
+
+  return [...head, ...bodies, ...registry, ...renderProducts(manifest?.products), ...renderServerHelpers(), ...(workflows.length ? renderWorkflows(workflows) : [])].join("\n");
+}
+
+export { render as renderTypes };
+
+export async function typegen(flags) {
+  const cfg = resolveConfig(flags);
+
+  if (!cfg.serverUrl || !cfg.token) {
+    console.error(`no workspace or data token for this project.\n\n${HOW_TO_CONNECT}`);
+    process.exitCode = 2;
+    return;
+  }
+  if (flags.dart) return dart(flags, cfg);
+
+  let manifest;
+  let workflows = [];
+  try {
+    manifest = await fetchManifest(cfg);
+    workflows = await fetchWorkflows(cfg).catch((e) => {
+      // A token that can read models but not list workflows still gets models.
+      if (e.status === 403) return [];
+      throw e;
+    });
+  } catch (e) {
+    console.error(`typegen failed: ${e.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const out = typeof flags.out === "string" ? flags.out : DEFAULT_OUT;
+  const generated = render(manifest, cfg, workflows);
+  const count = Object.keys(manifest?.models || {}).length;
+
+  if (flags.check) {
+    const current = existsSync(out) ? readFileSync(out, "utf8") : null;
+    if (current === generated) {
+      console.log(`${out} is up to date (schema version ${manifest?.schema_version}).`);
+      return;
+    }
+    console.error(
+      current === null
+        ? `${out} does not exist. Run: oalo typegen`
+        : `${out} is STALE (workspace schema version ${manifest?.schema_version}). Run: oalo typegen`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  mkdirSync(dirname(out) === "" ? "." : dirname(out), { recursive: true });
+  writeFileSync(out, generated);
+
+  console.log(`wrote ${out}`);
+  console.log(`  models          ${count}`);
+  console.log(`  workflows       ${workflows.length}`);
+  console.log(`  schema version  ${manifest?.schema_version}`);
+  console.log(`  env             ${cfg.env}`);
+  if (count === 0) {
+    console.log(`\n  No models visible. If this token is table-scoped, it only`);
+    console.log(`  describes the tables it can read.`);
+  }
+}
+
+const DEFINES = ".oalo/dart-defines.json";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * `oalo typegen --dart`: the Dart models, queries, mutations and providers a
+ * Flutter app built from Oalo's template uses, rendered by the Base's own
+ * generator (the one that writes them on the box), into lib/ under --out
+ * (default the project root). Also .oalo/dart-defines.json, so
+ * `flutter run --dart-define-from-file=.oalo/dart-defines.json` talks to the
+ * linked Base as the linked app.
+ */
+async function dart(flags, cfg, get = syncGet) {
+  const root = typeof flags.out === "string" ? flags.out : ".";
+  let r;
+  try {
+    r = await get("/_codegen/dart", cfg);
+  } catch (e) {
+    console.error(e.status === 404 ? "typegen failed: this Base is older than your CLI and can't render Dart yet" : `typegen failed: ${e.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const defines = { SYNC_SERVER_URL: cfg.serverUrl.replace(/\/$/, ""), OALO_ENV: cfg.env || "dev" };
+  if (cfg.appId && !UUID.test(cfg.appId)) defines.APP_SLUG = cfg.appId;
+  const files = { ...r.files, [DEFINES]: JSON.stringify(defines, null, 2) + "\n" };
+
+  if (flags.check) {
+    const stale = Object.entries(files).filter(([rel, content]) => {
+      const path = join(root, rel);
+      return !existsSync(path) || readFileSync(path, "utf8") !== content;
+    });
+    if (stale.length === 0) return void console.log(`Dart files are up to date (schema version ${r.schema_version}).`);
+    console.error(`stale or missing: ${stale.map(([rel]) => rel).join(", ")}. Run: oalo typegen --dart`);
+    process.exitCode = 1;
+    return;
+  }
+
+  for (const [rel, content] of Object.entries(files)) {
+    const path = join(root, rel);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+  }
+  const models = Object.keys(r.files).filter((f) => f.startsWith("lib/models/")).length;
+  console.log(`wrote lib/sync/generated (5 files) and lib/models (${models} model${models === 1 ? "" : "s"})${root === "." ? "" : ` under ${root}`}`);
+  console.log(`  schema version  ${r.schema_version}`);
+  console.log(`  env             ${defines.OALO_ENV}`);
+  console.log(`wrote ${DEFINES}: the Base, ${defines.APP_SLUG ? `app ${defines.APP_SLUG}, ` : ""}env ${defines.OALO_ENV}`);
+  if (!defines.APP_SLUG) console.log(`  No app slug: link one (oalo link --app <slug>) so sync and chat know which app this is.`);
+  console.log(`\nRun it against the Base: flutter run -d chrome --dart-define-from-file=${DEFINES}`);
+}
+
+export { dart as _dart };