dev-ui-bootstrap

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. Use when this capability is needed.
metadata	{"author":"cozystack"}

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.

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.

Use the phrasing "cozystack:dev-ui-bootstrap" (not "the skill") in messages to the operator, and state progress at each phase boundary.

Match the operator's natural language detected from prior conversation messages — use it in prompts, AskUserQuestion options, summaries, and gates. Code identifiers, commands, file paths, and commit messages stay in their canonical form (usually English).

Phase 1 — Parse arguments

$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).
• --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

Resolve in priority order:

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.

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.

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.

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.

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.

Then, unless --no-install:

pnpm --filter @cozystack/console add -D @playwright/test

Unless --no-browser:

cd $WT/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.

Write $WT/apps/console/playwright.config.ts:

import { defineConfig, devices } from "@playwright/test"

export default defineConfig({
  testDir: "./e2e",
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: "list",
  use: {
    baseURL: process.env.E2E_BASE_URL ?? "http://localhost:<PORT>",
    trace: "on-first-retry",
    screenshot: "only-on-failure",
  },
  projects: [
    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
  ],
})

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).

Patch $WT/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.

Phase 6 — Bring up kubectl proxy

Goal: a kubectl proxy instance is reachable on $PROXY_PORT and is talking to the kubeconfig the operator picked, not whatever happened to be active in the shell.

1. Check whether lsof -nP -iTCP:$PROXY_PORT -sTCP:LISTEN (or ss -tlnp) already has a listener.
2. If yes, inspect the existing process command line (ps -p <pid> -o args=). If it is a kubectl proxy pointing at the same kubeconfig (look for --kubeconfig in the args; if absent, check KUBECONFIG env in /proc/<pid>/environ), reuse it. If it is something else (different kubeconfig, unrelated process), stop and AskUserQuestion: kill the occupant, pick a different proxy port (and accept the Phase 7 vite.config.ts edit gate), or cancel. Do not silently switch ports — Phase 7 prefers leaving vite.config.ts untouched, so a port switch is an operator-driven decision.
3. If no listener, resolve the target context and start a new proxy in the background:

   CTX=$(kubectl --kubeconfig <path> config current-context)
   kubectl --kubeconfig <path> --context $CTX proxy --port=$PROXY_PORT &
   

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.

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:

• 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.
• 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:

cd $WT && pnpm --filter @cozystack/console dev:e2e \
  >$WT/.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.

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)
• 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
• 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 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.
• 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

• 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.
• ~/.kube/ — separate kubeconfigs per cluster (this host uses one-file-per-cluster, not a merged config).

---

Source: cozystack/ccp — distributed by TomeVault.