@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/forms-patterns.md

@@ -0,0 +1,264 @@
+---
+name: forms-patterns
+description: Form patterns with React Hook Form, Zod validation, multi-step forms, file uploads, and optimistic submission.
+---
+
+# Form Patterns
+
+## When to Use
+Apply when building user input forms in React applications. Use React Hook Form for performance, Zod for type-safe validation, multi-step wizards for complex flows, and optimistic submission for snappy UX. These patterns prevent common pitfalls: re-renders, unvalidated submissions, and poor error feedback.
+
+## How It Works
+
+### React Hook Form + Zod Validation
+
+Type-safe forms with zero re-renders on input change:
+
+```typescript
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { z } from "zod";
+
+const signupSchema = z.object({
+  name: z.string().min(2, "Name must be at least 2 characters"),
+  email: z.string().email("Invalid email address"),
+  password: z
+    .string()
+    .min(8, "Password must be at least 8 characters")
+    .regex(/[A-Z]/, "Must contain an uppercase letter")
+    .regex(/[0-9]/, "Must contain a number"),
+  confirmPassword: z.string(),
+}).refine((data) => data.password === data.confirmPassword, {
+  message: "Passwords do not match",
+  path: ["confirmPassword"],
+});
+
+type SignupForm = z.infer<typeof signupSchema>;
+
+function SignupPage() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isSubmitting },
+  } = useForm<SignupForm>({
+    resolver: zodResolver(signupSchema),
+  });
+
+  const onSubmit = async (data: SignupForm) => {
+    await fetch("/api/auth/signup", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(data),
+    });
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)} noValidate>
+      <div>
+        <label htmlFor="name">Name</label>
+        <input id="name" {...register("name")} />
+        {errors.name && <p role="alert">{errors.name.message}</p>}
+      </div>
+      <div>
+        <label htmlFor="email">Email</label>
+        <input id="email" type="email" {...register("email")} />
+        {errors.email && <p role="alert">{errors.email.message}</p>}
+      </div>
+      <div>
+        <label htmlFor="password">Password</label>
+        <input id="password" type="password" {...register("password")} />
+        {errors.password && <p role="alert">{errors.password.message}</p>}
+      </div>
+      <div>
+        <label htmlFor="confirmPassword">Confirm Password</label>
+        <input id="confirmPassword" type="password" {...register("confirmPassword")} />
+        {errors.confirmPassword && <p role="alert">{errors.confirmPassword.message}</p>}
+      </div>
+      <button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? "Creating account..." : "Sign Up"}
+      </button>
+    </form>
+  );
+}
+```
+
+### Multi-Step Form Wizard
+
+Break complex forms into digestible steps:
+
+```typescript
+const stepSchemas = [
+  z.object({ name: z.string().min(1), email: z.string().email() }),
+  z.object({ company: z.string().min(1), role: z.string().min(1) }),
+  z.object({ plan: z.enum(["free", "pro", "enterprise"]) }),
+];
+
+function MultiStepForm() {
+  const [step, setStep] = useState(0);
+  const [formData, setFormData] = useState({});
+
+  const currentSchema = stepSchemas[step];
+  const { register, handleSubmit, formState: { errors } } = useForm({
+    resolver: zodResolver(currentSchema),
+    defaultValues: formData,
+  });
+
+  const onStepSubmit = (data: Record<string, unknown>) => {
+    const merged = { ...formData, ...data };
+    setFormData(merged);
+
+    if (step < stepSchemas.length - 1) {
+      setStep(step + 1);
+    } else {
+      submitFinalForm(merged);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onStepSubmit)}>
+      <div aria-label={`Step ${step + 1} of ${stepSchemas.length}`}>
+        <progress value={step + 1} max={stepSchemas.length} />
+      </div>
+      {step === 0 && (
+        <>
+          <input {...register("name")} placeholder="Name" />
+          <input {...register("email")} placeholder="Email" />
+        </>
+      )}
+      {step === 1 && (
+        <>
+          <input {...register("company")} placeholder="Company" />
+          <input {...register("role")} placeholder="Role" />
+        </>
+      )}
+      {step === 2 && (
+        <select {...register("plan")}>
+          <option value="free">Free</option>
+          <option value="pro">Pro</option>
+          <option value="enterprise">Enterprise</option>
+        </select>
+      )}
+      <div>
+        {step > 0 && <button type="button" onClick={() => setStep(step - 1)}>Back</button>}
+        <button type="submit">{step === stepSchemas.length - 1 ? "Submit" : "Next"}</button>
+      </div>
+    </form>
+  );
+}
+```
+
+### File Upload with Preview
+
+```typescript
+function FileUploadField({ name, control }: { name: string; control: Control }) {
+  const { field } = useController({ name, control });
+  const [preview, setPreview] = useState<string | null>(null);
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (!file) return;
+
+    if (file.size > 5 * 1024 * 1024) {
+      alert("File must be under 5MB");
+      return;
+    }
+
+    field.onChange(file);
+    const reader = new FileReader();
+    reader.onload = () => setPreview(reader.result as string);
+    reader.readAsDataURL(file);
+  };
+
+  return (
+    <div>
+      <input type="file" accept="image/*" onChange={handleChange} />
+      {preview && <img src={preview} alt="Preview" style={{ maxWidth: 200 }} />}
+    </div>
+  );
+}
+```
+
+### Optimistic Submission
+
+Show success immediately, roll back on failure:
+
+```typescript
+function TodoList() {
+  const [todos, setTodos] = useState<Todo[]>([]);
+
+  const addTodo = async (text: string) => {
+    const optimisticTodo: Todo = {
+      id: `temp-${Date.now()}`,
+      text,
+      completed: false,
+    };
+
+    // Optimistic update
+    setTodos((prev) => [...prev, optimisticTodo]);
+
+    try {
+      const created = await fetch("/api/todos", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ text }),
+      }).then((r) => r.json());
+
+      // Replace optimistic with real
+      setTodos((prev) =>
+        prev.map((t) => (t.id === optimisticTodo.id ? created : t))
+      );
+    } catch {
+      // Roll back
+      setTodos((prev) => prev.filter((t) => t.id !== optimisticTodo.id));
+      toast.error("Failed to add todo");
+    }
+  };
+}
+```
+
+### Server-Side Validation Error Handling
+
+```typescript
+const onSubmit = async (data: SignupForm) => {
+  const res = await fetch("/api/auth/signup", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(data),
+  });
+
+  if (!res.ok) {
+    const body = await res.json();
+    // Map server errors to form fields
+    if (body.errors) {
+      for (const [field, message] of Object.entries(body.errors)) {
+        setError(field as keyof SignupForm, {
+          type: "server",
+          message: message as string,
+        });
+      }
+    }
+    return;
+  }
+  router.push("/dashboard");
+};
+```
+
+## Examples
+
+| Pattern | When | Result |
+|---------|------|--------|
+| RHF + Zod | Any form | Type-safe, zero unnecessary re-renders |
+| Multi-step wizard | Onboarding, checkout | Digestible steps, per-step validation |
+| File upload preview | Avatar, documents | Instant visual feedback before submit |
+| Optimistic submission | Todos, comments, likes | Instant UX, graceful rollback |
+| Server error mapping | Signup, settings | Field-level errors from API |
+
+## Checklist
+- [ ] Forms use React Hook Form with zodResolver for type-safe validation
+- [ ] Every input has a visible label and accessible error message
+- [ ] Submit button shows loading state and is disabled during submission
+- [ ] Server validation errors mapped back to individual form fields
+- [ ] Multi-step forms validate per step, not only on final submit
+- [ ] File uploads validate size and type before upload
+- [ ] Form state persists across page navigation (for long forms)
+- [ ] `noValidate` on form element to prevent browser default validation

package/assets/skills/gcp-patterns.md

@@ -0,0 +1,189 @@
+---
+name: gcp-patterns
+description: GCP patterns for Cloud Run, Firestore, Cloud Functions, Pub/Sub, Cloud Storage, and IAM best practices.
+---
+
+# GCP Patterns
+
+## When to Use
+Apply when building on Google Cloud Platform. Covers Cloud Run for containerized services, Firestore for document databases, Cloud Functions for event-driven compute, Pub/Sub for messaging, Cloud Storage for objects, and IAM for access control. Use this skill when designing GCP architectures, migrating workloads, or optimizing existing deployments.
+
+## How It Works
+
+### Cloud Run -- Serverless Containers
+
+```dockerfile
+FROM node:20-slim AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --production
+COPY . .
+RUN npm run build
+
+FROM node:20-slim
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+ENV PORT=8080
+EXPOSE 8080
+CMD ["node", "dist/server.js"]
+```
+
+```bash
+gcloud run deploy my-service \
+  --image gcr.io/my-project/my-service:latest \
+  --region us-central1 \
+  --concurrency 80 \
+  --min-instances 1 \
+  --max-instances 10 \
+  --memory 512Mi \
+  --cpu 1 \
+  --set-env-vars "NODE_ENV=production" \
+  --service-account my-service@my-project.iam.gserviceaccount.com
+```
+
+Set `--min-instances 1` to avoid cold starts for critical services. Use `--concurrency` to match your app's threading model. Keep container startup under 10 seconds.
+
+### Firestore -- Document Database
+
+```typescript
+import { Firestore, FieldValue } from "@google-cloud/firestore";
+
+const db = new Firestore();
+
+// Create/update with merge
+await db.collection("users").doc(userId).set({
+  name: "Alice",
+  email: "alice@example.com",
+  updatedAt: FieldValue.serverTimestamp(),
+}, { merge: true });
+
+// Query with composite filter
+const activeOrders = await db.collection("orders")
+  .where("userId", "==", userId)
+  .where("status", "in", ["pending", "processing"])
+  .orderBy("createdAt", "desc")
+  .limit(20)
+  .get();
+
+// Transaction -- atomic read-modify-write
+await db.runTransaction(async (tx) => {
+  const ref = db.collection("accounts").doc(accountId);
+  const snap = await tx.get(ref);
+  const balance = snap.data()?.balance ?? 0;
+  if (balance < amount) throw new Error("Insufficient funds");
+  tx.update(ref, { balance: balance - amount });
+  tx.create(db.collection("transactions").doc(), {
+    accountId, amount: -amount, createdAt: FieldValue.serverTimestamp(),
+  });
+});
+```
+
+Design documents for the read pattern -- denormalize. Keep documents under 1MB. Use subcollections for 1:many relationships.
+
+### Cloud Functions -- Event-Driven
+
+```typescript
+import { onDocumentCreated } from "firebase-functions/v2/firestore";
+import { onMessagePublished } from "firebase-functions/v2/pubsub";
+
+export const onOrderCreated = onDocumentCreated("orders/{orderId}", async (event) => {
+  const order = event.data?.data();
+  if (!order) return;
+  await sendConfirmationEmail(order.userId, order);
+  await updateInventory(order.items);
+});
+
+export const processAnalytics = onMessagePublished("analytics-events", async (event) => {
+  const data = event.data.message.json;
+  await bigquery.insert("events", data);
+});
+```
+
+### Pub/Sub -- Async Messaging
+
+```typescript
+import { PubSub } from "@google-cloud/pubsub";
+
+const pubsub = new PubSub();
+
+// Publish with ordering key
+const topic = pubsub.topic("order-events", { enableMessageOrdering: true });
+await topic.publishMessage({
+  data: Buffer.from(JSON.stringify({ orderId, action: "created" })),
+  orderingKey: orderId,
+  attributes: { eventType: "order.created" },
+});
+
+// Subscribe with flow control
+const sub = pubsub.subscription("order-processor", {
+  flowControl: { maxMessages: 10 },
+});
+sub.on("message", async (message) => {
+  try {
+    await processOrderEvent(JSON.parse(message.data.toString()));
+    message.ack();
+  } catch {
+    message.nack();
+  }
+});
+```
+
+Set dead-letter topics for messages that fail repeatedly. Use ordering keys only when needed -- they reduce throughput.
+
+### Cloud Storage -- Object Store
+
+```typescript
+import { Storage } from "@google-cloud/storage";
+
+const storage = new Storage();
+const bucket = storage.bucket("my-app-assets");
+
+// Resumable upload for large files
+await bucket.upload(localPath, {
+  destination: `uploads/${userId}/${filename}`,
+  resumable: true,
+  metadata: { contentType: "application/pdf" },
+});
+
+// Signed URL for temporary access
+const [url] = await bucket.file(`uploads/${userId}/${filename}`).getSignedUrl({
+  action: "read",
+  expires: Date.now() + 15 * 60 * 1000,
+});
+```
+
+### IAM -- Least Privilege
+
+```bash
+# One service account per service
+gcloud iam service-accounts create my-service-sa \
+  --display-name "My Service"
+
+# Grant only needed roles
+gcloud projects add-iam-policy-binding my-project \
+  --member "serviceAccount:my-service-sa@my-project.iam.gserviceaccount.com" \
+  --role "roles/datastore.user"
+```
+
+Never use the default compute service account in production. Use Workload Identity Federation for external services instead of key files.
+
+## Examples
+
+| Pattern | Service | Use Case |
+|---------|---------|----------|
+| Container API | Cloud Run | REST/gRPC microservices |
+| Document store | Firestore | User profiles, settings |
+| Event trigger | Cloud Functions | Firestore/Pub/Sub handlers |
+| Message bus | Pub/Sub | Service decoupling |
+| File storage | Cloud Storage | Uploads, backups, static assets |
+
+## Checklist
+- [ ] Cloud Run services have `--min-instances 1` for latency-critical paths
+- [ ] Firestore composite indexes created for all multi-field queries
+- [ ] Cloud Functions have memory and timeout configured per function
+- [ ] Pub/Sub subscriptions have dead-letter topics configured
+- [ ] Cloud Storage buckets have lifecycle rules for old objects
+- [ ] Each service uses a dedicated service account with minimal roles
+- [ ] No service account key files -- use Workload Identity Federation
+- [ ] Infrastructure defined in Terraform or Deployment Manager

package/assets/skills/git-workflow.md

@@ -0,0 +1,187 @@
+---
+name: git-workflow
+description: Git workflow patterns including branching strategies, conventional commits, rebasing, cherry-pick, and bisect.
+---
+
+# Git Workflow Patterns
+
+## When to Use
+Apply these patterns when collaborating on any software project using Git. Whether you are managing feature branches, writing commit messages, resolving merge conflicts, or tracking down regressions, consistent Git workflows reduce friction and keep the history readable. These patterns are especially important in teams using CI/CD, code review, and automated release pipelines.
+
+## How It Works
+
+### Branching Strategy (Trunk-Based with Short-Lived Branches)
+
+```bash
+# Create a feature branch from main
+git checkout main
+git pull origin main
+git checkout -b feat/user-avatars
+
+# Work on the branch with small, atomic commits
+git add src/components/Avatar.tsx src/components/Avatar.test.tsx
+git commit -m "feat(ui): add Avatar component with fallback initials"
+
+git add src/api/upload-avatar.ts
+git commit -m "feat(api): add avatar upload endpoint with S3 presigned URL"
+
+# Keep branch up to date with main
+git fetch origin
+git rebase origin/main
+
+# Push and create PR
+git push -u origin feat/user-avatars
+gh pr create --title "feat: user avatar upload and display" \
+  --body "Adds avatar component and S3 upload endpoint"
+```
+
+### Conventional Commits
+
+```bash
+# Format: <type>(<scope>): <description>
+# Types: feat, fix, docs, style, refactor, test, chore, perf, ci, build
+
+# Feature
+git commit -m "feat(auth): add OAuth 2.0 Google login"
+
+# Bug fix
+git commit -m "fix(api): handle null response in user endpoint"
+
+# Breaking change (note the ! after scope)
+git commit -m "feat(api)!: change /users response format to paginated"
+
+# Multi-line with body and footer
+git commit -m "fix(db): resolve connection pool exhaustion under load
+
+The pool was not releasing connections after transaction rollback.
+Added explicit release in the finally block of executeTransaction.
+
+Closes #342"
+```
+
+### Interactive Rebase for Clean History
+
+```bash
+# Squash the last 4 commits into a clean history before PR merge
+git rebase -i HEAD~4
+
+# In the editor:
+# pick abc1234 feat(auth): add login form skeleton
+# squash def5678 wip: hook up validation
+# squash 789abcd fix typo in error message
+# squash bcd0123 add tests for login flow
+
+# Result: one clean commit with a comprehensive message
+```
+
+### Cherry-Pick a Specific Commit
+
+```bash
+# Bring a hotfix from main into a release branch
+git checkout release/2.1
+git cherry-pick abc1234
+
+# Cherry-pick without committing (to modify before committing)
+git cherry-pick --no-commit abc1234
+git add -p  # stage only the parts you need
+git commit -m "fix(billing): backport invoice rounding fix to 2.1"
+```
+
+### Git Bisect to Find Regressions
+
+```bash
+# Start bisect
+git bisect start
+
+# Mark the current commit as bad
+git bisect bad
+
+# Mark a known good commit (e.g., last release tag)
+git bisect good v2.0.0
+
+# Git checks out a midpoint - test it, then mark good or bad
+npm test -- --run src/billing.test.ts
+git bisect good   # or: git bisect bad
+
+# Automate with a test script
+git bisect start HEAD v2.0.0
+git bisect run npm test -- --run src/billing.test.ts
+
+# Clean up
+git bisect reset
+```
+
+### Stash and Apply
+
+```bash
+# Save work in progress before switching branches
+git stash push -m "wip: dashboard chart refactor"
+
+# List stashes
+git stash list
+
+# Apply and remove from stash
+git stash pop
+
+# Apply without removing (keep stash for reuse)
+git stash apply stash@{0}
+
+# Stash only unstaged changes (keep staged files)
+git stash push --keep-index -m "unstaged changes only"
+```
+
+### Handling Merge Conflicts
+
+```bash
+# During rebase, when conflicts occur:
+git rebase origin/main
+# CONFLICT in src/config.ts
+
+# 1. Open the file, resolve the conflict markers
+# 2. Stage the resolved file
+git add src/config.ts
+
+# 3. Continue the rebase
+git rebase --continue
+
+# If you want to abort and go back to before the rebase
+git rebase --abort
+```
+
+### Tags and Releases
+
+```bash
+# Create an annotated tag for release
+git tag -a v2.1.0 -m "Release 2.1.0: avatar upload, improved billing"
+
+# Push tags
+git push origin v2.1.0
+
+# List tags matching a pattern
+git tag -l "v2.*"
+
+# Delete a tag locally and remotely
+git tag -d v2.1.0-beta
+git push origin --delete v2.1.0-beta
+```
+
+## Examples
+
+| Scenario | Command | Purpose |
+|----------|---------|---------|
+| Undo last commit (keep changes) | `git reset --soft HEAD~1` | Recommit with different message |
+| View file at specific commit | `git show abc1234:src/config.ts` | Inspect historical state |
+| Find who changed a line | `git blame -L 10,20 src/auth.ts` | Track authorship |
+| See branches merged to main | `git branch --merged main` | Clean up stale branches |
+| Diff only file names | `git diff --name-only HEAD~3` | Quick overview of recent changes |
+| Restore a deleted file | `git checkout HEAD~1 -- src/removed.ts` | Recover from accidental deletion |
+
+## Checklist
+- [ ] Feature branches are short-lived (< 2 days) and branched from main
+- [ ] Commits follow conventional commit format (`feat:`, `fix:`, `chore:`, etc.)
+- [ ] Rebase onto main before creating a PR to avoid merge commits
+- [ ] Each commit is atomic: it compiles, tests pass, and represents one logical change
+- [ ] Tags follow semver and are created for every release
+- [ ] Stale branches are deleted after PR merge
+- [ ] Never force-push to main or shared branches
+- [ ] Use `git bisect` instead of manual searching when tracking regressions