@makoai/app-sdk 2.4.0 → 2.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +30 -6
  2. package/index.js +15 -0
  3. package/package.json +1 -1
  4. package/vite.d.ts +29 -3
  5. package/vite.js +197 -30
package/README.md CHANGED
@@ -96,14 +96,38 @@ export default defineConfig({ plugins: [react(), makoData()] });
96
96
  ```
97
97
 
98
98
  `makoData()` answers `__data/index.json` (the app's `bindings/*.sql`) and
99
- `__data/<name>.parquet` during `vite dev` by streaming each binding's
100
- materialized artifact from the Mako API — a binding that was never
101
- materialized is built on first request, and `POST __data/<name>/refresh`
102
- (the SDK's `refresh()`) rebuilds one on demand. Results are cached under
103
- `node_modules/.mako-data/` for five minutes (`?refresh` bypasses; a stale
104
- copy is served if the API is unreachable). It is `apply: "serve"` only —
99
+ `__data/<name>.parquet` during `vite dev` from the Mako API, and what it asks
100
+ for is **your local binding file**: it sends the text of
101
+ `bindings/<name>.sql` and gets back the parquet of exactly that query, run
102
+ read-only through the workspace connection its front matter names. When the
103
+ text is the committed binding, that is the app's stored artifact (built on
104
+ first request if it never was); when you have edited it, Mako builds a draft
105
+ from your text and hands it back without storing it — nobody else, and no
106
+ published viewer, ever sees uncommitted SQL. Building needs edit access to the
107
+ app; read-only members get committed artifacts. `POST __data/<name>/refresh`
108
+ (the SDK's `refresh()`) rebuilds from the local text on demand.
109
+
110
+ Results are cached under `node_modules/.mako-data/` for five minutes
111
+ (`revalidateMs`; `?refresh` bypasses), next to a fingerprint of the text they
112
+ were built from: after an edit the cache is never served, however long
113
+ `revalidateMs` is, and while the API is unreachable a stale copy is served
114
+ only if it was built from the same text. It is `apply: "serve"` only —
105
115
  production builds never load it.
106
116
 
117
+ ### dbt models you are still building
118
+
119
+ A binding linked to dbt (`-- dbt_project: <id>`) writes `{{ dbt_schema }}`,
120
+ which renders to the production schema. To preview models you built into
121
+ your own dbt environment, point the dev server at it:
122
+
123
+ ```ts
124
+ makoData({ dbtEnvironment: "joan" }) // or MAKO_DBT_ENV=joan in the repo's .env
125
+ ```
126
+
127
+ The environment must exist in the linked dbt project (`dbt/environments.yml`),
128
+ and a personal environment (`owner_user_id`) renders only for its owner.
129
+ These builds are drafts too: never stored, never what a published app reads.
130
+
107
131
  It also answers `__data/viewer.json` (you, as Mako sees you), and
108
132
  `MAKO_VIEWER_AS=<email>` — in the environment or the repo's `.env` —
109
133
  previews the app as that member instead (editors of the app only).
package/index.js CHANGED
@@ -451,6 +451,21 @@ export function navigate(to, opts) {
451
451
  window.history.pushState(null, "", url);
452
452
  }
453
453
  emitLocation();
454
+ // Inside Mako's shell the app is a sandboxed iframe with an opaque origin,
455
+ // so the line above moved a URL nobody can see or copy. Tell the host,
456
+ // which projects the query onto its own address bar (/apps/<slug>?...)
457
+ // and seeds it back into the iframe when that link is opened. Only the
458
+ // query travels: the frame's pathname is the preview token, not the app's.
459
+ if (window.parent !== window) {
460
+ try {
461
+ window.parent.postMessage(
462
+ { type: "mako-app:navigate", search: url.search },
463
+ "*",
464
+ );
465
+ } catch {
466
+ // A host that is not Mako, or a frame that forbids it: nothing to tell.
467
+ }
468
+ }
454
469
  }
455
470
 
456
471
  export function useLocation() {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@makoai/app-sdk",
3
- "version": "2.4.0",
3
+ "version": "2.5.0",
4
4
  "description": "Mako app SDK: data bindings (useQuery/useDuckDB), URL state, theme.",
5
5
  "license": "MIT",
6
6
  "repository": {
package/vite.d.ts CHANGED
@@ -11,10 +11,25 @@ export interface MakoDataOptions {
11
11
  slug?: string;
12
12
  /** Repo root. Default: the nearest ancestor holding .mako/ or .git. */
13
13
  repoRoot?: string;
14
- /** Re-fetch a cached parquet after this long (ms). Default: 5 minutes. */
14
+ /**
15
+ * Re-fetch a cached parquet after this long (ms). Default: 5 minutes. A
16
+ * cache built from different binding text (or dbt environment) is never
17
+ * served, whatever this says — `Infinity` is safe while you edit SQL.
18
+ */
15
19
  revalidateMs?: number;
16
- /** Build a never-materialized binding on first request. Default: true. */
20
+ /**
21
+ * Build bindings through the API: the local `bindings/<name>.sql` text
22
+ * (uncommitted edits included), or the committed binding when it was never
23
+ * materialized. `false` serves committed artifacts only. Default: true.
24
+ */
17
25
  materialize?: boolean;
26
+ /**
27
+ * Render `{{ dbt_schema }}` in dbt-linked bindings against this dbt
28
+ * environment (e.g. your personal one, `dbt_<you>`) instead of production.
29
+ * Those builds are yours alone — never stored as the app's data. Default:
30
+ * MAKO_DBT_ENV, else production.
31
+ */
32
+ dbtEnvironment?: string;
18
33
  /**
19
34
  * Preview the app as this member (an email): `__data/viewer.json` answers
20
35
  * as Mako would for them. Default: MAKO_VIEWER_AS, else yourself.
@@ -32,6 +47,8 @@ export interface MakoContext {
32
47
  cacheDir: string;
33
48
  /** Email of the member being previewed, or "" for yourself. */
34
49
  viewAs: string;
50
+ /** dbt environment for `{{ dbt_schema }}`, or "" for production. */
51
+ dbtEnvironment: string;
35
52
  }
36
53
 
37
54
  /** Resolve credentials and identity the way `makoData` does. */
@@ -40,9 +57,18 @@ export function resolveMakoContext(
40
57
  options?: MakoDataOptions,
41
58
  ): MakoContext;
42
59
 
60
+ /**
61
+ * What a cached parquet was built from: a hash of the binding file's text and
62
+ * the dbt environment. The plugin serves a cache entry only for a match.
63
+ */
64
+ /** CRLF/CR → LF and no trailing whitespace — what bindingFingerprint hashes. */
65
+ export function normalizeBindingSource(source: string): string;
66
+
67
+ export function bindingFingerprint(source: string, dbtEnvironment?: string): string;
68
+
43
69
  /**
44
70
  * Serve the app's data bindings (`__data/index.json`, `__data/<name>.parquet`)
45
- * during a local `vite dev` by streaming materialized artifacts from Mako.
71
+ * during a local `vite dev`, built by Mako from the local binding files.
46
72
  */
47
73
  export function makoData(options?: MakoDataOptions): Plugin;
48
74
  export default makoData;
package/vite.js CHANGED
@@ -4,12 +4,20 @@
4
4
  // `__data/<name>.parquet` itself. On a laptop nothing does, so Vite's SPA
5
5
  // fallback returns index.html and DuckDB fails with "footer != PAR1". This
6
6
  // plugin is the laptop's answer: it lists the app's bindings/*.sql as
7
- // __data/index.json and streams each binding's materialized parquet from the
8
- // Mako API, authenticated with the workspace API key in the repo's .env.
7
+ // __data/index.json and serves each binding's parquet from the Mako API,
8
+ // authenticated with `mako login` or the workspace API key in the repo's .env.
9
+ //
10
+ // The LOCAL binding file is what gets built: its text goes to the API, which
11
+ // answers with the committed artifact when the text is the committed binding
12
+ // and with a throwaway draft build when it is not — so editing
13
+ // bindings/<name>.sql shows real data before anything is committed. The local
14
+ // cache is keyed by that text, so an edit never serves a parquet built from
15
+ // the old query.
9
16
  //
10
17
  // Plain ESM, Node built-ins only — like the rest of this package.
11
18
  import fs from "node:fs";
12
19
  import path from "node:path";
20
+ import { createHash } from "node:crypto";
13
21
  import { HOSTED_API_URL, findCredential, getAccessToken } from "./credentials.js";
14
22
 
15
23
  const BINDING_NAME = /^[A-Za-z0-9_][A-Za-z0-9_-]*$/;
@@ -85,14 +93,50 @@ export function resolveMakoContext(appDir, options = {}) {
85
93
  apiUrl,
86
94
  apiKey: options.apiKey ?? env("MAKO_API_KEY") ?? "",
87
95
  workspaceId: options.workspaceId ?? env("MAKO_WORKSPACE_ID") ?? ws.workspaceId ?? "",
88
- slug: options.slug ?? path.basename(path.resolve(appDir)),
96
+ // The manifest id is the app's identity (apps.md §29); the folder
97
+ // basename is only a fallback for apps that predate ids — and is
98
+ // ambiguous once apps nest.
99
+ slug: options.slug ?? readManifestId(appDir) ?? path.basename(path.resolve(appDir)),
89
100
  bindingsDir: path.join(appDir, "bindings"),
90
101
  cacheDir: path.join(appDir, "node_modules", ".mako-data"),
91
102
  /** Preview the app as this viewer (email) — see makoData(). */
92
103
  viewAs: options.viewAs ?? env("MAKO_VIEWER_AS") ?? "",
104
+ /** Render `{{ dbt_schema }}` against this dbt environment — see makoData(). */
105
+ dbtEnvironment: options.dbtEnvironment ?? env("MAKO_DBT_ENV") ?? "",
93
106
  };
94
107
  }
95
108
 
109
+ /** CRLF/CR → LF, no trailing whitespace at the end of the file. */
110
+ export function normalizeBindingSource(source) {
111
+ return source.replace(/\r\n?/g, "\n").trimEnd();
112
+ }
113
+
114
+ /**
115
+ * What a cached parquet was built from: the binding file's exact text plus
116
+ * the dbt environment it was rendered against. A cache entry is only ever
117
+ * served for the same fingerprint, whatever its age.
118
+ */
119
+ export function bindingFingerprint(source, dbtEnvironment = "") {
120
+ // Line endings and trailing whitespace are not the query: a Windows
121
+ // checkout (core.autocrlf) must not look like an edit. The API normalises
122
+ // the text it compares the same way.
123
+ return createHash("sha256")
124
+ .update(normalizeBindingSource(source))
125
+ .update("\0")
126
+ .update(dbtEnvironment)
127
+ .digest("hex")
128
+ .slice(0, 32);
129
+ }
130
+
131
+ function readManifestId(appDir) {
132
+ try {
133
+ const raw = JSON.parse(fs.readFileSync(path.join(appDir, "mako.json"), "utf8"));
134
+ return typeof raw.id === "string" && /^[0-9a-f]{24}$/i.test(raw.id) ? raw.id : null;
135
+ } catch {
136
+ return null;
137
+ }
138
+ }
139
+
96
140
  function listBindings(bindingsDir) {
97
141
  try {
98
142
  return fs
@@ -142,7 +186,8 @@ export function makoData(options = {}) {
142
186
  ` mako-data: ${bindings.length} binding(s) for apps/${ctx.slug}` +
143
187
  (problems.length
144
188
  ? ` — NOT CONNECTED: ${problems.join("; ")} (see CLAUDE.md → Credentials)`
145
- : ` via ${ctx.apiUrl} (${ctx.apiKey ? "API key" : "mako login"})`),
189
+ : ` via ${ctx.apiUrl} (${ctx.apiKey ? "API key" : "mako login"})` +
190
+ (ctx.dbtEnvironment ? `, dbt environment "${ctx.dbtEnvironment}"` : "")),
146
191
  );
147
192
 
148
193
  // fetch() with network failures translated into something a person can
@@ -192,24 +237,138 @@ export function makoData(options = {}) {
192
237
  return Buffer.from(await res.arrayBuffer());
193
238
  }
194
239
 
195
- // POST __data/<name>/refresh — the SDK's refresh(): rebuild the
196
- // binding through the API (the same call app_materialize makes), then
197
- // forget the local copy so the next read is the new artifact.
240
+ // The local binding file, or null when the app has none by that name
241
+ // (then the committed binding is all there is to serve).
242
+ function readSource(name) {
243
+ try {
244
+ return fs.readFileSync(path.join(ctx.bindingsDir, `${name}.sql`), "utf8");
245
+ } catch {
246
+ return null;
247
+ }
248
+ }
249
+
250
+ const cachePath = (name) => path.join(ctx.cacheDir, `${name}.parquet`);
251
+ const metaPath = (name) => path.join(ctx.cacheDir, `${name}.parquet.json`);
252
+
253
+ function cachedFingerprint(name) {
254
+ try {
255
+ return JSON.parse(fs.readFileSync(metaPath(name), "utf8")).fingerprint ?? null;
256
+ } catch {
257
+ return null;
258
+ }
259
+ }
260
+
261
+ function writeCache(name, buf, meta) {
262
+ fs.mkdirSync(ctx.cacheDir, { recursive: true });
263
+ fs.writeFileSync(cachePath(name), buf);
264
+ if (meta) fs.writeFileSync(metaPath(name), JSON.stringify(meta));
265
+ else fs.rmSync(metaPath(name), { force: true });
266
+ }
267
+
268
+ // An API that predates dev builds answers the route with its not-found
269
+ // handler (`{"success":false,"error":"Not Found"}`, or plain text from
270
+ // a proxy) — or, for a `mako login` token or scoped key, with the
271
+ // scoped-credential refusal, since the route is not on its allowlist
272
+ // yet. Remembered, so the rest of the session asks for the committed
273
+ // artifact directly (the behaviour before dev builds existed). Any
274
+ // other 404 (no such app) falls back for that request only, so the
275
+ // artifact route reports it.
276
+ let devBuildUnsupported = false;
277
+ const inflight = new Map();
278
+
279
+ // Build the LOCAL binding text through the API. Concurrent asks for the
280
+ // same text share one request (a page mounting several tables at once).
281
+ function devBuild(name, source, refresh) {
282
+ const fingerprint = bindingFingerprint(source, ctx.dbtEnvironment);
283
+ const key = `${name}:${fingerprint}:${refresh ? 1 : 0}`;
284
+ let pending = inflight.get(key);
285
+ if (pending) return pending;
286
+ pending = (async () => {
287
+ const res = await apiFetch(`${appBase()}/bindings/${encodeURIComponent(name)}/dev-build`, {
288
+ method: "POST",
289
+ headers: { ...(await headers()), "content-type": "application/json" },
290
+ body: JSON.stringify({
291
+ source,
292
+ ...(ctx.dbtEnvironment ? { dbtEnvironment: ctx.dbtEnvironment } : {}),
293
+ ...(refresh ? { refresh: true } : {}),
294
+ }),
295
+ });
296
+ if (!res.ok) {
297
+ const text = await res.text().catch(() => "");
298
+ let body = null;
299
+ try {
300
+ body = JSON.parse(text);
301
+ } catch {
302
+ // Not the API's JSON error envelope.
303
+ }
304
+ const predatesDevBuild =
305
+ (res.status === 404 && (!body || body.error === "Not Found")) ||
306
+ (res.status === 403 && /restricted to the (\/api\/mcp|Mako MCP) endpoint/.test(body?.error ?? ""));
307
+ if (predatesDevBuild || res.status === 404) {
308
+ if (!predatesDevBuild) return null;
309
+ devBuildUnsupported = true;
310
+ server.config.logger.warn?.(
311
+ ` mako-data: ${ctx.apiUrl} does not build local binding edits yet; serving committed bindings`,
312
+ );
313
+ return null;
314
+ }
315
+ const error = new Error(
316
+ res.status === 401
317
+ ? `the Mako API at ${ctx.apiUrl} refused the credential (HTTP 401) — ` +
318
+ (ctx.apiKey
319
+ ? "the MAKO_API_KEY in .env is invalid for this host/workspace"
320
+ : "run `npx @makoai/cli login` in this repo again")
321
+ : body?.error || `build ${name}: HTTP ${res.status}`,
322
+ );
323
+ error.status = res.status;
324
+ throw error;
325
+ }
326
+ const buf = Buffer.from(await res.arrayBuffer());
327
+ const meta = {
328
+ fingerprint,
329
+ dbtEnvironment: ctx.dbtEnvironment || null,
330
+ // A redirect to the stored artifact loses the API's headers; that
331
+ // answer is always the committed artifact.
332
+ build: res.headers.get("x-mako-build") ?? "artifact",
333
+ rowCount: Number(res.headers.get("x-mako-row-count") ?? "") || null,
334
+ builtAt: res.headers.get("x-mako-materialized-at") ?? new Date().toISOString(),
335
+ };
336
+ writeCache(name, buf, meta);
337
+ return { buf, meta };
338
+ })().finally(() => inflight.delete(key));
339
+ inflight.set(key, pending);
340
+ return pending;
341
+ }
342
+
343
+ // POST __data/<name>/refresh — the SDK's refresh(): rebuild the LOCAL
344
+ // binding through the API (the committed one is re-materialized and
345
+ // stored, an edited one is built as a draft), and cache what came back.
198
346
  async function refreshBinding(name, res) {
199
- const cached = path.join(ctx.cacheDir, `${name}.parquet`);
347
+ const source = options.materialize === false || devBuildUnsupported ? null : readSource(name);
200
348
  try {
201
- const built = await apiFetch(
349
+ const built = source === null ? null : await devBuild(name, source, true);
350
+ if (built) {
351
+ return json(res, 200, {
352
+ success: true,
353
+ binding: name,
354
+ materialization: "parquet",
355
+ rowCount: built.meta.rowCount ?? undefined,
356
+ byteSize: built.buf.length,
357
+ materializedAt: built.meta.builtAt,
358
+ });
359
+ }
360
+ const materialized = await apiFetch(
202
361
  `${appBase()}/bindings/${encodeURIComponent(name)}/materialize`,
203
362
  { method: "POST", headers: await headers() },
204
363
  );
205
- const body = await built.json().catch(() => ({}));
206
- if (!built.ok) {
207
- return json(res, built.status, {
364
+ const body = await materialized.json().catch(() => ({}));
365
+ if (!materialized.ok) {
366
+ return json(res, materialized.status, {
208
367
  success: false,
209
- error: body.error || `materialize ${name}: HTTP ${built.status}`,
368
+ error: body.error || `materialize ${name}: HTTP ${materialized.status}`,
210
369
  });
211
370
  }
212
- fs.rmSync(cached, { force: true });
371
+ fs.rmSync(cachePath(name), { force: true });
213
372
  json(res, 200, {
214
373
  success: true,
215
374
  binding: name,
@@ -221,7 +380,7 @@ export function makoData(options = {}) {
221
380
  } catch (error) {
222
381
  const message = error instanceof Error ? error.message : String(error);
223
382
  server.config.logger.error(` mako-data: ${message}`);
224
- json(res, 502, { success: false, error: message });
383
+ json(res, error?.status ?? 502, { success: false, error: message });
225
384
  }
226
385
  }
227
386
 
@@ -265,19 +424,30 @@ export function makoData(options = {}) {
265
424
  });
266
425
  }
267
426
  if (isRefresh) return refreshBinding(name, res);
268
- const cached = path.join(ctx.cacheDir, `${name}.parquet`);
427
+ const cached = cachePath(name);
269
428
  const refresh = /(^|&)refresh(=|&|$)/.test(query);
429
+ const source = options.materialize === false || devBuildUnsupported ? null : readSource(name);
430
+ // Null without a local file: the committed artifact, cached by age alone.
431
+ const fingerprint = source === null ? null : bindingFingerprint(source, ctx.dbtEnvironment);
432
+ // A cache built from other text (or another dbt environment) is not
433
+ // this binding's data, however fresh — serving it is how an edited
434
+ // query ended up read with the old query's columns.
435
+ const cacheMatches = () => fingerprint === null || cachedFingerprint(name) === fingerprint;
436
+ const serveCached = (how) => {
437
+ res.setHeader("content-type", "application/vnd.apache.parquet");
438
+ res.setHeader("x-mako-data", how);
439
+ return fs.createReadStream(cached).pipe(res);
440
+ };
270
441
  try {
271
442
  const stat = fs.statSync(cached, { throwIfNoEntry: false });
272
443
  const fresh = stat && Date.now() - stat.mtimeMs < revalidateMs;
273
- if (!refresh && fresh) {
274
- res.setHeader("content-type", "application/vnd.apache.parquet");
275
- res.setHeader("x-mako-data", "cache");
276
- return fs.createReadStream(cached).pipe(res);
444
+ if (!refresh && fresh && cacheMatches()) return serveCached("cache");
445
+ let buf = null;
446
+ if (source !== null) buf = (await devBuild(name, source, false))?.buf ?? null;
447
+ if (!buf) {
448
+ buf = await fetchArtifact(name);
449
+ writeCache(name, buf, null);
277
450
  }
278
- const buf = await fetchArtifact(name);
279
- fs.mkdirSync(ctx.cacheDir, { recursive: true });
280
- fs.writeFileSync(cached, buf);
281
451
  res.setHeader("content-type", "application/vnd.apache.parquet");
282
452
  res.setHeader("content-length", String(buf.length));
283
453
  res.setHeader("x-mako-data", "api");
@@ -285,13 +455,10 @@ export function makoData(options = {}) {
285
455
  } catch (error) {
286
456
  const message = error instanceof Error ? error.message : String(error);
287
457
  server.config.logger.error(` mako-data: ${message}`);
288
- if (fs.existsSync(cached)) {
289
- // Stale beats nothing while offline.
290
- res.setHeader("content-type", "application/vnd.apache.parquet");
291
- res.setHeader("x-mako-data", "stale");
292
- return fs.createReadStream(cached).pipe(res);
293
- }
294
- json(res, 502, { error: message });
458
+ // Stale beats nothing while offline — but only data built from THIS
459
+ // text; an old query's parquet is not a stale copy of a new one.
460
+ if (fs.existsSync(cached) && cacheMatches()) return serveCached("stale");
461
+ json(res, error?.status ?? 502, { error: message });
295
462
  }
296
463
  });
297
464
  },