@jaimevalasek/aioson 1.30.0 → 1.30.2

package/template/.aioson/docs/play/auth-services-and-testing.md

@@ -0,0 +1,235 @@
+---
+description: "AIOSON Play auth, cloud owner token, local operator auth, Play Services, requires_services, dev-link, symlink installs, and smoke testing."
+scope: "global"
+agents: [dev, deyvin, architect, qa, tester, pentester]
+task_types: [aioson-play-app, auth, service-integration, testing]
+triggers: [aioson-auth, AIOSON_COM_TOKEN, requires_services, service.json, dev-link, Play Services, smoke test]
+---
+
+# Auth, Services, And Testing
+
+## Auth systems
+
+AIOSON Play has two different auth surfaces:
+
+| Surface | Purpose | App receives |
+|---|---|---|
+| `aioson.com` cloud auth | Owner identity, trial, billing, license/status | `AIOSON_COM_TOKEN` |
+| `aioson-auth` Play Service | Local operators, login, RBAC, permissions | service URL and binding id |
+
+Do not mix them.
+
+Use `aioson.com` when the app needs subscription/trial/license state.
+Use `aioson-auth` when the app needs operators, roles, permissions, 2FA, or local RBAC.
+
+## Cloud owner/trial auth
+
+When the owner is logged into AIOSON Play, Play can inject:
+
+```text
+AIOSON_COM_TOKEN=<bearer token>
+```
+
+The app should read it on backend startup and persist it in local settings if needed. If absent, the app should fall back to manual login or a disconnected state.
+
+Do not call `https://aioson.com` directly from browser code with this token. Use backend proxy routes.
+
+Recommended backend proxy routes:
+
+| App route | Purpose |
+|---|---|
+| `GET /api/aioson/connection` | Check local token state |
+| `GET /api/aioson/status?projectId={id}` | Proxy app subscription/trial status |
+| `POST /api/aioson/login` | Manual cloud login fallback |
+| `DELETE /api/aioson/logout` | Clear local token |
+
+Cloud endpoints the backend may call:
+
+| Endpoint | Purpose |
+|---|---|
+| `POST /api/app-auth/token` | Manual token acquisition |
+| `POST /api/apps/{slug}/install` | Idempotent install/trial registration |
+| `GET /api/apps/{slug}/status?projectId={id}` | Subscription/trial status |
+
+## Local operator auth and RBAC
+
+For operator login and RBAC, depend on `aioson-auth`:
+
+```json
+{
+  "requires_services": ["aioson-auth"],
+  "auth": {
+    "version": 1,
+    "permissions": ["orders:read", "orders:create"],
+    "policies": [
+      { "id": "page:orders", "kind": "route", "path": "/orders", "requires": ["orders:read"] }
+    ]
+  }
+}
+```
+
+`auth.permissions[]` is the app-owned permission catalog. Play syncs it through
+the owner-only app inventory; `aioson-auth` registers it on the existing binding
+so the admin can assign permissions to global roles. Do not rely on Auth scanning
+app source code.
+
+Use `@aioson/auth-sdk` as the client layer when available. Avoid handwritten calls to auth endpoints unless the SDK cannot cover the specific case.
+
+Env vars Play injects for auth (only these exist):
+
+```text
+VITE_AIOSON_AUTH_URL=http://localhost:3001
+VITE_AIOSON_AUTH_BINDING_ID=<binding-id>
+```
+
+Play injects only the `VITE_`-prefixed auth vars. There is no `AIOSON_AUTH_URL` or `AIOSON_AUTH_BINDING_ID` without the prefix — do not read those, they will be `undefined`. Backend Node code reads the same injected vars through `process.env.VITE_AIOSON_AUTH_URL` and `process.env.VITE_AIOSON_AUTH_BINDING_ID`; the `VITE_` prefix does not stop Node from reading them at runtime. The app slug is the only auth-relevant value injected in both forms: `AIOSON_APP_SLUG` and `VITE_AIOSON_APP_SLUG`.
+
+Bearer header is preferred for auth calls:
+
+```http
+Authorization: Bearer <jwt>
+```
+
+Legacy `?token=` may still work in older paths, but new app code should prefer Bearer.
+
+Current implemented auth expectations from the Play docs:
+
+- JWT can include `binding_id` and `permissions`.
+- App permissions are declared in `manifest.json` `auth.permissions[]` and implemented by the app with SDK gates.
+- `/me/permissions` exists in `aioson-auth`.
+- `@aioson/auth-sdk` MVP exists.
+- Operator SSO token injection from Play keyring is planned in docs, not safe to rely on unless the local code confirms it.
+
+## Owner bypass
+
+Some flows allow owner-implicit behavior through the owner cloud identity. Do not use that as a replacement for operator RBAC when the app has real multi-user operator roles.
+
+## Play Services
+
+A Play Service is infrastructure, not an app webview.
+
+Service shape:
+
+```text
+service/
+  service.json
+  package.json
+  dist/
+```
+
+`service.json`:
+
+```json
+{
+  "slug": "aioson-auth",
+  "name": "AIOSON Auth",
+  "version": "1.0.0",
+  "description": "Servico de autenticacao para apps do AIOSON Play.",
+  "port": 3001,
+  "autostart": true,
+  "dev_command": "node dist/server.js",
+  "health_check": "/health"
+}
+```
+
+Rules:
+
+- Use ports in `3001-3099`.
+- Read `process.env.PORT` in the service.
+- Implement `GET /health`.
+- Configure CORS for localhost app origins.
+- Do not depend on Tauri APIs inside a Play Service.
+- Build to `dist/` before publishing or local symlink service testing.
+
+## Dev-link install
+
+Use dev-link for active app development:
+
+```text
+AIOSON Play -> Instalar App -> Linkar pasta (dev) -> select app folder with manifest.json
+```
+
+Dev-link creates a symlink from Play's app data directory to the source folder. It allows fast iteration, but it is not a production publish validation.
+
+Windows note: symlink creation normally needs Developer Mode enabled or elevated privileges.
+
+When `manifest.json` changes during dev-link, stop and reopen the app in Play to force manifest reload.
+
+## Local symlink layout
+
+Common Play data locations:
+
+```text
+Windows: %LOCALAPPDATA%\com.aioson.play\
+Linux:   ~/.local/share/com.aioson.play/
+```
+
+Inside:
+
+```text
+apps/{slug}/
+services/{slug}/
+```
+
+For manual local testing, symlink app or service folders there. Prefer the Play UI dev-link flow when available.
+
+## Testing an app
+
+Standalone smoke:
+
+```bash
+PORT=3399 pnpm dev
+curl http://localhost:3399/api/health
+curl http://localhost:3399/api/aioson-play
+```
+
+Play smoke:
+
+```text
+1. Start AIOSON Play.
+2. Dev-link the app folder.
+3. Open the app from the Play shell.
+4. Confirm badge/running state.
+5. Confirm webview renders.
+6. Confirm ProductBridge calls to :5180 work.
+7. Confirm missing auth/bindings show clear degraded states.
+```
+
+Data binding smoke:
+
+```bash
+curl http://localhost:5180/api/registry
+curl http://localhost:5180/api/connectors
+curl http://localhost:5180/api/bindings/meu-app
+```
+
+Service smoke:
+
+```bash
+curl http://localhost:3001/health
+```
+
+## QA checklist
+
+- [ ] `requires_services` matches actual service use.
+- [ ] Apps using `aioson-auth` declare `auth.permissions[]` in `manifest.json`.
+- [ ] Frontend and backend gates use `@aioson/auth-sdk` or a Bearer-compatible server check for those permissions.
+- [ ] Missing service does not produce a confusing crash.
+- [ ] `AIOSON_COM_TOKEN` is never exposed to frontend code.
+- [ ] Operator auth uses SDK or Bearer-compatible client.
+- [ ] `VITE_AIOSON_AUTH_BINDING_ID` absence is handled.
+- [ ] Service uses `process.env.PORT`.
+- [ ] Service has `/health`.
+- [ ] App dev-link reload was tested after manifest changes.
+- [ ] ProductBridge `:5180` endpoints are called only when Play is running or with a fallback/degraded path.
+
+## Source docs
+
+Canonical sources:
+
+- `app-cloud-auth.md`
+- `auth-integration-gaps.md`
+- `play-service-protocol.md`
+- `dev-link-install.md`
+- `local-dev-testing.md`
+- `platform-architecture.md`

package/template/.aioson/docs/play/llm-data-and-bindings.md

@@ -0,0 +1,238 @@
+---
+description: "How AIOSON Play apps should consume LLM connections, app-owned databases, Data Bindings, Global Connectors, MCPI, REST connectors, MCP tools, and ProductBridge."
+scope: "global"
+agents: [dev, deyvin, architect, analyst, qa, tester]
+task_types: [aioson-play-app, data-integration, llm-integration]
+triggers: [LLM connections, DATABASE_URL, data_bindings, Global Connectors, MCPI, MCP tools, ProductBridge]
+---
+
+# LLM, Data, And Bindings
+
+## Three separate surfaces
+
+Do not mix these:
+
+| Surface | Owner | App does |
+|---|---|---|
+| LLM connections | AIOSON Play Settings | Reads injected env vars or metadata and lazy-inits clients |
+| Operational app DB | The app | Reads `DATABASE_URL`, runs migrations, owns data |
+| External/domain data | Play Global Connectors | Declares `data_bindings`, binds aliases, calls ProductBridge |
+
+## LLM connections
+
+Play manages global LLM connections in Settings:
+
+- one API key per provider
+- models validated by operation
+- fallback order by operation
+- capabilities such as vision/audio inferred from validated models
+
+Apps should not store Play LLM secrets in repository files or frontend code.
+
+Expected app behavior:
+
+- Prefer app-local explicit config only when the app intentionally lets the user override provider settings.
+- Otherwise read provider API keys injected by Play during spawn, such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `OPENROUTER_API_KEY`.
+- Lazy-initialize LLM clients. Do not instantiate SDK clients at module load, because missing keys can crash the backend before the app can render a degraded state.
+- Treat `llm-chain.json` as metadata/order only when present. It must not contain API keys.
+- Treat `aioson-models.json` or `llm-chain.json` in the app cwd as optional/legacy for installed apps, not the primary credential contract.
+
+Recommended lazy pattern:
+
+```ts
+let client: OpenAI | null = null;
+
+function getOpenAiClient() {
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey) return null;
+  client ??= new OpenAI({ apiKey });
+  return client;
+}
+```
+
+Supported operation names in current Play docs include:
+
+- `text_generation`
+- `code_generation`
+- `image_understanding`
+- `image_generation`
+- `video_understanding`
+- `video_generation`
+- `speech_to_text`
+- `text_to_speech`
+- `audio_understanding`
+- `realtime_voice`
+
+## Operational database of the app
+
+The app owns its own operational database. Play does not provide a shared app database.
+
+Default recommendation:
+
+- SQLite with WAL mode for most local-first apps.
+- Read `DATABASE_URL` from env with fallback to `app-config.yaml`.
+- Declare supported drivers from day 1 even if only SQLite is used.
+
+`app-config.yaml` pattern:
+
+```yaml
+database:
+  default_url: "sqlite://./data/app.db?mode=rwc"
+  supported_drivers: ["sqlite", "postgres"]
+  sqlite_pragmas:
+    journal_mode: "WAL"
+    synchronous: "NORMAL"
+    busy_timeout: 5000
+```
+
+App code pattern:
+
+```ts
+const url = process.env.DATABASE_URL ?? config.database.default_url;
+const driver = url.startsWith("postgres://") ? "postgres" : "sqlite";
+const db = await connect(url, driver);
+
+if (driver === "sqlite") {
+  await db.exec("PRAGMA journal_mode=WAL");
+  await db.exec("PRAGMA synchronous=NORMAL");
+  await db.exec("PRAGMA busy_timeout=5000");
+}
+```
+
+Only move beyond SQLite when there is an objective need, such as:
+
+- persistent `SQLITE_BUSY` after WAL and `busy_timeout`
+- `pgvector`
+- serious JSONB indexing
+- full-text ranking beyond SQLite FTS5
+- multiple app processes writing to the same database
+- pre-existing customer Postgres infrastructure
+- multi-device sync or online-first architecture
+
+## External data through Data Bindings
+
+External domain data belongs to Play Global Connectors, not to app-specific connection UIs.
+
+The app declares slots in `app-config.yaml`:
+
+```yaml
+data_bindings:
+  - id: "busca-produtos"
+    description: "Busca produtos no catalogo por nome ou principio ativo"
+    accepted_types: ["mcpi", "api", "mcp"]
+    required_params:
+      - "search"
+
+  - id: "webhook-pedido"
+    description: "Notifica sistema externo quando um pedido e confirmado"
+    accepted_types: ["api"]
+    required_params:
+      - "pedido_json"
+```
+
+Fields:
+
+| Field | Meaning |
+|---|---|
+| `id` | Slot slug. Also the binding alias. Prefer kebab-case. |
+| `description` | Human-readable text for the app/admin UI. |
+| `accepted_types` | Canonical array: `mcpi`, `api`, `mcp`. |
+| `required_params` | Placeholder names expected by the connector. |
+
+`expected_type` is legacy. Prefer `accepted_types` in new apps.
+
+## What Play owns
+
+Play Settings owns:
+
+- Database Connections
+- Data Connectors
+- credential/keyring storage for connector auth
+- connector validation status
+- global admin view of App Data Sources
+
+For MCPI connectors, only validated Database Connections should be selectable when the driver supports validation.
+
+## What the app owns
+
+The app should expose a "Fontes de Dados" or equivalent in-app view when it has `data_bindings`.
+
+The app consumes ProductBridge:
+
+```ts
+const PLAY_BASE = import.meta.env.VITE_AIOSON_PLAY_URL || "http://localhost:5180";
+const APP_SLUG = import.meta.env.VITE_AIOSON_APP_SLUG || "meu-app";
+
+const connectors = await fetch(`${PLAY_BASE}/api/connectors?type=mcpi`).then(r => r.json());
+const bindings = await fetch(`${PLAY_BASE}/api/bindings/${APP_SLUG}`).then(r => r.json());
+
+await fetch(`${PLAY_BASE}/api/bindings/${APP_SLUG}`, {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({
+    connector_id: "<uuid-do-connector>",
+    alias: "busca-produtos"
+  })
+});
+```
+
+## Executing connectors
+
+After binding, execute through ProductBridge by alias:
+
+```http
+POST http://localhost:5180/api/mcp/execute
+Content-Type: application/json
+
+{
+  "alias": "busca-produtos",
+  "params": {
+    "search": "dipirona"
+  }
+}
+```
+
+The alias must match both:
+
+- `data_bindings[].id`
+- the active binding alias
+
+## Degraded state
+
+If a declared binding is absent:
+
+- Do not crash.
+- Show a clear degraded state.
+- Link the user to the app's data-source binding UI when possible.
+- For non-optional connectors, block only the affected workflow, not the whole app unless the app cannot function.
+
+Boot check:
+
+```ts
+async function getMissingBindings(appSlug: string) {
+  const playBase = import.meta.env.VITE_AIOSON_PLAY_URL || "http://localhost:5180";
+  const bindings = await fetch(`${playBase}/api/bindings/${appSlug}`).then(r => r.json());
+  const activeAliases = new Set(bindings.map((b: { alias: string }) => b.alias));
+  return declaredBindings.filter(binding => !activeAliases.has(binding.id));
+}
+```
+
+## LLM tool injection
+
+Global Connectors are only useful to the LLM after they are bound to the app. Play can generate tool metadata from bindings, and the sidecar/orchestrator can use it in LLM payloads.
+
+Agent rule:
+
+- Keep connector names and descriptions accurate.
+- Do not advertise tools/endpoints that are not implemented.
+- Use prepared statements or connector-side parameterization for MCPI. The LLM must not assemble raw SQL.
+
+## Source docs
+
+Canonical sources:
+
+- `app-data-bindings.md`
+- `app-database-choice.md`
+- `integration-manual.md`
+- `ai-app-integration.md`
+- `platform-architecture.md`