@enterpriseai/cli 3.19.0 → 3.19.2

package/resources/gofer/references/platform/eai-auth-access.md

@@ -0,0 +1,104 @@
+# App Access And Client Sign-In
+
+## Business Decision
+
+Sign-in confirms who a person is. It does not grant workspace access. An EAI
+workspace is the app's access boundary. It is separate from the shared CIAM
+sign-in directory.
+
+When authentication enters scope, ask:
+
+> Who should be able to use this app: only members of its EAI workspace
+> (recommended), or any authenticated EAI user?
+
+Default to `workspace-only`. Wait for the answer before changing auth code. Do
+not treat silence as approval. Continue unrelated approved work if possible.
+Keep stricter existing restrictions. Do not silently change an existing app's
+access policy. Ask again when the owner changes this decision.
+
+| Choice                   | App access                                                             | Data access                                                                               |
+| ------------------------ | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `workspace-only`         | Verified members of the configured workspace who meet app permissions. | Only the resources permitted by their roles.                                              |
+| `platform-authenticated` | Valid EAI users may enter the explicitly approved app experience.      | Workspace data still needs explicit authorization. No automatic membership or admin role. |
+
+The wider option needs an approved onboarding and data-isolation design. Do not
+use an app credential to give a visitor the owner's workspace access.
+
+Record the choice, rationale, confirmation, target workspace reference, app
+permissions, and tests in `spec.md`. Keep real tenant IDs and secrets out of
+public artifacts. Update plan, tasks, traceability, and validation on changes.
+
+## Server-Side Enforcement
+
+Verify identity and permissions on protected pages, server actions, and APIs.
+Resolve membership from the approved platform contract using the authenticated
+user and the configured app workspace. Do not trust a client-supplied tenant ID.
+Apply the platform's verified membership semantics, including inherited access
+only when the contract permits it. Do not assume direct membership is the only
+valid form of membership.
+
+A session, shared CIAM `tid`, matching email domain, hidden button, or selected
+CLI workspace access is not app authorization. The CLI operator is not the
+runtime user. Unknown, unavailable, revoked, or expired authorization must fail
+closed. Define bounded cache expiry and revocation handling. Never keep access
+forever because an earlier session was valid.
+
+## Separate Sign-In Decision
+
+Ask whether users should use normal EAI sign-in or their company sign-in through
+EAI. This does not change the app's workspace access policy. For client SSO,
+prefer federation through EAI's identity layer so platform sessions, API
+audiences, workspace membership, and permission checks remain intact. Do not
+point the app directly at a client issuer and assume EAI APIs accept it.
+
+Discover the installed CLI with `eai --describe` and exact command help. Never
+invent an `eai sso` command. Check the deployed platform contract and tenant
+entitlement before offering a configuration action. Provider capability, backend
+source, a setup menu, and successful end-to-end sign-in are different levels of
+evidence.
+
+## Workspace Admin SSO Setup
+
+1. Confirm the EAI workspace, app, current access decision, and SSO entitlement.
+2. Identify the client's identity administrator and approved provider.
+3. Verify the supported EAI setup route. If no supported CLI or admin screen
+   exists, request platform support. Do not bypass it with guessed endpoints.
+4. Have the client administrator prepare the federation registration, issuer,
+   callback settings, and required claims. Transfer secrets only through an
+   approved protected channel, never chat, specs, source, or logs.
+5. Have an authorized EAI operator configure the provider and associate the
+   intended user flow and apps. The platform role ID `tenant-admin` grants
+   workspace admin access. That role does not grant administration of the shared
+   Entra directory. Protect other workspaces' flows.
+6. Plan existing-account continuity and preserve memberships and roles. Never
+   link identities by email alone. Keep a tested emergency admin sign-in path.
+7. Test a pilot user, a denied user, session creation, and a protected EAI API
+   call before rollout. Test rollback and document who owns credential renewal.
+
+Adding SSO is not proof that existing CIAM users have migrated. Do not remove
+their original sign-in method until identity continuity and recovery pass.
+
+Microsoft documents Entra workforce sign-in through custom OIDC federation. It
+requires client registration, provider configuration, user-flow association, and
+sign-in testing. This vendor support does not prove the deployed EAI setup
+supports that path. Recheck EAI if it reports an older restriction.
+[Microsoft setup guide](https://learn.microsoft.com/en-us/entra/external-id/customers/how-to-entra-id-federation-customers).
+
+## Required Evidence
+
+Apply these checks when authentication is implemented or required. Do not add
+auth requirements to non-app work or an auth-free local MVP.
+
+- An authorized workspace member completes the first protected journey.
+- An authenticated non-member cannot access protected workspace content.
+- Anonymous users cannot access protected content.
+- A forged workspace selection cannot change the authorization boundary.
+- A revoked member loses access within the documented revocation bound.
+- An unavailable membership service does not grant access.
+- The wider mode, when approved, still denies unauthorized workspace data.
+- A federated pilot retains the correct EAI identity, memberships, and roles.
+- Changing the sign-in provider does not widen the approved access policy.
+
+Record browser and API evidence against acceptance criteria. If tests cannot
+run, mark the affected outcome unverified. Instructions and passing source tests
+do not prove that a customer's app or SSO configuration is secure.

package/resources/gofer/references/platform/eai-config-driven-ui.md

@@ -7,8 +7,8 @@ an app based on `https://github.com/eai-support/eai-app-template`.
 
 | File                        | Purpose                                                                         |
 | --------------------------- | ------------------------------------------------------------------------------- |
-| `src/eai.config/default.ts` | Default workspace config, store slices, API paths, storage keys, and layout slots. |
-| `src/eai.config/index.ts`   | Workspace key to config registry.                                                  |
+| `src/eai.config/default.ts` | Default tenant config, store slices, API paths, storage keys, and layout slots. |
+| `src/eai.config/index.ts`   | Tenant key to config registry.                                                  |
 | `src/eai.blocks.tsx`        | Component registry and app-local block extension point.                         |
 | `src/app/providers.tsx`     | Auth/session providers and EAI config runtime.                                  |
 | `src/hooks/useResources.ts` | ResourceAPI-backed business data.                                               |
@@ -48,7 +48,7 @@ Rules:
 
 - `component` must match a registered component name.
 - Lower `priority` renders first.
-- `props` are static, workspace configurable values.
+- `props` are static, tenant-configurable values.
 - `storeBindings` support dot notation on both `prop` and `storePath`.
 - `showWhen` supports `equals`, `notEquals`, `exists`, and compound `and`/`or`.
 
@@ -95,7 +95,7 @@ store: {
 }
 ```
 
-Persist only workspace-safe UI or workflow state. Never place access tokens,
+Persist only tenant-safe UI or workflow state. Never place access tokens,
 platform credentials, database connection details, blob credentials, search
 credentials, or model provider credentials in config or store state.
 
@@ -130,7 +130,7 @@ The config-driven UI should pair with the service matrix:
 
 | UI Need                                               | Service Pattern                                            |
 | ----------------------------------------------------- | ---------------------------------------------------------- |
-| Workspace business records                               | `useResources('<ObjectType>')`                             |
+| Tenant business records                               | `useResources('<ObjectType>')`                             |
 | File upload, document classification, or RAG indexing | `useDocuments()`                                           |
 | AI chat or workflow interaction                       | `useChat(workflowId, stage)`                               |
 | Browser streaming                                     | `/api/eai/stream/...` through the app BFF                  |

package/resources/gofer/references/platform/eai-error-catalog.yaml

@@ -41,13 +41,11 @@ catalog:
   - errorId: EAI_TENANT_ACCESS_REQUIRED
     match:
       containsAny:
-        - 'no workspace'
         - 'no tenant'
-        - 'workspace required'
-        - 'workspace required'
-        - 'insufficient workspace role'
-    meaning: The user lacks the workspace context needed for app delivery.
-    likelyCause: No membership, wrong workspace, or insufficient role.
+        - 'tenant required'
+        - 'insufficient tenant role'
+    meaning: The user lacks the workspace access needed for app delivery.
+    likelyCause: No membership, the wrong workspace, or an insufficient role.
     recovery:
       - 'eai workspace list --format json'
       - 'eai workspace select <workspace-slug>'
@@ -61,7 +59,7 @@ catalog:
         - 'Invite failed'
         - 'eai user invite'
         - '502'
-    meaning: A workspace member invite or role assignment reached an external service failure, and the target person may already exist as a direct workspace member with the wrong role.
+    meaning: A workspace member invite or role assignment reached an external service failure, and the target person may already have direct workspace membership with the wrong role.
     likelyCause: The invite/add path failed after, or despite, an existing workspace member record. Retrying the same invite may not change the member role.
     recovery:
       - 'Run eai errors explain user_invite_external_service_existing_member --format json when advertised'
@@ -73,6 +71,24 @@ catalog:
       - 'Tell the affected app user to sign out and sign back in because Auth.js session or JWT role data may be cached'
       - 'Do not edit databases or cloud portals directly unless EAI guidance reports an operator-only block'
     nextGate: tenant_member_role_verified
+  - errorId: EAI_APP_TOKEN_TENANT_CONTEXT_REQUIRED
+    match:
+      containsAny:
+        - 'app_token_tenant_context_required'
+        - 'MISSING_TENANT'
+        - 'Tenant context required for app tokens'
+    meaning: A platform automation app-token user lookup reached EAI but did not carry the required workspace context.
+    likelyCause: The caller used a root platform user or membership route such as /v4/platform/users/by-email or /v4/platform/users/{oid}/memberships instead of the tenant-scoped /v4/platform/tenants/{tenantId}/... route family, or the target environment has not deployed the matching PublicAPI/AdminAPI tenant-scoped routing hardening.
+    recovery:
+      - 'Run eai errors explain app_token_tenant_context_required --format json when advertised'
+      - 'eai whoami'
+      - 'eai workspace list --format json'
+      - 'Do not start by changing workspace members, role definitions, Entra configuration, databases, or cloud portals'
+      - 'Retry user lookup through /v4/platform/tenants/<tenant-id>/users/by-email?email=<email>'
+      - 'Retry membership lookup through /v4/platform/tenants/<tenant-id>/users/<oid>/memberships'
+      - 'Keep workspace member and role-definition reads on /v4/platform/tenants/<tenant-id>/members and /v4/platform/tenants/<tenant-id>/role-definitions'
+      - 'If workspace-scoped routes still return MISSING_TENANT, capture redacted route shape, HTTP status, server code, CLI version, active workspace slug, and deployed PublicAPI/AdminAPI versions for platform support'
+    nextGate: tenant_scoped_platform_route_verified
   - errorId: EAI_ENTRA_REDIRECT_URI_MISMATCH
     match:
       containsAny:
@@ -150,9 +166,23 @@ catalog:
     meaning: Object types cannot be published until app resources are provisioned.
     likelyCause: '`eai types seed` ran before `eai app provision` completed.'
     recovery:
-      - 'eai app provision <key> --tenant-id <workspace-id> --select --format json'
-      - 'eai types validate'
-      - 'eai types seed --tenant-key <key> --tenant-id <workspace-id> --format json'
+      - 'eai app provision <key> --tenant-id <tenant-id> --select --format json'
+      - 'eai types validate --tenant-key <key> --tenant-id <tenant-id>'
+      - 'eai types seed --tenant-key <key> --tenant-id <tenant-id> --format json'
+    nextGate: types_publish_ready
+  - errorId: EAI_APP_MANIFEST_VALIDATION_FAILED
+    match:
+      containsAny:
+        - 'app_manifest_validation_failed'
+        - 'app manifest save failed for both supported request shapes'
+    meaning: The maintained CLI could not match the deployed app-manifest request contract.
+    likelyCause: The installed CLI is old, or another manifest field fails after request-shape negotiation.
+    recovery:
+      - 'eai update --check'
+      - 'If eai update --check reports upgrade_required, obtain approval and run eai update'
+      - 'eai types validate --tenant-key <key> --tenant-id <tenant-id>'
+      - 'eai types seed --tenant-key <key> --tenant-id <tenant-id> --dry-run --format json'
+      - 'eai types seed --tenant-key <key> --tenant-id <tenant-id> --format json'
     nextGate: types_publish_ready
   - errorId: EAI_RESOURCE_NOT_READY
     match:
@@ -164,11 +194,39 @@ catalog:
     meaning: Backing resources or preview surfaces are not ready yet.
     likelyCause: Provisioning completed partially or downstream services are still unhealthy.
     recovery:
-      - 'eai resources storage status --tenant-id <workspace-id> --format json'
-      - 'eai resources storage doctor --tenant-id <workspace-id> --format json'
-      - 'eai verify storage --tenant-id <workspace-id>'
-      - 'eai resources schema --tenant-id <workspace-id> --format json'
+      - 'eai resources storage status --tenant-id <tenant-id> --format json'
+      - 'eai resources storage doctor --tenant-id <tenant-id> --format json'
+      - 'eai verify storage --tenant-id <tenant-id>'
+      - 'eai resources schema --tenant-id <tenant-id> --format json'
     nextGate: schema_storage_ready
+  - errorId: EAI_RESOURCEAPI_TENANT_CONTEXT_MISSING
+    match:
+      containsAny:
+        - 'RESOURCEAPI_TENANT_CONTEXT_MISSING'
+        - 'missing_tenant_context'
+    meaning: PublicAPI could not resolve tenant context for a tenant-scoped ResourceAPI request.
+    likelyCause: The app or caller omitted the effective tenant headers, or the BFF stripped tenant context before forwarding the request.
+    recovery:
+      - 'Retry the same /v4/data/resources/<tenant-id>/... request in four modes: path tenant only, tenant header only, X-Tenant-Id only, and both headers'
+      - 'Inspect the app BFF or proxy and confirm it forwards both tenant and X-Tenant-Id server-authoritatively for tenant-scoped calls'
+      - 'Use eai publicapi get /v4/platform/tenants/<tenant-id>/resource-metadata to confirm the tenant-level public contract'
+      - 'Use eai resources storage doctor --tenant-id <tenant-id> --format json after workspace context is fixed'
+    nextGate: tenant_context_resolved
+  - errorId: EAI_RESOURCEAPI_INSTALL_UNAVAILABLE
+    match:
+      containsAny:
+        - 'RESOURCEAPI_INSTALL_UNAVAILABLE'
+        - 'install_registry_no_match'
+        - 'RESOURCEAPI_INSTALL_REGISTRY_NO_MATCH'
+    meaning: PublicAPI could not resolve a usable ResourceAPI install for the tenant-scoped request.
+    likelyCause: Either workspace context was inconsistent across path and headers, or the workspace metadata/schema projection is incomplete for this app.
+    recovery:
+      - 'Compare /v4/platform/tenants/<tenant-id>/resource-metadata with /v4/data/resources/<tenant-id>/storage before concluding the workspace is unprovisioned'
+      - 'If the same /storage request flips between 200 and 503 by header mode, treat it as a workspace-context contract mismatch first'
+      - 'Check publishedObjectTypes in tenant resource metadata and treat it as operational state'
+      - 'Run eai resources storage doctor --tenant-id <tenant-id> --format json'
+      - 'Inspect the app BFF or proxy before escalating to a platform-only fault'
+    nextGate: storage_contract_verified
   - errorId: EAI_RESOURCE_SEARCH_EMBEDDING_REQUIRED
     match:
       containsAny:
@@ -179,19 +237,19 @@ catalog:
     meaning: Full-text resource search can be available on the v4 passive ResourceAPI surface while hybrid or vector search is not ready yet.
     likelyCause: The app or agent used the default hybrid v4 passive ResourceAPI search path before storage doctor reported semantic search readiness.
     recovery:
-      - 'eai resources storage doctor --tenant-id <workspace-id> --format json'
-      - 'If capabilities.search.fulltext is true, retry with eai resources search "<query>" --fulltext --tenant-id <workspace-id>'
+      - 'eai resources storage doctor --tenant-id <tenant-id> --format json'
+      - 'If capabilities.search.fulltext is true, retry with eai resources search "<query>" --fulltext --tenant-id <tenant-id>'
       - 'Use --hybrid or --vector only after capabilities.search.hybrid or capabilities.search.vector is true'
       - 'If semantic search is required for the scenario, record a platform capability gap in service-fit-matrix.md'
-      - 'Do not apply this fallback to legacy v1/v3 or active ResourceAPI behavior'
+      - 'Apply this fallback only to the published passive ResourceAPI search contract'
     nextGate: resource_search_mode_selected
   - errorId: EAI_WORKFLOW_NOT_READY
     match:
       containsAny:
         - 'workflow readiness failed'
         - 'workflow unavailable'
-    meaning: Required workflow support is not yet ready for this repo or workspace.
-    likelyCause: Workflow dependencies, package profile, or workspace features are missing.
+    meaning: Required workflow support is not yet ready for this repo or tenant.
+    likelyCause: Workflow dependencies, package profile, or tenant features are missing.
     recovery:
       - 'eai workflow readiness --format json'
       - 'eai --describe'

package/resources/gofer/references/platform/eai-repo-contract.md

@@ -31,20 +31,40 @@ Before app-delivery research, planning, implementation, or validation:
 
 1. Read `.specify/specs/{feature}/eai-preflight.md` when it exists.
 2. Read `.specify/references/platform/eai-error-catalog.yaml`.
-3. If CLI, login, workspace, template, or Gofer readiness is missing or stale, run
-   `/gofer:eai-first-run`.
-4. Use current CLI discovery instead of memory:
+3. Read `.specify/references/platform/eai-service-patterns.md` before choosing
+   storage, workflow, content, search, AI, or integration services.
+4. If CLI, login, workspace, template, or Gofer readiness is missing or stale,
+   run `/gofer:eai-first-run`.
+5. Use current CLI discovery instead of memory:
    - `eai update --check`
    - `eai --describe`
    - `eai agent guide --format json` when advertised
    - `eai whoami`
    - `eai workspace list --format json`
    - `eai provision entra` when advertised and identity setup is in scope
-5. When the repo is an EAI project, check drift before further build work:
+6. Do not invent, guess, or complete EAI CLI commands from memory. Before
+   suggesting or running an `eai ...` command, verify the exact command and
+   flags from `eai --describe` and command-specific `--help`. If the installed
+   CLI does not list it, do not run it.
+7. When the repo is an EAI project, check drift before further build work:
    - `eai template check --format json`
    - `eai gofer refresh --check --format json`
    - `eai workflow readiness --format json` when advertised by the CLI
 
+## Workspace Data Access Rule
+
+Keep PascalCase Object Type model names separate from the exact stored `slug`.
+Use lowercase kebab-case slugs in runtime paths and links; never re-derive or
+rename a historical stored slug.
+
+Workspace apps access EAI data as the signed-in user. Browser code calls the
+local BFF at `/api/eai/...`; the BFF forwards to PublicAPI with the user's
+session token. Do not add app-only `client_credentials` helpers,
+`EAI_SERVICE_*`, or `OBO_*` credentials for normal ResourceAPI reads, writes,
+files, or search. If work must continue after the user leaves the page,
+create/request a platform workflow/job from the signed-in user flow and pass
+workspace, app, user, and purpose context into it.
+
 ## Stack Policy
 
 For application delivery:
@@ -56,6 +76,29 @@ For application delivery:
 Do not silently replace an unavailable EAI capability with a non-EAI primary
 runtime, database, or hosting stack.
 
+## Platform Service Choice Rule
+
+For normal app work, make the best EAI Platform service choice for the business
+user and record it in `service-fit-matrix.md`.
+
+- Use PostgreSQL for relational, transactional, reporting, workflow state,
+  audit, and structured workspace business data.
+- Use DocumentDB for flexible JSON documents, nested records, high-change
+  schemas, and user-authored document state.
+- Use Blob Storage for large files, binary content, exports, and file-like
+  resources behind API-mediated access.
+- Use AI Search as a derived full-text, vector, or hybrid search projection, not
+  as the source of record.
+- Use EAI content understanding and document services for classification,
+  extraction, summarization, and Retrieval-Augmented Generation.
+- Use EAI workflows, goals, and targets for approvals, long-running work,
+  service goals, operating targets, and auditable process state.
+- Use platform AI services and workflow-backed agents before direct provider
+  SDKs or provider keys.
+
+Ask the user only when the choice affects cost, security, compliance,
+deployment, data residency, external systems, or material business scope.
+
 ## Ordered App-Delivery Gates
 
 Unless the live CLI advertises a different authoritative dependency, preserve
@@ -68,9 +111,9 @@ this gate order:
 5. `eai app provision`
 6. `eai provision entra` when required
 7. `eai env pull` when required
-8. `eai types validate`
-9. `eai types diff`
-10. `eai types seed`
+8. `eai types validate --tenant-key <key> --tenant-id <tenant-id>`
+9. `eai types seed`
+10. `eai types diff`
 11. `eai resources schema`
 12. Storage diagnostics and verification
 13. Workflow readiness and resource-call verification
@@ -84,12 +127,6 @@ Treat these as separate gates:
 - workflow readiness
 - preview readiness
 
-For Object Types, keep the PascalCase configuration/model `name` distinct from
-the exact lowercase kebab-case stored `slug`. Emitted relationship targets,
-runtime `target_type`, resource commands, paths, and governed v4 fields use the
-stored slug. Historical stored slugs are authoritative and must not be
-re-derived during validation or repair.
-
 ## Error Recovery Rule
 
 When an EAI CLI or platform command fails:
@@ -110,22 +147,23 @@ When an EAI CLI or platform command fails:
 6. Do not invent a new order or mark the repo ready when a prior gate is still
    blocked.
 
-For workspace member or admin changes, prefer `eai user invite`, `eai user list`,
-`eai user roles`, and `eai user role set` over direct database edits or cloud
-portal changes. If `eai user invite` fails with `EXTERNAL_SERVICE_ERROR`, a 5xx
-status, or the `user_invite_external_service_existing_member` reason, check for
-an existing direct member with
-`eai user list --workspace <workspace-id> --search <email> --format json`. If a direct
-member exists and the user approves, update the role with
+For workspace member or admin changes, prefer `eai user invite`,
+`eai user list`, `eai user roles`, and `eai user role set` over direct database
+edits or cloud portal changes. If `eai user invite` fails with
+`EXTERNAL_SERVICE_ERROR`, a 5xx status, or the
+`user_invite_external_service_existing_member` reason, check for an existing
+direct member with
+`eai user list --workspace <workspace-id> --search <email> --format json`. If a
+direct member exists and the user approves, update the role with
 `eai user role set --workspace <workspace-id> --member-id <member-id> --role tenant-admin --format json`,
 verify the read-back, and tell the affected app user to sign out and sign back
 in because Auth.js session or JWT role data may be cached.
 
 For Entra browser sign-in failures, treat `AADSTS50011`, redirect URI mismatch
 messages, and `/api/auth/callback/microsoft-entra-id` callback errors as EAI
-identity provisioning problems first. Confirm login and workspace with `eai whoami`
-and `eai workspace list --format json`, select the correct workspace if needed, then
-run the advertised equivalent of
+identity provisioning problems first. Confirm login and workspace with
+`eai whoami` and `eai workspace list --format json`, select the correct
+workspace if needed, then run the advertised equivalent of
 `eai provision entra --force --redirect-uri <confirmed-callback-uri>`. Record
 only a redacted callback route in Gofer artifacts. Use `--debug` only with
 explicit user approval, and redact private hostnames, private workspace/platform