@synapta/skills 0.1.1 → 0.2.0

package/skills/repo-bootstrap/references/examples/ldap-selfservice/internal-web-AGENTS.md

@@ -0,0 +1,448 @@
+# Frontend - TypeScript & Tailwind CSS
+
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-09 -->
+
+**Scope**: Frontend assets in `internal/web/` directory - TypeScript, Tailwind CSS, HTML templates
+
+**See also**: [../../AGENTS.md](../../AGENTS.md) for global standards, [../AGENTS.md](../AGENTS.md) for Go backend
+
+## Overview
+
+Frontend implementation for LDAP selfservice password changer with strict accessibility compliance:
+
+- **static/**: Client-side TypeScript, compiled CSS, static assets
+  - **js/**: TypeScript source files (compiled to ES modules)
+  - **styles.css**: Tailwind CSS output
+  - Icons, logos, favicons, manifest
+- **templates/**: Go HTML templates (\*.gohtml)
+- **handlers.go**: HTTP route handlers
+- **middleware.go**: Security headers, CORS, etc.
+- **server.go**: Fiber server setup
+
+**Key characteristics**:
+
+- **WCAG 2.2 AAA**: 7:1 contrast, keyboard navigation, screen reader support, adaptive density
+- **Ultra-strict TypeScript**: All strict flags enabled, no `any` types
+- **Tailwind CSS 4**: Utility-first, dark mode, responsive, accessible patterns
+- **Progressive enhancement**: Works without JavaScript (forms submit via HTTP)
+- **Password manager friendly**: Proper autocomplete attributes
+
+## Setup/Environment
+
+**Prerequisites**: Node.js 24+, pnpm 10.18+ (from root `package.json`)
+
+```bash
+# From project root
+pnpm install          # Install dependencies
+
+# Development (watch mode)
+pnpm css:dev          # Tailwind CSS watch
+pnpm js:dev           # TypeScript watch
+# OR
+pnpm dev              # Concurrent: CSS + TS + Go hot-reload
+```
+
+**No .env needed for frontend** - all config comes from Go backend
+
+**Browser targets**: Modern browsers with ES module support (Chrome 90+, Firefox 88+, Safari 14+, Edge 90+)
+
+## Build & Tests
+
+```bash
+# Build frontend assets
+pnpm build:assets     # TypeScript + CSS (production builds)
+
+# TypeScript
+pnpm js:build         # Compile TS → ES modules + minify
+pnpm js:dev           # Watch mode with preserveWatchOutput
+tsc --noEmit          # Type check only (no output)
+
+# CSS
+pnpm css:build        # Tailwind + PostCSS → styles.css
+pnpm css:dev          # Watch mode
+
+# Formatting
+pnpm prettier --write internal/web/    # Format TS, CSS, HTML templates
+pnpm prettier --check internal/web/    # Check formatting (CI)
+```
+
+**No unit tests yet** - TypeScript strict mode catches most errors, integration via Go tests
+
+**CI validation** (from `.github/workflows/check.yml`):
+
+```bash
+pnpm install
+pnpm js:build         # TypeScript strict compilation
+pnpm prettier --check .
+```
+
+**Accessibility testing**:
+
+- Keyboard navigation: Tab through all interactive elements
+- Screen reader: Test with VoiceOver (macOS/iOS) or NVDA (Windows)
+- Contrast: Verify 7:1 ratios with browser dev tools
+- See [../../docs/accessibility.md](../../docs/accessibility.md) for comprehensive guide
+
+## Code Style
+
+**TypeScript Ultra-Strict** (from `tsconfig.json`):
+
+```json
+{
+  "strict": true,
+  "noUncheckedIndexedAccess": true,
+  "exactOptionalPropertyTypes": true,
+  "noPropertyAccessFromIndexSignature": true,
+  "noImplicitReturns": true,
+  "noFallthroughCasesInSwitch": true,
+  "noUnusedLocals": true,
+  "noUnusedParameters": true
+}
+```
+
+**No `any` types allowed**:
+
+```typescript
+// ✅ Good: explicit types
+function validatePassword(password: string, minLength: number): boolean {
+  return password.length >= minLength;
+}
+
+// ❌ Bad: any type
+function validatePassword(password: any): boolean {
+  return password.length >= 8; // ❌ unsafe
+}
+```
+
+**Prettier formatting**:
+
+- 120 char width
+- 2-space indentation
+- Semicolons required
+- Double quotes (not single)
+- Trailing comma: none
+
+**File organization**:
+
+- TypeScript source: `static/js/*.ts`
+- Output: `static/js/*.js` (minified ES modules)
+- CSS input: `tailwind.css` (Tailwind directives)
+- CSS output: `static/styles.css` (PostCSS processed)
+
+## Accessibility Standards (WCAG 2.2 AAA)
+
+**Required compliance** - not optional:
+
+### Keyboard Navigation
+
+- All interactive elements focusable with Tab
+- Visual focus indicators (4px outline, 7:1 contrast)
+- Logical tab order (top to bottom, left to right)
+- No keyboard traps
+- Skip links where needed
+
+### Screen Readers
+
+- Semantic HTML: `<button>`, `<input>`, `<label>`, not `<div onclick>`
+- ARIA labels on icon-only buttons: `aria-label="Submit"`
+- Error messages: `aria-describedby` linking to error text
+- Live regions for dynamic content: `aria-live="polite"`
+- Form field associations: `<label for="id">` + `<input id="id">`
+
+### Color & Contrast
+
+- Text: 7:1 contrast ratio (AAA)
+- Large text (18pt+): 4.5:1 minimum
+- Focus indicators: 3:1 against adjacent colors
+- Dark mode: same contrast requirements
+- Never rely on color alone (use icons, text, patterns)
+
+### Responsive & Adaptive
+
+- Responsive: layout adapts to viewport size
+- Text zoom: 200% without horizontal scroll
+- Adaptive density: spacing adjusts for user preferences
+- Touch targets: 44×44 CSS pixels minimum (mobile)
+
+### Examples
+
+**✅ Good: Accessible button**
+
+```html
+<button type="submit" class="btn-primary focus:ring-4 focus:ring-blue-300" aria-label="Submit password change">
+  <svg aria-hidden="true">...</svg>
+  Change Password
+</button>
+```
+
+**❌ Bad: Inaccessible div-button**
+
+```html
+<div onclick="submit()" class="button">❌ not keyboard accessible Submit</div>
+```
+
+**✅ Good: Form with error handling**
+
+```html
+<form>
+  <label for="password">New Password</label>
+  <input
+    id="password"
+    type="password"
+    aria-describedby="password-error"
+    aria-invalid="true"
+    autocomplete="new-password"
+  />
+  <div id="password-error" role="alert">Password must be at least 8 characters</div>
+</form>
+```
+
+**❌ Bad: Form without associations**
+
+```html
+<form>
+  <div>Password</div>
+  ❌ not a label, no association <input type="password" /> ❌ no autocomplete, no error linkage
+  <div style="color: red">Error</div>
+  ❌ no role="alert", only color
+</form>
+```
+
+## Tailwind CSS Patterns
+
+**Use utility classes**, not custom CSS:
+
+**✅ Good: Utility classes**
+
+```html
+<button
+  class="rounded-lg bg-blue-600 px-4 py-2 font-semibold text-white hover:bg-blue-700 focus:ring-4 focus:ring-blue-300"
+>
+  Submit
+</button>
+```
+
+**❌ Bad: Custom CSS**
+
+```html
+<button class="custom-button">Submit</button>
+<style>
+  .custom-button {
+    background: blue;
+  } /* ❌ Use Tailwind utilities */
+</style>
+```
+
+**Dark mode support**:
+
+```html
+<div class="bg-white text-gray-900 dark:bg-gray-900 dark:text-gray-100">Content</div>
+```
+
+**Responsive design**:
+
+```html
+<div class="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3">
+  <!-- Responsive grid: 1 col mobile, 2 tablet, 3 desktop -->
+</div>
+```
+
+**Focus states (required)**:
+
+```html
+<button class="focus:ring-4 focus:ring-blue-300 focus:outline-none">
+  <!-- 4px focus ring, 7:1 contrast -->
+</button>
+```
+
+## TypeScript Patterns
+
+**Strict null checking**:
+
+```typescript
+// ✅ Good: handle nulls explicitly
+function getElement(id: string): HTMLElement | null {
+  return document.getElementById(id);
+}
+
+const el = getElement("password");
+if (el) {
+  // ✅ null check
+  el.textContent = "Hello";
+}
+
+// ❌ Bad: assume non-null
+const el = getElement("password");
+el.textContent = "Hello"; // ❌ may crash if null
+```
+
+**Type guards**:
+
+```typescript
+// ✅ Good: type guard for forms
+function isHTMLFormElement(element: Element): element is HTMLFormElement {
+  return element instanceof HTMLFormElement;
+}
+
+const form = document.querySelector("form");
+if (form && isHTMLFormElement(form)) {
+  form.addEventListener("submit", handleSubmit);
+}
+```
+
+**No unsafe array access**:
+
+```typescript
+// ✅ Good: check array bounds
+const items = ["a", "b", "c"];
+const first = items[0]; // string | undefined (noUncheckedIndexedAccess)
+if (first) {
+  console.log(first.toUpperCase());
+}
+
+// ❌ Bad: unsafe access
+console.log(items[0].toUpperCase()); // ❌ may crash if empty array
+```
+
+## PR/Commit Checklist
+
+**Before committing frontend code**:
+
+- [ ] Run `pnpm js:build` (TypeScript strict check)
+- [ ] Run `pnpm prettier --write internal/web/`
+- [ ] Verify keyboard navigation works
+- [ ] Test with screen reader (VoiceOver/NVDA)
+- [ ] Check contrast ratios (7:1 for text)
+- [ ] Test dark mode
+- [ ] Verify password manager autofill works
+- [ ] No console errors in browser
+- [ ] Test on mobile viewport (responsive)
+
+**Accessibility checklist**:
+
+- [ ] All interactive elements keyboard accessible
+- [ ] Focus indicators visible (4px outline, 7:1 contrast)
+- [ ] ARIA labels on icon-only buttons
+- [ ] Form fields properly labeled
+- [ ] Error messages linked with aria-describedby
+- [ ] No color-only information conveyance
+- [ ] Touch targets ≥44×44 CSS pixels (mobile)
+
+**Performance checklist**:
+
+- [ ] Minified JS (via `pnpm js:minify`)
+- [ ] CSS optimized (cssnano via PostCSS)
+- [ ] No unused Tailwind classes (purged automatically)
+- [ ] No console.log in production code
+
+## Good vs Bad Examples
+
+**✅ Good: Type-safe DOM access**
+
+```typescript
+function setupPasswordToggle(): void {
+  const toggle = document.getElementById("toggle-password");
+  const input = document.getElementById("password");
+
+  if (!toggle || !(input instanceof HTMLInputElement)) {
+    return; // Guard against missing elements
+  }
+
+  toggle.addEventListener("click", () => {
+    input.type = input.type === "password" ? "text" : "password";
+  });
+}
+```
+
+**❌ Bad: Unsafe DOM access**
+
+```typescript
+function setupPasswordToggle() {
+  const toggle = document.getElementById("toggle-password")!; // ❌ non-null assertion
+  const input = document.getElementById("password") as any; // ❌ any type
+
+  toggle.addEventListener("click", () => {
+    input.type = input.type === "password" ? "text" : "password"; // ❌ may crash
+  });
+}
+```
+
+**✅ Good: Accessible form validation**
+
+```typescript
+function showError(input: HTMLInputElement, message: string): void {
+  const errorId = `${input.id}-error`;
+  let errorEl = document.getElementById(errorId);
+
+  if (!errorEl) {
+    errorEl = document.createElement("div");
+    errorEl.id = errorId;
+    errorEl.setAttribute("role", "alert");
+    errorEl.className = "text-red-600 dark:text-red-400 text-sm mt-1";
+    input.parentElement?.appendChild(errorEl);
+  }
+
+  errorEl.textContent = message;
+  input.setAttribute("aria-invalid", "true");
+  input.setAttribute("aria-describedby", errorId);
+}
+```
+
+**❌ Bad: Inaccessible validation**
+
+```typescript
+function showError(input: any, message: string) {
+  // ❌ any type
+  input.style.borderColor = "red"; // ❌ color only, no text
+  alert(message); // ❌ blocks UI, not persistent
+}
+```
+
+## When Stuck
+
+**TypeScript issues**:
+
+1. **Type errors**: Check `tsconfig.json` flags, use proper types (no `any`)
+2. **Null errors**: Add null checks or type guards
+3. **Module errors**: Ensure ES module syntax (`import`/`export`)
+4. **Build errors**: `pnpm install` to refresh dependencies
+
+**CSS issues**:
+
+1. **Styles not applying**: Check Tailwind purge config, rebuild with `pnpm css:build`
+2. **Dark mode broken**: Use `dark:` prefix on utilities
+3. **Responsive broken**: Use `md:`, `lg:` breakpoint prefixes
+4. **Custom classes**: Don't - use Tailwind utilities instead
+
+**Accessibility issues**:
+
+1. **Keyboard nav broken**: Check tab order, focus indicators
+2. **Screen reader confusion**: Verify ARIA labels, semantic HTML
+3. **Contrast failure**: Use darker colors, test with dev tools
+4. **See**: [../../docs/accessibility.md](../../docs/accessibility.md)
+
+**Browser dev tools**:
+
+- Accessibility tab: Check ARIA, contrast, structure
+- Lighthouse: Run accessibility audit (aim for 100 score)
+- Console: No errors in production code
+
+## Testing Workflow
+
+**Manual testing required** (no automated frontend tests yet):
+
+1. **Visual testing**: Check all pages in light/dark mode
+2. **Keyboard testing**: Tab through all interactive elements
+3. **Screen reader testing**: Use VoiceOver (Cmd+F5) or NVDA
+4. **Responsive testing**: Test mobile, tablet, desktop viewports
+5. **Browser testing**: Chrome, Firefox, Safari, Edge
+6. **Password manager**: Test autofill with 1Password, LastPass, etc.
+
+**Accessibility testing tools**:
+
+- Browser dev tools Lighthouse
+- axe DevTools extension
+- WAVE browser extension
+- Manual keyboard/screen reader testing (required)
+
+**Integration testing**: Go backend tests exercise full request/response flow including frontend templates

package/skills/repo-bootstrap/references/examples/php-with-frontend/.scopes

@@ -0,0 +1,3 @@
+# Scopes for testing cross-language projects
+# Format: path:type
+web:frontend-typescript

package/skills/repo-bootstrap/references/examples/php-with-frontend/AGENTS.md

@@ -0,0 +1,91 @@
+<!-- FOR AI AGENTS - Human readability is a side effect, not a goal -->
+<!-- Managed by agent: keep sections and order; edit content, not structure -->
+<!-- Last updated: 2026-02-05 | Last verified: never -->
+
+# AGENTS.md
+
+**Precedence:** the **closest `AGENTS.md`** to the files you're changing wins. Root holds global defaults only.
+
+## Commands (unverified)
+> Source: composer.json — CI-sourced commands are most reliable
+
+<!-- AGENTS-GENERATED:START commands -->
+| Task | Command | ~Time |
+|------|---------|-------|
+| Typecheck | composer run phpstan | ~15s |
+| Lint | vendor/bin/php-cs-fixer fix --dry-run | ~10s |
+| Format | vendor/bin/php-cs-fixer fix | ~5s |
+| Test (single) | vendor/bin/phpunit | ~2s |
+| Test (all) | composer run test | ~30s |
+<!-- AGENTS-GENERATED:END commands -->
+
+> If commands fail, verify against Makefile/package.json/composer.json or ask user to update.
+
+## Workflow
+1. **Before coding**: Read nearest `AGENTS.md` + check Golden Samples for the area you're touching
+2. **After each change**: Run the smallest relevant check (lint → typecheck → single test)
+3. **Before committing**: Run full test suite if changes affect >2 files or touch shared code
+
+## File Map
+<!-- AGENTS-GENERATED:START filemap -->
+```
+web/             → documentation
+src/             → application source code
+```
+<!-- AGENTS-GENERATED:END filemap -->
+
+## Golden Samples (follow these patterns)
+<!-- AGENTS-GENERATED:START golden-samples -->
+| For | Reference | Key patterns |
+|-----|-----------|--------------|
+| Controller | `src/Controller.php` |  (class) |
+<!-- AGENTS-GENERATED:END golden-samples -->
+
+## Heuristics (quick decisions)
+<!-- AGENTS-GENERATED:START heuristics -->
+| When | Do |
+|------|-----|
+| Adding class | Follow PSR-4 in `Classes/` or `src/` |
+| Committing | Use Conventional Commits (feat:, fix:, docs:, etc.) |
+| Merging PRs | Squash and merge |
+| Adding dependency | Ask first - we minimize deps |
+| Unsure about pattern | Check Golden Samples above |
+<!-- AGENTS-GENERATED:END heuristics -->
+
+## Repository Settings
+<!-- AGENTS-GENERATED:START repo-settings -->
+- **Default branch:** `main`
+- **Merge strategy:** squash, merge, rebase
+<!-- AGENTS-GENERATED:END repo-settings -->
+
+## Boundaries
+
+### Always Do
+- Run pre-commit checks before committing
+- Add tests for new code paths
+- Use conventional commit format: `type(scope): subject`
+- Follow PSR-12 coding standards and PHP ^8.2 features
+
+### Ask First
+- Adding new dependencies
+- Modifying CI/CD configuration
+- Changing public API signatures
+- Running full e2e test suites
+- Repo-wide refactoring or rewrites
+
+### Never Do
+- Commit secrets, credentials, or sensitive data
+- Modify vendor/, node_modules/, or generated files
+- Push directly to main/master branch
+- Delete migration files or schema changes
+- Commit composer.lock without composer.json changes
+- Modify core framework files
+
+## Index of scoped AGENTS.md
+<!-- AGENTS-GENERATED:START scope-index -->
+- `./web/AGENTS.md` — Frontend application (TypeScript/React/Vue)
+<!-- AGENTS-GENERATED:END scope-index -->
+
+## When instructions conflict
+The nearest `AGENTS.md` wins. Explicit user prompts override files.
+- For PHP-specific patterns, follow PSR standards

package/skills/repo-bootstrap/references/examples/php-with-frontend/composer.json

@@ -0,0 +1,8 @@
+{
+    "name": "test/php-with-frontend",
+    "require": { "php": "^8.2" },
+    "scripts": {
+        "test": "vendor/bin/phpunit",
+        "phpstan": "vendor/bin/phpstan analyze"
+    }
+}

package/skills/repo-bootstrap/references/examples/php-with-frontend/package.json

@@ -0,0 +1,15 @@
+{
+    "name": "frontend",
+    "scripts": {
+        "dev": "vite",
+        "build": "vite build",
+        "lint": "eslint src",
+        "test": "vitest run"
+    },
+    "devDependencies": {
+        "eslint": "^8.56.0",
+        "react": "^18.0.0",
+        "vite": "^8.0.8",
+        "vitest": "^1.0.0"
+    }
+}

package/skills/repo-bootstrap/references/examples/php-with-frontend/src/Controller.php

@@ -0,0 +1,3 @@
+<?php
+namespace App;
+class Controller {}

package/skills/repo-bootstrap/references/examples/php-with-frontend/web/AGENTS.md

@@ -0,0 +1,92 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: 2026-02-05 -->
+
+# AGENTS.md — web
+
+<!-- AGENTS-GENERATED:START overview -->
+## Overview
+Frontend application (TypeScript/React/Vue)
+<!-- AGENTS-GENERATED:END overview -->
+
+<!-- AGENTS-GENERATED:START filemap -->
+## Key Files
+| File | Purpose |
+|------|---------|
+| `web/src/App.tsx` | (add description) |
+| `web/src/Button.tsx` | (add description) |
+| `web/src/Header.tsx` | (add description) |
+| `web/src/main.tsx` | (add description) |
+| `web/src/Footer.tsx` | (add description) |
+<!-- AGENTS-GENERATED:END filemap -->
+
+<!-- AGENTS-GENERATED:START golden-samples -->
+## Golden Samples (follow these patterns)
+| Pattern | Reference |
+|---------|-----------|
+| Standard implementation | `web/src/Button.tsx` |
+<!-- AGENTS-GENERATED:END golden-samples -->
+
+<!-- AGENTS-GENERATED:START setup -->
+## Setup & environment
+- Node version: >=20.0.0
+- Framework: react
+- Package manager: npm
+- Environment variables: See .env.example
+<!-- AGENTS-GENERATED:END setup -->
+
+<!-- AGENTS-GENERATED:START commands -->
+## Build & tests
+- Install: `npm install`
+- Typecheck: `npm run typecheck`
+- Lint: `npm run lint`
+- Format: `npx prettier --write .`
+- Test: `npm test`
+- Build: `npm run build`
+- Dev server: `npm run dev`
+<!-- AGENTS-GENERATED:END commands -->
+
+<!-- AGENTS-GENERATED:START code-style -->
+## Code style & conventions
+- TypeScript strict mode enabled (verified from tsconfig.json)
+- Use functional components with hooks
+- Naming: `camelCase` for variables/functions, `PascalCase` for components
+- File naming: `ComponentName.tsx`, `utilityName.ts`
+- Imports: group and sort (external, internal, types)
+- CSS: Tailwind CSS
+- Avoid class components
+<!-- AGENTS-GENERATED:END code-style -->
+
+<!-- AGENTS-GENERATED:START security -->
+## Security & safety
+- Sanitize user inputs before rendering
+- Raw HTML rendering only with sanitized content (use DOMPurify)
+- Validate environment variables at build time
+- Never expose secrets in client-side code
+- Use HTTPS for all API calls
+- Implement CSP headers
+- WCAG 2.2 AA accessibility compliance
+<!-- AGENTS-GENERATED:END security -->
+
+<!-- AGENTS-GENERATED:START checklist -->
+## PR/commit checklist
+- [ ] Tests pass: `npm test`
+- [ ] TypeScript compiles: `npm run typecheck`
+- [ ] Lint clean: `npm run lint`
+- [ ] Formatted: `npx prettier --write .`
+- [ ] Accessibility: keyboard navigation works, ARIA labels present
+- [ ] Responsive: tested on mobile, tablet, desktop
+- [ ] Performance: no unnecessary re-renders
+<!-- AGENTS-GENERATED:END checklist -->
+
+<!-- AGENTS-GENERATED:START examples -->
+## Patterns to Follow
+> **Prefer looking at real code in this repo over generic examples.**
+> See **Golden Samples** section above for files that demonstrate correct patterns.
+<!-- AGENTS-GENERATED:END examples -->
+
+<!-- AGENTS-GENERATED:START help -->
+## When stuck
+- Check React documentation: https://react.dev
+- Review TypeScript handbook: https://www.typescriptlang.org/docs/
+- Check root AGENTS.md for project-wide conventions
+- Review existing components for patterns
+<!-- AGENTS-GENERATED:END help -->

package/skills/repo-bootstrap/references/examples/php-with-frontend/web/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "frontend",
+  "private": true,
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "lint": "eslint src --ext .ts,.tsx",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "eslint": "^8.56.0",
+    "tailwindcss": "^3.4.0",
+    "typescript": "^5.3.0",
+    "vite": "^8.0.8",
+    "vitest": "^1.0.0"
+  }
+}

package/skills/repo-bootstrap/references/examples/php-with-frontend/web/src/App.tsx

@@ -0,0 +1,3 @@
+export default function App() {
+    return <div>Hello</div>;
+}