@revenexx/studio-commerce-devkit 0.1.4 → 0.1.6

package/README.md

@@ -95,6 +95,23 @@ Requires the `@revenexx` registry in `.npmrc` (+ a `read:packages` token), same
 as any `@revenexx/*` install. Build output goes to `.commerce-studio/` in your
 app (gitignore it).
 
+## Functions console (`/functions`)
+
+Run your app's **server-side code** locally against a **simulated API gateway** —
+open **`/functions`** (nav link in the top strip). It lists your app's routes
+from `manifest.capabilities.json`; pick one, fill path params / query / a JSON
+body (prefilled from the request schema), and **Send** → you see the real
+response (status, JSON, timing, and the function's `log()` output).
+
+How it works: each app is a single function at `src/main.js`
+(`@revenexx/app-sdk/router`). The gateway (`/gateway/<app>/<path…>`) builds an
+open-runtimes `FnContext`, `require()`s `src/main.js`, and invokes it. The
+function's data adapter is pointed at this host's `/pg` mock store
+(`REVENEXX_DATA_ENDPOINT`), so **function reads/writes share the same data as
+the Commerce Studio views** — create a market via `POST /markets`, then see it
+in the `/commerce` list. Requires the app's deps installed (its
+`@revenexx/app-sdk`); edits to `src/main.js` are picked up on the next run.
+
 ## Notes
 
 - Mock data is in-memory and regenerated on server restart; it's for *seeing the

package/app/layouts/default.vue

@@ -8,8 +8,12 @@
 
 <template>
   <div class="flex h-screen w-screen flex-col overflow-hidden bg-background text-foreground">
-    <header class="flex h-9 shrink-0 items-center gap-2 px-3 text-mono text-muted-foreground">
-      Commerce Studio · standalone app-building
+    <header class="flex h-9 shrink-0 items-center gap-3 px-3 text-mono text-muted-foreground">
+      <span>Commerce Studio · standalone app-building</span>
+      <nav class="ml-2 flex items-center gap-3">
+        <NuxtLink to="/commerce" class="hover:text-foreground" active-class="text-foreground">Commerce</NuxtLink>
+        <NuxtLink to="/functions" class="hover:text-foreground" active-class="text-foreground">Functions</NuxtLink>
+      </nav>
     </header>
     <div class="min-h-0 flex-1">
       <slot />

package/app/pages/functions.vue

@@ -0,0 +1,228 @@
+<script setup lang="ts">
+/**
+ * Functions console — a Postman-like surface to run an app's server-side
+ * function through the simulated API gateway (`/gateway/<app>/…`). Capabilities
+ * come from each app's manifest.capabilities.json; the response, timing and
+ * function logs come back from the gateway (dev-only devkit surface).
+ */
+interface Capability {
+  capability: string
+  summary?: string
+  route: { method: string, path: string }
+  parameters?: { name: string, in: string, required?: boolean, schema?: any, description?: string }[]
+  request?: { properties?: Record<string, any> }
+}
+interface AppCaps { app: string, folder: string, capabilities: Capability[] }
+
+useHead({ title: 'Functions · Commerce Studio' })
+
+const { data } = await useFetch<{ apps: AppCaps[] }>('/api/functions')
+const apps = computed(() => data.value?.apps ?? [])
+
+const selectedApp = ref('')
+watchEffect(() => { if (!selectedApp.value && apps.value.length) selectedApp.value = apps.value[0]!.app })
+const currentApp = computed(() => apps.value.find(a => a.app === selectedApp.value) ?? null)
+
+const filter = ref('')
+const capabilities = computed(() => {
+  const caps = [...(currentApp.value?.capabilities ?? [])]
+    .sort((a, b) => a.route.path.localeCompare(b.route.path) || a.route.method.localeCompare(b.route.method))
+  const f = filter.value.trim().toLowerCase()
+  return f ? caps.filter(c => `${c.capability} ${c.route.method} ${c.route.path}`.toLowerCase().includes(f)) : caps
+})
+
+const selected = ref<Capability | null>(null)
+const pathParams = reactive<Record<string, string>>({})
+const queryParams = reactive<Record<string, string>>({})
+const bodyText = ref('')
+
+function pathParamNames(path: string): string[] {
+  return [...path.matchAll(/\{([^}]+)\}/g)].map(m => m[1]!)
+}
+function skeletonFor(schema: any): unknown {
+  const t = String(schema?.type)
+  if (schema?.enum?.length) return schema.enum[0]
+  if (t.includes('object')) return {}
+  if (t.includes('array')) return []
+  if (t.includes('integer') || t.includes('number')) return 0
+  if (t.includes('bool')) return false
+  return ''
+}
+function selectCap(c: Capability) {
+  selected.value = c
+  for (const k of Object.keys(pathParams)) delete pathParams[k]
+  for (const n of pathParamNames(c.route.path)) pathParams[n] = ''
+  for (const k of Object.keys(queryParams)) delete queryParams[k]
+  for (const p of c.parameters ?? []) if (p.in === 'query') queryParams[p.name] = ''
+  bodyText.value = (['POST', 'PUT', 'PATCH'].includes(c.route.method) && c.request?.properties)
+    ? JSON.stringify(Object.fromEntries(Object.entries(c.request.properties).map(([k, s]) => [k, skeletonFor(s)])), null, 2)
+    : ''
+  response.value = null
+}
+
+const running = ref(false)
+const response = ref<{ status: number, body: unknown, logs: string[], durationMs: number, error?: string } | null>(null)
+
+function resolvedPath(): string {
+  let p = selected.value!.route.path
+  for (const [k, v] of Object.entries(pathParams)) p = p.replace(`{${k}}`, encodeURIComponent(v || `{${k}}`))
+  return p
+}
+
+async function send() {
+  if (!selected.value || !currentApp.value) return
+  running.value = true
+  response.value = null
+  const method = selected.value.route.method
+  const query: Record<string, string> = {}
+  for (const [k, v] of Object.entries(queryParams)) if (v !== '') query[k] = v
+  let body: unknown
+  if (['POST', 'PUT', 'PATCH'].includes(method) && bodyText.value.trim()) {
+    try { body = JSON.parse(bodyText.value) }
+    catch (e: any) {
+      response.value = { status: 0, body: null, logs: [], durationMs: 0, error: `Invalid JSON body: ${e.message}` }
+      running.value = false
+      return
+    }
+  }
+  try {
+    const res = await $fetch.raw(`/gateway/${currentApp.value.app}${resolvedPath()}`, {
+      method: method as any,
+      query,
+      body,
+      ignoreResponseError: true,
+    })
+    const logs = JSON.parse(decodeURIComponent(res.headers.get('x-fn-logs') || '%5B%5D'))
+    response.value = { status: res.status, body: res._data, logs, durationMs: Number(res.headers.get('x-fn-duration') || 0) }
+  }
+  catch (e: any) {
+    response.value = { status: 0, body: null, logs: [], durationMs: 0, error: e.message }
+  }
+  finally {
+    running.value = false
+  }
+}
+
+function methodClass(m: string) {
+  return ({ GET: 'text-emerald-700 bg-emerald-50', POST: 'text-blue-700 bg-blue-50', PUT: 'text-amber-700 bg-amber-50', PATCH: 'text-amber-700 bg-amber-50', DELETE: 'text-rose-700 bg-rose-50' } as Record<string, string>)[m] || 'text-muted-foreground bg-muted'
+}
+function statusClass(s: number) {
+  if (s >= 200 && s < 300) return 'text-emerald-700 bg-emerald-50'
+  if (s >= 400 && s < 500) return 'text-amber-700 bg-amber-50'
+  return 'text-rose-700 bg-rose-50'
+}
+const prettyBody = computed(() => {
+  try { return JSON.stringify(response.value?.body, null, 2) }
+  catch { return String(response.value?.body) }
+})
+</script>
+
+<template>
+  <div class="flex h-full min-h-0">
+    <!-- Left: app + capability list -->
+    <aside class="flex w-80 shrink-0 flex-col overflow-hidden border-r border-black/[0.06] bg-white">
+      <div class="border-b border-black/[0.06] px-4 pt-4 pb-3">
+        <h2 class="text-lg font-medium text-[#0B0522]">
+          Functions
+        </h2>
+        <p class="text-sm text-muted-foreground">
+          Run app code via the simulated gateway
+        </p>
+      </div>
+      <div class="space-y-2 px-3 py-2">
+        <select v-model="selectedApp" class="h-8 w-full rounded-md border border-input bg-transparent px-2 text-sm">
+          <option v-for="a in apps" :key="a.app" :value="a.app">{{ a.app }}</option>
+        </select>
+        <input v-model="filter" placeholder="Filter routes…" class="h-8 w-full rounded-md border border-input bg-transparent px-2 text-sm">
+      </div>
+      <nav class="flex-1 overflow-y-auto px-2 pb-3">
+        <button
+          v-for="c in capabilities"
+          :key="c.capability + c.route.method"
+          class="group flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-left transition-colors hover:bg-primary/5"
+          :class="selected?.capability === c.capability && selected?.route.method === c.route.method ? 'bg-primary/10' : ''"
+          @click="selectCap(c)"
+        >
+          <span class="w-12 shrink-0 rounded px-1 py-0.5 text-center text-[10px] font-semibold" :class="methodClass(c.route.method)">{{ c.route.method }}</span>
+          <span class="min-w-0 flex-1">
+            <span class="block truncate font-mono text-xs text-foreground/90">{{ c.route.path }}</span>
+            <span class="block truncate text-[11px] text-muted-foreground">{{ c.capability }}</span>
+          </span>
+        </button>
+        <p v-if="!capabilities.length" class="px-2 pt-3 text-sm text-muted-foreground">
+          No capabilities. Does this app ship a manifest.capabilities.json?
+        </p>
+      </nav>
+    </aside>
+
+    <!-- Right: request builder + response -->
+    <section class="flex min-w-0 flex-1 flex-col overflow-y-auto bg-white/40 p-4">
+      <div v-if="!selected" class="m-auto text-sm text-muted-foreground">
+        Select a capability to run it.
+      </div>
+
+      <template v-else>
+        <!-- request line -->
+        <div class="flex items-center gap-2">
+          <span class="rounded px-1.5 py-0.5 text-xs font-semibold" :class="methodClass(selected.route.method)">{{ selected.route.method }}</span>
+          <code class="min-w-0 flex-1 truncate rounded-md border border-black/[0.06] bg-white px-2 py-1.5 text-sm">{{ resolvedPath() }}</code>
+          <button
+            class="shrink-0 rounded-md bg-primary px-4 py-1.5 text-sm font-medium text-primary-foreground disabled:opacity-50"
+            :disabled="running"
+            @click="send"
+          >
+            {{ running ? 'Running…' : 'Send' }}
+          </button>
+        </div>
+        <p v-if="selected.summary" class="mt-1 text-sm text-muted-foreground">
+          {{ selected.summary }}
+        </p>
+
+        <!-- params -->
+        <div class="mt-4 grid gap-4 sm:grid-cols-2">
+          <div v-if="Object.keys(pathParams).length">
+            <div class="text-mono text-muted-foreground">Path params</div>
+            <div class="mt-1 space-y-1">
+              <label v-for="(_v, k) in pathParams" :key="k" class="flex items-center gap-2 text-sm">
+                <span class="w-28 shrink-0 truncate font-mono text-xs text-foreground/70">{{ k }}</span>
+                <input v-model="pathParams[k]" class="h-8 flex-1 rounded-md border border-input bg-white px-2 text-sm">
+              </label>
+            </div>
+          </div>
+          <div v-if="Object.keys(queryParams).length">
+            <div class="text-mono text-muted-foreground">Query</div>
+            <div class="mt-1 space-y-1">
+              <label v-for="(_v, k) in queryParams" :key="k" class="flex items-center gap-2 text-sm">
+                <span class="w-28 shrink-0 truncate font-mono text-xs text-foreground/70">{{ k }}</span>
+                <input v-model="queryParams[k]" class="h-8 flex-1 rounded-md border border-input bg-white px-2 text-sm">
+              </label>
+            </div>
+          </div>
+        </div>
+
+        <!-- body -->
+        <div v-if="['POST', 'PUT', 'PATCH'].includes(selected.route.method)" class="mt-4">
+          <div class="text-mono text-muted-foreground">Request body (JSON)</div>
+          <textarea v-model="bodyText" rows="8" class="mt-1 w-full rounded-md border border-input bg-white p-2 font-mono text-xs" spellcheck="false" />
+        </div>
+
+        <!-- response -->
+        <div v-if="response" class="mt-5 rounded-lg border border-black/[0.06] bg-white">
+          <div class="flex items-center gap-2 border-b border-black/[0.06] px-3 py-2">
+            <span class="text-mono text-muted-foreground">Response</span>
+            <span v-if="response.status" class="rounded px-1.5 py-0.5 text-xs font-semibold" :class="statusClass(response.status)">{{ response.status }}</span>
+            <span class="ml-auto text-xs text-muted-foreground">{{ response.durationMs }} ms</span>
+          </div>
+          <p v-if="response.error" class="px-3 py-2 text-sm text-rose-700">
+            {{ response.error }}
+          </p>
+          <pre v-else class="max-h-[40vh] overflow-auto px-3 py-2 font-mono text-xs leading-relaxed">{{ prettyBody }}</pre>
+          <div v-if="response.logs?.length" class="border-t border-black/[0.06] px-3 py-2">
+            <div class="text-mono text-muted-foreground">Logs</div>
+            <pre class="mt-1 max-h-40 overflow-auto font-mono text-[11px] text-foreground/80">{{ response.logs.join('\n') }}</pre>
+          </div>
+        </div>
+      </template>
+    </section>
+  </div>
+</template>

package/nuxt.config.ts

@@ -90,6 +90,16 @@ export default defineNuxtConfig({
     plugins: [tailwindcss()],
     server: {
       allowedHosts: ['commerce-studio.rvnxx.test', 'localhost'],
+      // Allow Vite to serve the studio packages' assets (e.g. @revenexx/studio's
+      // brand-font .woff2 referenced by its fonts.css). They live deep in the
+      // pnpm store, outside the default fs allow-list → 403 without this.
+      fs: {
+        allow: [
+          pkgDir('@revenexx/studio'),
+          pkgDir('@revenexx/studio-shared'),
+          pkgDir('@revenexx/studio-commerce'),
+        ],
+      },
     },
   },
   solarIcons: {
@@ -105,6 +115,9 @@ export default defineNuxtConfig({
       // Same-origin local shims (served by this host's server/routes):
       consoleApi: '',
       postgrestApi: '/pg',
+      // Functions console: the simulated API gateway + capability listing.
+      gatewayApi: '/gateway',
+      functionsApi: '/api/functions',
       // Standalone platform provider (any non-empty token unlocks the shims):
       devToken: 'dev',
       devTenant: 'dev',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revenexx/studio-commerce-devkit",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "description": "Preview any revenexx app locally in the Commerce Studio: renders the app's cockpit.json with mock data, no platform. Add as a devDependency and run `commerce-studio` from your app repo.",
   "bin": {
@@ -26,8 +26,8 @@
     "tw-animate-css": "^1.4.0",
     "vue": "^3.5.26",
     "vue-router": "^4.6.4",
-    "@revenexx/studio-shared": "0.1.2",
-    "@revenexx/studio-commerce": "0.1.4"
+    "@revenexx/studio-commerce": "0.1.4",
+    "@revenexx/studio-shared": "0.1.2"
   },
   "license": "SEE LICENSE IN LICENSE",
   "scripts": {

package/server/routes/api/functions.get.ts

@@ -0,0 +1,7 @@
+/**
+ * Lists each app's gateway contract (from manifest.capabilities.json) for the
+ * Functions console to render. Re-read per request → edit + reload reflects.
+ */
+export default defineEventHandler(() => {
+  return { apps: loadCapabilities() }
+})

package/server/routes/gateway/[app]/[...path].ts

@@ -0,0 +1,27 @@
+/**
+ * Simulated API gateway. Forwards any `<method> /gateway/<app>/<path…>` request
+ * to the app's function (its `src/main.js`, which self-routes via the app-sdk
+ * router). Returns the function's raw response body — so it behaves like the
+ * real gateway (curl/other tools work) — with the run's logs + timing exposed
+ * as response headers for the Functions console.
+ */
+export default defineEventHandler(async (event) => {
+  const app = getRouterParam(event, 'app') || ''
+  const rest = getRouterParam(event, 'path') || ''
+  const path = `/${String(rest).replace(/^\/+/, '')}`
+  const method = event.method
+  const query = getQuery(event) as Record<string, any>
+  const body = ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)
+    ? await readBody(event).catch(() => undefined)
+    : undefined
+
+  const url = getRequestURL(event)
+  const origin = `${url.protocol}//${url.host}`
+
+  const result = await invokeFunction(app, { method, path, query, body, origin })
+
+  setResponseStatus(event, result.status)
+  setResponseHeader(event, 'x-fn-duration', String(result.durationMs))
+  setResponseHeader(event, 'x-fn-logs', encodeURIComponent(JSON.stringify(result.logs)))
+  return result.body
+})

package/server/utils/functions.ts

@@ -0,0 +1,167 @@
+/**
+ * Functions runner + simulated API gateway.
+ *
+ * Each revenexx app is a single serverless function at `src/main.js`
+ * (`module.exports = async (context) => …`) built on `@revenexx/app-sdk/router`
+ * — a self-routing HTTP handler. This util loads that function from disk and
+ * invokes it with a fabricated open-runtimes `FnContext`, so the devkit can run
+ * the app's real server code locally:
+ *
+ *   • `loadCapabilities()` reads each app's `manifest.capabilities.json` (the
+ *     gateway contract: method + path + params + request schema) for the UI.
+ *   • `invokeFunction()` requires `src/main.js`, builds the FnContext, injects
+ *     the gateway identity headers, and captures the response + logs + timing.
+ *
+ * Data unifies with the Commerce Studio: we point the function's runtime data
+ * adapter (`REVENEXX_DATA_ENDPOINT`) at this host's own `/pg` shim, so the
+ * function reads/writes the SAME mock store the AppRenderer renders.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { createRequire } from 'node:module'
+import { appsDir } from './commerce'
+
+function readJson(path: string): any | null {
+  try {
+    return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : null
+  }
+  catch {
+    return null
+  }
+}
+
+export interface CapabilityDef {
+  capability: string
+  summary?: string
+  version?: string
+  route: { method: string, path: string }
+  parameters?: { name: string, in: string, required?: boolean, schema?: any, description?: string }[]
+  request?: { properties?: Record<string, any> } & Record<string, any>
+}
+
+interface AppEntry {
+  name: string
+  folder: string
+  base: string
+  capabilities: CapabilityDef[]
+}
+
+/** Apps under APPS_DIR that expose a runnable function (`src/main.js`). */
+export function appEntries(): AppEntry[] {
+  const dir = appsDir()
+  const one = (base: string, folder: string): AppEntry | null => {
+    if (!existsSync(join(base, 'src', 'main.js'))) return null
+    const manifest = readJson(join(base, 'manifest.json')) ?? {}
+    const caps = readJson(join(base, 'manifest.capabilities.json'))
+    const capabilities: CapabilityDef[] = Array.isArray(caps) ? caps.filter((c: any) => c?.route?.path) : []
+    return { name: manifest.name ?? folder, folder, base, capabilities }
+  }
+  // Single-app: APPS_DIR is itself an app (the `commerce-studio` bin case).
+  const self = one(dir, dir.split('/').filter(Boolean).pop() || 'app')
+  if (self) return [self]
+  const out: AppEntry[] = []
+  for (const folder of readdirSync(dir)) {
+    const base = join(dir, folder)
+    if (folder.startsWith('.') || !statSync(base).isDirectory()) continue
+    const e = one(base, folder)
+    if (e) out.push(e)
+  }
+  return out
+}
+
+/** The gateway contract per app, for the Functions console to render. */
+export function loadCapabilities() {
+  return appEntries().map(e => ({ app: e.name, folder: e.folder, capabilities: e.capabilities }))
+}
+
+/**
+ * Minimal unsigned dev JWT carrying a tenant claim. NOT a real credential — it
+ * only satisfies `main.js`'s non-empty `x-revenexx-context` check and the
+ * runtime adapter's claim read; the `/pg` shim ignores auth entirely.
+ */
+function devJwt(): string {
+  const b64 = (o: unknown) => Buffer.from(JSON.stringify(o)).toString('base64url')
+  return `${b64({ alg: 'none', typ: 'JWT' })}.${b64({ sub: 'dev', tenant_id: 'dev', iss: 'devkit' })}.`
+}
+
+export interface InvokeResult {
+  status: number
+  body: unknown
+  headers: Record<string, string>
+  logs: string[]
+  durationMs: number
+}
+
+export async function invokeFunction(appName: string, opts: {
+  method: string
+  path: string
+  query?: Record<string, any>
+  body?: unknown
+  headers?: Record<string, string>
+  origin: string
+}): Promise<InvokeResult> {
+  const entry = appEntries().find(e => e.name === appName || e.folder === appName)
+  if (!entry) {
+    return { status: 404, body: { error: `Unknown app '${appName}'` }, headers: {}, logs: [], durationMs: 0 }
+  }
+  const mainPath = join(entry.base, 'src', 'main.js')
+
+  // Unify the function's data plane with the devkit's /pg mock store, and give
+  // the runtime adapter an identity (headers below also carry it).
+  process.env.REVENEXX_DATA_ENDPOINT = `${opts.origin}/pg`
+  process.env.REVENEXX_CONTEXT = devJwt()
+  process.env.REVENEXX_TENANT = 'dev'
+
+  const require = createRequire(mainPath)
+  // Bust the app's own module cache so edits to main.js / db.generated.js are
+  // picked up on each run (the SDK in node_modules stays cached).
+  for (const key of Object.keys(require.cache)) {
+    if (key.startsWith(entry.base)) delete require.cache[key]
+  }
+
+  const logs: string[] = []
+  const push = (m: unknown, prefix = '') => logs.push(prefix + (typeof m === 'string' ? m : JSON.stringify(m)))
+  let captured: { status: number, body: unknown, headers: Record<string, string> } | null = null
+
+  const res = {
+    json(data: unknown, statusCode = 200, headers: Record<string, string> = {}) {
+      captured = { status: statusCode, body: data, headers }
+      return data
+    },
+    send(body: unknown, statusCode = 200, headers: Record<string, string> = {}) {
+      captured = { status: statusCode, body, headers }
+      return body
+    },
+  }
+  const context = {
+    req: {
+      method: opts.method,
+      path: opts.path,
+      url: opts.path,
+      headers: { 'x-revenexx-context': devJwt(), 'x-revenexx-tenant': 'dev', ...(opts.headers ?? {}) },
+      query: opts.query ?? {},
+      body: opts.body ?? {},
+      bodyText: opts.body != null ? JSON.stringify(opts.body) : '',
+    },
+    res,
+    log: (m: unknown) => push(m),
+    error: (m: unknown) => push(m, 'ERROR: '),
+  }
+
+  const started = Date.now()
+  try {
+    const mod = require(mainPath)
+    const handler = typeof mod === 'function' ? mod : (mod?.default ?? mod)
+    if (typeof handler !== 'function') {
+      return { status: 500, body: { error: `app '${appName}' src/main.js does not export a function` }, headers: {}, logs, durationMs: Date.now() - started }
+    }
+    const ret = await handler(context)
+    // The SDK router answers via res.json(); fall back to the return value.
+    if (!captured) captured = { status: 200, body: ret ?? null, headers: {} }
+  }
+  catch (err: any) {
+    push(err?.stack ?? String(err), 'ERROR: ')
+    return { status: 500, body: { error: err?.message ?? String(err) }, headers: {}, logs, durationMs: Date.now() - started }
+  }
+  return { ...captured!, logs, durationMs: Date.now() - started }
+}