eai-cli 0.0.0-bootstrap.0

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

@@ -0,0 +1,134 @@
+# EAI Repo Contract
+
+Use this file when a repository is already initialized from the EAI app
+template, or when Gofer is about to initialize one.
+
+## Purpose
+
+This is the repo-owned fallback contract for any AI agent working in an
+EAI-oriented repository. It defines the minimum safe behavior even when live
+docs are unavailable.
+
+Treat this file and the adjacent fallback references as repo-owned guidance in
+the same trust boundary as `AGENTS.md`, `CLAUDE.md`, and other checked-in
+instruction files. They are not a cryptographic proof of external platform
+state.
+
+## Detecting An EAI Repo
+
+Treat the repo as EAI-initialized when either of these marker sets exists:
+
+- both `src/eai.config/object-types.ts` and `src/eai.config/register.ts`
+- `manifest.yml` together with the `src/eai.config/` directory
+
+The broader EAI app shape often also includes `.env.example`, `.npmrc`, and a
+template-owned `package.json`, but those are supporting signals rather than the
+primary identification markers.
+
+## Mandatory First Actions
+
+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, tenant, template, or Gofer readiness is missing or stale, run
+   `/gofer:eai-first-run`.
+4. Use current CLI discovery instead of memory:
+   - `eai update --check`
+   - `eai --describe`
+   - `eai agent guide --format json` when advertised
+   - `eai whoami`
+   - `eai tenant 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:
+   - `eai template check --format json`
+   - `eai gofer refresh --check --format json`
+   - `eai workflow readiness --format json` when advertised by the CLI
+
+## Stack Policy
+
+For application delivery:
+
+1. EAI Platform first, including the EAI app template.
+2. Azure second, where it fits the documented EAI operating model.
+3. Everything else only by explicit exception recorded in the feature artifacts.
+
+Do not silently replace an unavailable EAI capability with a non-EAI primary
+runtime, database, or hosting stack.
+
+## Ordered App-Delivery Gates
+
+Unless the live CLI advertises a different authoritative dependency, preserve
+this gate order:
+
+1. Template init or verify current template ownership
+2. Dependency install
+3. Login and tenant selection
+4. App list/create/select
+5. `eai app provision`
+6. `eai provision entra` when required
+7. `eai env pull` when required
+8. `eai types validate`
+9. `eai types seed`
+10. `eai types diff`
+11. `eai resources schema`
+12. Storage diagnostics and verification
+13. Workflow readiness and resource-call verification
+14. Preview or dev startup
+
+Treat these as separate gates:
+
+- provisioning
+- object-type publish
+- schema/storage health
+- workflow readiness
+- preview readiness
+
+## Error Recovery Rule
+
+When an EAI CLI or platform command fails:
+
+1. Match the failure against
+   `.specify/references/platform/eai-error-catalog.yaml`.
+2. Run `eai errors explain <code-or-reason> --format json` when the CLI
+   advertises it, and use its public-safe reasons plus next `eai` commands
+   before guessing platform internals.
+3. Run read-only diagnostics from the guidance before mutating fixes. Apply a
+   mutating fix only when it is listed by live EAI guidance or the fallback
+   catalog and the user has approved any admin or tenant-membership change.
+4. Record the command shape, status, server code, request ID when present, last
+   completed gate, blocked gate, and next recovery command in
+   `.specify/specs/{feature}/eai-preflight.md`.
+5. Stop at the retry or escalation condition instead of repeatedly rerunning the
+   same failing command.
+6. Do not invent a new order or mark the repo ready when a prior gate is still
+   blocked.
+
+For tenant 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 --tenant <tenant-id> --search <email> --format json`. If a direct
+member exists and the user approves, update the role with
+`eai user role set --tenant <tenant-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 tenant with `eai whoami`
+and `eai tenant list --format json`, select the correct tenant 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, tenant IDs, client IDs,
+tokens, and raw debug output before writing artifacts. Use Azure Portal edits
+only when the installed EAI CLI does not advertise an Entra provisioning path or
+the CLI reports an operator-only block.
+
+## Privacy And Safety
+
+- Do not record tokens, secrets, or `.env.local` values in Gofer artifacts.
+- Record tenant and app state in product-safe labels only.
+- Keep repo-owned fallback references public-safe and non-sensitive.

package/resources/gofer/references/platform/eai-service-patterns.md

@@ -0,0 +1,56 @@
+# EAI Service Pattern Reference
+
+This public-safe matrix teaches eai-gofer how to choose platform services when
+planning or implementing an EAI app. It is a compact companion to the runnable
+patterns in `eai-app-template/docs/platform/eai-service-patterns.md`.
+
+## Boundary Rules
+
+- App browser code calls the local BFF at `/api/eai/...`.
+- App streaming calls use `/api/eai/stream/...`.
+- The CLI may call PublicAPI directly because `eai login` provides the user
+  token.
+- Prefer named template SDK hooks and named `eai` commands before custom calls.
+- Use `eai publicapi` only for authorized PublicAPI V4 routes that do not yet
+  have a named SDK or CLI command.
+- Do not generate direct downstream database, blob, search, or platform secrets.
+
+## Service Selection Matrix
+
+| Need                 | App Pattern                                                                       | CLI Pattern                                                                                                                                                           | Notes                                                                                                                             |
+| -------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Frontend composition | `src/eai.config` layout slots plus `src/eai.blocks.tsx` registry                  | `eai gofer refresh` installs this reference pack                                                                                                                      | Keep config data-only; callbacks belong in overrides.                                                                             |
+| Data model           | Object Types in `src/eai.config/object-types.ts`                                  | `eai types validate`, `eai types seed`, `eai types diff`                                                                                                              | Object Types define ResourceAPI contracts.                                                                                        |
+| Structured resources | `useResources(type)` / `client.resources`                                         | `eai resources list/get/create/update/delete/query`                                                                                                                   | Default for tenant business data.                                                                                                 |
+| Resource actions     | `client.resources.executeAction(type, id, action)`                                | named resources command if available; otherwise `eai publicapi post /v4/data/resources/...`                                                                           | Actions enforce object-type rules.                                                                                                |
+| Resource search      | local helper around `/v4/data/resources/{tenant}/search` if SDK support is absent | `eai resources storage doctor --format json`, then `eai resources search "query" --fulltext`; use `--hybrid` or `--vector` only when doctor reports those modes ready | V4 passive ResourceAPI search is a projection over canonical data. Fulltext can be usable before semantic search modes are ready. |
+| Resource files       | local helper around resource file routes                                          | `eai resources file upload/get/delete`                                                                                                                                | Use for file fields on ResourceAPI objects.                                                                                       |
+| Documents            | `useDocuments().upload/classify/ragIndex`                                         | `eai docs upload`, `eai docs classify`, `eai docs index`                                                                                                              | Use for platform document processing and RAG.                                                                                     |
+| Chat                 | `useChat(workflowId, stage).send/stream`                                          | `eai chat send`, `eai chat stream`                                                                                                                                    | Use v4 chat shape with `message`, `conversation_id`, and `params`.                                                                |
+| Advanced PublicAPI   | BFF/server helper                                                                 | `eai publicapi <method> /v4/...`                                                                                                                                      | Use only when named SDK/CLI support is missing.                                                                                   |
+
+## Storage Backend Rules
+
+- `postgresql`: canonical structured resource storage.
+- `documentdb`: document-model persistence when the data genuinely needs it.
+- `blob`: large files or file-like resources behind API-mediated access.
+- `search`: derived full-text/vector/hybrid projection, not the sole system of
+  record for runtime writes. On the v4 passive ResourceAPI interface, treat
+  full-text readiness separately from hybrid/vector readiness; semantic modes
+  require `eai resources storage doctor` to report `capabilities.search.hybrid`
+  or `capabilities.search.vector`. Do not apply this fallback rule to legacy
+  v1/v3 or active ResourceAPI behavior.
+
+Document RAG indexing is a documents service pattern (`eai docs index` or
+`useDocuments().ragIndex(...)`), not a reason to create a search-only Object
+Type.
+
+## Config-Driven UI Rules
+
+- Use the EAI App Template slot shape: `{ components: [...] }`.
+- Register components before referencing them in config.
+- Add store slices before adding `storeBindings`.
+- Use JSON-safe `showWhen` conditions for visibility.
+- Put functions, React nodes, auth handlers, router callbacks, analytics hooks,
+  and render props in overrides.
+- Validate component names and store paths before completion.

package/resources/gofer/references/platform/eai.md

@@ -0,0 +1,85 @@
+# Platform CLI Reference
+
+Use this fallback when external CLI documentation is unavailable.
+
+## Version Pinning Rule
+
+- Detect the installed CLI version.
+- Record the `major.minor` version in generated plan and task artifacts.
+- Avoid pinning implementation guidance to patch-specific behavior.
+
+## Command Guidance Contract
+
+- Use live CLI discovery before assuming syntax:
+  - `eai update --check`
+  - `eai --describe`
+  - `eai agent guide --format json` when advertised
+  - `eai whoami`
+  - `eai tenant list --format json`
+- When the repo is already an EAI app project, also check:
+  - `eai template check --format json`
+  - `eai gofer refresh --check --format json`
+  - `eai workflow readiness --format json` when advertised
+  - `eai provision entra` when identity callback or Entra registration setup is
+    in scope
+- When any `eai` command fails, run
+  `eai errors explain <code-or-reason> --format json` when advertised and use
+  its public-safe reasons and next commands before guessing remediation.
+- Treat every EAI failure as a recovery loop:
+  1. capture the command shape, status, server code, and request ID when present
+     without writing secrets or raw private debug output;
+  2. prefer live `eai errors explain` guidance for the code or reason;
+  3. if live guidance is unavailable, match
+     `.specify/references/platform/eai-error-catalog.yaml`;
+  4. run read-only diagnostics before mutating fixes;
+  5. stop at the retry or escalation condition instead of looping.
+- Include scaffolding or setup commands only when they are supported by the
+  target project.
+- Include deployment commands only when the target repository documents a
+  deployment path.
+- Add a user-visible notice when fallback references were used.
+
+## Ordered EAI App Delivery Sequence
+
+Unless the live CLI advertises a different dependency order:
+
+1. Confirm template ownership or initialize with `eai init`
+2. Install dependencies
+3. Confirm login and tenant selection
+4. Confirm or create/select the app
+5. Provision app resources
+6. Run object-type validation and publish
+7. Verify schema, storage, and workflow readiness
+8. Start preview or dev runtime
+
+Do not treat provisioning, object-type publish, schema/storage health, workflow
+readiness, and preview as interchangeable states.
+
+## Error Recovery
+
+When commands fail, consult `eai-error-catalog.yaml` in the same folder. Match
+the failure to a recovery path, then use
+`eai errors explain <code-or-reason> --format json` when the CLI advertises it.
+Record the blocked gate in `.specify/specs/{feature}/eai-preflight.md`, and
+avoid inventing a new order.
+
+For tenant member or admin changes, use EAI CLI membership commands first. If
+`eai user invite` fails with `EXTERNAL_SERVICE_ERROR`, a 5xx status, or the
+`user_invite_external_service_existing_member` reason, check whether the person
+already exists with
+`eai user list --tenant <tenant-id> --search <email> --format json`. If a direct
+member exists and the user approves the role change, use
+`eai user role set --tenant <tenant-id> --member-id <member-id> --role tenant-admin --format json`,
+verify the read-back, then 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 use direct
+database edits or cloud portal changes unless EAI guidance reports an
+operator-only block.
+
+If a browser sign-in flow reports `AADSTS50011` or a Microsoft Entra redirect
+URI mismatch, do not start with manual Azure Portal edits. Confirm the EAI login
+and tenant, confirm the callback URI from the failing authorize request in the
+active session, then run the advertised
+`eai provision entra --force --redirect-uri <confirmed-callback-uri>` path and
+retry sign-in. Record only a redacted callback route in Gofer artifacts. Use
+`--debug` only with explicit user approval, and redact private hostnames, tenant
+IDs, client IDs, tokens, and raw debug output before writing artifacts.

package/resources/gofer/references/platform/vertical-template.md

@@ -0,0 +1,49 @@
+# Vertical Template Reference
+
+Use `https://github.com/eai-tools/eai-app-template` as the canonical public app
+template for EnterpriseAI app-delivery work.
+
+This file is the preferred alias for the legacy `eai-app-template.md` fallback
+reference. Both names are kept so older EnterpriseAI consumers and newer public
+Gofer terminology resolve to the same guidance.
+
+## Source Of Truth
+
+- New apps are scaffolded with `eai init`, which defaults to the EAI App
+  Template.
+- Runnable service patterns live in the template, especially
+  `docs/platform/config-driven-ui.md`, `docs/platform/eai-service-patterns.md`,
+  `src/hooks`, and `packages/platform-sdk`.
+- Config-driven UI composition lives in `src/eai.config/default.ts`,
+  `src/eai.config/index.ts`, and `src/eai.blocks.tsx`.
+- eai-gofer should use those public template patterns and the installed `eai`
+  CLI instead of copying private platform documentation.
+
+## App Boundary Contract
+
+1. Browser code calls the local app BFF at `/api/eai/...`.
+2. Browser streaming uses `/api/eai/stream/...`.
+3. The BFF or server helpers attach auth, tenant, and correlation headers.
+4. The frontend never receives direct downstream database, blob, search, or
+   PublicAPI credentials.
+5. Prefer PublicAPI V4 surfaces; v3 route-family mapping is compatibility glue.
+
+## Implementation Contract
+
+- Use Object Types as the data model contract.
+- Use the template SDK and hooks for resources, documents, and chat.
+- Use config slots with `{ components: [...] }`, not stale array-only slot
+  examples.
+- Use `storeBindings` for data-driven props and code-level overrides for
+  callbacks, auth actions, analytics hooks, render props, and React nodes.
+- Use the CLI for setup and verification:
+  - `eai login`
+  - `eai tenant select <tenant-slug>`
+  - `eai types validate`
+  - `eai types seed --tenant-key <key> --tenant-id <tenant-id>`
+  - `eai types diff --tenant-key <key> --tenant-id <tenant-id>`
+  - `eai resources schema --tenant-id <tenant-id>`
+  - `eai verify calls --tenant-id <tenant-id> --resource-type <type>`
+
+Do not describe retired templates as canonical scaffolds. The surviving public
+scaffold is the EAI App Template.