eai-cli 0.0.0-bootstrap.0

package/resources/gofer/powershell-scripts/install-optional-tools.ps1

@@ -0,0 +1,214 @@
+param(
+  [string]$WorkspacePath = (Get-Location).Path,
+  [string]$Tools = ''
+)
+
+$ErrorActionPreference = 'Stop'
+$HasFailure = $false
+
+function Write-Info {
+  param([string]$Message)
+  Write-Host "[gofer] $Message"
+}
+
+function Write-Warn {
+  param([string]$Message)
+  Write-Warning "[gofer] $Message"
+}
+
+function Invoke-Step {
+  param(
+    [string]$Description,
+    [scriptblock]$ScriptBlock
+  )
+
+  Write-Info $Description
+  try {
+    & $ScriptBlock
+  } catch {
+    $script:HasFailure = $true
+    Write-Warn "Failed: $Description"
+    Write-Warn $_.Exception.Message
+  }
+}
+
+function Test-CommandExists {
+  param([string]$CommandName)
+  return $null -ne (Get-Command $CommandName -ErrorAction SilentlyContinue)
+}
+
+function Get-JsPackageManager {
+  if (Test-Path (Join-Path $WorkspacePath 'bun.lockb')) {
+    return 'bun'
+  }
+
+  if (Test-Path (Join-Path $WorkspacePath 'pnpm-lock.yaml')) {
+    return 'pnpm'
+  }
+
+  if (Test-Path (Join-Path $WorkspacePath 'yarn.lock')) {
+    return 'yarn'
+  }
+
+  if (Test-Path (Join-Path $WorkspacePath 'package.json')) {
+    return 'npm'
+  }
+
+  return ''
+}
+
+function Install-RepoPackage {
+  param(
+    [string]$PackageManager,
+    [string]$PackageName
+  )
+
+  switch ($PackageManager) {
+    'npm' {
+      Invoke-Step "Installing $PackageName with npm" { npm install --save-dev $PackageName }
+    }
+    'pnpm' {
+      Invoke-Step "Installing $PackageName with pnpm" { pnpm add --save-dev $PackageName }
+    }
+    'yarn' {
+      Invoke-Step "Installing $PackageName with yarn" { yarn add --dev $PackageName }
+    }
+    'bun' {
+      Invoke-Step "Installing $PackageName with bun" { bun add --dev $PackageName }
+    }
+    default {
+      $script:HasFailure = $true
+      Write-Warn "No supported JS package manager detected for $PackageName"
+    }
+  }
+}
+
+function Install-PlaywrightBrowsers {
+  if (-not (Test-Path (Join-Path $WorkspacePath 'package.json'))) {
+    Write-Warn 'Skipping Playwright browser install because package.json was not found'
+    return
+  }
+
+  Push-Location $WorkspacePath
+  try {
+    Invoke-Step 'Installing Playwright browsers' { npx playwright install }
+  } finally {
+    Pop-Location
+  }
+}
+
+function Install-NpmGlobalPackage {
+  param([string]$PackageName)
+
+  if (-not (Test-CommandExists 'npm')) {
+    $script:HasFailure = $true
+    Write-Warn "npm is required to install $PackageName globally"
+    return
+  }
+
+  Invoke-Step "Installing $PackageName globally with npm" { npm install --global $PackageName }
+}
+
+function Install-GitHubCli {
+  if (Test-CommandExists 'gh') {
+    Write-Info 'GitHub CLI is already installed'
+    return
+  }
+
+  if (Test-CommandExists 'winget') {
+    Invoke-Step 'Installing GitHub CLI with winget' {
+      winget install --id GitHub.cli --exact --source winget
+    }
+    return
+  }
+
+  if (Test-CommandExists 'choco') {
+    Invoke-Step 'Installing GitHub CLI with Chocolatey' { choco install gh --yes }
+    return
+  }
+
+  $script:HasFailure = $true
+  Write-Warn 'No supported package manager found to install GitHub CLI'
+}
+
+function Install-AzureCli {
+  if (Test-CommandExists 'az') {
+    Write-Info 'Azure CLI is already installed'
+    return
+  }
+
+  if (Test-CommandExists 'winget') {
+    Invoke-Step 'Installing Azure CLI with winget' {
+      winget install --id Microsoft.AzureCLI --exact --source winget
+    }
+    return
+  }
+
+  if (Test-CommandExists 'choco') {
+    Invoke-Step 'Installing Azure CLI with Chocolatey' { choco install azure-cli --yes }
+    return
+  }
+
+  $script:HasFailure = $true
+  Write-Warn 'No supported package manager found to install Azure CLI'
+}
+
+if ([string]::IsNullOrWhiteSpace($Tools)) {
+  Write-Info 'No tools selected. Nothing to install.'
+  exit 0
+}
+
+$toolList = $Tools.Split(',', [System.StringSplitOptions]::RemoveEmptyEntries)
+$packageManager = Get-JsPackageManager
+
+Write-Info "Workspace: $WorkspacePath"
+Write-Info "Selected tools: $Tools"
+
+foreach ($tool in $toolList) {
+  switch ($tool.Trim()) {
+    'stryker' {
+      Install-RepoPackage -PackageManager $packageManager -PackageName '@stryker-mutator/core'
+    }
+    'playwright' {
+      Install-RepoPackage -PackageManager $packageManager -PackageName '@playwright/test'
+      Install-PlaywrightBrowsers
+    }
+    'claude' {
+      Install-NpmGlobalPackage -PackageName '@anthropic-ai/claude-code'
+    }
+    'codex' {
+      Install-NpmGlobalPackage -PackageName '@openai/codex-cli'
+    }
+    'copilot' {
+      Install-NpmGlobalPackage -PackageName '@github/copilot'
+    }
+    'gemini' {
+      Install-NpmGlobalPackage -PackageName '@google/gemini-cli'
+    }
+    'gh' {
+      Install-GitHubCli
+    }
+    'az' {
+      Install-AzureCli
+    }
+    default {
+      $script:HasFailure = $true
+      Write-Warn "Unknown tool id: $tool"
+    }
+  }
+}
+
+Write-Info 'Suggested next steps:'
+Write-Info '  claude login'
+Write-Info '  codex login'
+Write-Info '  copilot login'
+Write-Info '  gemini auth login'
+Write-Info '  gh auth login'
+Write-Info '  az login'
+
+if ($HasFailure) {
+  Write-Warn 'Optional tool installation completed with warnings or failures'
+  exit 1
+}
+
+Write-Info 'Optional tool installation complete'

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

@@ -0,0 +1,17 @@
+# Public Platform Reference Pack
+
+This folder contains public-safe fallback references for EAI Gofer workflows
+that need platform, template, or deployment guidance while offline.
+
+Core files:
+
+- `eai.md` - CLI and platform fallback guidance
+- `eai-repo-contract.md` - repo-owned behavior contract for AI agents in EAI repos
+- `eai-error-catalog.yaml` - common EAI CLI/platform failure signatures and recovery paths
+- `vertical-template.md` - preferred fallback template guidance alias
+- `eai-app-template.md` - legacy fallback template guidance alias kept for compatibility
+- `deployment-repo.md` - fallback deployment guidance
+
+These files are intentionally public-safe. Private repositories can replace or
+extend them with organization-specific references, but Gofer should always be
+able to fall back to this pack without exposing secrets or tenant-private data.

package/resources/gofer/references/platform/deployment-repo.md

@@ -0,0 +1,9 @@
+# Deployment Reference
+
+Use this fallback when deployment documentation cannot be fetched.
+
+## Deployment Guidance Contract
+
+- Record the target environment for each deliverable.
+- Require deployment-readiness checks before deployment task completion.
+- Surface fallback notices when local references are used.

package/resources/gofer/references/platform/eai-app-template.md

@@ -0,0 +1,45 @@
+# EAI App Template Reference
+
+Use `https://github.com/eai-tools/eai-app-template` as the canonical public app
+template for EnterpriseAI app-delivery work.
+
+## 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.

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

@@ -0,0 +1,156 @@
+# EAI Config-Driven UI Reference
+
+Use this public-safe guide when eai-gofer is planning, generating, or modifying
+an app based on `https://github.com/eai-tools/eai-app-template`.
+
+## Source Files
+
+| File                        | Purpose                                                                         |
+| --------------------------- | ------------------------------------------------------------------------------- |
+| `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.                                               |
+| `src/hooks/useDocuments.ts` | Document upload, classification, and RAG indexing.                              |
+| `src/hooks/useChat.ts`      | Streaming and non-streaming chat workflows.                                     |
+
+## Construction Rules
+
+1. Keep tenant-specific values in config: branding, feature flags, API
+   endpoints, storage keys, store slices, and layout slots.
+2. Register renderable components before referencing them from config.
+3. Reference components by their registered string name.
+4. Use `storeBindings` to map global store paths into component props.
+5. Use JSON-safe `showWhen` conditions for visibility.
+6. Keep functions, React nodes, auth actions, analytics callbacks, router
+   navigation, and render props in code-level overrides.
+7. Keep browser service calls behind BFF routes and template hooks.
+
+## Component Entry Shape
+
+```ts
+{
+  component: 'TaskSummary',
+  priority: 10,
+  props: {
+    title: 'Open tasks',
+  },
+  storeBindings: [
+    { prop: 'tasks', storePath: 'tasks.items' },
+    { prop: 'isLoading', storePath: 'tasks.isLoading' },
+  ],
+  showWhen: { path: 'user.isAuthenticated', equals: true },
+}
+```
+
+Rules:
+
+- `component` must match a registered component name.
+- Lower `priority` renders first.
+- `props` are static, tenant-configurable values.
+- `storeBindings` support dot notation on both `prop` and `storePath`.
+- `showWhen` supports `equals`, `notEquals`, `exists`, and compound `and`/`or`.
+
+## Slot Shape
+
+Use the template slot shape:
+
+```ts
+layout: {
+  header: {
+    components: [{ component: 'AppHeader', priority: 1 }],
+  },
+  middlePane: {
+    components: [
+      { component: 'TaskSummary', priority: 1 },
+      { component: 'TaskList', priority: 2 },
+    ],
+  },
+  rightPane: {
+    components: [{ component: 'AssistantPanel', priority: 1 }],
+  },
+}
+```
+
+Do not generate stale array-only slots such as
+`middlePane: [{ component: 'Dashboard' }]`.
+
+## Store Slice Shape
+
+```ts
+store: {
+  tasks: {
+    initialState: {
+      items: [],
+      selectedId: null,
+      isLoading: false,
+    },
+    persist: true,
+  },
+  ui: {
+    initialState: { showWelcome: true },
+    persist: false,
+  },
+}
+```
+
+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.
+
+## Runtime Override Boundary
+
+Config is data-only. Use wrapper components for runtime behavior:
+
+```tsx
+const componentOverrides = {
+  TaskList: {
+    onSelectTask: (taskId: string) => setSelectedTaskId(taskId),
+  },
+  AssistantPanel: {
+    onSendMessage: sendMessage,
+  },
+};
+```
+
+Put these values in overrides, not config:
+
+- event handlers
+- auth login/logout handlers
+- router callbacks
+- analytics callbacks
+- render props
+- React nodes
+- non-serializable objects
+
+## Service Pairing
+
+The config-driven UI should pair with the service matrix:
+
+| UI Need                                               | Service Pattern                                            |
+| ----------------------------------------------------- | ---------------------------------------------------------- |
+| 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                  |
+| Advanced platform route                               | Server-side helper or `eai publicapi` for CLI verification |
+
+Do not call downstream platform services, storage backends, search indexes, or
+model providers directly from browser components.
+
+## eai-gofer Validation Checklist
+
+Before marking app UI work complete:
+
+- Confirm each config component name exists in the registry or an app-local
+  block extension.
+- Confirm each `storeBindings[].storePath` is backed by a store slice or a
+  documented runtime provider.
+- Confirm each `showWhen.path` is backed by a store slice.
+- Confirm callbacks and React nodes are in overrides, not config.
+- Confirm service hooks match the selected capability: resources, documents,
+  chat, or approved PublicAPI route.
+- Confirm examples are public-safe and do not reference private docs,
+  credentials, internal repository names, or organization-only implementation
+  details.

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

@@ -0,0 +1,197 @@
+version: 1
+catalog:
+  - errorId: EAI_CLI_MISSING
+    match:
+      containsAny:
+        - 'command not found: eai'
+        - 'eai: command not found'
+    meaning: EAI CLI is not installed or not on PATH.
+    likelyCause: Local workstation or container is missing the CLI.
+    recovery:
+      - 'npm config set @eai-tools:registry https://eai-tools.github.io/eai/registry/ --location=user'
+      - 'npm install -g @eai-tools/cli'
+      - 'eai --version'
+    nextGate: cli_installed
+  - errorId: EAI_CLI_OUTDATED
+    match:
+      containsAny:
+        - 'update available'
+        - 'upgrade required'
+        - 'behind latest'
+    meaning: Installed EAI CLI is behind the expected release.
+    likelyCause: Global CLI package has not been updated.
+    recovery:
+      - 'eai update --check'
+      - 'eai update'
+      - 'eai --describe'
+    nextGate: cli_release_current
+  - errorId: EAI_NOT_LOGGED_IN
+    match:
+      containsAny:
+        - 'not logged in'
+        - 'login required'
+        - 'token expired'
+    meaning: The current session has no usable EAI authentication.
+    likelyCause: User has not logged in or the token has expired.
+    recovery:
+      - 'eai login'
+      - 'eai whoami'
+      - 'eai tenant list --format json'
+    nextGate: tenant_ready
+  - errorId: EAI_TENANT_ACCESS_REQUIRED
+    match:
+      containsAny:
+        - 'no tenant'
+        - 'tenant required'
+        - 'insufficient tenant role'
+    meaning: The user lacks the tenant context needed for app delivery.
+    likelyCause: No membership, wrong tenant, or insufficient role.
+    recovery:
+      - 'eai tenant list --format json'
+      - 'eai tenant select <tenant-slug>'
+      - 'eai whoami'
+    nextGate: tenant_ready
+  - errorId: EAI_USER_INVITE_EXTERNAL_SERVICE_EXISTING_MEMBER
+    match:
+      containsAny:
+        - 'user_invite_external_service_existing_member'
+        - 'EXTERNAL_SERVICE_ERROR'
+        - 'Invite failed'
+        - 'eai user invite'
+        - '502'
+    meaning: A tenant member invite or role assignment reached an external service failure, and the target person may already exist as a direct tenant member with the wrong role.
+    likelyCause: The invite/add path failed after, or despite, an existing tenant 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'
+      - 'eai whoami'
+      - 'eai user roles --tenant <tenant-id> --format json'
+      - 'eai user list --tenant <tenant-id> --search <email> --format json'
+      - 'If an existing direct member is present and the user approves, run eai user role set --tenant <tenant-id> --member-id <member-id> --role tenant-admin --format json'
+      - 'Verify the member read-back with eai user list --tenant <tenant-id> --search <email> --format json'
+      - '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_ENTRA_REDIRECT_URI_MISMATCH
+    match:
+      containsAny:
+        - 'AADSTS50011'
+        - 'reply URL specified in the request does not match'
+        - 'redirect URI does not match'
+        - 'redirect_uri'
+        - '/api/auth/callback/microsoft-entra-id'
+    meaning: The live app is sending an Entra callback URL that is not registered on the selected Entra app registration.
+    likelyCause: Preview or deployed host changed, Entra provisioning has not been refreshed for the app, or the runtime client ID points at an app registration without the confirmed callback URI.
+    recovery:
+      - 'eai whoami'
+      - 'eai tenant list --format json'
+      - 'eai tenant select <tenant-slug-or-id> when the active tenant is wrong'
+      - 'Confirm the callback route from the failing browser log in the active session; record only a redacted pattern such as https://<app-host>/api/auth/callback/...'
+      - 'eai provision entra --force --redirect-uri <confirmed-callback-uri>'
+      - 'Use --debug only with explicit user approval, and redact private hostnames, tenant IDs, client IDs, tokens, and raw debug output before writing artifacts'
+      - 'Retry the sign-in flow and confirm the authorize request now uses the registered redirect_uri'
+      - 'If mismatch persists, align AUTH_ENTRA_CLIENT_ID or ENTRA_CLIENT_ID with the Entra app registration returned by EAI'
+    nextGate: entra_redirect_registered
+  - errorId: EAI_NOT_PROJECT
+    match:
+      containsAny:
+        - 'E001'
+        - 'Not in an EAI project'
+    meaning: The current repo is not initialized from the EAI app template.
+    likelyCause: Template init has not run in this repo or folder.
+    recovery:
+      - 'Run /gofer:eai-first-run'
+      - 'Confirm folder choice and tenant'
+      - 'eai init <app-name> --skip-prompts --company-tenant <active-tenant-id>'
+    nextGate: template_ready
+  - errorId: EAI_TEMPLATE_DRIFT
+    match:
+      containsAny:
+        - 'template drift'
+        - 'template check failed'
+        - 'template out of date'
+    meaning: Repo template files have drifted from the expected EAI template baseline.
+    likelyCause: Local repo changes or newer template release not applied.
+    recovery:
+      - 'eai template check --format json'
+      - 'Follow the advertised refresh or reconcile path from eai --describe'
+    nextGate: template_drift_resolved
+  - errorId: EAI_GOFER_DRIFT
+    match:
+      containsAny:
+        - 'gofer refresh'
+        - 'gofer scaffold drift'
+        - 'refresh required'
+    meaning: The Gofer scaffold inside the repo is behind the expected version.
+    likelyCause: Repo Gofer assets were not refreshed after a CLI/plugin update.
+    recovery:
+      - 'eai gofer refresh --check --format json'
+      - 'Run the advertised refresh path'
+      - 'node .specify/scripts/node/gofer-workspace-check.mjs --host auto --json'
+    nextGate: gofer_drift_resolved
+  - errorId: EAI_VERTICAL_NOT_SELECTED
+    match:
+      containsAny:
+        - 'no vertical selected'
+        - 'select app first'
+        - 'app key required'
+    meaning: App-scoped work started before selecting the target app.
+    likelyCause: '`eai app select` has not been run for the active tenant.'
+    recovery:
+      - 'eai app list --format json'
+      - 'eai app select <key> --format json'
+    nextGate: app_selected
+  - errorId: EAI_PROVISION_REQUIRED_FOR_TYPES
+    match:
+      containsAny:
+        - 'App resources must be provisioned before publishing object types'
+        - '409'
+    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 <tenant-id> --select --format json'
+      - 'eai types validate'
+      - 'eai types seed --tenant-key <key> --tenant-id <tenant-id> --format json'
+    nextGate: types_publish_ready
+  - errorId: EAI_RESOURCE_NOT_READY
+    match:
+      containsAny:
+        - '503'
+        - 'Service Unavailable'
+        - 'storage not ready'
+        - 'preview not ready'
+    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 <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_RESOURCE_SEARCH_EMBEDDING_REQUIRED
+    match:
+      containsAny:
+        - 'resource_search_embedding_required'
+        - 'search_embedding_required'
+        - 'Search vector embedding endpoint is not configured'
+        - 'Configure Azure OpenAI embedding endpoint and deployment before vector or hybrid search'
+    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 <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'
+    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 tenant.
+    likelyCause: Workflow dependencies, package profile, or tenant features are missing.
+    recovery:
+      - 'eai workflow readiness --format json'
+      - 'eai --describe'
+      - 'Record blocked workflow capability in service-fit-matrix.md'
+    nextGate: workflow_ready