@jaimevalasek/aioson 1.30.0 → 1.30.2

package/template/.aioson/docs/play/manifest-and-runtime.md

@@ -0,0 +1,267 @@
+---
+description: "AIOSON Play app manifest, runtime, package manager, scripts, ports, endpoint declaration, split-stack, and compatibility contract."
+scope: "global"
+agents: [dev, deyvin, architect, qa, tester]
+task_types: [aioson-play-app, runtime, manifest]
+triggers: [manifest.json, Play runtime, PORT, pnpm, ProductBridge, /api/aioson-play, requires_services]
+---
+
+# Manifest And Runtime
+
+## Manifest basics
+
+`manifest.json` is the app identity and runtime contract for Play.
+
+Minimum shape:
+
+```json
+{
+  "slug": "meu-app",
+  "name": "Meu App",
+  "version": "0.1.0",
+  "runtime": "vite",
+  "has_api": true
+}
+```
+
+Use stable lowercase slugs. The same slug is reused by Play registry, `VITE_AIOSON_APP_SLUG`, auth binding, cloud app status, package/update metadata, and data bindings.
+
+## Runtime detection
+
+Play can detect common Node stacks from `package.json`, but explicit manifest fields are allowed when autodetect is not enough.
+
+Supported Node runtime families in current docs:
+
+| Stack | Signal |
+|---|---|
+| Next.js | `next` dependency |
+| Vite | `vite` dependency or devDependency |
+| Generic Node | `scripts.dev` |
+
+For Play drafts and AIOSON-authored app work, use `pnpm`:
+
+- `pnpm install`
+- `pnpm add <pkg>`
+- `pnpm add -D <pkg>`
+- canonical lockfile: `pnpm-lock.yaml`
+
+Do not create or preserve `package-lock.json` or `yarn.lock` in Play draft work unless an existing non-Play app explicitly requires it.
+
+## Scripts
+
+`package.json` should provide a single Play entrypoint:
+
+```json
+{
+  "scripts": {
+    "dev": "node src/server.js",
+    "start": "node dist/server.js"
+  }
+}
+```
+
+Rules:
+
+- `dev` must work when Play injects `PORT`.
+- `start` should work for published/build output when source is absent.
+- Do not put fixed app ports in scripts.
+- Do not run production build as the dev command.
+- In Play drafts, do not fight the Play-injected cache env vars for Next/Vite/SWC.
+
+## Ports
+
+Reserved ranges:
+
+| Range | Purpose |
+|---|---|
+| `3001-3099` | Play Services, fixed in `service.json` |
+| `3100-3299` | Internal Play systems, do not use |
+| `3300-3499` | Marketplace-installed apps |
+| `3500-3999` | Draft/dev-link apps |
+| `4000-4099` | External curated apps, compatibility range |
+| `5173` | Vite dev default, not a Play app contract |
+| `5180` | ProductBridge HTTP server |
+
+Rule: the app reads its own port from env; it discovers other ports through ProductBridge or service env vars.
+
+Generic Node server:
+
+```js
+const port = Number(process.env.PORT) || 3000;
+app.listen(port, "0.0.0.0");
+```
+
+Split-stack backend:
+
+```js
+const port = Number(process.env.BACKEND_PORT) || 3301;
+server.listen(port, "0.0.0.0");
+```
+
+## Split-stack apps
+
+Use split-stack when the app has separate frontend and backend processes.
+
+Manifest pattern:
+
+```json
+{
+  "slug": "meu-app",
+  "name": "Meu App",
+  "version": "0.1.0",
+  "stack": "split",
+  "processes": {
+    "frontend": { "port_env": "PORT", "framework": "vite" },
+    "backend": { "port_env": "BACKEND_PORT", "framework": "node" }
+  },
+  "webview_target": "frontend"
+}
+```
+
+Rules:
+
+- `webview_target` must match a key under `processes`.
+- The frontend port is for the Play webview.
+- Browser code should call `/api` same-origin and let Vite/Next proxy to the backend.
+- The backend should use `BACKEND_PORT`.
+- Do not hardcode `BACKEND_PORT` in scripts.
+
+## Next.js and Vite notes
+
+For Next.js in Play drafts, include `allowedDevOrigins` with explicit loopback hosts. Next 16+ does not accept a wildcard for this case.
+
+```ts
+const nextConfig = {
+  allowedDevOrigins: ["127.0.0.1", "localhost", "::1", "0.0.0.0"]
+};
+
+export default nextConfig;
+```
+
+For Vite in Play drafts, prefer the current AIOSON Play draft convention: let Play pass the port through its spawn command and avoid declaring a fixed `server.port` unless the existing app contract explicitly uses env-driven split-stack config.
+
+## ProductBridge
+
+ProductBridge is fixed at:
+
+```text
+http://localhost:5180
+```
+
+In browser/frontend code:
+
+```ts
+const PLAY_URL = import.meta.env.VITE_AIOSON_PLAY_URL || "http://localhost:5180";
+```
+
+Useful endpoints:
+
+| Endpoint | Purpose |
+|---|---|
+| `GET /api/registry` | Discover running apps and Play Services |
+| `GET /api/connectors` | List Global Connectors |
+| `GET /api/bindings/:app_slug` | List app bindings |
+| `POST /api/bindings/:app_slug` | Bind connector to app slot |
+| `POST /api/mcp/execute` | Execute connector by alias |
+
+## Capability endpoint
+
+If `has_api: true`, expose:
+
+```text
+GET /api/aioson-play
+```
+
+It declares identity, API base URL, endpoints, auth metadata, and events for Play, Bridge Apps, and LLM orchestration.
+
+Minimum response shape:
+
+```json
+{
+  "name": "Meu App",
+  "slug": "meu-app",
+  "version": "0.1.0",
+  "api_base_url": "http://localhost:3399",
+  "endpoints": [
+    {
+      "path": "/api/items",
+      "method": "GET",
+      "description": "Lista itens visiveis ao usuario",
+      "params": [],
+      "auth": false
+    }
+  ],
+  "events": []
+}
+```
+
+Only list endpoints that exist. The orchestrator may try to call what this endpoint advertises.
+
+## Services dependency
+
+When an app requires a Play Service:
+
+```json
+{
+  "requires_services": ["aioson-auth"]
+}
+```
+
+Play uses this to show onboarding requirements, check service install/runtime state, and block or degrade app launch when the required service is missing.
+
+For apps that use `aioson-auth`, declare the RBAC catalog in the same manifest:
+
+```json
+{
+  "requires_services": ["aioson-auth"],
+  "auth": {
+    "version": 1,
+    "permissions": [
+      "orders:read",
+      { "name": "orders:create", "label": "Criar pedidos" }
+    ],
+    "policies": [
+      { "id": "page:orders", "kind": "route", "path": "/orders", "requires": ["orders:read"] }
+    ]
+  }
+}
+```
+
+`auth.permissions[]` is the source of truth for the permission catalog shown by
+`aioson-auth`. The app still implements the actual route/API gates with the SDK;
+the Auth dashboard assigns the declared permissions to global roles. Play/Auth do
+not scan app source code to infer permissions.
+
+## Publish compatibility
+
+Publishable apps should declare compatibility:
+
+```json
+{
+  "compatibility": {
+    "min_play_version": "0.2.0",
+    "min_runtime_version": "1.0.0",
+    "max_runtime_version": "1.x",
+    "sidecar_contract": "ndjson-v1",
+    "schema_version": 1,
+    "requires_migration": false
+  }
+}
+```
+
+If local data schema changes:
+
+- Increment `schema_version`.
+- Provide idempotent migrations where possible.
+- Never delete user data as the default migration strategy.
+- Use backup before destructive or risky migration.
+
+## Source docs
+
+Canonical sources:
+
+- `ai-app-integration.md`
+- `aioson-endpoint-protocol.md`
+- `port-management.md`
+- `software-update-compatibility.md`
+- `.aioson/rules/aioson-play-conventions.md` in this repo

package/template/.aioson/docs/play/source-map.md

@@ -0,0 +1,104 @@
+---
+description: "Map from AIOSON Play app compatibility topics to canonical source docs in the aioson-play repository."
+scope: "global"
+agents: [dev, deyvin, architect, analyst, qa, tester, product, sheldon, pentester]
+task_types: [aioson-play-app, source-map, integration]
+triggers: [AIOSON Play source docs, canonical Play docs, integration docs, ProductBridge, data bindings]
+---
+
+# Source Map
+
+Canonical source directory:
+
+```text
+C:\dev\aioson-play\.aioson\docs\integrations\
+```
+
+This AIOSON folder is a curated operational layer. When exact Play runtime behavior matters and the source repo is present, read the canonical file below.
+
+## Entry points
+
+| Need | Canonical doc |
+|---|---|
+| Build or modify a Play-compatible app | `ai-app-integration.md` |
+| Cross-cutting Play/platform fix | `platform-architecture.md` |
+| Auth roadmap/gaps and delivered slices | `auth-integration-gaps.md` |
+
+## Topic map
+
+| Topic | Canonical doc |
+|---|---|
+| App developer overview | `aioson-app-developer-guide.md` |
+| `/api/aioson-play` capability endpoint | `aioson-endpoint-protocol.md` |
+| ProductBridge and port registry | `port-management.md` |
+| Play Services and `service.json` | `play-service-protocol.md` |
+| Cloud owner/trial auth | `app-cloud-auth.md` |
+| Data Bindings and Global Connectors | `app-data-bindings.md` |
+| App operational database choice | `app-database-choice.md` |
+| External systems, MCPI/API/MCP connector manual | `integration-manual.md` |
+| Dev-link install | `dev-link-install.md` |
+| Local symlink testing | `local-dev-testing.md` |
+| App update and compatibility fields | `software-update-compatibility.md` |
+| Atendimento reference integration | `atendimento-squad-integration.md` |
+| Farmacia implementation review | `farmacia-implementation-review.md` |
+
+## Current source docs observed
+
+As of 2026-06-23, the Play integration source directory contains:
+
+```text
+ai-app-integration.md
+aioson-app-developer-guide.md
+aioson-endpoint-protocol.md
+app-cloud-auth.md
+app-data-bindings.md
+app-database-choice.md
+atendimento-squad-integration.md
+auth-integration-gaps.md
+dev-link-install.md
+farmacia-implementation-review.md
+integration-manual.md
+local-dev-testing.md
+platform-architecture.md
+play-service-protocol.md
+port-management.md
+README.md
+software-update-compatibility.md
+```
+
+## Embedded contract stamped into apps
+
+Play stamps a canonical contract directly into each app, between
+`AIOSON-PLAY-CONTRACT:START` / `AIOSON-PLAY-CONTRACT:END` markers. Source:
+
+```text
+C:\dev\aioson-play\src-tauri\src\resources\play_app_contract.md
+```
+
+This is the most authoritative single-file contract for an installed app. It carries:
+
+- The closed whitelist of env vars Play injects at spawn, including `AIOSON_APP_DIR` (absolute app dir) and the auth vars in `VITE_`-only form.
+- `.aioson/preview.json` — written by Play at runtime with `{ running, url, port }`; read it on demand to learn the live preview URL/port instead of guessing.
+- The "ready-for-Play" gate the app must pass before being declared done.
+
+When an app project already contains this stamped block, treat it as primary and do not contradict it. The docs in this folder are the AIOSON-side fallback when the stamped contract or the `aioson-play` repo is not available.
+
+## Known priority notes
+
+- `.aioson/rules/aioson-play-conventions.md` in this AIOSON repo overrides older examples when working inside Play drafts, especially package manager and draft runtime behavior.
+- Older Play docs may show `npm` examples. In AIOSON-authored Play draft work, use `pnpm`.
+- Some canonical docs describe planned behavior. Check wording before implementing: "planejado", "futuro", "pendente", or "nao implementado" means do not rely on it as shipped runtime behavior.
+- If a canonical doc and local Play source code disagree, inspect code and update the canonical Play doc before relying on the changed behavior.
+
+## Suggested human-facing Play Guide page
+
+If AIOSON Play exposes a "Guia" tab for human users, it should not dump these agent docs. It should present a short human path:
+
+1. Create an app folder with `manifest.json`.
+2. Use `pnpm`.
+3. Make the app read `PORT`.
+4. Add `app-config.yaml` only when using database config or data sources.
+5. Link the folder through "Instalar App -> Linkar pasta (dev)".
+6. Test inside the Play webview.
+
+The detailed implementation contract should remain here for AIOSON agents and in the canonical `aioson-play` integration docs.