lua-cli 3.41.0 → 3.42.0-beta.2

package/scripts/generate-catalog.ts

@@ -0,0 +1,94 @@
+/**
+ * U34 (LUA-1008) — generate the machine-readable platform catalogue (`catalog.json`) for a lua-cli release,
+ * and optionally diff it against the previous release's catalogue.
+ *
+ * Run from the repo root after `pnpm run build:shared` (an unbuilt shared dist fails the run on purpose —
+ * otherwise every imported SDK type would read as `any`):
+ *
+ *   node_modules/.bin/tsx packages/lua-cli/scripts/generate-catalog.ts \
+ *     --out packages/lua-cli/temp/catalog/catalog.json \
+ *     [--previous <previous catalog.json>] \
+ *     [--diff-out packages/lua-cli/temp/catalog/catalog-diff.json] \
+ *     [--summary <markdown file to append the diff to, e.g. $GITHUB_STEP_SUMMARY>]
+ *
+ * `--previous` pointing at a missing file is not an error: the diff then lists everything as added.
+ * The logic lives in `generate-catalog.lib.ts` (fixture-tested); this file only wires argv and files.
+ */
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { WAVE2_FLAGS, WAVE2_REUSED_FLAGS } from '@lua/shared-types';
+import type { PlatformCatalog } from '@lua/shared-types';
+import {
+  CatalogError,
+  diffCatalogs,
+  generateCatalog,
+  renderDiffMarkdown,
+  serializeCatalog,
+  type CatalogStatusManifest,
+} from './generate-catalog.lib.js';
+
+function parseArgs(argv: string[]): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) throw new CatalogError(`unexpected argument '${arg}'`);
+    const value = argv[i + 1];
+    if (value === undefined || value.startsWith('--')) throw new CatalogError(`${arg} needs a value`);
+    out[arg.slice(2)] = value;
+    i++;
+  }
+  return out;
+}
+
+function writeFile(file: string, content: string): void {
+  fs.mkdirSync(path.dirname(path.resolve(file)), { recursive: true });
+  fs.writeFileSync(file, content);
+}
+
+function main(): void {
+  const args = parseArgs(process.argv.slice(2));
+  const packageDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const pkg = JSON.parse(fs.readFileSync(path.join(packageDir, 'package.json'), 'utf8')) as { version: string };
+  const manifest = JSON.parse(
+    fs.readFileSync(path.join(packageDir, 'catalog-status.json'), 'utf8')
+  ) as CatalogStatusManifest;
+
+  const { catalog, warnings } = generateCatalog({
+    packageDir,
+    manifest,
+    knownFlags: [...Object.keys(WAVE2_FLAGS), ...WAVE2_REUSED_FLAGS],
+    cliVersion: pkg.version,
+    now: new Date(),
+  });
+  for (const w of warnings) console.warn(`warning: ${w}`);
+
+  const out = args.out ?? path.join(packageDir, 'temp', 'catalog', 'catalog.json');
+  writeFile(out, serializeCatalog(catalog));
+  console.log(
+    `catalog.json v${catalog.cliVersion}: ${catalog.sdk.length} SDK exports, ${catalog.commands.length} commands, ` +
+      `${catalog.primitives.length} primitives, ${catalog.limits.length} limits, ${catalog.features.length} features → ${out}`
+  );
+
+  if (args.previous !== undefined || args['diff-out'] !== undefined || args.summary !== undefined) {
+    const previous =
+      args.previous && fs.existsSync(args.previous)
+        ? (JSON.parse(fs.readFileSync(args.previous, 'utf8')) as PlatformCatalog)
+        : null;
+    if (!previous) console.log('no previous catalogue: every entry counts as added');
+    const diff = diffCatalogs(previous, catalog);
+    if (args['diff-out']) writeFile(args['diff-out'], serializeCatalog(diff));
+    const markdown = renderDiffMarkdown(diff);
+    if (args.summary) fs.appendFileSync(args.summary, markdown);
+    console.log(
+      `diff vs ${diff.fromVersion || '(none)'}: +${diff.added.length} -${diff.removed.length} ~${diff.changed.length}`
+    );
+  }
+}
+
+try {
+  main();
+} catch (err) {
+  console.error(err instanceof CatalogError ? `generate-catalog: ${err.message}` : err);
+  process.exit(1);
+}

package/template/package.json

@@ -20,7 +20,7 @@
     "inquirer": "^12.9.6",
     "stripe": "^17.5.0",
     "js-yaml": "^4.1.0",
-    "lua-cli": "^3.41.0",
+    "lua-cli": "^3.42.0-beta.2",
     "openai": "^5.23.0",
     "uuid": "^13.0.0",
     "zod": "^3.24.1"

package/template/tsconfig.json

@@ -14,5 +14,5 @@
       "@/services/*": ["src/services/*"]
     }
   },
-  "exclude": ["dist", "dist-v2", "node_modules"]
+  "exclude": ["dist", "dist-v2", "node_modules", "src/apps/*/web"]
 }

package/template-web-app/app.ts

@@ -0,0 +1,29 @@
+import { defineWebApp, route } from 'lua-cli';
+import { z } from 'zod';
+
+/**
+ * __APP_NAME__ — a Lua web app.
+ *
+ * Pages: the Vite project in ./web (runs in the browser, inside Lua Workspace
+ * and the admin console). Routes: the handlers below (run in the Lua sandbox
+ * with the signed-in person as `auth`; Data, env() and fetch are available).
+ *
+ *   lua apps dev __APP_NAME__        pages with hot reload, routes run locally as you
+ *   lua test webapp --name __APP_NAME__ --route 'GET /hello'
+ *   lua push webapp --name __APP_NAME__
+ */
+export default defineWebApp({
+  name: '__APP_NAME__',
+  description: 'A Lua web app',
+  pages: {
+    root: './web',
+    nav: [{ path: '/', label: 'Overview' }],
+  },
+  routes: {
+    'GET /hello': route({
+      description: 'Greets the signed-in person',
+      responses: { 200: z.object({ message: z.string() }) },
+      handler: async ({ auth }) => ({ message: `Hello, ${auth.name ?? auth.email ?? auth.userId}` }),
+    }),
+  },
+});

package/template-web-app/web/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>__APP_NAME__</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template-web-app/web/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "__APP_NAME__-web",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "vite build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@base-ui/react": "~1.8.0",
+    "@lua-ai-global/ui": "~0.2.0",
+    "@phosphor-icons/react": "~2.1.10",
+    "react": "~19.3.0",
+    "react-dom": "~19.3.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "~4.3.3",
+    "@types/react": "~19.3.0",
+    "@types/react-dom": "~19.3.0",
+    "@vitejs/plugin-react": "~6.1.1",
+    "shadcn": "~3.8.5",
+    "tailwindcss": "~4.3.3",
+    "tw-animate-css": "~1.4.0",
+    "typescript": "~5.9.3",
+    "vite": "~8.3.1"
+  }
+}

package/template-web-app/web/src/App.tsx

@@ -0,0 +1,28 @@
+import { useEffect, useState } from 'react';
+import { Button } from '@lua-ai-global/ui/button';
+import { Card } from '@lua-ai-global/ui/card';
+import { lua } from './lua/client';
+
+export function App() {
+  const [message, setMessage] = useState<string>();
+  const [error, setError] = useState<string>();
+
+  const load = () => {
+    setError(undefined);
+    lua
+      .api<{ message: string }>('GET', '/hello')
+      .then((r) => setMessage(r.message))
+      .catch((e: Error) => setError(e.message));
+  };
+  useEffect(load, []);
+
+  return (
+    <main className="min-h-screen bg-background p-6 text-foreground">
+      <Card className="mx-auto max-w-md space-y-4 p-6">
+        <h1 className="text-lg font-semibold">{lua.appName}</h1>
+        <p className="text-muted-foreground">{error ?? message ?? 'Loading…'}</p>
+        <Button onClick={load}>Say hello again</Button>
+      </Card>
+    </main>
+  );
+}

package/template-web-app/web/src/index.css

@@ -0,0 +1,3 @@
+@import '@lua-ai-global/ui/styles.css';
+/* Tailwind scans the design system's compiled components for the classes they use. */
+@source '../node_modules/@lua-ai-global/ui/dist';

package/template-web-app/web/src/lua/client.ts

@@ -0,0 +1,264 @@
+/**
+ * Lua app client — the page side of a Lua web app.
+ *
+ * - Session: the shell opens this app in an iframe with a single-use handoff
+ *   code in the URL fragment (`#code=…`). The client exchanges it with lua-auth
+ *   for a Firebase custom token, signs in (identitytoolkit) and keeps the ID
+ *   token in memory only, refreshing it (securetoken) before it expires. No
+ *   cookie, no localStorage: a reload asks the shell for a new code.
+ * - Bridge (protocol v1): posts `lua:ready` once loaded, takes `lua:init`
+ *   (theme, density, locale, path) from the host, posts `lua:auth:expired`
+ *   when the session cannot be renewed so the shell re-issues a code. Messages
+ *   go only to, and are only accepted from, the shells the gateway lists in
+ *   the bootstrap (`hostOrigins`, the same list as the CSP's frame-ancestors).
+ * - `api(method, path, body?)`: calls a route of this app through the gateway
+ *   (`/_lua/api/<path>`) with the session. A 401 renews the token once and
+ *   retries; only a second 401 ends the session.
+ *
+ * Under `lua apps dev` the bootstrap says `dev: true`: there is no handoff and
+ * the dev server runs routes as the developer.
+ *
+ * Generated by `lua apps new`; yours to edit. (A packaged `@lua-ai-global/app-client`
+ * replaces this file later.)
+ */
+
+export interface LuaBootstrap {
+  v: 1;
+  app: { id: string; name: string; version: string; deployment: number; origin: string };
+  apiBase: string;
+  manifest: string;
+  auth: { origin: string; exchangePath: string; audience: string; firebaseApiKey?: string };
+  embedded: boolean;
+  /** The shells allowed to frame this app; the bridge talks to these only. */
+  hostOrigins?: string[];
+  theme: 'light' | 'dark';
+  density: 'compact' | 'comfortable';
+  preview: boolean;
+  /** Set by `lua apps dev` only. */
+  dev?: boolean;
+}
+
+export interface LuaInit {
+  v: 1;
+  theme?: 'light' | 'dark';
+  density?: 'compact' | 'comfortable';
+  locale?: string;
+  path?: string;
+}
+
+declare global {
+  interface Window {
+    __LUA__?: LuaBootstrap;
+  }
+}
+
+const BRIDGE_VERSION = 1;
+const IDENTITY = 'https://identitytoolkit.googleapis.com/v1/accounts:signInWithCustomToken';
+const SECURE_TOKEN = 'https://securetoken.googleapis.com/v1/token';
+/** Renew this long before the ID token expires. */
+const REFRESH_MARGIN_MS = 5 * 60_000;
+
+export class LuaApiError extends Error {
+  constructor(
+    readonly status: number,
+    readonly code: string | undefined,
+    message: string,
+    readonly executionId?: string
+  ) {
+    super(message);
+    this.name = 'LuaApiError';
+  }
+}
+
+interface Tokens {
+  idToken: string;
+  refreshToken: string;
+  expiresInS: number;
+}
+
+const nonEmpty = (v: unknown): v is string => typeof v === 'string' && v.length > 0;
+
+/** A token response is only a session when every field is there; anything else is "no session". */
+function tokensFrom(idToken: unknown, refreshToken: unknown, expiresIn: unknown): Tokens | null {
+  const expiresInS = Number(expiresIn);
+  if (!nonEmpty(idToken) || !nonEmpty(refreshToken) || !Number.isFinite(expiresInS) || expiresInS <= 0) return null;
+  return { idToken, refreshToken, expiresInS };
+}
+
+async function jsonOrNull(response: Response | undefined): Promise<Record<string, unknown> | null> {
+  if (!response?.ok) return null;
+  try {
+    const body = await response.json();
+    return body && typeof body === 'object' ? (body as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+class LuaAppClient {
+  private readonly boot: LuaBootstrap | undefined = window.__LUA__;
+  private idToken: string | undefined;
+  private refreshToken: string | undefined;
+  private refreshTimer: ReturnType<typeof setTimeout> | undefined;
+  private renewing: Promise<boolean> | undefined;
+  private session: Promise<void> | undefined;
+  private readonly initListeners: Array<(init: LuaInit) => void> = [];
+
+  get appName(): string {
+    return this.boot?.app.name ?? document.title;
+  }
+
+  get theme(): 'light' | 'dark' {
+    return this.boot?.theme ?? 'dark';
+  }
+
+  onInit(listener: (init: LuaInit) => void): void {
+    this.initListeners.push(listener);
+  }
+
+  /** Take the handoff code, open the session, tell the host we are ready. */
+  start(): Promise<void> {
+    if (!this.session) {
+      window.addEventListener('message', (event) => {
+        // Only the shell that framed us, from an origin the gateway allows, speaks the bridge.
+        if (event.source !== window.parent || !this.hostOrigins().includes(event.origin)) return;
+        if (event.data?.type !== 'lua:init') return;
+        for (const listener of this.initListeners) listener(event.data as LuaInit);
+      });
+      this.session = this.openSession().finally(() => this.post({ type: 'lua:ready', v: BRIDGE_VERSION }));
+    }
+    return this.session;
+  }
+
+  async api<T>(method: string, path: string, body?: unknown): Promise<T> {
+    await this.start();
+    let response = await this.send(method, path, body);
+    // A 401 usually means the ID token lapsed between refreshes: renew once and retry once.
+    if (response.status === 401 && (await this.renew())) response = await this.send(method, path, body);
+    if (response.status === 401) this.expired();
+    const text = await response.text();
+    let data: any;
+    try {
+      data = text ? JSON.parse(text) : undefined;
+    } catch {
+      data = text;
+    }
+    if (!response.ok) {
+      throw new LuaApiError(
+        response.status,
+        data?.code,
+        data?.message ?? response.statusText,
+        response.headers.get('x-lua-execution-id') ?? undefined
+      );
+    }
+    return data as T;
+  }
+
+  private send(method: string, path: string, body?: unknown): Promise<Response> {
+    const base = this.boot?.apiBase ?? '/_lua/api';
+    const headers: Record<string, string> = { accept: 'application/json' };
+    if (this.idToken) headers.authorization = `Bearer ${this.idToken}`;
+    if (body !== undefined) headers['content-type'] = 'application/json';
+    return fetch(`${base}${path.startsWith('/') ? path : `/${path}`}`, {
+      method,
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+  }
+
+  private async openSession(): Promise<void> {
+    const boot = this.boot;
+    if (!boot || boot.dev) return; // `lua apps dev`: the dev server is the caller's session.
+    const code = new URLSearchParams(location.hash.slice(1)).get('code');
+    // The code is single-use: drop it from the URL before anything can copy it.
+    if (code) history.replaceState(null, '', location.pathname + location.search);
+    if (!code || !boot.auth.firebaseApiKey) return this.expired();
+
+    const exchanged = await jsonOrNull(
+      await fetch(`${boot.auth.origin}${boot.auth.exchangePath}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ code, audience: boot.auth.audience }),
+      }).catch(() => undefined)
+    );
+    if (!nonEmpty(exchanged?.token)) return this.expired();
+
+    const signedIn = await jsonOrNull(
+      await fetch(`${IDENTITY}?key=${encodeURIComponent(boot.auth.firebaseApiKey)}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ token: exchanged!.token, returnSecureToken: true }),
+      }).catch(() => undefined)
+    );
+    const tokens = signedIn && tokensFrom(signedIn.idToken, signedIn.refreshToken, signedIn.expiresIn);
+    if (!tokens) return this.expired();
+    this.keep(tokens);
+  }
+
+  private keep(tokens: Tokens): void {
+    this.idToken = tokens.idToken;
+    this.refreshToken = tokens.refreshToken;
+    clearTimeout(this.refreshTimer);
+    this.refreshTimer = setTimeout(
+      () => void this.renew().then((ok) => ok || this.expired()),
+      Math.max(tokens.expiresInS * 1000 - REFRESH_MARGIN_MS, 30_000)
+    );
+  }
+
+  /** Swap the refresh token for a new ID token. One renewal at a time; `false` when it cannot be done. */
+  private renew(): Promise<boolean> {
+    if (!this.renewing) {
+      this.renewing = this.refreshOnce().finally(() => (this.renewing = undefined));
+    }
+    return this.renewing;
+  }
+
+  private async refreshOnce(): Promise<boolean> {
+    const key = this.boot?.auth.firebaseApiKey;
+    if (!key || !this.refreshToken) return false;
+    const r = await jsonOrNull(
+      await fetch(`${SECURE_TOKEN}?key=${encodeURIComponent(key)}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({ grant_type: 'refresh_token', refresh_token: this.refreshToken }),
+      }).catch(() => undefined)
+    );
+    const tokens = r && tokensFrom(r.id_token, r.refresh_token, r.expires_in);
+    if (!tokens) return false;
+    this.keep(tokens);
+    return true;
+  }
+
+  /** The session is gone: the shell answers with a fresh handoff code. */
+  private expired(): void {
+    this.idToken = undefined;
+    this.refreshToken = undefined;
+    clearTimeout(this.refreshTimer);
+    this.post({ type: 'lua:auth:expired', v: BRIDGE_VERSION });
+  }
+
+  private hostOrigins(): string[] {
+    return this.boot?.hostOrigins ?? [];
+  }
+
+  /**
+   * One post per allowed shell origin: the browser delivers it only when the
+   * framing window really has that origin, so no other page ever receives it.
+   * A browser refuses some shell origins as a target outright (a web browser
+   * throws on the desktop app's `tauri://localhost`), so each post stands
+   * alone: one origin this browser cannot address must not stop the others,
+   * or fail the session that posts `lua:ready` when it opens.
+   */
+  private post(message: { type: string; v: number }): void {
+    if (window.parent === window) return;
+    for (const origin of this.hostOrigins()) {
+      try {
+        window.parent.postMessage(message, origin);
+      } catch {
+        // Not addressable from this browser; the shell that framed us has one of the others.
+      }
+    }
+  }
+}
+
+export const lua = new LuaAppClient();

package/template-web-app/web/src/main.tsx

@@ -0,0 +1,16 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { App } from './App';
+import { lua } from './lua/client';
+import './index.css';
+
+// Theme follows the shell: first from the bootstrap, then from the host's `init`.
+document.documentElement.classList.toggle('dark', lua.theme === 'dark');
+lua.onInit((init) => document.documentElement.classList.toggle('dark', init.theme === 'dark'));
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>
+);
+void lua.start();

package/template-web-app/web/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "isolatedModules": true
+  },
+  "include": ["src"]
+}

package/template-web-app/web/vite.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+// `lua push webapp` builds with this config and pins only what the Lua gateway
+// needs on top of it (base '/', assets under assets/, the CSP nonce).
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+});