@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/golang-patterns.md

@@ -0,0 +1,185 @@
+---
+name: golang-patterns
+description: Go patterns for interfaces, error handling, goroutines, channels, context, testing, and project layout.
+---
+
+# Go Patterns
+
+## When to Use
+
+Apply these patterns when writing Go 1.21+ code. Use this skill for designing
+interfaces, handling errors idiomatically, managing concurrency with goroutines
+and channels, propagating cancellation with context, and structuring projects.
+
+## How It Works
+
+### Small Interfaces
+
+Define interfaces where they are consumed, not where they are implemented. Keep
+interfaces small (1-3 methods). Accept interfaces, return structs.
+
+```go
+// In the consumer package, not the provider
+type UserStore interface {
+    GetUser(ctx context.Context, id string) (*User, error)
+}
+
+type Handler struct {
+    store UserStore // accepts interface
+}
+
+func NewHandler(s UserStore) *Handler {
+    return &Handler{store: s} // returns concrete struct
+}
+```
+
+### Error Handling
+
+Wrap errors with `fmt.Errorf("context: %w", err)` to build an error chain. Define
+sentinel errors for expected conditions. Use `errors.Is` and `errors.As` to inspect.
+
+```go
+var ErrNotFound = errors.New("not found")
+
+func (s *Store) GetUser(ctx context.Context, id string) (*User, error) {
+    row := s.db.QueryRowContext(ctx, "SELECT ... WHERE id = $1", id)
+    var u User
+    if err := row.Scan(&u.ID, &u.Name); err != nil {
+        if errors.Is(err, sql.ErrNoRows) {
+            return nil, fmt.Errorf("get user %s: %w", id, ErrNotFound)
+        }
+        return nil, fmt.Errorf("get user %s: %w", id, err)
+    }
+    return &u, nil
+}
+```
+
+### Goroutines and Channels
+
+Always ensure goroutines can exit. Use `errgroup` for fan-out with error propagation.
+Use buffered channels when the producer should not block.
+
+```go
+import "golang.org/x/sync/errgroup"
+
+func FetchAll(ctx context.Context, urls []string) ([]Response, error) {
+    g, ctx := errgroup.WithContext(ctx)
+    results := make([]Response, len(urls))
+
+    for i, url := range urls {
+        g.Go(func() error {
+            resp, err := fetch(ctx, url)
+            if err != nil {
+                return err
+            }
+            results[i] = resp
+            return nil
+        })
+    }
+
+    if err := g.Wait(); err != nil {
+        return nil, err
+    }
+    return results, nil
+}
+```
+
+### Context
+
+Pass `context.Context` as the first parameter of every function that does I/O or
+may be long-running. Never store context in a struct. Use `context.WithTimeout`
+for deadlines.
+
+```go
+func (s *Service) Process(ctx context.Context, id string) error {
+    ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
+    defer cancel()
+
+    data, err := s.store.Fetch(ctx, id)
+    if err != nil {
+        return fmt.Errorf("process %s: %w", id, err)
+    }
+    return s.transform(ctx, data)
+}
+```
+
+### Functional Options
+
+Use the functional options pattern for configurable constructors instead of
+large config structs with zero values.
+
+```go
+type Server struct {
+    port    int
+    timeout time.Duration
+}
+
+type Option func(*Server)
+
+func WithPort(p int) Option     { return func(s *Server) { s.port = p } }
+func WithTimeout(d time.Duration) Option { return func(s *Server) { s.timeout = d } }
+
+func NewServer(opts ...Option) *Server {
+    s := &Server{port: 8080, timeout: 30 * time.Second} // defaults
+    for _, opt := range opts {
+        opt(s)
+    }
+    return s
+}
+```
+
+### Project Layout
+
+```
+project/
+  cmd/
+    server/main.go       # entrypoint
+  internal/
+    user/                 # domain package
+      user.go
+      store.go
+      handler.go
+      handler_test.go
+  pkg/                    # public library code (use sparingly)
+  go.mod
+  go.sum
+```
+
+Keep `main.go` minimal: parse config, wire dependencies, start server. All logic
+lives in `internal/` packages.
+
+## Examples
+
+**Pattern: Table-driven config validation**
+```go
+type rule struct {
+    name  string
+    check func() error
+}
+
+func Validate(cfg Config) error {
+    rules := []rule{
+        {"port range", func() error { if cfg.Port < 1 || cfg.Port > 65535 { return errors.New("invalid port") }; return nil }},
+        {"timeout positive", func() error { if cfg.Timeout <= 0 { return errors.New("timeout must be positive") }; return nil }},
+    }
+    for _, r := range rules {
+        if err := r.check(); err != nil {
+            return fmt.Errorf("validate %s: %w", r.name, err)
+        }
+    }
+    return nil
+}
+```
+
+## Checklist
+
+- [ ] Interfaces defined at the consumer, 1-3 methods each
+- [ ] Errors wrapped with `%w` and context about what failed
+- [ ] Sentinel errors for expected conditions (`ErrNotFound`, `ErrConflict`)
+- [ ] Every goroutine has a clear exit path (context cancellation, done channel)
+- [ ] `errgroup` for fan-out with error propagation
+- [ ] `context.Context` is the first parameter for I/O functions
+- [ ] `defer cancel()` immediately after `context.WithTimeout`
+- [ ] Functional options for constructors with optional configuration
+- [ ] Business logic in `internal/`, entrypoints in `cmd/`
+- [ ] `go vet` and `golangci-lint` pass with zero warnings

package/assets/skills/graphql-patterns.md

@@ -0,0 +1,244 @@
+---
+name: graphql-patterns
+description: GraphQL patterns for schema design, resolvers, dataloaders, subscriptions, federation, and error handling.
+---
+
+# GraphQL Patterns
+
+## When to Use
+
+Apply these patterns when designing and implementing GraphQL APIs. Use this skill
+for structuring schemas, writing efficient resolvers, solving N+1 problems with
+DataLoader, implementing real-time subscriptions, federating across services, and
+handling errors gracefully.
+
+## How It Works
+
+### Schema Design
+
+Design schemas around the client's data needs, not your database tables. Use
+clear naming conventions. Prefer object types over primitives for extensibility.
+
+```graphql
+type Query {
+  project(id: ID!): Project
+  projects(filter: ProjectFilter, first: Int = 20, after: String): ProjectConnection!
+}
+
+type Mutation {
+  createProject(input: CreateProjectInput!): CreateProjectPayload!
+  updateProject(id: ID!, input: UpdateProjectInput!): UpdateProjectPayload!
+  deleteProject(id: ID!): DeleteProjectPayload!
+}
+
+type Project {
+  id: ID!
+  name: String!
+  description: String
+  status: ProjectStatus!
+  owner: User!
+  tasks(first: Int = 10, after: String): TaskConnection!
+  createdAt: DateTime!
+  updatedAt: DateTime!
+}
+
+enum ProjectStatus {
+  ACTIVE
+  ARCHIVED
+  DRAFT
+}
+
+input CreateProjectInput {
+  name: String!
+  description: String
+}
+
+type CreateProjectPayload {
+  project: Project
+  errors: [UserError!]!
+}
+
+type UserError {
+  field: String
+  message: String!
+  code: ErrorCode!
+}
+```
+
+### Relay-Style Pagination
+
+Use cursor-based pagination with `Connection`, `Edge`, and `PageInfo` types. This
+scales better than offset pagination and handles real-time insertions.
+
+```graphql
+type ProjectConnection {
+  edges: [ProjectEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type ProjectEdge {
+  node: Project!
+  cursor: String!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+```
+
+### Resolvers
+
+Keep resolvers thin. Delegate to service/data layer. Return the right types
+for your schema. Use context for auth and shared services.
+
+```typescript
+const resolvers = {
+  Query: {
+    project: async (_, { id }, ctx) => {
+      const project = await ctx.services.project.findById(id)
+      if (!project) return null
+      if (!ctx.user.canView(project)) throw new ForbiddenError('Not authorized')
+      return project
+    },
+
+    projects: async (_, { filter, first, after }, ctx) => {
+      return ctx.services.project.paginate({ filter, first, after, userId: ctx.user.id })
+    },
+  },
+
+  Project: {
+    owner: (project, _, ctx) => {
+      return ctx.loaders.user.load(project.ownerId)
+    },
+
+    tasks: (project, { first, after }, ctx) => {
+      return ctx.services.task.paginateByProject(project.id, { first, after })
+    },
+  },
+
+  Mutation: {
+    createProject: async (_, { input }, ctx) => {
+      try {
+        const project = await ctx.services.project.create(input, ctx.user)
+        return { project, errors: [] }
+      } catch (err) {
+        return { project: null, errors: [{ field: 'name', message: err.message, code: 'INVALID_INPUT' }] }
+      }
+    },
+  },
+}
+```
+
+### DataLoader for N+1 Prevention
+
+DataLoader batches individual loads into a single query per tick. Create a new
+DataLoader per request to avoid stale caches across users.
+
+```typescript
+import DataLoader from 'dataloader'
+
+function createLoaders(db: Database) {
+  return {
+    user: new DataLoader<string, User>(async (ids) => {
+      const users = await db.user.findMany({ where: { id: { in: [...ids] } } })
+      const map = new Map(users.map(u => [u.id, u]))
+      return ids.map(id => map.get(id) ?? new Error(`User ${id} not found`))
+    }),
+
+    projectsByOwner: new DataLoader<string, Project[]>(async (ownerIds) => {
+      const projects = await db.project.findMany({ where: { ownerId: { in: [...ownerIds] } } })
+      const grouped = new Map<string, Project[]>()
+      for (const p of projects) {
+        const list = grouped.get(p.ownerId) ?? []
+        list.push(p)
+        grouped.set(p.ownerId, list)
+      }
+      return ownerIds.map(id => grouped.get(id) ?? [])
+    }),
+  }
+}
+
+// In context factory (per request)
+const context = ({ req }) => ({
+  user: authenticate(req),
+  loaders: createLoaders(db),
+  services,
+})
+```
+
+### Subscriptions
+
+Use subscriptions for real-time updates. Backed by a pub/sub system (Redis,
+in-memory for dev). Filter events server-side.
+
+```typescript
+const resolvers = {
+  Subscription: {
+    taskUpdated: {
+      subscribe: (_, { projectId }, ctx) => {
+        if (!ctx.user.canView(projectId)) throw new ForbiddenError()
+        return ctx.pubsub.asyncIterableIterator(`TASK_UPDATED:${projectId}`)
+      },
+    },
+  },
+}
+
+// In mutation resolver after updating a task:
+await pubsub.publish(`TASK_UPDATED:${task.projectId}`, { taskUpdated: task })
+```
+
+### Federation
+
+Split your graph across services. Each service owns its types. Use `@key` for
+entity resolution and `extend` for cross-service references.
+
+```graphql
+# Users service
+type User @key(fields: "id") {
+  id: ID!
+  name: String!
+  email: String!
+}
+
+# Projects service
+type User @key(fields: "id") {
+  id: ID!
+  projects: [Project!]!
+}
+
+type Project @key(fields: "id") {
+  id: ID!
+  name: String!
+  owner: User!
+}
+```
+
+## Examples
+
+**Pattern: Query complexity limiting**
+```typescript
+import { createComplexityPlugin } from 'graphql-query-complexity'
+
+const complexityPlugin = createComplexityPlugin({
+  maximumComplexity: 1000,
+  estimators: [fieldExtensionsEstimator(), simpleEstimator({ defaultComplexity: 1 })],
+  onComplete: (complexity) => { console.log('Query complexity:', complexity) },
+})
+```
+
+## Checklist
+
+- [ ] Schema designed around client needs, not database structure
+- [ ] Input types for mutations; payload types with `errors` field for user errors
+- [ ] Cursor-based pagination (`Connection`/`Edge`/`PageInfo`) for all lists
+- [ ] DataLoader created per-request to batch and cache entity lookups
+- [ ] Resolvers are thin: delegate to service/data layer
+- [ ] Subscriptions filter events server-side (not client-side)
+- [ ] Query depth and complexity limits enforced
+- [ ] `@key` directives for federated entity resolution
+- [ ] N+1 queries verified absent via query logging in dev
+- [ ] Error codes in `UserError` type, not raw exception messages

package/assets/skills/i18n-patterns.md

@@ -0,0 +1,172 @@
+---
+name: i18n-patterns
+description: Internationalization patterns with i18next, ICU message format, RTL layout, Intl API, and locale detection.
+---
+
+# Internationalization Patterns
+
+## When to Use
+Apply these patterns when your app supports multiple languages or locales -- even if you start with just English. Retrofitting i18n is far more expensive than building it in from the start. This skill covers string externalization, ICU message formatting, plurals, right-to-left layout, date/number formatting with the Intl API, and automatic locale detection.
+
+## How It Works
+
+### i18next Setup -- Foundation
+
+```typescript
+import i18next from "i18next";
+import Backend from "i18next-http-backend";
+import LanguageDetector from "i18next-browser-languagedetector";
+
+await i18next
+  .use(Backend)
+  .use(LanguageDetector)
+  .init({
+    fallbackLng: "en",
+    supportedLngs: ["en", "es", "fr", "de", "ja", "ar"],
+    ns: ["common", "auth", "dashboard"],
+    defaultNS: "common",
+    interpolation: { escapeValue: false },
+    detection: {
+      order: ["querystring", "cookie", "navigator", "htmlTag"],
+      caches: ["cookie"],
+    },
+    backend: { loadPath: "/locales/{{lng}}/{{ns}}.json" },
+  });
+```
+
+### Translation Files -- Organize by Namespace
+
+```json
+// locales/en/common.json
+{
+  "nav": { "home": "Home", "settings": "Settings", "logout": "Log out" },
+  "actions": { "save": "Save", "cancel": "Cancel", "delete": "Delete" }
+}
+
+// locales/es/common.json
+{
+  "nav": { "home": "Inicio", "settings": "Configuracion", "logout": "Cerrar sesion" },
+  "actions": { "save": "Guardar", "cancel": "Cancelar", "delete": "Eliminar" }
+}
+```
+
+### ICU Message Format -- Plurals and Gender
+
+```json
+{
+  "items_count": "{count, plural, =0 {No items} one {# item} other {# items}}",
+  "greeting": "{gender, select, male {He} female {She} other {They}} updated their profile."
+}
+```
+
+```typescript
+t("items_count", { count: 0 });   // "No items"
+t("items_count", { count: 1 });   // "1 item"
+t("items_count", { count: 42 });  // "42 items"
+```
+
+| Language | Plural Categories |
+|----------|------------------|
+| English | one, other |
+| French | one, many, other |
+| Arabic | zero, one, two, few, many, other |
+| Japanese | other (no plurals) |
+
+Always use ICU plurals -- never `count === 1 ? "item" : "items"` in code.
+
+### React Integration
+
+```tsx
+import { useTranslation, Trans } from "react-i18next";
+
+function Dashboard() {
+  const { t } = useTranslation("dashboard");
+  return (
+    <div>
+      <h1>{t("title")}</h1>
+      <p>{t("items_count", { count: orders.length })}</p>
+      <Trans i18nKey="welcome_message" t={t}>
+        Welcome, <strong>{{ name: user.name }}</strong>!
+        Check your <a href="/inbox">inbox</a>.
+      </Trans>
+    </div>
+  );
+}
+```
+
+### Date, Number, and Currency Formatting
+
+```typescript
+// Dates
+new Intl.DateTimeFormat("de-DE", { dateStyle: "long", timeStyle: "short" })
+  .format(new Date()); // "26. Mai 2026, 14:30"
+
+// Numbers
+new Intl.NumberFormat("en-US", { notation: "compact", compactDisplay: "short" })
+  .format(1_500_000); // "1.5M"
+
+// Currency
+new Intl.NumberFormat("ja-JP", { style: "currency", currency: "JPY" })
+  .format(1500); // "Y1,500"
+
+// Relative time
+new Intl.RelativeTimeFormat("en", { numeric: "auto" })
+  .format(-1, "day"); // "yesterday"
+```
+
+### RTL (Right-to-Left) Layout
+
+```css
+/* Use logical properties -- not left/right */
+.sidebar {
+  margin-inline-start: 1rem;
+  padding-inline-end: 2rem;
+  border-inline-start: 2px solid;
+}
+```
+
+```tsx
+function App() {
+  const { i18n } = useTranslation();
+  const dir = ["ar", "he", "fa"].includes(i18n.language) ? "rtl" : "ltr";
+  return (
+    <html lang={i18n.language} dir={dir}>
+      <body>{/* ... */}</body>
+    </html>
+  );
+}
+```
+
+### Locale Detection Strategy
+
+```typescript
+import { match } from "@formatjs/intl-localematcher";
+import Negotiator from "negotiator";
+
+// Priority: URL param > cookie > Accept-Language header > default
+function detectLocale(req: Request): string {
+  const negotiator = new Negotiator(req);
+  const languages = negotiator.languages();
+  return match(languages, ["en", "es", "fr", "de", "ja", "ar"], "en");
+}
+```
+
+## Examples
+
+| Pattern | Purpose | Key API |
+|---------|---------|---------|
+| ICU plurals | Correct grammar per language | i18next-icu |
+| Intl.DateTimeFormat | Locale-aware dates | Built-in |
+| Intl.NumberFormat | Numbers and currency | Built-in |
+| CSS logical properties | RTL-compatible layout | Native CSS |
+| Accept-Language | Server-side locale detection | Negotiator |
+
+## Checklist
+- [ ] All user-visible strings externalized into translation files
+- [ ] Plurals use ICU format, not ternary operators
+- [ ] Dates, numbers, and currencies formatted with `Intl` API
+- [ ] CSS uses logical properties (`inline-start` / `inline-end`)
+- [ ] `dir` attribute set on `<html>` based on language direction
+- [ ] Locale detection follows priority: URL > cookie > header > default
+- [ ] Translation keys are namespaced (`auth.login`, not `login`)
+- [ ] No string concatenation for translated sentences