@polardbx/pxbaas 0.0.0-stage → 0.1.0-beta.2

package/templates/webapp/manifest.json

@@ -0,0 +1,299 @@
+{
+  "version": 1,
+  "templates": [
+    {
+      "id": "spa",
+      "description": "Self-contained single-page webapp: inline HTML/CSS/JS + a built-in JSON API via ?action=. Best for shareable demos.",
+      "entrypoint": "index.ts"
+    },
+    {
+      "id": "api",
+      "description": "Headless JSON backend (Deno.serve) with ?action= routing and CORS. Best for webhooks / API-only demos.",
+      "entrypoint": "index.ts"
+    },
+    {
+      "id": "mpa",
+      "description": "Multi-page static webapp: real index.html/about.html/style.css/app.js served by path via the proxy static branch, plus a worker JSON API via ?action=. Best for traditional multi-page sites.",
+      "entrypoint": "index.ts",
+      "mode": "mpa",
+      "files": [
+        "index.ts",
+        "index.html",
+        "about.html",
+        "style.css",
+        "app.js"
+      ],
+      "pages": [
+        "index.html",
+        "about.html"
+      ],
+      "assets": [
+        "style.css",
+        "app.js"
+      ]
+    },
+    {
+      "id": "vanilla-static",
+      "description": "Minimal text-only static app for validating the /apps mount and release lifecycle.",
+      "entrypoint": "frontend/index.html",
+      "mode": "webapp",
+      "files": [
+        "frontend/index.html",
+        "frontend/style.css",
+        "frontend/app.js"
+      ],
+      "frontend": {
+        "root": "frontend/dist",
+        "routing": "files",
+        "index": "index.html",
+        "fallback": null
+      },
+      "backend": null
+    },
+    {
+      "id": "react-vite",
+      "description": "React + Vite static app with HashRouter, relative base, plain CSS, and exact dependency versions.",
+      "entrypoint": "frontend/src/App.tsx",
+      "mode": "webapp",
+      "files": [
+        "frontend/package.json",
+        "frontend/package-lock.json",
+        "frontend/index.html",
+        "frontend/tsconfig.json",
+        "frontend/vite.config.ts",
+        "frontend/src/main.tsx",
+        "frontend/src/App.tsx",
+        "frontend/src/style.css"
+      ],
+      "frontend": {
+        "root": "frontend/dist",
+        "routing": "files",
+        "index": "index.html",
+        "fallback": null
+      },
+      "backend": null
+    },
+    {
+      "id": "react-vite-hono",
+      "description": "React + Vite + HashRouter frontend with a Deno-served, platform-versioned Hono backend.",
+      "entrypoint": "backend/index.ts",
+      "mode": "webapp",
+      "files": [
+        "frontend/package.json",
+        "frontend/package-lock.json",
+        "frontend/index.html",
+        "frontend/tsconfig.json",
+        "frontend/vite.config.ts",
+        "frontend/src/main.tsx",
+        "frontend/src/App.tsx",
+        "frontend/src/style.css",
+        "backend/index.ts"
+      ],
+      "frontend": {
+        "root": "frontend/dist",
+        "routing": "files",
+        "index": "index.html",
+        "fallback": null
+      },
+      "backend": {
+        "entrypoint": "backend/index.ts",
+        "framework": "hono",
+        "pathMode": "strip-app-api-prefix",
+        "verifyJwt": false,
+        "secrets": [],
+        "egressPolicy": "deny"
+      }
+    },
+    {
+      "id": "ssr-hono",
+      "description": "SSR-shell webapp: Hono worker server-renders the page shell at /page (static-miss fallthrough, fallback=worker); browser hydrates and fetches data client-side. Single-file self-contained worker per D16.",
+      "entrypoint": "backend/index.ts",
+      "mode": "webapp",
+      "files": [
+        "backend/index.ts",
+        "frontend/dist/index.html"
+      ],
+      "frontend": {
+        "root": "frontend/dist",
+        "routing": "files",
+        "index": "index.html",
+        "fallback": "worker"
+      },
+      "backend": {
+        "entrypoint": "backend/index.ts",
+        "framework": "hono",
+        "pathMode": "strip-app-api-prefix",
+        "verifyJwt": false,
+        "secrets": [],
+        "egressPolicy": "deny"
+      },
+      "ssrProbePath": "/page"
+    },
+    {
+      "id": "ssr-auth",
+      "description": "SSR webapp with proxy-injected session (方案 C): the worker server-renders authenticated pages from trusted X-App-User-* headers; it never reads cookies, never sets Set-Cookie, and never puts tokens in URLs. Requires capabilities.sessionMode=proxy-injected-header.",
+      "entrypoint": "backend/index.ts",
+      "mode": "webapp",
+      "files": [
+        "backend/index.ts",
+        "frontend/dist/index.html"
+      ],
+      "frontend": {
+        "root": "frontend/dist",
+        "routing": "files",
+        "index": "index.html",
+        "fallback": null
+      },
+      "backend": {
+        "entrypoint": "backend/index.ts",
+        "framework": "deno",
+        "pathMode": "strip-app-api-prefix",
+        "verifyJwt": false,
+        "secrets": [],
+        "egressPolicy": "deny",
+        "session": "proxy-injected"
+      }
+    },
+    {
+      "id": "ssr-blog",
+      "description": "Full-site SSR blog (zero npm deps) with proxy-injected session: the worker renders every page server-side from the instance internal base and reads identity ONLY from X-App-User-* headers. Requires capabilities.sessionMode=proxy-injected-header.",
+      "entrypoint": "backend/index.ts",
+      "mode": "webapp",
+      "files": [
+        "README.md",
+        "backend/index.ts",
+        "db/schema.sql",
+        "db/rls.json",
+        "frontend/dist/index.html"
+      ],
+      "frontend": {
+        "root": "frontend/dist",
+        "routing": "files",
+        "index": "index.html",
+        "fallback": "worker"
+      },
+      "backend": {
+        "entrypoint": "backend/index.ts",
+        "framework": "deno",
+        "pathMode": "strip-app-api-prefix",
+        "verifyJwt": false,
+        "secrets": [],
+        "egressPolicy": "deny",
+        "session": "proxy-injected"
+      },
+      "ssrProbePath": "/posts",
+      "nextSteps": [
+        "Initialize the database BEFORE deploy: run `pxbaas app db-init <name> --dir <appsDir>`. It reads db/schema.sql (DDL + seed) and db/rls.json (RLS registry), shows the full plan, and applies it only after you authorize (--dry-run to preview, --yes for non-interactive). Works in single-tenant (/pg/query) AND multi-tenant (/api/tenant-ddl with your per-tenant service_role key); the CLI never auto-runs DDL.",
+        "Requires capabilities.sessionMode=proxy-injected-header.",
+        "Data-plane base and anon key come from the platform-in SUPABASE_INTERNAL_URL / SUPABASE_ANON_KEY (edge-runtime MR #30497903); no plaintext key editing is needed."
+      ]
+    },
+    {
+      "id": "csr-bff",
+      "description": "Front/back separated CSR blog: real static pages served by path plus a same-origin Deno BFF worker that proxies /api/* to the instance internal REST/Auth. Identity comes from proxy-injected X-App-User-Token (client Authorization is stripped on /apps).",
+      "entrypoint": "backend/index.ts",
+      "mode": "webapp",
+      "files": [
+        "README.md",
+        "backend/index.ts",
+        "db/schema.sql",
+        "db/rls.json",
+        "frontend/dist/admin.html",
+        "frontend/dist/article.html",
+        "frontend/dist/blog.js",
+        "frontend/dist/blogger.html",
+        "frontend/dist/index.html",
+        "frontend/dist/login.html",
+        "frontend/dist/profile.html",
+        "frontend/dist/signup.html",
+        "frontend/dist/style.css"
+      ],
+      "frontend": {
+        "root": "frontend/dist",
+        "routing": "files",
+        "index": "index.html",
+        "fallback": null
+      },
+      "backend": {
+        "entrypoint": "backend/index.ts",
+        "framework": "deno",
+        "pathMode": "strip-app-api-prefix",
+        "verifyJwt": false,
+        "secrets": [],
+        "egressPolicy": "deny",
+        "session": "proxy-injected"
+      },
+      "nextSteps": [
+        "Initialize the database BEFORE deploy: run `pxbaas app db-init <name> --dir <appsDir>`. It reads db/schema.sql (DDL + seed) and db/rls.json (RLS registry), shows the full plan, and applies it only after you authorize (--dry-run to preview, --yes for non-interactive). Works in single-tenant (/pg/query) AND multi-tenant (/api/tenant-ddl with your per-tenant service_role key); the CLI never auto-runs DDL.",
+        "Requires capabilities.sessionMode=proxy-injected-header.",
+        "The BFF forwards to the platform-injected SUPABASE_INTERNAL_URL with SUPABASE_ANON_KEY (edge-runtime MR #30497903); no plaintext key editing is needed."
+      ]
+    },
+    {
+      "id": "ssr-shop",
+      "description": "React 18 + Hono SSR shop: catalog/detail/search are fully server-rendered from MySQL; cart/checkout/orders hydrate in the browser. Browser-side session (localStorage + Authorization direct to /rest,/auth); order gating enforced by RLS.",
+      "entrypoint": "backend/index.ts",
+      "mode": "webapp",
+      "files": [
+        "README.md",
+        "backend/index.ts",
+        "db/schema.sql",
+        "db/rls.json",
+        "frontend/dist/index.html"
+      ],
+      "frontend": {
+        "root": "frontend/dist",
+        "routing": "files",
+        "index": "index.html",
+        "fallback": "worker"
+      },
+      "backend": {
+        "entrypoint": "backend/index.ts",
+        "framework": "hono",
+        "pathMode": "strip-app-api-prefix",
+        "verifyJwt": false,
+        "secrets": [],
+        "egressPolicy": "deny",
+        "session": "browser-side"
+      },
+      "ssrProbePath": "/shop",
+      "nextSteps": [
+        "Initialize the database BEFORE deploy: run `pxbaas app db-init <name> --dir <appsDir>`. It reads db/schema.sql (DDL + seed) and db/rls.json (RLS: products public-read; orders and order_items owner-gated by buyer_email = jwt.email), shows the full plan, and applies it only after you authorize (--dry-run to preview, --yes for non-interactive). Works in single-tenant (/pg/query) AND multi-tenant (/api/tenant-ddl with your per-tenant service_role key); the CLI never auto-runs DDL.",
+        "Create the admin account (admin@shop.demo) via GoTrue signup if the admin whitelist is needed.",
+        "Data-plane base and anon key come from the platform-injected SUPABASE_INTERNAL_URL / SUPABASE_ANON_KEY (edge-runtime MR #30497903); no plaintext key editing is needed. Requires the instance to report react/react-dom in capabilities.ssrLibs."
+      ]
+    },
+    {
+      "id": "ssr-frameworks",
+      "description": "Four-framework SSR showcase (React / Vue / Preact / Solid on Hono) rendering the same UI spec server-side, plus /compare. No data plane and no credentials; heaviest cold start of the set (~60s), so warm the tenant sandbox before publish.",
+      "entrypoint": "backend/index.ts",
+      "mode": "webapp",
+      "files": [
+        "README.md",
+        "backend/index.ts",
+        "frontend/dist/index.html"
+      ],
+      "frontend": {
+        "root": "frontend/dist",
+        "routing": "files",
+        "index": "index.html",
+        "fallback": "worker"
+      },
+      "backend": {
+        "entrypoint": "backend/index.ts",
+        "framework": "hono",
+        "pathMode": "strip-app-api-prefix",
+        "verifyJwt": false,
+        "secrets": [],
+        "egressPolicy": "deny",
+        "session": "none"
+      },
+      "ssrProbePath": "/react",
+      "nextSteps": [
+        "No data plane and no credentials are required.",
+        "Heaviest cold start of the set (~60s with four SSR renderers): warm the tenant sandbox before publish and retry APP_SSR_PROBE_FAILED 3-5 times.",
+        "Requires the instance to report react/react-dom, vue/@vue/server-renderer, preact/preact-render-to-string and solid-js in capabilities.ssrLibs, else deploy is blocked by no-remote-import / ssr-lib-not-allowed."
+      ]
+    }
+  ]
+}

package/templates/webapp/mpa/about.html

@@ -0,0 +1,29 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>{{APP_NAME}} — About</title>
+<link rel="stylesheet" href="style.css" />
+</head>
+<body>
+  <h1>About {{APP_NAME}}</h1>
+  <nav class="nav">
+    <a href="index.html">Home</a> · <a href="about.html">About</a>
+  </nav>
+
+  <div class="card">
+    <p>
+      This is a second static page (<code>about.html</code>). Navigating here from
+      the home page uses a plain relative link — no client-side router, no
+      single-file bundle. Each page is a real file served by path.
+    </p>
+    <p class="muted">
+      Add more pages by dropping new <code>.html</code> files into the app
+      directory and listing them under <code>pages</code> in <code>app.json</code>.
+    </p>
+  </div>
+
+  <script src="app.js"></script>
+</body>
+</html>

package/templates/webapp/mpa/app.js

@@ -0,0 +1,42 @@
+// {{APP_NAME}} — shared client script (MPA). Runs in the BROWSER on every page.
+//
+// Guardrails:
+//  - Asset links in the HTML are relative; here the API call uses a COMPUTED base
+//    (the function directory) + "?action=..." so the request returns through
+//    Kong -> proxy -> sandbox on the same /functions/v1/{{SLUG}}/ path and never
+//    escapes the prefix.
+//  - Defensive element lookups: the same script is included on every page, and
+//    not every page has every widget.
+(function () {
+  // Directory of the current page, e.g. /functions/v1/{{SLUG}}/
+  var base = location.pathname.endsWith("/")
+    ? location.pathname
+    : location.pathname.replace(/\/[^/]*$/, "/");
+
+  var urlEl = document.getElementById("url");
+  if (urlEl) urlEl.textContent = location.origin + base;
+
+  var n = 0;
+  var countEl = document.getElementById("count");
+  var incBtn = document.getElementById("inc");
+  if (incBtn) {
+    incBtn.addEventListener("click", function () {
+      n++;
+      if (countEl) countEl.textContent = String(n);
+    });
+  }
+
+  var pingBtn = document.getElementById("ping");
+  var apiEl = document.getElementById("api");
+  if (pingBtn) {
+    pingBtn.addEventListener("click", async function () {
+      if (apiEl) apiEl.textContent = "loading…";
+      try {
+        var r = await fetch(base + "?action=time", { headers: { Accept: "application/json" } });
+        if (apiEl) apiEl.textContent = JSON.stringify(await r.json(), null, 2);
+      } catch (e) {
+        if (apiEl) apiEl.textContent = "error: " + e;
+      }
+    });
+  }
+})();

package/templates/webapp/mpa/index.html

@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>{{APP_NAME}}</title>
+<!-- RELATIVE asset link: resolves to /functions/v1/{{SLUG}}/style.css -->
+<link rel="stylesheet" href="style.css" />
+</head>
+<body>
+  <h1>{{APP_NAME}}</h1>
+  <nav class="nav">
+    <a href="index.html">Home</a> · <a href="about.html">About</a>
+  </nav>
+
+  <p class="muted">
+    A multi-page webapp: <code>index.html</code>, <code>about.html</code>,
+    <code>style.css</code> and <code>app.js</code> are served as real static files
+    by the BaaS proxy, reverse-proxied via Kong <code>/functions/v1/</code>.
+  </p>
+
+  <div class="card">
+    <div class="muted">Share URL (opens directly in a browser)</div>
+    <code id="url">loading…</code>
+  </div>
+
+  <div class="card">
+    <div>① Client-side counter (from <code>app.js</code>)</div>
+    <div class="big" id="count">0</div>
+    <button id="inc">+1</button>
+  </div>
+
+  <div class="card">
+    <div>② Call the worker API (computed base + <code>?action=time</code>)</div>
+    <button id="ping">GET ?action=time</button>
+    <pre id="api" class="muted">Click to fetch server time</pre>
+  </div>
+
+  <!-- RELATIVE script src: resolves to /functions/v1/{{SLUG}}/app.js -->
+  <script src="app.js"></script>
+</body>
+</html>

package/templates/webapp/mpa/index.ts

@@ -0,0 +1,60 @@
+// {{APP_NAME}} — multi-page webapp (MPA) Edge Function worker.
+//
+// Spec: follow the `pxbaas-app-spec` skill — `pxbaas app deploy` lints this app against it.
+//
+// Deploy with:  pxbaas app deploy {{SLUG}}
+// Share URL:    {endpoint}/functions/v1/{{SLUG}}/            (serves static index.html)
+//               {endpoint}/functions/v1/{{SLUG}}/about.html  (serves static about.html)
+//               {endpoint}/functions/v1/{{SLUG}}/style.css   (static asset)
+// Built-in API: {endpoint}/functions/v1/{{SLUG}}/?action=time
+//
+// How an MPA works here (Plan B):
+//  - The real static files (index.html / about.html / style.css / app.js) are
+//    served DIRECTLY by the BaaS proxy static branch — they never reach this
+//    worker. That is why they can be linked by relative path from the pages.
+//  - This worker only handles the JSON API (?action=...) and any non-asset path.
+//  - app.json declares `"mode": "mpa"` which is what turns the static branch on
+//    for this function; without it the proxy routes everything to this worker.
+//
+// Guardrails baked into this template (do NOT break them):
+//  - Pages reference assets with RELATIVE links (style.css, app.js, about.html),
+//    never root-absolute ("/style.css") which would escape the /functions/v1/ prefix.
+//  - API calls use a computed base + "?action=..." so they return through
+//    Kong -> proxy -> sandbox on the same path.
+//  - CORS headers are set for browser calls; reflected input is JSON-only here.
+
+function corsHeaders(): Record<string, string> {
+  return {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "POST, GET, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type, Authorization, apikey, X-Tenant-Id",
+  };
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json", ...corsHeaders() },
+  });
+}
+
+Deno.serve((req: Request) => {
+  const url = new URL(req.url);
+
+  if (req.method === "OPTIONS") {
+    return new Response(null, { status: 204, headers: corsHeaders() });
+  }
+
+  // Built-in JSON API — extend with your own actions here.
+  const action = url.searchParams.get("action");
+  if (action === "time") {
+    return json({ ok: true, now: new Date().toISOString() });
+  }
+  if (action) {
+    return json({ ok: false, error: `unknown action: ${action}` }, 400);
+  }
+
+  // No ?action: static pages/assets are served by the proxy before reaching here,
+  // so anything that lands on the worker is an unknown dynamic path.
+  return json({ ok: false, error: "not found" }, 404);
+});

package/templates/webapp/mpa/style.css

@@ -0,0 +1,42 @@
+/* {{APP_NAME}} — shared stylesheet (MPA). Served as a real static .css file. */
+:root { color-scheme: light dark; }
+
+body {
+  font-family: -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  max-width: 720px;
+  margin: 40px auto;
+  padding: 0 20px;
+  line-height: 1.6;
+}
+
+h1 { margin-bottom: 4px; }
+
+.nav { margin: 8px 0 20px; font-size: 15px; }
+.nav a { text-decoration: none; color: #0a7; font-weight: 600; }
+.nav a:hover { text-decoration: underline; }
+
+.card {
+  border: 1px solid #ddd;
+  border-radius: 12px;
+  padding: 16px 20px;
+  margin: 16px 0;
+}
+
+code, pre {
+  background: #f4f4f5;
+  padding: 2px 6px;
+  border-radius: 4px;
+  word-break: break-all;
+}
+pre { padding: 12px; overflow: auto; }
+
+button {
+  font-size: 15px;
+  padding: 8px 16px;
+  border-radius: 8px;
+  border: 1px solid #ccc;
+  cursor: pointer;
+}
+
+.big { font-size: 32px; font-weight: 700; }
+.muted { color: #888; font-size: 13px; }

package/templates/webapp/react-vite/frontend/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.0" />
+    <title>{{APP_NAME}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./src/main.tsx"></script>
+  </body>
+</html>