@oalo-ai/cli 0.0.0-stage → 0.1.1

package/src/commands/whoami.js

@@ -0,0 +1,112 @@
+import { OaloChannel } from "../channel.js";
+import { resolve as resolveConfig, controlPlane, readToken, HOW_TO_CONNECT } from "../config.js";
+import { fetchManifest } from "../api.js";
+import { serverInfo, cliTooOld, CLI_VERSION } from "../server.js";
+import { dim } from "../events.js";
+
+/**
+ * `oalo whoami [--json]`: which workspace, person and connection this machine
+ * uses, and whether each saved token works right now. The first thing to run
+ * after `oalo login`, and when a command is refused.
+ */
+export async function whoami(flags) {
+  const cfg = resolveConfig(flags);
+  const { url, token } = controlPlane(cfg);
+
+  if (!url || !token) {
+    console.error(`Not connected to a workspace.\n\n${HOW_TO_CONNECT}`);
+    process.exitCode = 2;
+    return;
+  }
+
+  const info = await serverInfo(url);
+  const out = { workspace: url, cli_version: CLI_VERSION, server: info, me: null, data_token: null, problems: [] };
+
+  if (!info) out.problems.push(`could not reach ${url}`);
+  const old = cliTooOld(info);
+  if (old) out.problems.push(old);
+
+  // Control plane: who the CLI token acts as.
+  const ch = new OaloChannel({ url, token, timeoutMs: 15000 });
+  try {
+    await ch.connect();
+    out.me = await ch.call("cli_api:whoami", {});
+  } catch (e) {
+    out.problems.push(
+      e.code === "unknown_event"
+        ? `${url} runs an older Oalo, so it can't say who you are. Your CLI token does work.`
+        : `CLI token: ${e.message}`,
+    );
+  } finally {
+    ch.close();
+  }
+
+  // Data plane: is there a data token for this workspace, and does it work?
+  const dataToken = (cfg.serverUrl === url && cfg.token) || readToken({ serverUrl: url, appId: cfg.appId }, "sync");
+  if (dataToken) {
+    try {
+      const m = await fetchManifest({ serverUrl: url, token: dataToken, env: cfg.env });
+      out.data_token = { works: true, tables: Object.keys(m?.models || {}).length };
+    } catch (e) {
+      out.data_token = { works: false, error: e.message };
+    }
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify(out, null, 2));
+  } else {
+    print(out);
+  }
+  if (out.problems.length || !out.me) process.exitCode = 1;
+}
+
+function print({ workspace, cli_version, server, me, data_token, problems }) {
+  const rows = [];
+  rows.push(["workspace", me?.org_name ? `${workspace}  (${me.org_name})` : workspace]);
+
+  if (me) {
+    const role = [me.role, me.developer && me.role !== "admin" ? "developer" : null, me.restricted ? "restricted access" : null]
+      .filter(Boolean)
+      .join(", ");
+    rows.push(["you", `${me.username || me.user_id}${me.email ? ` <${me.email}>` : ""}, ${role}`]);
+
+    const c = me.connection;
+    rows.push([
+      "connection",
+      c
+        ? `"${c.name}", created ${day(c.created_at)}${c.last_used_at ? `, last used ${ago(c.last_used_at)}` : ""}${c.expires_at ? `, expires ${day(c.expires_at)}` : ""}`
+        : "not a saved connection",
+    ]);
+  }
+
+  rows.push([
+    "data token",
+    !data_token
+      ? "none saved (typegen and tail need one)"
+      : data_token.works
+        ? `works (${data_token.tables} tables)`
+        : `rejected: ${data_token.error}`,
+  ]);
+
+  rows.push([
+    "server",
+    !server ? "unreachable" : server.features.length ? `api ${server.api}: ${server.features.join(", ")}` : `api ${server.api} (older than this CLI: no login, whoami or emit)`,
+  ]);
+  rows.push(["cli", cli_version]);
+
+  const w = Math.max(...rows.map(([k]) => k.length));
+  for (const [k, v] of rows) console.log(`${k.padEnd(w)}  ${v}`);
+
+  if (me && !me.developer) console.log(dim("\noalo emit needs admin or Developer access. An admin can turn on Developer for you under Team."));
+  for (const p of problems) console.error(`\n${p}`);
+}
+
+const day = (iso) => (iso ? iso.slice(0, 10) : "?");
+
+function ago(iso) {
+  const s = Math.max(0, (Date.now() - Date.parse(iso)) / 1000);
+  if (s < 90) return "just now";
+  if (s < 5400) return `${Math.round(s / 60)} min ago`;
+  if (s < 129600) return `${Math.round(s / 3600)} h ago`;
+  return `${Math.round(s / 86400)} days ago`;
+}

package/src/config.js

@@ -0,0 +1,157 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, appendFileSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+
+/**
+ * Two stores, deliberately split.
+ *
+ *   .oalo/config.json       in the PROJECT, meant to be committed.
+ *                           Which workspace, which app, which env.
+ *   ~/.oalo/credentials.json  at USER level, never in the project tree.
+ *
+ * A sync token is workspace-wide data access with no end-user identity: it can
+ * read and write every member's rows. Keeping it out of the repo has to be
+ * structural, not a habit — so it is never written under the project at all,
+ * and `oalo link` additionally adds `.oalo/credentials*` to .gitignore in case
+ * someone later puts one there by hand.
+ */
+
+export const PROJECT_CONFIG = ".oalo/config.json";
+// OALO_HOME relocates the credential store. Needed so tests never touch a real
+// developer's credentials, and useful for CI and containers where $HOME is not
+// where you want a long-lived token to land.
+const CRED_PATH = join(process.env.OALO_HOME || homedir(), ".oalo", "credentials.json");
+
+function readJson(path, fallback) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(path, data, mode) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(data, null, 2) + "\n");
+  if (mode) chmodSync(path, mode);
+}
+
+export function readConfig(cwd = process.cwd()) {
+  return readJson(join(cwd, PROJECT_CONFIG), null);
+}
+
+export function writeConfig(config, cwd = process.cwd()) {
+  writeJson(join(cwd, PROJECT_CONFIG), config);
+}
+
+/** Credentials are keyed by workspace + app, so one machine can hold several. */
+function credKey({ serverUrl, appId }) {
+  return `${serverUrl}#${appId || "-"}`;
+}
+
+/**
+ * Tokens are stored BY KIND, because the CLI uses two different kinds against
+ * the same workspace and they are not interchangeable:
+ *
+ *   sync — the DATA plane (/api/sync/v1). What `oalo typegen` reads.
+ *   cli  — the CONTROL plane (the build surface). What `oalo mcp` joins with.
+ *
+ * Handing a sync token to the channel just fails to authenticate, so keeping
+ * them distinct in the store is what stops a confusing "token rejected" when
+ * the token is perfectly valid for something else.
+ *
+ *   { "<url>#<app>": { sync: {token, saved_at}, cli: {token, saved_at} } }
+ */
+export const TOKEN_KINDS = ["sync", "cli"];
+
+export function readToken(config, kind = "sync") {
+  const all = readJson(CRED_PATH, {});
+  // `oalo login` saves per workspace (no app), so an app-specific link falls
+  // back to the workspace's own entry.
+  const entry = all[credKey(config)] || (config.appId ? all[credKey({ ...config, appId: null })] : null);
+  if (!entry) return null;
+  // Tolerate the earlier flat shape ({token, saved_at}) as a sync token.
+  if (typeof entry.token === "string") return kind === "sync" ? entry.token : null;
+  return entry[kind]?.token ?? null;
+}
+
+export function writeToken(config, token, kind = "sync", extra = {}) {
+  const all = readJson(CRED_PATH, {});
+  const key = credKey(config);
+  const existing = all[key] && typeof all[key].token !== "string" ? all[key] : {};
+  all[key] = { ...existing, [kind]: { token, saved_at: new Date().toISOString(), ...extra } };
+  // 0600: the file holds workspace-wide access.
+  writeJson(CRED_PATH, all, 0o600);
+  return CRED_PATH;
+}
+
+/** All workspaces that have a token of `kind`, newest-written first. */
+export function listWorkspaces(kind) {
+  const all = readJson(CRED_PATH, {});
+  return Object.entries(all)
+    .map(([key, entry]) => {
+      const flat = typeof entry?.token === "string";
+      const rec = flat ? (kind === "sync" ? { token: entry.token, saved_at: entry.saved_at } : null) : entry?.[kind];
+      if (!rec?.token) return null;
+      const [serverUrl, appId] = key.split("#");
+      return { serverUrl, appId: appId === "-" ? null : appId, token: rec.token, savedAt: rec.saved_at };
+    })
+    .filter(Boolean)
+    .sort((a, b) => String(b.savedAt).localeCompare(String(a.savedAt)));
+}
+
+export const credentialsPath = () => CRED_PATH;
+
+/** The saved entry for a workspace (no app), e.g. to find a login's connection id. */
+export function readEntry(serverUrl) {
+  return readJson(CRED_PATH, {})[credKey({ serverUrl, appId: null })] || null;
+}
+
+/** Forget every saved credential for a workspace. Returns how many entries went. */
+export function forgetWorkspace(serverUrl) {
+  const all = readJson(CRED_PATH, {});
+  const keys = Object.keys(all).filter((k) => k.split("#")[0] === serverUrl);
+  for (const k of keys) delete all[k];
+  if (keys.length) writeJson(CRED_PATH, all, 0o600);
+  return keys.length;
+}
+
+/**
+ * The control-plane URL and CLI token for a command. When this project (or
+ * --server / OALO_URL) names a workspace, only that workspace's token is used;
+ * a token saved for another workspace would just fail to authenticate. With
+ * no workspace named, the most recently saved one is used.
+ */
+export function controlPlane(cfg) {
+  if (cfg.cliToken) return { url: cfg.serverUrl, token: cfg.cliToken };
+  const saved = listWorkspaces("cli");
+  const match = cfg.serverUrl ? saved.find((w) => w.serverUrl === cfg.serverUrl) : saved[0];
+  return { url: cfg.serverUrl || match?.serverUrl || null, token: match?.token || null };
+}
+
+/** How to get a CLI token, for "needs a CLI token" messages. */
+export const HOW_TO_CONNECT =
+  "Connect this machine with:\n  oalo login <workspace>      (your Base at <workspace>.oalo.ai)\n\n" +
+  "Or create a connection in the dashboard under Account -> CLI & agents and run the oalo link command it shows.";
+
+/** Defensive: the token never lands here, but make sure it cannot if it did. */
+export function ensureGitignored(cwd = process.cwd()) {
+  const gi = join(cwd, ".gitignore");
+  const rule = ".oalo/credentials*";
+  const current = existsSync(gi) ? readFileSync(gi, "utf8") : "";
+  if (current.includes(rule)) return false;
+  appendFileSync(gi, `${current.endsWith("\n") || !current ? "" : "\n"}\n# Oalo — never commit credentials\n${rule}\n`);
+  return true;
+}
+
+/** Resolve config + token, preferring explicit flags, then config, then env. */
+export function resolve(flags = {}, cwd = process.cwd()) {
+  const cfg = readConfig(cwd) || {};
+  const serverUrl = flags.server || cfg.serverUrl || process.env.OALO_URL || null;
+  const appId = flags.app || cfg.appId || null;
+  const env = flags.env || cfg.env || "dev";
+  const base = { serverUrl, appId, env };
+  const token = flags.token || process.env.OALO_SYNC_TOKEN || readToken(base, "sync");
+  const cliToken = flags["cli-token"] || process.env.OALO_CLI_TOKEN || readToken(base, "cli");
+  return { ...base, token, cliToken, schemaVersion: cfg.schemaVersion ?? null };
+}

package/src/data.js

@@ -0,0 +1,392 @@
+/**
+ * The data plane for `oalo data` and its MCP tools: models and rows in this
+ * workspace's `dev` and `prod` schemas.
+ *
+ * Two credentials, on purpose:
+ *   - Reads (models, list, get, watch, routes) use the sync token. The one
+ *     `oalo login` saves is read-only, which is all they need.
+ *   - Row writes (push, delete) use a write token limited to the tables written,
+ *     created as the signed-in person over the CLI token the first time a table
+ *     is written, and saved beside the read token. Defining and promoting
+ *     models goes over the CLI token directly (`data:create_model`,
+ *     `data:promote_model`), so it follows the person's dashboard access.
+ *
+ * Every write names its schema. `prod` rows sync to live apps at once, so a
+ * write to `prod` must be asked for explicitly (see `targetEnv`).
+ */
+import { hostname } from "node:os";
+import { syncRequest, ApiError } from "./api.js";
+import { readEntry, writeToken } from "./config.js";
+
+export const BULK_MAX = 1000;
+const WRITE_TOKEN_DAYS = 30;
+
+// ── input ────────────────────────────────────────────────────────────────
+
+/**
+ * Parse rows from a file's text. `format` is jsonl, json or csv; when omitted
+ * it is guessed from the file name. JSON may be an array or `{rows: [...]}`.
+ * CSV values stay strings unless `types` is set, which turns plain numbers,
+ * true/false and empty cells into numbers, booleans and null. Off by default,
+ * since ids and phone numbers with leading zeros must stay text.
+ */
+export function parseRecords(text, { format, name = "", types = false } = {}) {
+  const fmt = format || guessFormat(name, text);
+  const clean = text.replace(/^/, "");
+
+  if (fmt === "jsonl") {
+    return clean
+      .split(/\r?\n/)
+      .map((l) => l.trim())
+      .filter(Boolean)
+      .map((l, i) => {
+        try {
+          return JSON.parse(l);
+        } catch (e) {
+          throw new Error(`line ${i + 1} is not valid JSON: ${e.message}`);
+        }
+      });
+  }
+
+  if (fmt === "json") {
+    const data = JSON.parse(clean);
+    const rows = Array.isArray(data) ? data : Array.isArray(data?.rows) ? data.rows : null;
+    if (!rows) throw new Error("JSON input must be an array of objects, or {\"rows\": [...]}");
+    return rows;
+  }
+
+  if (fmt === "csv") return parseCsv(clean, { types });
+  throw new Error(`unknown format ${fmt} (use jsonl, json or csv)`);
+}
+
+function guessFormat(name, text) {
+  if (/\.jsonl$|\.ndjson$/i.test(name)) return "jsonl";
+  if (/\.json$/i.test(name)) return "json";
+  if (/\.csv$/i.test(name)) return "csv";
+  const t = text.trimStart();
+  if (t.startsWith("[") || t.startsWith("{\"rows\"")) return "json";
+  if (t.startsWith("{")) return "jsonl";
+  return "csv";
+}
+
+/** RFC 4180 CSV: quoted fields, "" escapes, commas and newlines inside quotes. */
+export function parseCsv(text, { types = false } = {}) {
+  const rows = [];
+  let row = [];
+  let field = "";
+  let quoted = false;
+
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (quoted) {
+      if (c === '"' && text[i + 1] === '"') {
+        field += '"';
+        i++;
+      } else if (c === '"') {
+        quoted = false;
+      } else {
+        field += c;
+      }
+    } else if (c === '"') {
+      quoted = true;
+    } else if (c === ",") {
+      row.push(field);
+      field = "";
+    } else if (c === "\n" || c === "\r") {
+      if (c === "\r" && text[i + 1] === "\n") i++;
+      row.push(field);
+      rows.push(row);
+      row = [];
+      field = "";
+    } else {
+      field += c;
+    }
+  }
+  if (field !== "" || row.length) {
+    row.push(field);
+    rows.push(row);
+  }
+
+  const [header, ...body] = rows.filter((r) => !(r.length === 1 && r[0] === ""));
+  if (!header) return [];
+  return body.map((r) => Object.fromEntries(header.map((h, i) => [h.trim(), cast(r[i] ?? "", types)])));
+}
+
+function cast(v, types) {
+  if (!types) return v;
+  if (v === "") return null;
+  if (v === "true" || v === "false") return v === "true";
+  if (/^-?(0|[1-9]\d*)(\.\d+)?$/.test(v)) return Number(v);
+  return v;
+}
+
+/**
+ * Records to Sync API rows. The row id comes from `idField` (default `id`), so
+ * sending the same record again updates it instead of adding a copy. A record
+ * that already has a `document` is passed through as a full row. Records with
+ * no id are reported, unless `newIds` lets the server make them up (then a
+ * re-send adds copies, which is why it is opt-in).
+ */
+export function toRows(records, { idField = "id", newIds = false } = {}) {
+  const rows = [];
+  const missing = [];
+
+  records.forEach((rec, i) => {
+    if (rec === null || typeof rec !== "object" || Array.isArray(rec)) {
+      missing.push({ index: i, error: "not an object" });
+      return;
+    }
+    const raw = rec[idField];
+    const id = raw === undefined || raw === null || raw === "" ? null : String(raw);
+    if (!id && !newIds) {
+      missing.push({ index: i, error: `no ${idField}` });
+      return;
+    }
+    if (rec.document && typeof rec.document === "object") {
+      rows.push(id ? { ...rec, id } : rec);
+    } else {
+      const { [idField]: _drop, ...fields } = rec;
+      rows.push(id ? { id, ...(idField === "id" ? fields : { ...fields, [idField]: raw }) } : fields);
+    }
+  });
+
+  return { rows, missing };
+}
+
+export function chunk(list, size = BULK_MAX) {
+  const out = [];
+  for (let i = 0; i < list.length; i += size) out.push(list.slice(i, i + size));
+  return out;
+}
+
+// ── which schema ─────────────────────────────────────────────────────────
+
+/**
+ * The schema a write goes to: `--env` if given, else the project's linked env
+ * (default dev). Writing to `prod` without `--env prod` on the command line is
+ * refused, so a project linked to prod can't push there by accident.
+ */
+export function targetEnv(flags, cfg) {
+  const env = flags.env || cfg.env || "dev";
+  if (!["dev", "prod"].includes(env)) throw new Error(`--env must be dev or prod (got ${env})`);
+  if (env === "prod" && flags.env !== "prod") {
+    throw new Error("this project is linked to prod. Rows written there sync to live apps at once: pass --env prod to confirm.");
+  }
+  return env;
+}
+
+// ── reads ────────────────────────────────────────────────────────────────
+
+export async function listModels(cfg) {
+  const { body } = await syncRequest("GET", "/manifest", cfg);
+  return body;
+}
+
+export async function routes(cfg) {
+  const { body } = await syncRequest("GET", "/_routes", cfg);
+  return body;
+}
+
+export async function listRows(cfg, table, { since, limit, includeDeleted, order } = {}) {
+  const { body } = await syncRequest("GET", `/${encodeURIComponent(table)}`, cfg, {
+    query: { since, limit, include_deleted: includeDeleted ? "true" : undefined, order },
+  });
+  return body;
+}
+
+export async function getRow(cfg, table, id) {
+  const { body } = await syncRequest("GET", `/${encodeURIComponent(table)}/${encodeURIComponent(id)}`, cfg);
+  return body;
+}
+
+/**
+ * Follow a table's live stream (`GET /:table/stream`, server-sent events):
+ * rows after `since` first, then each write as it happens. Calls `onEvent(name,
+ * data)` until `signal` aborts.
+ */
+export async function watchRows(cfg, table, { since = 0, onEvent, signal, fetchImpl = fetch }) {
+  const url = new URL(`${cfg.serverUrl.replace(/\/$/, "")}/api/sync/v1/${encodeURIComponent(table)}/stream`);
+  url.searchParams.set("since", String(since));
+  if (cfg.env) url.searchParams.set("env", cfg.env);
+
+  const res = await fetchImpl(url, { headers: { Authorization: `Bearer ${cfg.token}`, Accept: "text/event-stream" }, signal });
+  if (!res.ok) throw new ApiError(`HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`, res.status, null);
+
+  const decoder = new TextDecoder();
+  let buf = "";
+  for await (const part of res.body) {
+    buf += decoder.decode(part, { stream: true });
+    let cut;
+    while ((cut = buf.indexOf("\n\n")) >= 0) {
+      const block = buf.slice(0, cut);
+      buf = buf.slice(cut + 2);
+      let event = "message";
+      let data = "";
+      for (const line of block.split("\n")) {
+        if (line.startsWith("event:")) event = line.slice(6).trim();
+        else if (line.startsWith("data:")) data += line.slice(5).trim();
+      }
+      if (!data) continue;
+      let parsed = data;
+      try {
+        parsed = JSON.parse(data);
+      } catch {
+        /* keep text */
+      }
+      onEvent(event, parsed);
+    }
+  }
+}
+
+// ── writes ───────────────────────────────────────────────────────────────
+
+/**
+ * Upsert rows in batches of up to 1,000. Bulk upserts by id are safe to repeat,
+ * so a batch that hits a network error or a 5xx is retried, and a 429 waits
+ * until the rate-limit window resets. Rows the server rejects are collected,
+ * not fatal. Returns `{written, failed: [{id, error}], batches}`.
+ *
+ * `onBatch({done, total})` reports progress. `sleep` and `fetchImpl` are for
+ * tests.
+ */
+export async function pushRows(cfg, table, rows, { onBatch, sleep = defaultSleep, fetchImpl = fetch, maxRetries = 4 } = {}) {
+  const batches = chunk(rows);
+  let written = 0;
+  const failed = [];
+
+  for (let b = 0; b < batches.length; b++) {
+    const operations = batches[b].map((row) => ({ op: "upsert", row }));
+    const res = await withRetry(
+      () => syncRequest("POST", `/${encodeURIComponent(table)}/bulk`, cfg, { body: { operations }, fetchImpl }),
+      { sleep, maxRetries },
+    );
+
+    for (const r of res.body?.results || []) {
+      if (r.ok) written++;
+      else failed.push({ id: r.id, error: r.error || "rejected" });
+    }
+
+    onBatch?.({ done: Math.min((b + 1) * BULK_MAX, rows.length), total: rows.length });
+
+    // Out of budget for this window: wait for it instead of earning a 429.
+    if (res.headers?.get?.("x-ratelimit-remaining") === "0" && b < batches.length - 1) {
+      await sleep(resetDelayMs(res.headers));
+    }
+  }
+
+  return { written, failed, batches: batches.length };
+}
+
+/** Soft-delete rows by id through `bulk`, with the same batching and retries. */
+export async function deleteRows(cfg, table, ids, { sleep = defaultSleep, fetchImpl = fetch, maxRetries = 4 } = {}) {
+  let deleted = 0;
+  const failed = [];
+  for (const batch of chunk(ids)) {
+    const operations = batch.map((id) => ({ op: "delete", id: String(id) }));
+    const res = await withRetry(
+      () => syncRequest("POST", `/${encodeURIComponent(table)}/bulk`, cfg, { body: { operations }, fetchImpl }),
+      { sleep, maxRetries },
+    );
+    for (const r of res.body?.results || []) {
+      if (r.ok) deleted++;
+      else failed.push({ id: r.id, error: r.error || "rejected" });
+    }
+  }
+  return { deleted, failed };
+}
+
+export async function deleteRow(cfg, table, id) {
+  const { body } = await syncRequest("DELETE", `/${encodeURIComponent(table)}/${encodeURIComponent(id)}`, cfg);
+  return body;
+}
+
+async function withRetry(fn, { sleep, maxRetries }) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await fn();
+    } catch (e) {
+      const retryable = e instanceof ApiError && (e.status === 0 || e.status === 429 || e.status >= 500);
+      if (!retryable || attempt >= maxRetries) throw e;
+      await sleep(e.status === 429 ? resetDelayMs(e.headers) : 1000 * 2 ** attempt);
+    }
+  }
+}
+
+// `x-ratelimit-reset` is the window's end in Unix seconds. Wait until then, at
+// least a second and at most a minute (the window is 60 seconds).
+export function resetDelayMs(headers, now = Date.now()) {
+  const reset = Number(headers?.get?.("x-ratelimit-reset"));
+  if (!Number.isFinite(reset) || reset <= 0) return 5000;
+  return Math.min(60_000, Math.max(1000, reset * 1000 - now));
+}
+
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// ── the write token ──────────────────────────────────────────────────────
+
+/**
+ * A sync token that can write `tables`, made as the signed-in person.
+ *
+ * Saved per workspace with the tables it covers. When a write needs a table it
+ * doesn't cover, a new token is made for the old tables plus the new one and
+ * the old token is revoked, so there is one write token per workspace, limited
+ * to the tables this machine has written. It expires after 30 days.
+ *
+ * `channel` is a connected OaloChannel on the CLI token. `log` reports what was
+ * created, since making a credential should never be silent.
+ */
+export async function writeTokenFor(serverUrl, tables, channel, { log = () => {}, now = Date.now() } = {}) {
+  const saved = readEntry(serverUrl)?.sync_write;
+  const covered = new Set(saved?.tables || []);
+  const live = saved?.token && (!saved.expires_at || Date.parse(saved.expires_at) > now + 60_000);
+  if (live && tables.every((t) => covered.has(t))) return saved.token;
+
+  const all = [...new Set([...(live ? covered : []), ...tables])].sort();
+  const expires_at = new Date(now + WRITE_TOKEN_DAYS * 86_400_000).toISOString();
+  const minted = await channel.call("sync_api:create_token", {
+    name: `${hostname()} CLI writes`,
+    scopes: all.map((t) => `write:${t}`),
+    expires_at,
+  });
+  if (!minted?.token) throw new Error("the workspace did not return a token");
+
+  writeToken({ serverUrl, appId: null }, minted.token, "sync_write", { id: minted.id, tables: all, expires_at });
+  log(`made a write token for ${all.join(", ")} (expires ${expires_at.slice(0, 10)}). See it with \`oalo tokens list\`.`);
+
+  if (saved?.id && saved.id !== minted.id) {
+    try {
+      await channel.call("sync_api:revoke_token", { id: saved.id });
+    } catch {
+      /* already gone; nothing to do */
+    }
+  }
+  return minted.token;
+}
+
+// ── models (over the CLI token) ──────────────────────────────────────────
+
+/**
+ * `--field name:type` flags to the Data API's field list. Types: string, text,
+ * integer, float, boolean, datetime, date, json, list, references:<table>.
+ * A bare name is a string.
+ */
+export function parseFields(specs) {
+  const list = (Array.isArray(specs) ? specs : [specs]).filter((s) => typeof s === "string" && s);
+  return list.flatMap((s) => s.split(",")).map((s) => {
+    const [name, ...rest] = s.trim().split(":");
+    return { name, type: rest.length ? rest.join(":") : "string" };
+  });
+}
+
+export async function createModel(channel, { name, fields, ownedBy, shared }) {
+  const params = { name, fields };
+  if (ownedBy) {
+    params.owner_field = ownedBy;
+    params.shared = false;
+  } else if (shared !== undefined) {
+    params.shared = shared;
+  }
+  return channel.call("data:create_model", params);
+}
+
+export const promoteModel = (channel, table) => channel.call("data:promote_model", { table });