diff --git a/backend b/backend index 32a5f94..e8e2fe6 160000 --- a/backend +++ b/backend @@ -1 +1 @@ -Subproject commit 32a5f949d955bdd7e34b16349644d14569acf23c +Subproject commit e8e2fe6f7f76ef4d8c1bf088c00b53e7073fbb8d diff --git a/docs/adr/0002-pocketbase-gvisor-microapps.md b/docs/adr/0002-pocketbase-gvisor-microapps.md new file mode 100644 index 0000000..3bc2877 --- /dev/null +++ b/docs/adr/0002-pocketbase-gvisor-microapps.md @@ -0,0 +1,80 @@ +# ADR-0002: PocketBase + gVisor Platform For Agent-Built Microapps + +Дата: 2026-03-23 +Статус: accepted + +## Контекст + +Нужен минимальный платформенный слой, в котором агент может собирать микро-приложения для клиентов по жёсткому шаблону: + +- данные и auth живут в PocketBase; +- код приложения исполняется изолированно в Deno runtime; +- delivery идёт только из шаблонного репозитория и после валидации; +- control-plane хранится в основной Prisma-базе проекта. + +Ключевые ограничения: + +- агент не должен деплоить произвольный код вне шаблона; +- приложения разных клиентов должны быть логически и операционно изолированы; +- база данных и execution host разводятся в разные контуры; +- rollout и rollback должны опираться на versioned deploy records. + +## Решение + +Принимаем MVP-схему из двух data-plane компонентов и одного control-plane: + +1. `PocketBase` +- отдельный сервис данных для микро-приложений; +- каждое приложение получает собственный `pocketbaseInstanceId` и URL; +- доступ из микро-приложения идёт только через разрешённый service account. + +2. `Deno runner` в `gVisor` +- каждое приложение исполняется как контейнер с `runsc`; +- runtime получает лимиты по CPU/RAM/PIDs и whitelist по env/network; +- runner запускает только Deno entrypoint из шаблона микро-приложения. + +3. `backend` как control-plane +- хранит `MicroAppProject`, `MicroAppRuntimeConfig`, `MicroAppDeployment`; +- выдаёт конфиг для provisioning и delivery; +- знает путь репозитория, ветку, template checksum, preview/prod URL. + +## Поток + +1. Агент создаёт проект только из `microapps/templates/pocketbase-deno-dashboard`. +2. Валидатор проверяет структуру репозитория и `app.config.ts`. +3. Control-plane создаёт или обновляет запись `MicroAppProject`. +4. Delivery pipeline фиксирует новую версию в `MicroAppDeployment`. +5. Runner поднимает Deno-контейнер через `gVisor`. +6. Публикация идёт через preview domain, а promotion в основной домен выполняется отдельно. + +## Delivery + +- source of truth: git-репозиторий приложения; +- deploy unit: versioned template-compliant app directory; +- preview создаётся автоматически после успешной валидации; +- production переключается через отдельный promote шаг; +- rollback выполняется redeploy предыдущей записи `MicroAppDeployment`. + +## Домены + +На первом этапе платформа хранит: + +- `primaryDomain` +- `previewDomain` + +Привязка доменов и DNS-автоматизация выносятся в отдельный шаг интеграции с Cloudflare и не блокируют запуск control-plane MVP. + +## Последствия + +Плюсы: + +- появляется единый control-plane для клиентских микро-приложений; +- есть жёсткий шаблон и проверяемый runtime policy; +- база данных и execution host разделены; +- есть основа для preview/prod flow и rollback. + +Минусы: + +- runtime по-прежнему требует отдельного delivery automation поверх git; +- provisioning PocketBase instance пока остаётся внешней операцией; +- домены и TLS-автоматизация ещё не включены в MVP-каркас. diff --git a/microapps/runtime/Dockerfile b/microapps/runtime/Dockerfile new file mode 100644 index 0000000..7b9b3d1 --- /dev/null +++ b/microapps/runtime/Dockerfile @@ -0,0 +1,22 @@ +FROM debian:bookworm-slim + +ARG DENO_VERSION=2.6.4 + +RUN apt-get update \ + && apt-get install --yes --no-install-recommends ca-certificates curl tini unzip \ + && rm -rf /var/lib/apt/lists/* + +RUN curl -fsSL "https://dl.deno.land/release/v${DENO_VERSION}/deno-x86_64-unknown-linux-gnu.zip" -o /tmp/deno.zip \ + && unzip /tmp/deno.zip -d /usr/local/bin \ + && chmod +x /usr/local/bin/deno \ + && rm /tmp/deno.zip + +WORKDIR /workspace + +COPY microapps/runtime/entrypoint.sh /usr/local/bin/microapp-entrypoint + +RUN chmod +x /usr/local/bin/microapp-entrypoint + +ENV DENO_DIR=/deno-dir + +ENTRYPOINT ["/usr/bin/tini", "--", "/usr/local/bin/microapp-entrypoint"] diff --git a/microapps/runtime/entrypoint.sh b/microapps/runtime/entrypoint.sh new file mode 100644 index 0000000..29a2477 --- /dev/null +++ b/microapps/runtime/entrypoint.sh @@ -0,0 +1,15 @@ +#!/usr/bin/env sh +set -eu + +APP_DIR="${APP_DIR:-/workspace/app}" +ENTRYPOINT_FILE="${ENTRYPOINT_FILE:-$APP_DIR/main.ts}" +ALLOW_READ="${ALLOW_READ:-$APP_DIR}" +ALLOW_ENV="${ALLOW_ENV:-PORT,POCKETBASE_URL,POCKETBASE_SERVICE_EMAIL,POCKETBASE_SERVICE_PASSWORD,APP_OWNER_TEAM_ID,APP_SLUG}" +ALLOW_NET="${ALLOW_NET:-127.0.0.1,localhost}" + +exec deno run \ + --no-prompt \ + --allow-read="$ALLOW_READ" \ + --allow-env="$ALLOW_ENV" \ + --allow-net="$ALLOW_NET" \ + "$ENTRYPOINT_FILE" diff --git a/microapps/runtime/run-with-gvisor.sh b/microapps/runtime/run-with-gvisor.sh new file mode 100644 index 0000000..71a25b8 --- /dev/null +++ b/microapps/runtime/run-with-gvisor.sh @@ -0,0 +1,17 @@ +#!/usr/bin/env sh +set -eu + +IMAGE_NAME="${IMAGE_NAME:-clientflow/microapp-runtime}" +APP_DIR="${APP_DIR:-$(pwd)/microapps/templates/pocketbase-deno-dashboard}" +ALLOW_NET="${ALLOW_NET:-127.0.0.1,localhost}" + +docker run \ + --rm \ + --runtime=runsc \ + --memory=256m \ + --cpus=0.5 \ + --pids-limit=128 \ + -e APP_DIR=/workspace/app \ + -e ALLOW_NET="$ALLOW_NET" \ + -v "$APP_DIR:/workspace/app:ro" \ + "$IMAGE_NAME" diff --git a/microapps/templates/pocketbase-deno-dashboard/app.config.ts b/microapps/templates/pocketbase-deno-dashboard/app.config.ts new file mode 100644 index 0000000..2fc4d17 --- /dev/null +++ b/microapps/templates/pocketbase-deno-dashboard/app.config.ts @@ -0,0 +1,28 @@ +export default { + manifestVersion: 1, + name: "PocketBase Deno Dashboard", + slug: "pocketbase-deno-dashboard", + runtime: "deno-gvisor", + entrypoint: "./main.ts", + pocketbase: { + collections: ["dashboard_cards"], + collectionPrefix: "dashboard", + }, + permissions: { + allowEnv: [ + "PORT", + "POCKETBASE_URL", + "POCKETBASE_SERVICE_EMAIL", + "POCKETBASE_SERVICE_PASSWORD", + "APP_OWNER_TEAM_ID", + "APP_SLUG", + ], + allowNet: ["pocketbase.internal"], + allowRead: ["./"], + allowWrite: [], + }, + libraries: [ + "internal/pocketbase-client", + "internal/dashboard-ui", + ], +} as const; diff --git a/microapps/templates/pocketbase-deno-dashboard/deno.json b/microapps/templates/pocketbase-deno-dashboard/deno.json new file mode 100644 index 0000000..22350fb --- /dev/null +++ b/microapps/templates/pocketbase-deno-dashboard/deno.json @@ -0,0 +1,17 @@ +{ + "tasks": { + "dev": "deno run --watch --allow-read=. --allow-env=PORT,POCKETBASE_URL,POCKETBASE_SERVICE_EMAIL,POCKETBASE_SERVICE_PASSWORD,APP_OWNER_TEAM_ID,APP_SLUG --allow-net=127.0.0.1,localhost,pocketbase.internal main.ts", + "check": "deno check main.ts pocketbase/client.ts app.config.ts" + }, + "fmt": { + "lineWidth": 100, + "singleQuote": false + }, + "lint": { + "rules": { + "tags": [ + "recommended" + ] + } + } +} diff --git a/microapps/templates/pocketbase-deno-dashboard/main.ts b/microapps/templates/pocketbase-deno-dashboard/main.ts new file mode 100644 index 0000000..1f85030 --- /dev/null +++ b/microapps/templates/pocketbase-deno-dashboard/main.ts @@ -0,0 +1,162 @@ +import appConfig from "./app.config.ts"; +import { createPocketBaseClient } from "./pocketbase/client.ts"; + +const port = Number(Deno.env.get("PORT") || "8080"); +const pocketbaseUrl = mustGetEnv("POCKETBASE_URL"); +const pocketbaseEmail = mustGetEnv("POCKETBASE_SERVICE_EMAIL"); +const pocketbasePassword = mustGetEnv("POCKETBASE_SERVICE_PASSWORD"); +const ownerTeamId = mustGetEnv("APP_OWNER_TEAM_ID"); +const appSlug = Deno.env.get("APP_SLUG") || appConfig.slug; + +const pocketbase = createPocketBaseClient({ + baseUrl: pocketbaseUrl, + email: pocketbaseEmail, + password: pocketbasePassword, +}); + +type DashboardCard = { + id: string; + title: string; + metric: string; + description: string | null; +}; + +function renderHtml(cards: DashboardCard[]) { + const cardsMarkup = cards.length === 0 + ? `

No dashboard cards yet.

` + : cards.map((card) => ` +
+

${escapeHtml(card.title)}

+ ${escapeHtml(card.metric)} + ${escapeHtml(card.description || "No description")} +
+ `).join(""); + + return ` + + + + + ${escapeHtml(appConfig.name)} + + + +
+
+

PocketBase + Deno

+

${escapeHtml(appConfig.name)}

+

App slug: ${escapeHtml(appSlug)} • Team: ${escapeHtml(ownerTeamId)}

+
+
${cardsMarkup}
+
+ + `; +} + +function mustGetEnv(name: string) { + const value = Deno.env.get(name); + if (!value) { + throw new Error(`Missing required env: ${name}`); + } + return value; +} + +function escapeHtml(value: string) { + return value + .replaceAll("&", "&") + .replaceAll("<", "<") + .replaceAll(">", ">") + .replaceAll('"', """) + .replaceAll("'", "'"); +} + +async function handleRequest() { + const cards = await pocketbase.listRecords({ + collectionName: `${appConfig.pocketbase.collectionPrefix}_cards`, + filter: `teamId = "${ownerTeamId}"`, + }); + + return new Response(renderHtml(cards), { + headers: { + "content-type": "text/html; charset=utf-8", + }, + }); +} + +Deno.serve({ port }, () => handleRequest()); diff --git a/microapps/templates/pocketbase-deno-dashboard/pocketbase/client.ts b/microapps/templates/pocketbase-deno-dashboard/pocketbase/client.ts new file mode 100644 index 0000000..9ed65ed --- /dev/null +++ b/microapps/templates/pocketbase-deno-dashboard/pocketbase/client.ts @@ -0,0 +1,73 @@ +type PocketBaseClientOptions = { + baseUrl: string; + email: string; + password: string; +}; + +type PocketBaseListOptions = { + collectionName: string; + filter?: string; +}; + +type AuthResponse = { + token: string; +}; + +type RecordListResponse = { + items: TRecord[]; +}; + +export function createPocketBaseClient(options: PocketBaseClientOptions) { + let cachedToken: string | null = null; + + async function authenticate() { + if (cachedToken) return cachedToken; + + const response = await fetch( + `${options.baseUrl}/api/collections/_superusers/auth-with-password`, + { + method: "POST", + headers: { + "content-type": "application/json", + }, + body: JSON.stringify({ + identity: options.email, + password: options.password, + }), + }, + ); + + if (!response.ok) { + throw new Error(`PocketBase auth failed with status ${response.status}`); + } + + const payload = await response.json() as AuthResponse; + cachedToken = payload.token; + return cachedToken; + } + + return { + async listRecords(input: PocketBaseListOptions) { + const token = await authenticate(); + const url = new URL( + `${options.baseUrl}/api/collections/${input.collectionName}/records`, + ); + if (input.filter) { + url.searchParams.set("filter", input.filter); + } + + const response = await fetch(url, { + headers: { + Authorization: `Bearer ${token}`, + }, + }); + + if (!response.ok) { + throw new Error(`PocketBase list failed with status ${response.status}`); + } + + const payload = await response.json() as RecordListResponse; + return payload.items; + }, + }; +} diff --git a/microapps/validator/validate_microapp_repo.ts b/microapps/validator/validate_microapp_repo.ts new file mode 100644 index 0000000..96ddc09 --- /dev/null +++ b/microapps/validator/validate_microapp_repo.ts @@ -0,0 +1,69 @@ +const projectDir = Deno.args[0]; + +if (!projectDir) { + throw new Error("Usage: deno run --allow-read microapps/validator/validate_microapp_repo.ts "); +} + +const requiredFiles = new Set([ + "app.config.ts", + "deno.json", + "main.ts", + "pocketbase/client.ts", +]); + +const allowedTopLevelEntries = new Set([ + "app.config.ts", + "deno.json", + "main.ts", + "pocketbase", +]); + +const rootEntries = new Set(); + +for await (const entry of Deno.readDir(projectDir)) { + rootEntries.add(entry.name); +} + +for (const file of requiredFiles) { + const path = `${projectDir}/${file}`; + await Deno.stat(path); +} + +for (const entry of rootEntries) { + if (!allowedTopLevelEntries.has(entry)) { + throw new Error(`Unexpected top-level entry: ${entry}`); + } +} + +const configModule = await import(`file://${Deno.realPathSync(`${projectDir}/app.config.ts`)}`); +const config = configModule.default as { + manifestVersion?: number; + runtime?: string; + libraries?: string[]; + permissions?: { + allowEnv?: string[]; + allowNet?: string[]; + }; +}; + +if (config.manifestVersion !== 1) { + throw new Error("app.config.ts must export manifestVersion = 1"); +} + +if (config.runtime !== "deno-gvisor") { + throw new Error("app.config.ts must declare runtime = 'deno-gvisor'"); +} + +if (!Array.isArray(config.libraries) || config.libraries.length === 0) { + throw new Error("app.config.ts must declare at least one approved library"); +} + +if (!Array.isArray(config.permissions?.allowEnv) || config.permissions.allowEnv.length === 0) { + throw new Error("app.config.ts must declare allowEnv permissions"); +} + +if (!Array.isArray(config.permissions?.allowNet) || config.permissions.allowNet.length === 0) { + throw new Error("app.config.ts must declare allowNet permissions"); +} + +console.log(`Microapp repo at ${projectDir} matches the enforced template contract.`); diff --git a/skills/pocketbase-microapp-builder/SKILL.md b/skills/pocketbase-microapp-builder/SKILL.md new file mode 100644 index 0000000..07de69e --- /dev/null +++ b/skills/pocketbase-microapp-builder/SKILL.md @@ -0,0 +1,60 @@ +--- +name: pocketbase-microapp-builder +description: Use when creating or updating regulated microapps that must run on the PocketBase plus Deno gVisor platform. This skill scaffolds only from the approved template, validates the repo contract, and prepares control-plane metadata for delivery. +--- + +# PocketBase Microapp Builder + +Build only template-compliant microapps for the internal PocketBase + Deno + gVisor platform. + +## When to use + +Use this skill when the user asks to: + +- create a new regulated microapp; +- update an existing microapp that must stay inside the allowed platform contract; +- prepare a repo for preview/prod delivery on the microapp platform. + +Do not use this skill for arbitrary apps, unrestricted package installation, or custom runtime wiring outside the approved platform. + +## Approved platform contract + +- Template source: `../../microapps/templates/pocketbase-deno-dashboard` +- Validator: `../../microapps/validator/validate_microapp_repo.ts` +- Runtime image: `../../microapps/runtime/Dockerfile` +- Control-plane persistence: `../../backend/src/microapps/service.ts` + +The app must keep: + +- `app.config.ts` +- `deno.json` +- `main.ts` +- `pocketbase/client.ts` + +Only the approved top-level entries are allowed. + +## Workflow + +1. Copy the template from `../../microapps/templates/pocketbase-deno-dashboard`. +2. Edit only the app name, slug, collection names, UI copy, and business logic that still fits the template. +3. Keep runtime as `deno-gvisor`. +4. Keep PocketBase access through the local wrapper in `pocketbase/client.ts`. +5. Run: + +```bash +deno run --allow-read ../../microapps/validator/validate_microapp_repo.ts +``` + +6. Prepare control-plane metadata: +- repository path +- branch +- PocketBase URL +- PocketBase instance id +- preview/prod domains +- allowed hosts/env keys/libraries + +## Delivery expectations + +- Preview should be created from a validated repo version. +- Production should be promoted from a previously validated version. +- Rollback should target a previous deployment record instead of ad hoc hotfixing in runtime.