create-command-center 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/LICENSE.agent-skills +21 -0
- package/README.md +42 -2
- package/RELEASING.md +25 -0
- package/UPSTREAM.md +11 -0
- package/bin/create-command-center.mjs +34 -0
- package/installer/install.mjs +103 -0
- package/installer/template/AGENTS.md +9 -0
- package/installer/template/README.md +11 -0
- package/installer/template/gitignore +4 -0
- package/installer/template/repos/index.md +5 -0
- package/package.json +16 -4
- package/references/accessibility-checklist.md +160 -0
- package/references/definition-of-done.md +67 -0
- package/references/observability-checklist.md +92 -0
- package/references/orchestration-patterns.md +370 -0
- package/references/performance-checklist.md +239 -0
- package/references/security-checklist.md +250 -0
- package/references/testing-patterns.md +236 -0
- package/skills/accessibility-engineering/SKILL.md +133 -0
- package/skills/accessibility-engineering/scripts/audit-a11y.sh +233 -0
- package/skills/api-and-interface-design/SKILL.md +369 -0
- package/skills/browser-testing-with-devtools/SKILL.md +319 -0
- package/skills/cc/SKILL.md +24 -0
- package/skills/cc/assets/config.md +24 -0
- package/skills/cc/assets/progress.md +23 -0
- package/skills/cc/references/jobs.md +28 -0
- package/skills/cc/references/registration.md +39 -0
- package/skills/ci-cd-and-automation/SKILL.md +395 -0
- package/skills/code-review-and-quality/SKILL.md +402 -0
- package/skills/code-simplification/SKILL.md +331 -0
- package/skills/constraint-driven-development/SKILL.md +319 -0
- package/skills/constraint-driven-development/references/floor-guard.md +182 -0
- package/skills/constraint-driven-development/scripts/quality-gate.mjs +45 -0
- package/skills/context-engineering/SKILL.md +353 -0
- package/skills/debugging-and-error-recovery/SKILL.md +300 -0
- package/skills/deprecation-and-migration/SKILL.md +252 -0
- package/skills/documentation-and-adrs/SKILL.md +320 -0
- package/skills/doubt-driven-development/SKILL.md +245 -0
- package/skills/frontend-ui-engineering/SKILL.md +346 -0
- package/skills/git-workflow-and-versioning/SKILL.md +355 -0
- package/skills/idea-refine/SKILL.md +195 -0
- package/skills/idea-refine/examples.md +238 -0
- package/skills/idea-refine/frameworks.md +99 -0
- package/skills/idea-refine/refinement-criteria.md +113 -0
- package/skills/idea-refine/scripts/idea-refine.sh +15 -0
- package/skills/incremental-implementation/SKILL.md +249 -0
- package/skills/interview-me/SKILL.md +235 -0
- package/skills/observability-and-instrumentation/SKILL.md +238 -0
- package/skills/performance-optimization/SKILL.md +267 -0
- package/skills/performance-optimization/references/optimization-patterns.md +250 -0
- package/skills/planning-and-task-breakdown/SKILL.md +259 -0
- package/skills/security-and-hardening/SKILL.md +216 -0
- package/skills/security-and-hardening/references/hardening-patterns.md +333 -0
- package/skills/shipping-and-launch/SKILL.md +336 -0
- package/skills/source-driven-development/SKILL.md +217 -0
- package/skills/spec-driven-development/SKILL.md +307 -0
- package/skills/test-driven-development/SKILL.md +400 -0
- package/skills/using-agent-skills/SKILL.md +194 -0
|
@@ -0,0 +1,250 @@
|
|
|
1
|
+
# Security Checklist
|
|
2
|
+
|
|
3
|
+
Quick reference for web application security. Use alongside the `security-and-hardening` skill.
|
|
4
|
+
|
|
5
|
+
## Table of Contents
|
|
6
|
+
|
|
7
|
+
- [Threat Modeling (Start Here)](#threat-modeling-start-here)
|
|
8
|
+
- [Pre-Commit Checks](#pre-commit-checks)
|
|
9
|
+
- [Authentication](#authentication)
|
|
10
|
+
- [Authorization](#authorization)
|
|
11
|
+
- [Input Validation](#input-validation)
|
|
12
|
+
- [Security Headers](#security-headers)
|
|
13
|
+
- [CORS Configuration](#cors-configuration)
|
|
14
|
+
- [Data Protection](#data-protection)
|
|
15
|
+
- [Dependency Security](#dependency-security)
|
|
16
|
+
- [AI / LLM Security](#ai--llm-security)
|
|
17
|
+
- [Error Handling](#error-handling)
|
|
18
|
+
- [OWASP Top 10 Quick Reference](#owasp-top-10-quick-reference)
|
|
19
|
+
- [OWASP Top 10 for LLMs Quick Reference](#owasp-top-10-for-llms-quick-reference)
|
|
20
|
+
|
|
21
|
+
## Threat Modeling (Start Here)
|
|
22
|
+
|
|
23
|
+
Before reaching for controls, spend five minutes thinking like an attacker:
|
|
24
|
+
|
|
25
|
+
- [ ] Trust boundaries mapped (requests, uploads, webhooks, third-party APIs, LLM output, and local values written by processes you don't control)
|
|
26
|
+
- [ ] Assets named (credentials, PII, payment data, admin actions, money movement)
|
|
27
|
+
- [ ] STRIDE run per boundary (Spoofing, Tampering, Repudiation, Info disclosure, DoS, Elevation)
|
|
28
|
+
- [ ] Abuse cases written next to use cases ("how would I misuse this?")
|
|
29
|
+
|
|
30
|
+
## Pre-Commit Checks
|
|
31
|
+
|
|
32
|
+
- [ ] No secrets in code (`git diff --cached -i -G'password|secret|api_key|token' --name-only` — lists only the names of files whose staged diff matches, never the value itself; any output means review those files before committing)
|
|
33
|
+
- [ ] `.gitignore` covers: `.env`, `.env.local`, `*.pem`, `*.key`
|
|
34
|
+
- [ ] `.env.example` uses placeholder values (not real secrets)
|
|
35
|
+
|
|
36
|
+
## Authentication
|
|
37
|
+
|
|
38
|
+
- [ ] Passwords hashed with bcrypt (≥12 rounds), scrypt, or argon2
|
|
39
|
+
- [ ] Session cookies: `httpOnly`, `secure`, `sameSite: 'lax'`
|
|
40
|
+
- [ ] Session expiration configured (reasonable max-age)
|
|
41
|
+
- [ ] Rate limiting on login endpoint (≤10 attempts per 15 minutes)
|
|
42
|
+
- [ ] Password reset tokens: time-limited (≤1 hour), single-use
|
|
43
|
+
- [ ] Account lockout after repeated failures (optional, with notification)
|
|
44
|
+
- [ ] MFA supported for sensitive operations (optional but recommended)
|
|
45
|
+
|
|
46
|
+
## Authorization
|
|
47
|
+
|
|
48
|
+
- [ ] Every protected endpoint checks authentication
|
|
49
|
+
- [ ] Every resource access checks ownership/role (prevents IDOR)
|
|
50
|
+
- [ ] Admin endpoints require admin role verification
|
|
51
|
+
- [ ] API keys scoped to minimum necessary permissions
|
|
52
|
+
- [ ] JWT tokens validated (signature, expiration, issuer)
|
|
53
|
+
|
|
54
|
+
## Input Validation
|
|
55
|
+
|
|
56
|
+
- [ ] All user input validated at system boundaries (API routes, form handlers)
|
|
57
|
+
- [ ] Validation uses allowlists (not denylists)
|
|
58
|
+
- [ ] String lengths constrained (min/max)
|
|
59
|
+
- [ ] Numeric ranges validated
|
|
60
|
+
- [ ] Email, URL, and date formats validated with proper libraries
|
|
61
|
+
- [ ] File uploads: type restricted, size limited, content verified
|
|
62
|
+
- [ ] SQL queries parameterized (no string concatenation)
|
|
63
|
+
- [ ] HTML output encoded (use framework auto-escaping)
|
|
64
|
+
- [ ] URLs validated before redirect (prevent open redirect)
|
|
65
|
+
- [ ] Server-side URL fetches allowlisted; private/reserved IPs blocked (prevent SSRF)
|
|
66
|
+
- [ ] Destructive path operations (delete/move/overwrite): symlinks resolved, allowlisted root, minimum depth, ownership evidence read before the call
|
|
67
|
+
|
|
68
|
+
### Destructive Path Operations
|
|
69
|
+
|
|
70
|
+
Containment for a target named by data. Resolve first, then decide — and treat the
|
|
71
|
+
result as a candidate, not as authorization:
|
|
72
|
+
|
|
73
|
+
```typescript
|
|
74
|
+
import { realpath, readFile } from 'node:fs/promises';
|
|
75
|
+
import { resolve, relative, isAbsolute, join, sep } from 'node:path';
|
|
76
|
+
|
|
77
|
+
const ALLOWED_ROOTS = ['/var/lib/myapp/sessions']; // an allowlist, not a pattern
|
|
78
|
+
const MIN_DEPTH = 1; // so a root is never the target
|
|
79
|
+
|
|
80
|
+
async function resolveDeletable(candidate: string, expectedOwner: string) {
|
|
81
|
+
const target = await realpath(resolve(candidate)); // symlinks resolved BEFORE the check
|
|
82
|
+
const inRoot = ALLOWED_ROOTS.some((root) => {
|
|
83
|
+
const rel = relative(root, target);
|
|
84
|
+
// `rel === '..'` / `'../'` only — a plain `startsWith('..')` would also
|
|
85
|
+
// reject a legitimate child named `..cache`.
|
|
86
|
+
if (rel === '' || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return false;
|
|
87
|
+
return rel.split(sep).length >= MIN_DEPTH;
|
|
88
|
+
});
|
|
89
|
+
if (!inRoot) throw new Error(`refusing: outside allowed roots (${target})`);
|
|
90
|
+
|
|
91
|
+
const owner = await readFile(join(target, '.owner'), 'utf8').catch(() => null);
|
|
92
|
+
if (owner?.trim() !== expectedOwner) throw new Error(`refusing: unproven owner (${target})`);
|
|
93
|
+
return target;
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
What this does not do, and must be said where the snippet is copied from:
|
|
98
|
+
|
|
99
|
+
- **The marker is self-attestation.** Anything that can write inside the root can write
|
|
100
|
+
`.owner`. `expectedOwner` has to come from authenticated state, and the marker needs
|
|
101
|
+
integrity protection (restrictive ownership, or a MAC) before it is authorization
|
|
102
|
+
rather than a consistency check against a misderived target.
|
|
103
|
+
- **Returning a path leaves a check/use race.** Where an untrusted process can swap an
|
|
104
|
+
ancestor between the check and the call, operate on a descriptor with no-follow,
|
|
105
|
+
beneath-the-root semantics, or guarantee the hierarchy is immutable for the duration.
|
|
106
|
+
|
|
107
|
+
## Security Headers
|
|
108
|
+
|
|
109
|
+
```
|
|
110
|
+
Content-Security-Policy: default-src 'self'; script-src 'self'
|
|
111
|
+
Strict-Transport-Security: max-age=31536000; includeSubDomains
|
|
112
|
+
X-Content-Type-Options: nosniff
|
|
113
|
+
X-Frame-Options: DENY
|
|
114
|
+
X-XSS-Protection: 0 (disabled, rely on CSP)
|
|
115
|
+
Referrer-Policy: strict-origin-when-cross-origin
|
|
116
|
+
Permissions-Policy: camera=(), microphone=(), geolocation=()
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
## CORS Configuration
|
|
120
|
+
|
|
121
|
+
```typescript
|
|
122
|
+
// Restrictive (recommended)
|
|
123
|
+
cors({
|
|
124
|
+
origin: ['https://yourdomain.com', 'https://app.yourdomain.com'],
|
|
125
|
+
credentials: true,
|
|
126
|
+
methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
|
|
127
|
+
allowedHeaders: ['Content-Type', 'Authorization'],
|
|
128
|
+
})
|
|
129
|
+
|
|
130
|
+
// NEVER use in production:
|
|
131
|
+
cors({ origin: '*' }) // Allows any origin
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## Data Protection
|
|
135
|
+
|
|
136
|
+
- [ ] Sensitive fields excluded from API responses (`passwordHash`, `resetToken`, etc.)
|
|
137
|
+
- [ ] Sensitive data not logged (passwords, tokens, full CC numbers)
|
|
138
|
+
- [ ] PII encrypted at rest (if required by regulation)
|
|
139
|
+
- [ ] HTTPS for all external communication
|
|
140
|
+
- [ ] Database backups encrypted
|
|
141
|
+
- [ ] Personal data is classified, collected against a stated purpose, and minimized
|
|
142
|
+
- [ ] Personal data has a retention limit and a working deletion path (incl. backups, caches, indexes)
|
|
143
|
+
- [ ] Export/delete (data-subject) requests are supported where required; third-party sharing has consent and a data-processing agreement
|
|
144
|
+
|
|
145
|
+
## Dependency Security
|
|
146
|
+
|
|
147
|
+
First locate the **installation boundary**. If the package is matched by a parent `workspaces` declaration, use that workspace root; otherwise use the nearest project root that owns both its manifest and dependency graph. At that boundary, corroborate `packageManager` (when present), the lockfile, and CI commands. Stop if they disagree or competing manager lockfiles exist there. A nested project is independent only when it is outside the parent workspace; independent subprojects may legitimately use different managers.
|
|
148
|
+
|
|
149
|
+
| Manager/version signal | Frozen/immutable CI install | Known-advisory audit |
|
|
150
|
+
|---|---|---|
|
|
151
|
+
| npm (`package-lock.json` or `npm-shrinkwrap.json`) | `npm ci` | `npm audit` |
|
|
152
|
+
| pnpm | `pnpm install --frozen-lockfile` | `pnpm audit` |
|
|
153
|
+
| Yarn 2+ | `yarn install --immutable` | `yarn npm audit -A -R` |
|
|
154
|
+
| Yarn 1 | `yarn install --frozen-lockfile` | `yarn audit` |
|
|
155
|
+
|
|
156
|
+
For an unlisted manager or version, consult its official documentation; do not substitute another manager's commands or newer defaults.
|
|
157
|
+
|
|
158
|
+
### Install-Script Gate
|
|
159
|
+
|
|
160
|
+
Never discover dependency lifecycle scripts by first executing an ordinary install on a client whose defaults have not been verified.
|
|
161
|
+
|
|
162
|
+
1. Bootstrap with dependency scripts disabled, or with a documented default-deny policy plus fail-closed enforcement.
|
|
163
|
+
2. Inspect the exact script source and package version before approval.
|
|
164
|
+
3. Record the narrowest native allow/deny policy at the installation boundary and commit it.
|
|
165
|
+
4. Run a clean frozen/immutable install with that policy and verify the required packages still build.
|
|
166
|
+
|
|
167
|
+
**Point-in-time snapshot:** Package-manager defaults and command names change quickly. Verify this matrix against the pinned client's current official documentation before relying on it.
|
|
168
|
+
|
|
169
|
+
| Manager version | Native policy |
|
|
170
|
+
|---|---|
|
|
171
|
+
| npm without verified granular approvals | Bootstrap with `npm ci --ignore-scripts`, or persist `ignore-scripts=true` when project-wide blocking is intended. Keep scripts disabled or deliberately upgrade before allowing any reviewed dependency script. |
|
|
172
|
+
| npm 11.18.x (verified on 11.18.0) | Unreviewed dependency scripts run with a warning by default. Enforce `strict-allow-scripts=true` before a normal install, then use the workspace-unaware `npm install-scripts ls` from the installation boundary; keep approvals version-pinned and denials name-wide. |
|
|
173
|
+
| npm 12.x (verified on 12.0.1) | Unreviewed dependency scripts are skipped by default; `strict-allow-scripts=true` makes their presence fail the install before execution. Use the same `npm install-scripts` review and approval flow. |
|
|
174
|
+
| pnpm 11+ | Use `pnpm approve-builds` and commit `allowBuilds` decisions; `strictDepBuilds` defaults to `true`, so unreviewed builds fail. |
|
|
175
|
+
| pnpm 10.26–10.x | Configure `allowBuilds` explicitly, or use `pnpm approve-builds` with the legacy `onlyBuiltDependencies` / `ignoredBuiltDependencies` lists. Set `strictDepBuilds: true`; its v10 default is `false`. |
|
|
176
|
+
| pnpm 10.1–10.25 | `pnpm approve-builds` records the legacy lists; enable `strictDepBuilds` where supported (10.3+). |
|
|
177
|
+
| Older or unknown pnpm | Bootstrap with `pnpm install --frozen-lockfile --ignore-scripts`. Keep scripts disabled unless the pinned version documents an enforceable policy. |
|
|
178
|
+
| Yarn 4.14+ | Dependency postinstalls are disabled by default. Grant only required exceptions with top-level `dependenciesMeta.<package>.built: true`. |
|
|
179
|
+
| Yarn 2–4.13 | Set `enableScripts: false` in `.yarnrc.yml`, then grant only required exceptions with top-level `dependenciesMeta.<package>.built: true`; do not enable scripts globally. |
|
|
180
|
+
| Yarn 1 | Bootstrap with `yarn install --ignore-scripts`; keep scripts disabled unless each required exception is reviewed under the pinned client's documented workflow. |
|
|
181
|
+
|
|
182
|
+
Authoritative checks: [npm install-scripts](https://docs.npmjs.com/cli/v11/commands/npm-install-scripts/), [install policy](https://docs.npmjs.com/cli/v11/commands/npm-install/), and [CLI releases](https://github.com/npm/cli/releases); [pnpm approve-builds](https://pnpm.io/cli/approve-builds) and [build settings](https://pnpm.io/settings#allowbuilds); [Yarn security](https://yarnpkg.com/features/security) and [manifest](https://yarnpkg.com/configuration/manifest#dependenciesMeta).
|
|
183
|
+
|
|
184
|
+
**Supply-chain hygiene** (advisory audits do not catch newly malicious packages):
|
|
185
|
+
- [ ] Exactly one authoritative lockfile per project/workspace root is committed and CI never rewrites it
|
|
186
|
+
- [ ] Critical/high findings are triaged for reachability; deferrals have a reason and review date
|
|
187
|
+
- [ ] Forced audit remediation (`npm audit fix --force` or equivalent) is never automatic; remediation diffs and changelogs are reviewed
|
|
188
|
+
- [ ] Registry signatures/provenance are verified where the manager supports it
|
|
189
|
+
- [ ] Dependency lifecycle scripts are blocked before first execution and approved only through the pinned manager's native policy
|
|
190
|
+
- [ ] New dependencies are reviewed for ownership, maintenance, release age, provenance, transitive graph, and typosquatting
|
|
191
|
+
|
|
192
|
+
## AI / LLM Security
|
|
193
|
+
|
|
194
|
+
For any feature that calls an LLM (chatbots, summarizers, agents, RAG):
|
|
195
|
+
|
|
196
|
+
- [ ] Model output treated as untrusted — never into `eval`/SQL/shell/`innerHTML`/file paths
|
|
197
|
+
- [ ] Prompt injection assumed; permissions enforced in code, not in the system prompt
|
|
198
|
+
- [ ] Secrets, cross-tenant data, and full system prompts kept out of the context window
|
|
199
|
+
- [ ] Tool/agent permissions scoped; destructive or irreversible actions require confirmation
|
|
200
|
+
- [ ] Token, rate, and recursion/loop limits set (bound consumption)
|
|
201
|
+
|
|
202
|
+
## Error Handling
|
|
203
|
+
|
|
204
|
+
```typescript
|
|
205
|
+
// Production: generic error, no internals
|
|
206
|
+
res.status(500).json({
|
|
207
|
+
error: { code: 'INTERNAL_ERROR', message: 'Something went wrong' }
|
|
208
|
+
});
|
|
209
|
+
|
|
210
|
+
// NEVER in production:
|
|
211
|
+
res.status(500).json({
|
|
212
|
+
error: err.message,
|
|
213
|
+
stack: err.stack, // Exposes internals
|
|
214
|
+
query: err.sql, // Exposes database details
|
|
215
|
+
});
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
## OWASP Top 10 Quick Reference
|
|
219
|
+
|
|
220
|
+
Numbering follows the [OWASP Top 10:2025](https://owasp.org/Top10/2025/). Cite a category with its year (`A06:2025`), since the 2021 edition used different numbers for several of the same categories.
|
|
221
|
+
|
|
222
|
+
| # | Vulnerability | Prevention |
|
|
223
|
+
|---|---|---|
|
|
224
|
+
| A01 | Broken Access Control (now includes SSRF) | Auth checks on every endpoint, ownership verification; validate/allowlist server-side fetch URLs, restrict outbound requests |
|
|
225
|
+
| A02 | Security Misconfiguration | Security headers, minimal permissions, secure defaults |
|
|
226
|
+
| A03 | Software Supply Chain Failures | The ecosystem's dependency audit (`npm audit`, `pip-audit`, ...), keep deps updated, minimal deps, review new packages and install scripts |
|
|
227
|
+
| A04 | Cryptographic Failures | HTTPS, strong hashing, no secrets in code |
|
|
228
|
+
| A05 | Injection | Parameterized queries, input validation |
|
|
229
|
+
| A06 | Insecure Design | Threat modeling, spec-driven development |
|
|
230
|
+
| A07 | Authentication Failures | Strong passwords, rate limiting, session management |
|
|
231
|
+
| A08 | Software or Data Integrity Failures | Verify updates, signed artifacts, no deserialization of untrusted data |
|
|
232
|
+
| A09 | Security Logging and Alerting Failures | Log security events, alert on them, don't log secrets |
|
|
233
|
+
| A10 | Mishandling of Exceptional Conditions | Fail closed, handle every error path, generic error bodies |
|
|
234
|
+
|
|
235
|
+
## OWASP Top 10 for LLMs Quick Reference
|
|
236
|
+
|
|
237
|
+
For apps with LLM features. See the [OWASP GenAI Security Project](https://genai.owasp.org/llm-top-10/).
|
|
238
|
+
|
|
239
|
+
| ID | Risk | Prevention |
|
|
240
|
+
|---|---|---|
|
|
241
|
+
| LLM01 | Prompt Injection | Don't trust the system prompt as a boundary; enforce permissions in code |
|
|
242
|
+
| LLM02 | Sensitive Information Disclosure | Keep secrets/PII out of prompts; filter outputs |
|
|
243
|
+
| LLM03 | Supply Chain | Vet models, datasets, and plugins like any dependency |
|
|
244
|
+
| LLM04 | Data and Model Poisoning | Use trusted model sources, verify integrity; vet fine-tuning and RAG data |
|
|
245
|
+
| LLM05 | Improper Output Handling | Treat model output as untrusted; validate, parameterize, encode |
|
|
246
|
+
| LLM06 | Excessive Agency | Scope tool permissions; confirm destructive actions |
|
|
247
|
+
| LLM07 | System Prompt Leakage | Assume the system prompt can leak; put no secrets in it |
|
|
248
|
+
| LLM08 | Vector and Embedding Weaknesses | Partition RAG embeddings per tenant; validate documents before indexing |
|
|
249
|
+
| LLM09 | Misinformation | Ground answers with citations; validate critical claims; keep a human in the loop |
|
|
250
|
+
| LLM10 | Unbounded Consumption | Cap tokens, request rate, and loop/recursion depth |
|
|
@@ -0,0 +1,236 @@
|
|
|
1
|
+
# Testing Patterns Reference (JavaScript/TypeScript)
|
|
2
|
+
|
|
3
|
+
Quick reference of JavaScript/TypeScript testing patterns — Jest, React Testing Library, Supertest, and Playwright — illustrating the universal principles from the `test-driven-development` skill. The principles (Arrange-Act-Assert, naming, mock discipline, anti-patterns) apply in any ecosystem; the syntax and tooling shown here are JS/TS-specific. In another stack, follow the same principles with the repository's own test framework and commands.
|
|
4
|
+
|
|
5
|
+
## Table of Contents
|
|
6
|
+
|
|
7
|
+
- [Test Structure (Arrange-Act-Assert)](#test-structure-arrange-act-assert)
|
|
8
|
+
- [Test Naming Conventions](#test-naming-conventions)
|
|
9
|
+
- [Common Assertions](#common-assertions)
|
|
10
|
+
- [Mocking Patterns](#mocking-patterns)
|
|
11
|
+
- [React/Component Testing](#reactcomponent-testing)
|
|
12
|
+
- [API / Integration Testing](#api--integration-testing)
|
|
13
|
+
- [E2E Testing (Playwright)](#e2e-testing-playwright)
|
|
14
|
+
- [Test Anti-Patterns](#test-anti-patterns)
|
|
15
|
+
|
|
16
|
+
## Test Structure (Arrange-Act-Assert)
|
|
17
|
+
|
|
18
|
+
```typescript
|
|
19
|
+
it('describes expected behavior', () => {
|
|
20
|
+
// Arrange: Set up test data and preconditions
|
|
21
|
+
const input = { title: 'Test Task', priority: 'high' };
|
|
22
|
+
|
|
23
|
+
// Act: Perform the action being tested
|
|
24
|
+
const result = createTask(input);
|
|
25
|
+
|
|
26
|
+
// Assert: Verify the outcome
|
|
27
|
+
expect(result.title).toBe('Test Task');
|
|
28
|
+
expect(result.priority).toBe('high');
|
|
29
|
+
expect(result.status).toBe('pending');
|
|
30
|
+
});
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Test Naming Conventions
|
|
34
|
+
|
|
35
|
+
```typescript
|
|
36
|
+
// Pattern: [unit] [expected behavior] [condition]
|
|
37
|
+
describe('TaskService.createTask', () => {
|
|
38
|
+
it('creates a task with default pending status', () => {});
|
|
39
|
+
it('throws ValidationError when title is empty', () => {});
|
|
40
|
+
it('trims whitespace from title', () => {});
|
|
41
|
+
it('generates a unique ID for each task', () => {});
|
|
42
|
+
});
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Common Assertions
|
|
46
|
+
|
|
47
|
+
```typescript
|
|
48
|
+
// Equality
|
|
49
|
+
expect(result).toBe(expected); // Strict equality (===)
|
|
50
|
+
expect(result).toEqual(expected); // Deep equality (objects/arrays)
|
|
51
|
+
expect(result).toStrictEqual(expected); // Deep equality + type matching
|
|
52
|
+
|
|
53
|
+
// Truthiness
|
|
54
|
+
expect(result).toBeTruthy();
|
|
55
|
+
expect(result).toBeFalsy();
|
|
56
|
+
expect(result).toBeNull();
|
|
57
|
+
expect(result).toBeDefined();
|
|
58
|
+
expect(result).toBeUndefined();
|
|
59
|
+
|
|
60
|
+
// Numbers
|
|
61
|
+
expect(result).toBeGreaterThan(5);
|
|
62
|
+
expect(result).toBeLessThanOrEqual(10);
|
|
63
|
+
expect(result).toBeCloseTo(0.3, 5); // Floating point
|
|
64
|
+
|
|
65
|
+
// Strings
|
|
66
|
+
expect(result).toMatch(/pattern/);
|
|
67
|
+
expect(result).toContain('substring');
|
|
68
|
+
|
|
69
|
+
// Arrays / Objects
|
|
70
|
+
expect(array).toContain(item);
|
|
71
|
+
expect(array).toHaveLength(3);
|
|
72
|
+
expect(object).toHaveProperty('key', 'value');
|
|
73
|
+
|
|
74
|
+
// Errors
|
|
75
|
+
expect(() => fn()).toThrow();
|
|
76
|
+
expect(() => fn()).toThrow(ValidationError);
|
|
77
|
+
expect(() => fn()).toThrow('specific message');
|
|
78
|
+
|
|
79
|
+
// Async
|
|
80
|
+
await expect(asyncFn()).resolves.toBe(value);
|
|
81
|
+
await expect(asyncFn()).rejects.toThrow(Error);
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Mocking Patterns
|
|
85
|
+
|
|
86
|
+
### Mock Functions
|
|
87
|
+
|
|
88
|
+
```typescript
|
|
89
|
+
const mockFn = jest.fn();
|
|
90
|
+
mockFn.mockReturnValue(42);
|
|
91
|
+
mockFn.mockResolvedValue({ data: 'test' });
|
|
92
|
+
mockFn.mockImplementation((x) => x * 2);
|
|
93
|
+
|
|
94
|
+
expect(mockFn).toHaveBeenCalled();
|
|
95
|
+
expect(mockFn).toHaveBeenCalledWith('arg1', 'arg2');
|
|
96
|
+
expect(mockFn).toHaveBeenCalledTimes(3);
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### Mock Modules
|
|
100
|
+
|
|
101
|
+
```typescript
|
|
102
|
+
// Mock an entire module
|
|
103
|
+
jest.mock('./database', () => ({
|
|
104
|
+
query: jest.fn().mockResolvedValue([{ id: 1, title: 'Test' }]),
|
|
105
|
+
}));
|
|
106
|
+
|
|
107
|
+
// Mock specific exports
|
|
108
|
+
jest.mock('./utils', () => ({
|
|
109
|
+
...jest.requireActual('./utils'),
|
|
110
|
+
generateId: jest.fn().mockReturnValue('test-id'),
|
|
111
|
+
}));
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
### Mock at Boundaries Only
|
|
115
|
+
|
|
116
|
+
```
|
|
117
|
+
Mock these: Don't mock these:
|
|
118
|
+
├── Database calls ├── Internal utility functions
|
|
119
|
+
├── HTTP requests ├── Business logic
|
|
120
|
+
├── File system operations ├── Data transformations
|
|
121
|
+
├── External API calls ├── Validation functions
|
|
122
|
+
└── Time/Date (when needed) └── Pure functions
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
## React/Component Testing
|
|
126
|
+
|
|
127
|
+
```tsx
|
|
128
|
+
import { render, screen, fireEvent, waitFor } from '@testing-library/react';
|
|
129
|
+
|
|
130
|
+
describe('TaskForm', () => {
|
|
131
|
+
it('submits the form with entered data', async () => {
|
|
132
|
+
const onSubmit = jest.fn();
|
|
133
|
+
render(<TaskForm onSubmit={onSubmit} />);
|
|
134
|
+
|
|
135
|
+
// Find elements by accessible role/label (not test IDs)
|
|
136
|
+
await screen.findByRole('textbox', { name: /title/i });
|
|
137
|
+
fireEvent.change(screen.getByRole('textbox', { name: /title/i }), {
|
|
138
|
+
target: { value: 'New Task' },
|
|
139
|
+
});
|
|
140
|
+
fireEvent.click(screen.getByRole('button', { name: /create/i }));
|
|
141
|
+
|
|
142
|
+
await waitFor(() => {
|
|
143
|
+
expect(onSubmit).toHaveBeenCalledWith({ title: 'New Task' });
|
|
144
|
+
});
|
|
145
|
+
});
|
|
146
|
+
|
|
147
|
+
it('shows validation error for empty title', async () => {
|
|
148
|
+
render(<TaskForm onSubmit={jest.fn()} />);
|
|
149
|
+
|
|
150
|
+
fireEvent.click(screen.getByRole('button', { name: /create/i }));
|
|
151
|
+
|
|
152
|
+
expect(await screen.findByText(/title is required/i)).toBeInTheDocument();
|
|
153
|
+
});
|
|
154
|
+
});
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
## API / Integration Testing
|
|
158
|
+
|
|
159
|
+
```typescript
|
|
160
|
+
import request from 'supertest';
|
|
161
|
+
import { app } from '../src/app';
|
|
162
|
+
|
|
163
|
+
describe('POST /api/tasks', () => {
|
|
164
|
+
it('creates a task and returns 201', async () => {
|
|
165
|
+
const response = await request(app)
|
|
166
|
+
.post('/api/tasks')
|
|
167
|
+
.send({ title: 'Test Task' })
|
|
168
|
+
.set('Authorization', `Bearer ${testToken}`)
|
|
169
|
+
.expect(201);
|
|
170
|
+
|
|
171
|
+
expect(response.body).toMatchObject({
|
|
172
|
+
id: expect.any(String),
|
|
173
|
+
title: 'Test Task',
|
|
174
|
+
status: 'pending',
|
|
175
|
+
});
|
|
176
|
+
});
|
|
177
|
+
|
|
178
|
+
it('returns 422 for invalid input', async () => {
|
|
179
|
+
const response = await request(app)
|
|
180
|
+
.post('/api/tasks')
|
|
181
|
+
.send({ title: '' })
|
|
182
|
+
.set('Authorization', `Bearer ${testToken}`)
|
|
183
|
+
.expect(422);
|
|
184
|
+
|
|
185
|
+
expect(response.body.error.code).toBe('VALIDATION_ERROR');
|
|
186
|
+
});
|
|
187
|
+
|
|
188
|
+
it('returns 401 without authentication', async () => {
|
|
189
|
+
await request(app)
|
|
190
|
+
.post('/api/tasks')
|
|
191
|
+
.send({ title: 'Test' })
|
|
192
|
+
.expect(401);
|
|
193
|
+
});
|
|
194
|
+
});
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
## E2E Testing (Playwright)
|
|
198
|
+
|
|
199
|
+
```typescript
|
|
200
|
+
import { test, expect } from '@playwright/test';
|
|
201
|
+
|
|
202
|
+
test('user can create and complete a task', async ({ page }) => {
|
|
203
|
+
// Navigate and authenticate
|
|
204
|
+
await page.goto('/');
|
|
205
|
+
await page.getByRole('textbox', { name: /email/i }).fill('test@example.com');
|
|
206
|
+
await page.getByLabel(/password/i).fill('testpass123');
|
|
207
|
+
await page.getByRole('button', { name: /log in/i }).click();
|
|
208
|
+
|
|
209
|
+
// Create a task
|
|
210
|
+
await page.getByRole('button', { name: /new task/i }).click();
|
|
211
|
+
await page.getByRole('textbox', { name: /title/i }).fill('Buy groceries');
|
|
212
|
+
await page.getByRole('button', { name: /create/i }).click();
|
|
213
|
+
|
|
214
|
+
// Verify task appears
|
|
215
|
+
// listitem has no accessible name from its content, so filter by text
|
|
216
|
+
const task = page.getByRole('listitem').filter({ hasText: /buy groceries/i });
|
|
217
|
+
await expect(task).toBeVisible();
|
|
218
|
+
|
|
219
|
+
// Complete the task
|
|
220
|
+
await task.getByRole('checkbox', { name: /complete buy groceries/i }).check();
|
|
221
|
+
await expect(task).toHaveCSS('text-decoration-line', 'line-through');
|
|
222
|
+
});
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
## Test Anti-Patterns
|
|
226
|
+
|
|
227
|
+
| Anti-Pattern | Problem | Better Approach |
|
|
228
|
+
|---|---|---|
|
|
229
|
+
| Testing implementation details | Breaks on refactor | Test inputs/outputs |
|
|
230
|
+
| Snapshot everything | No one reviews snapshot diffs | Assert specific values |
|
|
231
|
+
| Shared mutable state | Tests pollute each other | Setup/teardown per test |
|
|
232
|
+
| Testing third-party code | Wastes time, not your bug | Mock the boundary |
|
|
233
|
+
| Skipping tests to pass CI | Hides real bugs | Fix or delete the test |
|
|
234
|
+
| Using `test.skip` permanently | Dead code | Remove or fix it |
|
|
235
|
+
| Overly broad assertions | Doesn't catch regressions | Be specific |
|
|
236
|
+
| No async error handling | Swallowed errors, false passes | Always `await` async tests |
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: accessibility-engineering
|
|
3
|
+
description: Audits existing interfaces for WCAG 2.2 AA conformance and remediates the violations found. Use when auditing a page or component for accessibility, running axe-core or pa11y, triaging a11y violations, or checking screen reader and contrast issues before shipping.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Accessibility Engineering
|
|
7
|
+
|
|
8
|
+
## Overview
|
|
9
|
+
|
|
10
|
+
Accessibility is not a polish step — it's a legal requirement in many jurisdictions, an engineering quality standard, and a prerequisite for shipping. This skill audits existing interfaces, triages the findings, and remediates verified violations. The goal is WCAG 2.2 AA compliance supported by automated tools and manual testing.
|
|
11
|
+
|
|
12
|
+
## When to Use
|
|
13
|
+
|
|
14
|
+
- Before shipping a user-facing change that needs an accessibility audit
|
|
15
|
+
- When a11y issues are reported (e.g., "screen reader can't read this", "keyboard navigation broken")
|
|
16
|
+
- When auditing an existing interface for compliance
|
|
17
|
+
- When triaging axe-core or pa11y findings
|
|
18
|
+
- When remediating verified accessibility violations
|
|
19
|
+
|
|
20
|
+
**Do NOT use** for building new UI components from scratch; use `frontend-ui-engineering` for construction guidance. Do not use for backend-only changes, CLIs, or library code with no UI output.
|
|
21
|
+
|
|
22
|
+
## Workflow
|
|
23
|
+
|
|
24
|
+
### Phase 1: Route New UI Work
|
|
25
|
+
|
|
26
|
+
For component construction, interaction patterns, and focus-management guidance, use `../frontend-ui-engineering/SKILL.md`. Do not restate that skill here. Return to this workflow once an interface exists and needs auditing or remediation.
|
|
27
|
+
|
|
28
|
+
### Phase 2: Run Automated Audit
|
|
29
|
+
|
|
30
|
+
Execute accessibility checks in this order:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
# axe-core rules through pinned @axe-core/cli (the axe-core package ships no CLI)
|
|
34
|
+
npx --yes @axe-core/cli@4.13.0 http://localhost:3000 --exit
|
|
35
|
+
|
|
36
|
+
# Keep the JSON for the accessibility-auditor
|
|
37
|
+
npx --yes @axe-core/cli@4.13.0 http://localhost:3000 --dir ./a11y-reports --save axe.json
|
|
38
|
+
|
|
39
|
+
# Pinned pa11y for HTML validation (WCAG2AA rules via HTML_CodeSniffer)
|
|
40
|
+
npx --yes pa11y@9.1.1 http://localhost:3000
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
For a combined report, run `bash skills/accessibility-engineering/scripts/audit-a11y.sh url <url> --json`. It runs both pinned tools, records their status and versions, and fails rather than reporting a clean result when either tool does not produce a valid report.
|
|
44
|
+
|
|
45
|
+
Review the violations grouped by severity:
|
|
46
|
+
- **Critical** — Blocks screen reader access entirely (missing alt text on info images, empty buttons)
|
|
47
|
+
- **Serious** — Makes content difficult or impossible to access (low contrast, missing labels)
|
|
48
|
+
- **Moderate** — Causes confusion or extra effort (heading level skips, redundant ARIA)
|
|
49
|
+
- **Minor** — Cosmetic or progressive enhancement (missing lang attribute on inner elements)
|
|
50
|
+
|
|
51
|
+
For each violation, verify it's a real issue (not a false positive) by inspecting the element in the browser.
|
|
52
|
+
|
|
53
|
+
### Phase 3: Manual Testing
|
|
54
|
+
|
|
55
|
+
Automated checks are a smoke test, not proof of conformance. Complete the audit manually.
|
|
56
|
+
|
|
57
|
+
**Keyboard audit:**
|
|
58
|
+
1. Tab through every interactive element — can you see where you are?
|
|
59
|
+
2. Activate buttons and links with Enter/Space
|
|
60
|
+
3. Close modals with Escape
|
|
61
|
+
4. Navigate lists with Arrow keys
|
|
62
|
+
5. Verify no keyboard traps exist
|
|
63
|
+
|
|
64
|
+
**Screen reader audit (VoiceOver on macOS, NVDA on Windows):**
|
|
65
|
+
1. Navigate by heading (VoiceOver: Ctrl+Option+Cmd+H) — is the structure logical?
|
|
66
|
+
2. Navigate by landmark (open the rotor with Ctrl+Option+U, choose Landmarks) — are regions labeled?
|
|
67
|
+
3. Navigate by link (open the rotor with Ctrl+Option+U, choose Links) — do link descriptions make sense out of context?
|
|
68
|
+
4. Interact with a form — are labels announced? Are error messages read?
|
|
69
|
+
5. Navigate a dynamic update — are changes announced?
|
|
70
|
+
|
|
71
|
+
**Visual audit:**
|
|
72
|
+
1. Verify color contrast (4.5:1 text, 3:1 large text, 3:1 UI components)
|
|
73
|
+
2. Zoom to 200% — does layout break or overlap?
|
|
74
|
+
3. Test with forced colors / high contrast mode (Windows High Contrast)
|
|
75
|
+
4. Reduce motion (prefers-reduced-motion) — are animations disabled?
|
|
76
|
+
5. Test focus visibility — is the focus ring visible against all backgrounds?
|
|
77
|
+
|
|
78
|
+
### Phase 4: Fix Violations
|
|
79
|
+
|
|
80
|
+
For each finding, apply the remediation in order:
|
|
81
|
+
|
|
82
|
+
1. **Fix the root cause** — Replace a `<div>` with `<button>`, add `<label>`, set `alt` text
|
|
83
|
+
2. **Add ARIA as bridge** — If native HTML can't express the pattern, add ARIA attributes
|
|
84
|
+
3. **Test the fix** — Re-run the automated check and manual verification
|
|
85
|
+
|
|
86
|
+
Apply the accessibility checklist (`../../references/accessibility-checklist.md`) as a minimal baseline.
|
|
87
|
+
|
|
88
|
+
## Common Rationalizations
|
|
89
|
+
|
|
90
|
+
| Rationalization | Reality |
|
|
91
|
+
|---|---|
|
|
92
|
+
| "We'll fix a11y later" | Delayed remediation compounds across components and can create legal liability. Audit before shipping. |
|
|
93
|
+
| "Automated tools caught everything" | Automated checks cannot prove keyboard or screen reader behavior. Manual testing is mandatory. |
|
|
94
|
+
| "Screen reader users are a tiny minority" | Accessibility is a requirement, not a usage-share calculation. Keyboard navigation, captions, and clear structure also help users across contexts. |
|
|
95
|
+
| "This is an internal tool, it doesn't need a11y" | Internal tools are subject to the same regulations. Disabled employees and contractors need access. |
|
|
96
|
+
| "I'll just use aria-label everywhere" | ARIA is a bridge, not a foundation. Semantic HTML first. Overusing ARIA creates maintenance burden and can make things worse. |
|
|
97
|
+
| "The design system handles accessibility" | Design systems provide accessible primitives. How you compose them determines whether the result is accessible. |
|
|
98
|
+
| "The audit passed axe-core, so we're done" | Pass axe-core as a smoke test, then test with screen readers and keyboard. A green lighthouse score is not a clean bill of health. |
|
|
99
|
+
|
|
100
|
+
## Red Flags
|
|
101
|
+
|
|
102
|
+
- Elements that look clickable but aren't keyboard-focusable
|
|
103
|
+
- Color as the sole indicator of state (red for error, green for success)
|
|
104
|
+
- Focus outline removed without a visible replacement
|
|
105
|
+
- Missing labels on form inputs
|
|
106
|
+
- No heading hierarchy or skipped heading levels
|
|
107
|
+
- Empty or unlabeled buttons and links
|
|
108
|
+
- Modals that don't trap focus or restore focus on close
|
|
109
|
+
- No `alt` text on meaningful images (or `alt=""` missing on decorative ones)
|
|
110
|
+
- Touch targets that fail SC 2.5.8's 24x24 CSS px size-or-spacing requirement and do not qualify for an exception (AA; 44x44 is the AAA target, SC 2.5.5)
|
|
111
|
+
- Autoplaying video or audio without controls
|
|
112
|
+
- Low contrast text (especially on hover, disabled states, placeholders)
|
|
113
|
+
|
|
114
|
+
## See Also
|
|
115
|
+
|
|
116
|
+
- `../../references/accessibility-checklist.md` — Quick reference for WCAG 2.2 AA
|
|
117
|
+
- `../frontend-ui-engineering/SKILL.md` — Building accessible components from the start
|
|
118
|
+
- `../../agents/accessibility-auditor.md` — Dedicated a11y audit persona for deep reviews
|
|
119
|
+
|
|
120
|
+
## Verification
|
|
121
|
+
|
|
122
|
+
After completing the accessibility workflow:
|
|
123
|
+
|
|
124
|
+
- [ ] Automated audit passes with no Critical or Serious violations
|
|
125
|
+
- [ ] All interactive elements are keyboard accessible (Tab, Enter, Escape, Arrow keys)
|
|
126
|
+
- [ ] Screen reader navigation by heading, landmark, and link verified with a named browser + AT pair (or recorded as `manual` and untested — never reported as verified)
|
|
127
|
+
- [ ] Focus order matches visual order
|
|
128
|
+
- [ ] Color contrast passes 4.5:1 text / 3:1 large text / 3:1 UI components
|
|
129
|
+
- [ ] All form inputs have associated labels
|
|
130
|
+
- [ ] All images have appropriate `alt` text
|
|
131
|
+
- [ ] Dynamic content changes are announced (aria-live)
|
|
132
|
+
- [ ] Page is usable at 200% zoom with no content loss
|
|
133
|
+
- [ ] Touch targets satisfy SC 2.5.8's 24x24 CSS px size-or-spacing requirement or a normative exception (AA); 44x44 is the enhanced AAA target (SC 2.5.5)
|