@coralai/sps-cli 0.42.0 → 0.44.0

package/skills/frontend/references/testing.md

@@ -0,0 +1,216 @@
+# Frontend Testing
+
+Component tests, E2E (Playwright), visual regression. For TDD, see `coding-standards/references/tdd.md`.
+
+## The pyramid, frontend version
+
+```
+         ▲
+         │   Visual / E2E (5%)       ← real browser, real flows
+         │   Integration (20%)        ← component + key deps; real rendering
+         │   Unit (75%)               ← functions, hooks, reducers; no DOM
+         ▼
+```
+
+Invert this and tests become slow, flaky, and your fast feedback loop dies.
+
+## Unit tests — pure logic
+
+For reducers, selectors, utility functions, validation. Same rules as any language.
+
+```
+describe('priceWithTax', () => {
+  it('adds tax by rate', () => {
+    expect(priceWithTax(100, 0.2)).toBe(120);
+  });
+});
+```
+
+## Component tests — Testing Library philosophy
+
+Test the component through the accessibility tree, not through implementation internals.
+
+```
+import { render, screen } from '@testing-library/react';
+import { userEvent } from '@testing-library/user-event';
+
+test('submit is disabled until email is valid', async () => {
+  render(<SignupForm />);
+  const email = screen.getByLabelText(/email/i);
+  const submit = screen.getByRole('button', { name: /sign up/i });
+
+  expect(submit).toBeDisabled();
+  await userEvent.type(email, 'a@x.com');
+  expect(submit).toBeEnabled();
+});
+```
+
+Key conventions:
+- **Query by role** (`getByRole('button', { name: 'Save' })`) — that's what a screen reader sees.
+- **Query by label / text** for inputs and visible content.
+- **Never by className / test-id unless nothing else works.**
+- **Never assert on implementation details** (internal state, prop changes, class names).
+
+## Mock at the network boundary
+
+Don't mock internal hooks. Mock the fetch / WS. Tests stay honest.
+
+```
+import { setupServer } from 'msw/node';
+import { http, HttpResponse } from 'msw';
+
+const server = setupServer(
+  http.get('/api/users/:id', ({ params }) =>
+    HttpResponse.json({ id: params.id, email: 'a@x.com' })
+  ),
+);
+
+beforeAll(() => server.listen());
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+
+test('loads and renders user', async () => {
+  render(<UserCard id="u1" />);
+  expect(await screen.findByText('a@x.com')).toBeInTheDocument();
+});
+```
+
+MSW (Mock Service Worker) works for unit/integration tests and in the browser. Same mocks everywhere.
+
+## Async: `findBy` over `waitFor` + `getBy`
+
+```
+# ✅ waits implicitly; throws if not found in time
+expect(await screen.findByText('Welcome')).toBeInTheDocument();
+
+# ❌ verbose
+await waitFor(() => expect(screen.getByText('Welcome')).toBeInTheDocument());
+```
+
+## Don't sleep in tests
+
+If `setTimeout(..., 500)` is the only way to make it pass, fake the timer:
+
+```
+vi.useFakeTimers();
+// interact
+vi.advanceTimersByTime(500);
+// assert
+vi.useRealTimers();
+```
+
+Real sleeps make tests slow and flaky.
+
+## Hook / composable tests
+
+```
+import { renderHook, act } from '@testing-library/react';
+
+test('useCounter increments', () => {
+  const { result } = renderHook(() => useCounter());
+  act(() => result.current.increment());
+  expect(result.current.count).toBe(1);
+});
+```
+
+Vue's equivalent uses `mount` with a minimal wrapper.
+
+## Store / reducer tests
+
+Pure functions — test without a DOM.
+
+```
+test('cartReducer adds item', () => {
+  const state = cartReducer(initial, { type: 'add', item });
+  expect(state.items).toHaveLength(1);
+});
+```
+
+If you need the store under Redux-Toolkit or similar, create a test-only store instance. Don't export globals shared across tests.
+
+## E2E — Playwright (or Cypress)
+
+Playwright has clear advantages:
+- First-class TypeScript, no CLI glue.
+- Multi-browser (Chromium, Firefox, WebKit).
+- Parallel by default.
+- Network interception built in.
+
+```
+import { test, expect } from '@playwright/test';
+
+test('signup flow', async ({ page }) => {
+  await page.goto('/signup');
+  await page.getByLabel('Email').fill('a@x.com');
+  await page.getByLabel('Password').fill('correct horse battery staple');
+  await page.getByRole('button', { name: 'Create account' }).click();
+  await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();
+});
+```
+
+Rules:
+- **Write by role / label**, not CSS selectors.
+- **Wait for state, not for time.** Playwright's `expect().toBeVisible()` auto-retries.
+- **Own your data.** Seed the DB (API or fixture) before each test; tests shouldn't depend on state from other tests.
+- **Keep E2E to happy-path + critical flows.** Unit / integration cover the combinatorics.
+
+## Visual regression
+
+Tools: Playwright built-in screenshot diff, Chromatic (Storybook), Percy, Applitools.
+
+```
+await expect(page).toHaveScreenshot('home.png');
+```
+
+Traps:
+- Flaky anti-alias / font rendering across OSes → run on Linux in CI only, accept minor diff tolerance.
+- Time / random IDs in the screenshot → stub or mask.
+- Snapshot explosion (one per page × browser × theme) → be selective.
+
+Great for design systems and key pages. Less valuable for the long tail.
+
+## Storybook
+
+Isolate components. One story per variant.
+
+```
+export default { title: 'Button' };
+
+export const Primary = () => <Button variant="primary">Save</Button>;
+export const Disabled = () => <Button disabled>Save</Button>;
+export const Long = () => <Button>Save my very long message</Button>;
+```
+
+- Run component tests against stories (`play` function).
+- Run a11y checks against stories (`@storybook/addon-a11y`).
+- Use as visual regression fixture.
+
+Kills the "how did the component look in that one state again?" question.
+
+## CI configuration
+
+Typical split:
+
+| Stage | Runs | On |
+|---|---|---|
+| Unit | Every commit | All PRs, fast fail |
+| Integration / component | Every commit | All PRs |
+| E2E happy path | Every commit | PRs, on staging |
+| Visual regression | Daily + on design-touching PRs | Scheduled |
+| Full E2E matrix | On main / pre-release | Nightly |
+
+Run the cheap ones on every commit; save the expensive ones for what they uniquely catch.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| Testing internal state / prop of a component | Test behaviour the user experiences |
+| Snapshot tests for entire pages | Brittle; use for specific outputs |
+| `data-testid` everywhere | Rely on roles / labels first |
+| Mocking React / Vue internals | You're testing the framework, not your code |
+| Shared global state between E2E tests | Seed per-test; reset between |
+| 50 E2E tests, 5 unit tests | Flip the pyramid |
+| Waiting for `await page.waitForTimeout(1000)` | Wait for a condition / state |
+| Testing against prod or shared staging | Test against ephemeral / dedicated env |
+| CSS-class-based assertions (`toHaveClass('active')`) | Assert on observable effect (visible text, role, aria) |

package/skills/frontend-developer/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: frontend-developer
+description: Persona skill — think like a frontend developer. Users, latency, accessibility, state clarity. Overlay on top of `frontend` + language skills. For patterns, load `frontend`.
+origin: agency-agents-fork + original (https://github.com/msitarzewski/agency-agents, MIT)
+---
+
+# Frontend Developer
+
+Think like a frontend developer. This is a **mindset overlay** — load `frontend` for patterns.
+
+## When to load
+
+- Building / reviewing UI
+- Making a call on what state shape to use
+- Reviewing a design for technical feasibility
+- Debating component API, routing, or data fetching
+- Triaging a frontend perf / a11y issue
+
+## The posture
+
+1. **Users don't see your code.** They see latency, layout shifts, broken keyboards. Measure what they experience.
+2. **State is the hard part.** Components are easy. Server state ≠ client state ≠ URL state — don't mix them.
+3. **Native first, custom second.** `<button>` beats `<div role="button">`. Always.
+4. **Every feature has a loading state AND an error state.** Design all three up front, not "happy path, will add later".
+5. **Accessibility is correctness.** Keyboard, contrast, screen reader. Not a final pass.
+6. **Perf is a feature, not an optimization pass.** Budgets in CI, not hope.
+7. **The browser is hostile.** Old versions, slow networks, third-party scripts, ad blockers. Degrade gracefully.
+
+## The questions you always ask
+
+- **What does this look like at 300 ms latency?** Many interactions.
+- **What if the fetch fails halfway?** Partial render, retry, error message.
+- **What if the user presses Tab?** Does focus go where a keyboard user expects?
+- **What state is this, exactly?** Local, shared, server, URL, derived?
+- **Is this URL bookmarkable?** Would I land on the same view if I pasted it?
+- **Which images / fonts / scripts block first paint?** Measure LCP.
+- **Does this work with JavaScript disabled / broken?** (For critical content paths.)
+- **Is this accessible with a screen reader?** Actually tested, not just "has alt attributes".
+- **Who re-renders when this state changes?** Keep the blast radius small.
+- **What does this cost in bundle bytes?** Every library has a weight.
+
+## The checklist
+
+### UX shape
+- [ ] Loading state designed
+- [ ] Error state designed with actionable message
+- [ ] Empty state designed
+- [ ] Disabled states clear (not just grayed out — provide the reason)
+- [ ] Optimistic updates for user-initiated writes
+
+### Accessibility
+- [ ] Semantic HTML throughout
+- [ ] Keyboard-navigable
+- [ ] Visible focus styles (`:focus-visible`)
+- [ ] Screen-reader tested for critical flows
+- [ ] Contrast ≥ WCAG AA (4.5:1 text / 3:1 UI)
+- [ ] Respects `prefers-reduced-motion`
+
+### State
+- [ ] Server data via a cache lib (TanStack Query / SWR / Apollo / equivalent)
+- [ ] No duplicate sources of truth
+- [ ] URL holds filters / selected tabs / deep state
+- [ ] Forms validate client-side + server-side
+- [ ] Drafts persisted where the user expects (offline / reload)
+
+### Performance
+- [ ] LCP < 2.5 s, INP < 200 ms, CLS < 0.1 (at 75th percentile)
+- [ ] Images sized to display; lazy below the fold
+- [ ] Bundle analysis done; no 5 MB surprises
+- [ ] Route-level code splitting
+- [ ] Virtualization for long lists
+- [ ] Web fonts preloaded with `font-display: swap`
+
+### Code
+- [ ] Components do one thing
+- [ ] Props typed
+- [ ] Side effects in hooks / stores, not in render
+- [ ] No `any` / untyped data
+- [ ] Dead code / commented-out code removed
+
+## Tradeoffs you name
+
+- **CSR vs. SSR vs. SSG** — per-page, based on content and SEO needs.
+- **Controlled vs. uncontrolled** — controlled for complex forms, uncontrolled for simple.
+- **Optimistic vs. pessimistic** — optimistic for routine writes, pessimistic for dangerous ones (payments, delete).
+- **Animation vs. function** — animation is a detail; don't block interactions.
+- **Client-side vs. server-side validation** — both, not one.
+
+## What you push back on
+
+- **Designs that ignore loading / error / empty states.** Those ARE the user experience.
+- **Accessibility-as-final-sprint.** Costs more to retrofit.
+- **"Just wrap it in a div with onClick".** No.
+- **Reactive libraries for static data.** Over-engineering.
+- **Prop drilling 6 levels deep.** Context / composition.
+- **Toasts / dialogs for critical errors.** Modals that block progress, then. Not a toast that vanishes.
+
+## Forbidden patterns
+
+- `<div onClick>` where `<button>` / `<a>` fits
+- Placeholder used as label
+- Color as the only error signal
+- Business logic in JSX
+- `useEffect` to derive state (use computed values / `useMemo`)
+- Untyped data at boundaries
+- Images without `width`/`height` (layout shift)
+- Toasts swallowing irrecoverable errors
+- "Submit" enabled during in-flight submit (double-submit bug)
+- Hand-rolled date pickers / selects that ignore keyboard / screen reader
+
+## Pair with
+
+- [`frontend`](../frontend/SKILL.md) — the patterns.
+- A language skill (`typescript`) — syntax and types.
+- [`coding-standards`](../coding-standards/SKILL.md) — general principles.

package/skills/git-workflow/SKILL.md

@@ -0,0 +1,355 @@
+---
+name: git-workflow
+description: Workflow skill — git hygiene beyond commit-message style. Branching, rebasing, conflict resolution, recovering from mistakes. For commit-message format and PR sizing, see `coding-standards/references/commits-and-prs.md`.
+origin: original
+---
+
+# Git Workflow
+
+Day-to-day git habits for keeping history useful and recovery cheap. For commit message style and PR sizing, load [`coding-standards/references/commits-and-prs.md`](../coding-standards/references/commits-and-prs.md).
+
+## When to load
+
+- Starting a new feature branch
+- Reviewing how to structure a series of commits
+- Resolving a merge / rebase conflict
+- Recovering from a "bad git operation"
+- Onboarding to a repo with a specific workflow (trunk-based, GitFlow, etc.)
+
+## The posture
+
+1. **Commits are communication.** The history is read by your future self and your teammates. Make it readable.
+2. **Small, logical, atomic commits.** Each commit reverts cleanly. Each commit tells one story.
+3. **Rebase your own branch; never shared branches.** History rewriting on public branches breaks everyone.
+4. **Never `--force` without `--force-with-lease`.** The safer form checks no one else has pushed.
+5. **Lost work is usually recoverable.** `git reflog` remembers.
+6. **When in doubt, stash or branch before experimenting.** Cheap insurance.
+
+## Workflow patterns
+
+Pick one per project and stick to it.
+
+### Trunk-based
+
+Short-lived branches, merge to `main` at least daily. Best for CI-strong teams.
+
+```
+main ─────────────●──────●──────●──────●──────
+                  ↑      ↑      ↑      ↑
+                  feature branches, 1–3 days each
+```
+
+Pros: minimal merge pain, fast feedback, clear integration point.
+Cons: needs strong CI and feature flags to ship incomplete work safely.
+
+### Feature-branch + PR (pragmatic default)
+
+Named branches per feature, merged via PR to `main`. Branches live days to a week.
+
+```
+main ─────●────────●────────●─────
+           \      /  \      /
+            feature1    feature2
+```
+
+Most teams. Rebase on `main` before merging to keep history linear.
+
+### GitFlow
+
+`develop`, `release/*`, `hotfix/*` alongside `main`. Heavier; fits products with long support branches.
+
+```
+main (release tags)
+  │
+  ├─ release/* (stabilization)
+  │
+  └─ develop
+       ├─ feature/*
+       └─ hotfix/* → main + develop
+```
+
+Use when you ship monthly / quarterly and have parallel release support. Overkill for most web apps.
+
+## Branch naming
+
+```
+<type>/<short-slug>
+
+feat/partial-shipments
+fix/auth-alg-none
+chore/bump-node-20
+refactor/extract-validator
+```
+
+Include a ticket id if your team tracks: `fix/SEC-412-alg-none`.
+
+Rules:
+- Lowercase + hyphens.
+- No personal names (`alice/wip`); one-off personal branches die without review.
+- No `feature/` prefix — type is the prefix, and `feature/` duplicates.
+
+## The commit loop
+
+Good session flow:
+
+1. `git status` before starting — clean? any leftover changes?
+2. Make a change; run tests.
+3. `git diff` — review before staging.
+4. `git add -p` — stage in logical chunks, not everything blindly.
+5. `git commit` — one logical change, good message.
+6. Repeat.
+
+`-p` (patch) mode is underrated. It lets you split "one big edit" into several commits.
+
+## Rebase your own branch on `main`
+
+Keeps a clean linear history and avoids dirty "Merge main into feature" commits.
+
+```bash
+git fetch origin
+git rebase origin/main
+# resolve conflicts if any
+git push --force-with-lease
+```
+
+Never rebase a branch others are working on — they'll have conflicts and lose commits.
+
+## Interactive rebase — clean up your history
+
+Before opening a PR:
+
+```bash
+git rebase -i origin/main
+```
+
+Opens an editor listing your commits. Actions:
+
+| Action | Effect |
+|---|---|
+| `pick` | Keep as-is |
+| `reword` | Change the commit message |
+| `edit` | Stop to amend the commit |
+| `squash` | Combine with the previous commit; edit message |
+| `fixup` | Combine with previous; keep previous message |
+| `drop` | Delete |
+
+Use to squash WIP commits, fix typos in messages, reorder logically. Don't use on already-pushed-to-shared branches.
+
+## Handling conflicts
+
+When rebase or merge hits a conflict:
+
+```bash
+# git marks conflict files; you edit and resolve
+<<<<<<< HEAD
+your code
+=======
+their code
+>>>>>>> branch
+
+# After editing:
+git add <resolved-files>
+git rebase --continue         # or git merge --continue
+
+# To back out:
+git rebase --abort
+```
+
+Rules:
+- **Read both sides.** Don't just pick one wholesale.
+- **Ensure tests pass after the resolution.** A bad merge compiles but breaks behaviour.
+- **Commit the resolution as is.** Don't mix in other changes.
+
+### `rerere` — reuse recorded resolutions
+
+Turn on once, saves pain on repeated rebases:
+
+```bash
+git config --global rerere.enabled true
+```
+
+Git remembers how you resolved a given conflict; applies it automatically next time the same conflict appears.
+
+## Force-push safely
+
+Rebasing changes commit SHAs, requiring a force-push. Use `--force-with-lease`:
+
+```bash
+git push --force-with-lease
+```
+
+`--force` overwrites the remote without checking. If someone else pushed to your branch, you silently overwrite their work. `--force-with-lease` fails safely in that case.
+
+Better alias:
+
+```bash
+git config --global alias.pf 'push --force-with-lease'
+```
+
+## Recovering lost work
+
+Almost all "lost" git operations are recoverable via `reflog`.
+
+```bash
+git reflog                     # list of everything HEAD has pointed to
+# HEAD@{0}: rebase: ...
+# HEAD@{1}: rebase: ...
+# HEAD@{2}: commit: "WIP"
+git checkout HEAD@{2}          # go back to the state before you broke it
+```
+
+If your last commit was broken and you ran `git reset --hard`:
+
+```bash
+git reflog
+git reset --hard HEAD@{1}      # restore
+```
+
+Works for ~90 days by default. The golden rule: **commit often. Committed work is almost never truly lost.**
+
+## `stash` — quick save
+
+Interrupting to switch branches?
+
+```bash
+git stash push -m "WIP: auth refactor"
+git switch other-branch
+
+# later
+git switch original-branch
+git stash pop                  # reapply and remove from stash
+# or:
+git stash apply stash@{0}       # reapply but keep in stash
+git stash list
+```
+
+Stash names help when you accumulate several. Don't let stashes pile up — they're not backup.
+
+## Cherry-pick
+
+```bash
+git cherry-pick <sha>
+```
+
+Copy a commit from another branch. Handy for:
+- Backporting a fix to a release branch.
+- Salvaging one commit from an abandoned branch.
+
+Avoid using cherry-pick as a regular integration strategy; it creates duplicate work in the history.
+
+## Worktrees — parallel branches
+
+```bash
+git worktree add ../myrepo-release release/v2
+# work in both directories simultaneously
+git worktree remove ../myrepo-release
+```
+
+One clone, multiple branches checked out in separate directories. Useful for long-running release branches, bisect, comparison.
+
+## `bisect` — find the commit that broke things
+
+```bash
+git bisect start
+git bisect bad                  # current is broken
+git bisect good v1.2.0          # this tag was fine
+
+# git checks out a commit in the middle; test it
+git bisect good                 # or bisect bad
+# repeat until git identifies the culprit
+git bisect reset
+```
+
+`git bisect run ./test.sh` automates it — git runs your script at each step.
+
+## `.gitignore` discipline
+
+Keep it current. Default entries:
+
+```
+# dependencies
+node_modules/
+.venv/
+target/
+
+# env / secrets
+.env
+.env.local
+*.pem
+*.key
+
+# IDE / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# build
+dist/
+build/
+*.pyc
+```
+
+If a file was committed by accident, ignoring it doesn't remove it — use `git rm --cached <file>` + commit.
+
+## `.gitattributes` — normalize line endings
+
+Avoid CRLF / LF chaos across Windows + Mac + Linux:
+
+```
+* text=auto eol=lf
+*.sh text eol=lf
+*.bat text eol=crlf
+*.png binary
+```
+
+Commit it; once everyone has it, cross-OS diffs go quiet.
+
+## Git hooks — local enforcement
+
+- **pre-commit** — run linter / formatter / tests before a commit is allowed.
+- **commit-msg** — enforce commit message format.
+- **pre-push** — run tests before push.
+
+Use a hook manager (`lefthook`, `husky`, `pre-commit`) so hooks are in the repo, shared with the team.
+
+```yaml
+# lefthook.yml
+pre-commit:
+  parallel: true
+  commands:
+    lint: { run: pnpm lint }
+    format-check: { run: pnpm format:check }
+```
+
+Don't `--no-verify` your hooks. If a hook fails, fix the underlying issue.
+
+## Recovery cheat-sheet
+
+| "I accidentally..." | Fix |
+|---|---|
+| Committed to wrong branch | `git reset --soft HEAD~1`, switch branches, recommit |
+| Deleted a branch | `git reflog` → find SHA → `git branch <name> <sha>` |
+| Force-pushed over someone | Coordinate; `git reflog` on their machine can recover |
+| Committed a secret | Rotate the secret immediately; history rewrite is secondary |
+| Lost uncommitted changes | `git reflog` only helps if committed; stashes via `git stash list` |
+| Merged wrong branch | `git reset --hard HEAD~1` (before push), or `git revert` (after push) |
+| Detached HEAD | `git branch <newname>` before switching away |
+
+## Forbidden patterns
+
+- `git push --force` (without `--force-with-lease`)
+- `--no-verify` to skip hooks because "they're annoying"
+- 20+ `WIP` / `fix` commits pushed to main (squash them)
+- Long-lived feature branches (weeks+) without merging / rebasing
+- Editing `.gitignore` without committing the removals that `.gitignore` was meant to catch
+- Rebasing a shared branch
+- Committing secrets (even if planning to remove next commit)
+- `git add -A` without review
+- Keeping personal branches around in the remote for months
+- Mixing rename + content change in one commit (hides the rename)
+
+## Pair with
+
+- [`coding-standards/references/commits-and-prs.md`](../coding-standards/references/commits-and-prs.md) — commit messages + PR sizing.
+- [`devops/references/ci-cd.md`](../devops/references/ci-cd.md) — branch protection + CI triggers.