Console Development

---
name: console-development
description:
  Run, diagnose, or manually test the private Stacktape Console locally, especially when local API/UI behavior must use
  the shared dev RDS data, Cognito users, AWS services, OAuth callbacks, or provider webhooks. Use for Console dev-mode
  setup, deciding between UI-only and full mode, shared-dev migrations, and GitHub/GitLab/Bitbucket end-to-end testing.
---

# Console development

Work from the public workspace root with `apps/console` initialized. Read the root and Console `AGENTS.md` files before
changing code. Check Git status in both repositories.

Before deploying, migrating, starting full local mode or running acceptance tests that need a stable dev backend,
acquire the task-owned shared reservation described in `docs/testing.md#shared-dev-reservation`. Hold it through tests
and cleanup. Do not reuse another task's reservation or treat an old timestamp as permission to release it.
`stacktape-dev` hosts both production and dev; reuse the existing dev Stacktape organization, but never treat the
account, organization or existing connections as disposable. For unattended browser user/SSM setup, read
`apps/console/e2e/README.md`.

## Choose the smallest valid mode

- For repeatable behavior covered by an isolated API/PostgreSQL/browser fixture, use the lane in
  [Console testing](../../../docs/testing/console.md) without shared-dev credentials or a reservation. This skill's full
  local mode applies when the work needs the shared dev data plane or external services.
- Use `pnpm dev:console:ui` only for UI changes that the deployed dev API already supports. It serves the UI at
  `http://localhost:4000` and points it at the deployed dev API.
- Use `pnpm dev:console` when shared-dev or realistic manual testing needs changed API code, API/UI contracts,
  database-backed behavior or permissions. It runs the API at `http://localhost:3000` and the UI at
  `http://localhost:4000`.
- Use `pnpm deploy:console:dev` only when an external system must call changed code, such as an OAuth callback or
  webhook that cannot reach localhost. This changes the real `console-app-dev` stack.
- Never substitute the production stage or `pnpm deploy:console` for a development test.

## Full dev-mode contract

`pnpm dev:console` performs one guarded workflow:

1. Builds the source CLI artifacts.
2. verifies the Stacktape login;
3. verifies the standard AWS SDK credential chain belongs to account `977946299200`;
4. reads current non-secret database and Cognito identifiers from `console-app-dev`;
5. opens an SSM tunnel through `bastionHost` to the shared dev `mainDatabase`;
6. starts the local API container and UI against the shared dev data plane; and
7. closes both processes together.

The API uses real rows, organizations, projects, provider connections, and dev-stage runtime parameters. The local
`console-app-devlocal` stack contains support resources and the assumable role for local workloads. Its resolved-config
fingerprint causes a one-time refresh when IAM or other support configuration changes; ordinary source edits reuse it.
Deployed `dev` Lambdas remain responsible for external webhooks and background work.

Do not start a separate local PostgreSQL container for shared-data tests. Do not manually copy database passwords,
Cognito IDs, API keys, or provider tokens into files or chat.

## Prerequisites and recovery

- Stacktape login: `pnpm dev:cli login`
- AWS credentials for the expected account (environment, shared profile, or another standard SDK source)
- Docker Desktop
- Required parameter names:
  - `pnpm parameters:check:console:dev`
  - `pnpm parameters:check:console:devlocal`

If startup reports an expired login, run the login command and finish its browser flow. If it rejects the AWS account,
switch the AWS profile outside the repository and retry. Stop the foreground `pnpm dev:console` process normally first.
For an agent-mode session, use `pnpm dev:cli dev:stop --agentPort <this-session-port>`. After a crash, inspect Docker
and remove only exact container IDs recorded for this session, then verify its listeners and tunnel are gone. Do not use
blanket `--cleanupContainers` on a shared machine: it guesses ownership from names and does not track foreground dev
sessions. Never delete the shared `console-app-dev` stack as cleanup.

Committed Prisma migrations go to the shared dev database only through `pnpm migrate:console:dev`. Do not use
`prisma migrate dev`, destructive pushes, or the production migration command.

## Manual testing

Test through the browser as a customer would. Verify the visible success path, cancellation or denial, retry after an
error, empty and large lists, search/pagination, stale tabs, disconnect/reconnect, and organization isolation. Inspect
the browser network response and API logs when UI feedback is ambiguous; do not treat a toast alone as proof.

For Git-provider work, read [references/git-provider-e2e.md](references/git-provider-e2e.md) before testing. Ask the
user for provider sign-in, MFA or approval only when the authorized browser session or active tool requires it. First
check [agent browser access](../../../apps/console/e2e/README.md#agent-browser-access): SSM-backed Playwright login is
available for Console, including headed WSL mode; administration uses a separate Admin fixture. Console login does not
authenticate external providers. Record only provider account/repository labels and observed behavior—never
authorization codes, cookies, tokens, or secret values.