feat(ai-workspace): add local relay profiles

2026-06-20 12:54:19 +03:00
parent 2d5fef3948
commit 3526351b1b
28 changed files with 2959 additions and 77 deletions
@@ -0,0 +1,106 @@
+# NODE.DC Environment Contract
+
+This contract separates local feature testing from deployed runtime.
+
+## Profiles
+
+`local`
+
+- Runs Launcher, Engine, Ops/Gateway, AI Workspace Assistant, databases, and fixtures on the developer machine.
+- May use the deployed AI Hub only as a thin relay for a remote Codex worker.
+- Must not call production Launcher, Engine, Ops, Authentik, or Gateway endpoints.
+
+`tunnel-local-e2e`
+
+- Explicit escape hatch for Tailscale/ngrok-style testing.
+- Same business services are still local, but relay URLs may use tunnel/private addresses.
+- Must be opt-in through `NODEDC_ENV=tunnel-local-e2e`.
+
+`staging`
+
+- Deployed test stack with staging data and staging Authentik/OIDC clients.
+- Used after local smoke is green.
+
+`prod`
+
+- Production data and production public domains.
+- Only deploy artifacts that passed local and staging checks.
+
+## URL Classes
+
+- Browser URL: opened by a user browser.
+- Internal service URL: used by one backend to call another backend.
+- Relay URL: used only to move messages between a local assistant and a remote worker.
+- Downstream app URL: used by an assistant adapter to read or mutate its owning app.
+
+Do not mix these classes. A remote worker must not call Launcher, Engine, Ops, or Authentik directly in `local`.
+
+## Local Remote Worker Chain
+
+```text
+local Engine
+  -> local AI Workspace Assistant
+  -> deployed AI Hub relay
+  -> remote Codex worker
+  -> deployed AI Hub relay
+  -> local AI Workspace Assistant
+  -> local Launcher / local Engine / local Ops
+```
+
+The deployed AI Hub is transport only. It must not decide product access, own app routes, or force production downstream URLs.
+
+## Required Local Defaults
+
+Engine local server:
+
+```text
+NODEDC_ENV=local
+NODEDC_LAUNCHER_INTERNAL_URL=http://127.0.0.1:5173
+NODEDC_LAUNCHER_ORIGIN=http://launcher.local.nodedc
+AUTHENTIK_PUBLIC_BASE_URL=http://auth.local.nodedc
+NODEDC_AI_WORKSPACE_ASSISTANT_URL=http://127.0.0.1:18082
+OPS_RETENTION_ENABLED=false
+```
+
+Platform local stack:
+
+```text
+NODEDC_ENV=local
+AI_WORKSPACE_HUB_PUBLIC_URL=wss://ai-hub.nodedc.ru/api/ai-workspace/hub
+AI_WORKSPACE_HUB_INTERNAL_URL=https://ai-hub.nodedc.ru
+AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ENABLED=true
+AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ID=local-dev
+```
+
+The AI Hub URLs above are allowed only because they are relay URLs. Production app URLs such as `https://hub.nodedc.ru`, `https://engine.nodedc.ru`, `https://ops.nodedc.ru`, and `https://id.nodedc.ru` are forbidden in local app config.
+
+Assistant action calls in local must use the relay route:
+
+```text
+remote worker assistant_action_call
+  -> deployed AI Hub /api/ai-workspace/hub/v1/assistant-relays/<relayId>/actions
+  -> local AI Workspace Assistant long-poll
+  -> local Launcher / Engine / Ops adapter
+```
+
+Do not route local assistant actions through the deployed Assistant or deployed product backends.
+
+## Guardrail
+
+Run the complete local testing gate before local AI Workspace testing:
+
+```sh
+sh platform/infra/scripts/check-local-test-system.sh
+```
+
+Run this narrower env-only guard when changing env files:
+
+```sh
+node platform/infra/scripts/check-local-environment-safety.mjs
+```
+
+Run the broader AI Workspace contract check before changing worker/assistant routing:
+
+```sh
+platform/infra/scripts/check-ai-workspace-config-contract.sh
+```