Merge pull request #15 from cozystack/docs/dev-ui-bootstrap-in-tree

docs(dev-ui-bootstrap): retarget skill to the in-tree console

Author: myasnikovdaniil

plugins/cozystack/skills/dev-ui-bootstrap/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: dev-ui-bootstrap
-description: Bootstrap a UI dev sandbox — Playwright end-to-end testing scaffolding for the cozystack-ui SPA plus a Vite dev server connected to a chosen Kubernetes cluster. Use whenever the operator wants to fix, debug, screenshot, or write Playwright tests against the Cozystack console — e.g. "prepare cozystack-ui for a fix", "spin up the UI against my dev cluster", "install playwright in cozystack-ui", "give me a UI sandbox pointing at <kubeconfig>". Handles worktree creation, @playwright/test + Chromium install, playwright.config.ts, dev:e2e / test:e2e scripts, kubectl proxy against a kubeconfig, and a Vite server on a free port so the operator can immediately start poking at the running app.
+description: Bootstrap a UI dev sandbox — Playwright end-to-end testing scaffolding for the Cozystack console UI (vendored in the monorepo at `packages/system/dashboard/images/console`) plus a Vite dev server connected to a chosen Kubernetes cluster. Use whenever the operator wants to fix, debug, screenshot, or write Playwright tests against the Cozystack console — e.g. "prepare the console UI for a fix", "spin up cozystack-ui against my dev cluster", "install playwright in the console", "give me a UI sandbox pointing at <kubeconfig>". Handles monorepo worktree creation, @playwright/test + Chromium install, playwright.config.ts, dev:e2e / test:e2e scripts, kubectl proxy against a kubeconfig, and a Vite server on a free port so the operator can immediately start poking at the running app.
 argument-hint: "[--kubeconfig=<path>] [--worktree=<name>] [--port=<n>] [--proxy-port=<n>] [--no-install] [--no-browser]"
 ---
 
 # cozystack:dev-ui-bootstrap
 
-This skill puts an operator in front of a running, working copy of `cozystack-ui` with Playwright wired up, pointed at a real Kubernetes cluster of their choosing. It is the standard entry point for "I want to fix something in the UI" tasks — every step is reversible and avoids touching the repo's main worktree.
+This skill puts an operator in front of a running copy of the Cozystack console UI with Playwright wired up, pointed at a real Kubernetes cluster of their choosing. The UI is vendored in-tree in the `cozystack/cozystack` monorepo at `packages/system/dashboard/images/console` (the standalone `cozystack-ui` repo is archived). It is the standard entry point for "I want to fix something in the UI" tasks — every step is reversible and avoids touching the monorepo's main worktree.
 
 Work in reasoning mode. Walk through the phases in order. State which phase you are in as you go, so the operator can interrupt early if a default is wrong for their machine.
 
@@ -19,60 +19,67 @@ Match the operator's natural language detected from prior conversation messages
 `$ARGUMENTS` is the free-form tail after `/cozystack:dev-ui-bootstrap`. Extract:
 
 - `--kubeconfig=<path>` — kubeconfig the Vite dev server should hit through `kubectl proxy`. If absent: list `~/.kube/*config*` files via `ls`, then `AskUserQuestion` to pick one, defaulting to `~/.kube/config` (or `$KUBECONFIG` if set). Never assume `~/.kube/config` silently — picking the wrong cluster is a frequent footgun.
-- `--worktree=<name>` — name (relative to `<repo>/.claude/worktrees/`) for the throwaway worktree. Default: `fix-app` (matches the in-tree convention).
-- `--port=<n>` — Vite dev port. Default: pick the first free port starting at `3002` (since `3001` is the repo default and is often already in use by another session).
-- `--proxy-port=<n>` — `kubectl proxy` port. Default: `8001` (matches `apps/console/vite.config.ts`). If already in use by a proxy pointing at a *different* kubeconfig, pick the next free port (see Phase 7 for the Vite-side consequence).
+- `--worktree=<name>` — name (relative to `<repo>/.claude/worktrees/`) for the throwaway monorepo worktree. Default: `fix-app`.
+- `--port=<n>` — Vite dev port. Default: pick the first free port starting at `3002` (since `3001` is the console default and is often already in use by another session).
+- `--proxy-port=<n>` — `kubectl proxy` port. Default: `8001` (matches the console's `apps/console/vite.config.ts`). If already in use by a proxy pointing at a *different* kubeconfig, pick the next free port (see Phase 7 for the Vite-side consequence).
 - `--no-install` — skip `pnpm install` and `@playwright/test` install if they are already present.
 - `--no-browser` — skip `npx playwright install chromium`.
 
-## Phase 2 — Locate the cozystack-ui repo
+## Phase 2 — Locate the console workspace (in-tree in the monorepo)
 
-Resolve in priority order:
+The console UI is a pnpm workspace inside the monorepo, not a standalone repo. Resolve two paths:
 
-1. If `pwd` is inside a checkout of `cozystack-ui` (contains `apps/console/package.json` with `"name": "@cozystack/console"`) → use the repo root from `git rev-parse --show-toplevel`.
-2. `~/aenix/cozystack-ui` — the canonical clone on contributors' workstations.
-3. Otherwise — `AskUserQuestion` for the path. Do not `git clone`; the skill is for an already-cloned working copy.
+- `$REPO` — the `cozystack/cozystack` monorepo root (git / worktree operations happen here).
+- `$CONSOLE` — the workspace root, `$REPO/packages/system/dashboard/images/console` (all `pnpm` / `vite` / `playwright` / file edits happen here; it holds `pnpm-workspace.yaml`, the root `package.json`, `pnpm-lock.yaml`, and `apps/console`).
 
-Verify `pnpm` and `kubectl` are on `$PATH`, and that the workspace's `package.json` has `"packageManager": "pnpm@..."`. If either binary is missing, stop and tell the operator to install it — do not auto-install package managers or CLIs. Catching this here avoids failing five phases deeper when `kubectl proxy` is first invoked.
+Resolve `$REPO` in priority order:
+
+1. If `pwd` is inside a cozystack monorepo checkout whose `<toplevel>/packages/system/dashboard/images/console/apps/console/package.json` has `"name": "@cozystack/console"` → use the toplevel from `git rev-parse --show-toplevel`.
+2. `~/aenix/cozystack` — the canonical monorepo clone on contributors' workstations.
+3. Otherwise — `AskUserQuestion` for the monorepo path. Do not `git clone`; the skill is for an already-cloned working copy.
+
+> The console UI used to live in a standalone `cozystack-ui` repo. It was vendored into the monorepo (cozystack/cozystack#2963) and that repo is archived — there is no `~/aenix/cozystack-ui` to use anymore.
+
+Verify `pnpm` and `kubectl` are on `$PATH`, and that `$CONSOLE/package.json` has `"packageManager": "pnpm@..."`. If either binary is missing, stop and tell the operator to install it — do not auto-install package managers or CLIs. Catching this here avoids failing five phases deeper when `kubectl proxy` is first invoked.
 
 ## Phase 3 — Worktree creation
 
-Create a feature worktree off `main` for the upcoming fix work. The repo's CLAUDE.md is emphatic that the primary working directory must stay on its default branch — multiple Claude sessions share it.
+Create a feature worktree of the **monorepo** off `main` for the upcoming fix work. The user's CLAUDE.md is emphatic that the primary working directory must stay on its default branch — multiple Claude sessions share it.
 
 ```bash
-git -C <repo> worktree add <repo>/.claude/worktrees/<name> -b fix/<name> main
+git -C $REPO worktree add $REPO/.claude/worktrees/<name> -b fix/<name> main
 ```
 
 If a worktree at that path already exists:
 
 - If clean and on the expected branch → reuse it; no `git worktree add`.
 - If dirty or on a different branch → `AskUserQuestion`: reuse / pick a new name / cancel.
 
-Set `$WT` to the absolute worktree path. Every subsequent command in this skill runs from `$WT`.
+Set `$WT` to the absolute worktree path, and re-point `$CONSOLE` into it: `$CONSOLE="$WT/packages/system/dashboard/images/console"`. Every subsequent `pnpm` / `vite` / `playwright` / file command in this skill runs from `$CONSOLE`; only `git` and worktree operations use `$REPO` / `$WT`.
 
 ## Phase 4 — Install dependencies
 
-Always run `pnpm install` once in `$WT` (fast no-op if the lockfile is satisfied) — workspace symlinks must exist before Playwright lands.
+Always run `pnpm install` once in `$CONSOLE` (fast no-op if the lockfile is satisfied) — workspace symlinks must exist before Playwright lands. (Run it from `$CONSOLE`, not `$WT`: the monorepo root is not a pnpm workspace; the console subdirectory is.)
 
 Then, unless `--no-install`:
 
 ```bash
-pnpm --filter @cozystack/console add -D @playwright/test
+cd $CONSOLE && pnpm --filter @cozystack/console add -D @playwright/test
 ```
 
 Unless `--no-browser`:
 
 ```bash
-cd $WT/apps/console && pnpm exec playwright install chromium
+cd $CONSOLE/apps/console && pnpm exec playwright install chromium
 ```
 
 Chromium is ~120 MB. Note the size in the running commentary so an operator on a slow link knows what is happening. The download lives in `~/.cache/ms-playwright/` and is shared across worktrees — usually a one-time cost.
 
 ## Phase 5 — Write Playwright config + scripts
 
-Idempotency: if `apps/console/playwright.config.ts` already exists, diff against the template below and ask before overwriting — the operator may have customised it.
+Idempotency: if `$CONSOLE/apps/console/playwright.config.ts` already exists, diff against the template below and ask before overwriting — the operator may have customised it.
 
-Write `$WT/apps/console/playwright.config.ts`:
+Write `$CONSOLE/apps/console/playwright.config.ts`:
 
 ```ts
 import { defineConfig, devices } from "@playwright/test"
@@ -97,14 +104,14 @@ export default defineConfig({
 
 Replace `<PORT>` with the resolved Vite dev port. The `E2E_BASE_URL` env-var override lets CI or another session point Playwright at a different running instance.
 
-Create `$WT/apps/console/e2e/` (empty — tests land here as the operator writes them).
+Create `$CONSOLE/apps/console/e2e/` (empty — tests land here as the operator writes them).
 
-Patch `$WT/apps/console/package.json` `"scripts"` with `Edit` — preserve unrelated keys, do not rewrite the whole file:
+Patch `$CONSOLE/apps/console/package.json` `"scripts"` with `Edit` — preserve unrelated keys, do not rewrite the whole file:
 
 - Add `"dev:e2e": "vite --port <PORT>"` next to `"dev"`.
 - Add `"test:e2e": "playwright test"` next to `"test"`.
 
-No semicolons in the config file — the repo's CLAUDE.md is strict: every file in the tree is semicolon-free, and reformatting unrelated files is forbidden.
+No semicolons in the config file — the console's `CLAUDE.md` is strict: every file in the tree is semicolon-free, and reformatting unrelated files is forbidden.
 
 ## Phase 6 — Bring up `kubectl proxy`
 
@@ -119,53 +126,55 @@ Goal: a `kubectl proxy` instance is reachable on `$PROXY_PORT` and is talking to
    ```
 4. Smoke-test with `curl -sS -o /dev/null -w "%{http_code}" http://localhost:$PROXY_PORT/api`. Expect `200`. `/api` is the unauthenticated API-group discovery endpoint — it returns `200` from any reachable apiserver and avoids false negatives from RBAC-restricted kubeconfigs that cannot `get namespaces/default`. On `401`/`403` the kubeconfig is wrong or expired — surface the error and stop. On connection refused, wait up to 5 s for the proxy to come up before failing.
 
-Capture the proxy process ID and the kubeconfig path in a marker file at `$WT/.cozystack-dev-ui-bootstrap-proxy` so a follow-up session knows what is running. Never write secrets there — kubeconfig path and context name only.
+Capture the proxy process ID and the kubeconfig path in a marker file at `$CONSOLE/.cozystack-dev-ui-bootstrap-proxy` so a follow-up session knows what is running. Never write secrets there — kubeconfig path and context name only.
 
 ## Phase 7 — Start the Vite dev server
 
-If `$PROXY_PORT` is non-default (8001), the dev server still hard-codes `http://localhost:8001` in `vite.config.ts`. Two options:
+If `$PROXY_PORT` is non-default (8001), the dev server still hard-codes `http://localhost:8001` in `apps/console/vite.config.ts`. Two options:
 
-- Preferred: keep the default proxy port `8001` and explain why. The repo treats `vite.config.ts` as load-bearing and edits there are best left for a separate PR.
+- Preferred: keep the default proxy port `8001` and explain why. The console treats `vite.config.ts` as load-bearing and edits there are best left for a separate PR.
 - If the operator explicitly said "change the proxy port", `AskUserQuestion` before touching `vite.config.ts`.
 
-Start the dev server in the background, redirecting output to a log file under `$WT` so the polling loop has something to grep:
+Start the dev server in the background, redirecting output to a log file under `$CONSOLE` so the polling loop has something to grep:
 
 ```bash
-cd $WT && pnpm --filter @cozystack/console dev:e2e \
-  >$WT/.cozystack-dev-ui-bootstrap-vite.log 2>&1 &
+cd $CONSOLE && pnpm --filter @cozystack/console dev:e2e \
+  >$CONSOLE/.cozystack-dev-ui-bootstrap-vite.log 2>&1 &
 ```
 
-Wait for the `ready in` / `Local:` line via a polling loop against that log file (`until grep -q "ready in" $WT/.cozystack-dev-ui-bootstrap-vite.log; do sleep 0.5; done`, with a 30 s timeout guard). Then `curl -sS -o /dev/null -w "%{http_code}" http://localhost:$PORT/` and expect `200`.
+Wait for the `ready in` / `Local:` line via a polling loop against that log file (`until grep -q "ready in" $CONSOLE/.cozystack-dev-ui-bootstrap-vite.log; do sleep 0.5; done`, with a 30 s timeout guard). Then `curl -sS -o /dev/null -w "%{http_code}" http://localhost:$PORT/` and expect `200`.
 
 If the server fails to bind (port already in use after the free-port scan), the cause is usually a stale `vite` from a prior crashed session. Run `lsof -nP -iTCP:$PORT -sTCP:LISTEN` and show the result — let the operator decide whether to kill it.
 
 ## Phase 8 — Summary
 
 Print a compact handoff:
 
-- Worktree: `$WT` (branch `fix/<name>`)
-- Repo state: clean / dirty (one-line `git status -s`)
+- Monorepo worktree: `$WT` (branch `fix/<name>`); console workspace at `$CONSOLE`
+- Repo state: clean / dirty (one-line `git -C $WT status -s`)
 - Kubeconfig: `<path>` → cluster context `<name>` (resolved in Phase 6)
 - `kubectl proxy`: `pid <n>` on `http://localhost:$PROXY_PORT` (smoke `200`)
 - Vite dev: `pid <n>` on `http://localhost:$PORT` (smoke `200`)
-- Playwright: configured at `apps/console/playwright.config.ts`, run with `pnpm --filter @cozystack/console test:e2e`
+- Playwright: configured at `$CONSOLE/apps/console/playwright.config.ts`, run with `pnpm --filter @cozystack/console test:e2e` from `$CONSOLE`
 - Next steps the operator can take, e.g.: "Tell me what to fix, or paste a Playwright test idea and I will draft it."
 
 Do **not** open the browser. Leave that to the operator — the dev server is reachable and the operator may want to attach an authenticated session, devtools, or a screen recorder of their own choice.
 
 ## Guardrails
 
-- **Never** run `git checkout` in the primary `cozystack-ui` working tree. All branch work happens inside the worktree from Phase 3.
-- **Never** edit files in the primary working tree of `cozystack-ui` — only inside `$WT`.
+- **Never** run `git checkout` in the primary cozystack monorepo working tree. All branch work happens inside the worktree from Phase 3.
+- **Never** edit files in the primary monorepo working tree — only inside `$WT` / `$CONSOLE`.
 - **Never** commit, push, or open a PR as part of this skill. The skill *prepares* the environment; the fix itself is a separate, operator-driven step that goes through the normal commit / PR gates.
 - **Never** start a `kubectl proxy` with a kubeconfig the operator did not explicitly pick. If `--kubeconfig` is absent, ask.
 - **Never** kill a process the operator did not authorise. If a port is occupied, show what is on it and stop.
-- **Never** add a new top-level dependency to the cozystack-ui workspace other than `@playwright/test`. The repo's CLAUDE.md is strict about bundle size; Playwright is dev-only and acceptable.
+- **Never** add a new top-level dependency to the console workspace other than `@playwright/test`. The console's `CLAUDE.md` is strict about bundle size; Playwright is dev-only and acceptable.
 - Refuse to run against a kubeconfig whose current-context name contains `prod` unless the operator re-confirms with `AskUserQuestion`. The console is read/write — pointing it at production is a deploy-shaped risk.
 
 ## References
 
+All paths below are relative to `$CONSOLE` (`packages/system/dashboard/images/console` inside the monorepo):
+
 - `apps/console/vite.config.ts` — the existing dev server proxy contract (`/api`, `/apis`, `/k8s` → `http://localhost:8001`).
 - `apps/console/package.json` — where the new `dev:e2e` and `test:e2e` scripts land.
-- `CLAUDE.md` (repo root) — code style (no semicolons, `.ts` extensions in imports, no `any`, etc.) and the worktree mandate.
+- `CLAUDE.md` (at `$CONSOLE`) — code style (no semicolons, `.ts` extensions in imports, no `any`, etc.). The monorepo root `AGENTS.md` covers the broader worktree mandate.
 - `~/.kube/` — separate kubeconfigs per cluster (this host uses one-file-per-cluster, not a merged config).