cc-codeconductor 1.4.2 → 1.5.1

package/presets/agy/skills/api-versioning/SKILL.md

@@ -0,0 +1,394 @@
+---
+id: api-versioning
+name: api-versioning
+description: >
+  Provides expert knowledge for designing, implementing, and managing REST API
+  versioning strategies with deprecation workflows.
+
+user-invokable: true
+license: MIT
+metadata:
+  author: lgzarturo
+  category: api
+
+compatibility:
+  tools: [claude, codex, gemini, agy, opencode]
+  stacks:
+    languages: [kotlin, java, typescript, python, go]
+    frameworks: [spring-boot, spring-mvc, express, fastapi]
+
+risk:
+  level: high
+  can_execute_shell: false
+  can_modify_files: true
+  requires_network: false
+
+inputs:
+  - source_files
+  - openapi spec files
+  - existing controller classes
+
+outputs:
+  - versioned controller classes
+  - OpenAPI spec updates
+  - deprecation headers
+  - changelog entries
+  - contract test scaffolding
+
+quality:
+  reviewed_by: codeconductor-core
+  version: 0.1.0
+---
+
+# API Versioning
+
+## Versioning Strategies
+
+### URL Path Versioning (recommended for breaking changes)
+
+```text
+GET /api/v1/users
+GET /api/v2/users
+```
+
+Tradeoffs:
+
+- Explicit and visible in logs, proxies, and browser history
+- Easy to cache at the CDN level — the URL uniquely identifies the resource
+  version
+- Easy to route at the load balancer
+- Results in some duplication of controller code
+- Changing the URL violates REST HATEOAS principles, though in practice this is
+  acceptable
+
+Use this when: you have breaking changes and need maximum visibility and
+cacheability.
+
+### Header Versioning
+
+```text
+GET /api/users
+Accept: application/vnd.myapp+json;version=1
+```
+
+Tradeoffs:
+
+- Cleaner URLs
+- Harder to test manually — browsers and curl require extra flags
+- Cannot be bookmarked or linked directly
+- CDN caching requires `Vary: Accept` header, which reduces cache hit rates
+
+Use this when: you need clean URLs and your clients are all programmatic (no
+browsers).
+
+### Query Parameter Versioning (avoid)
+
+```text
+GET /api/users?version=1
+```
+
+This approach contaminates resource URLs with transport concerns. The version is
+not part of the resource identity. Do not use it. The only valid exception is
+temporary backward-compat support during a migration window.
+
+## When to Version
+
+Version when the change is breaking. Not every change requires a version bump.
+
+**Breaking — requires new version:**
+
+- Removing a field from a response
+- Renaming a field
+- Changing a field's type (e.g., `string` to `object`)
+- Changing the meaning of an existing field
+- Removing an endpoint
+- Changing required fields in a request
+- Changing status codes in a non-additive way
+
+**Not breaking — no version bump needed:**
+
+- Adding an optional field to a response
+- Adding a new endpoint
+- Adding an optional request parameter
+- Deprecating a field (marking it, but still returning it)
+- Performance improvements
+- Bug fixes that restore documented behavior
+
+## Deprecation Process
+
+When a version or endpoint is being phased out, follow this process:
+
+**Step 1: Mark in OpenAPI.**
+
+```yaml
+paths:
+  /api/v1/users/{id}:
+    get:
+      deprecated: true
+      description: |
+        Deprecated since 2026-05-07. Use /api/v2/users/{id} instead.
+        Sunset date: 2026-11-07.
+      summary: Get user by ID (deprecated)
+```
+
+**Step 2: Add deprecation headers to responses.**
+
+```kotlin
+@GetMapping("/{id}")
+fun getUserV1(@PathVariable id: UUID, response: HttpServletResponse): ResponseEntity<UserV1Response> {
+    response.addHeader("Deprecation", "date=\"Wed, 07 May 2026 00:00:00 GMT\"")
+    response.addHeader("Sunset", "Mon, 07 Nov 2026 00:00:00 GMT")
+    response.addHeader("Link", "</api/v2/users/$id>; rel=\"successor-version\"")
+    return ResponseEntity.ok(userService.getById(id).toV1Response())
+}
+```
+
+**Step 3: Document in CHANGELOG.**
+
+```markdown
+## Deprecated
+
+- `GET /api/v1/users/{id}` — deprecated in favor of `GET /api/v2/users/{id}`.
+  Sunset: 2026-11-07.
+```
+
+**Step 4: Maintain dual support.**
+
+Keep at least two active major versions at all times. When v3 ships, v1 can be
+removed (v2 and v3 remain active).
+
+**Step 5: Communicate the sunset date.**
+
+Notify consumers before the sunset date through:
+
+- API changelog
+- Developer portal announcements
+- Deprecation headers (machine-readable)
+- Direct contact if you have consumer registration data
+
+Do not remove a version without a minimum 6-month notice period. 3 months is the
+absolute minimum if forced.
+
+## OpenAPI Conventions
+
+### One file per version (simple cases)
+
+```text
+openapi-v1.yaml
+openapi-v2.yaml
+```
+
+Each file is self-contained and independently valid.
+
+### Single file with version in info (evolving APIs)
+
+```yaml
+openapi: '3.1.0'
+info:
+  title: Users API
+  version: '2.0.0'
+```
+
+Use `$ref` to share schemas across versions without duplication.
+
+### Cross-version schema reuse
+
+```yaml
+# schemas/user-base.yaml
+UserBase:
+  type: object
+  properties:
+    id:
+      type: string
+      format: uuid
+    email:
+      type: string
+
+# openapi-v1.yaml
+components:
+  schemas:
+    UserResponse:
+      allOf:
+        - $ref: './schemas/user-base.yaml#/UserBase'
+        - properties:
+            full_name:
+              type: string
+
+# openapi-v2.yaml — splits full_name into first_name + last_name
+components:
+  schemas:
+    UserResponse:
+      allOf:
+        - $ref: './schemas/user-base.yaml#/UserBase'
+        - properties:
+            first_name:
+              type: string
+            last_name:
+              type: string
+```
+
+### Documenting breaking changes
+
+Put the breaking change in the endpoint description, not just in a changelog:
+
+```yaml
+/api/v2/users/{id}:
+  get:
+    description: |
+      Returns user details.
+
+      Breaking changes from v1:
+      - `full_name` has been replaced by `first_name` and `last_name`
+```
+
+## Spring Boot Implementation
+
+### URL path versioning
+
+```kotlin
+// V1 controller — never modify once published
+@RestController
+@RequestMapping("/api/v1/users")
+class UserV1Controller(private val userService: UserService) {
+
+    @GetMapping("/{id}")
+    @Deprecated("Use /api/v2/users/{id}", ReplaceWith("UserV2Controller.getUser()"))
+    fun getUser(
+        @PathVariable id: UUID,
+        response: HttpServletResponse
+    ): ResponseEntity<UserV1Response> {
+        response.addHeader("Deprecation", "date=\"Wed, 07 May 2026 00:00:00 GMT\"")
+        response.addHeader("Sunset", "Mon, 07 Nov 2026 00:00:00 GMT")
+        return when (val result = userService.getById(id)) {
+            is UserResult.Found -> ResponseEntity.ok(result.user.toV1Response())
+            is UserResult.NotFound -> ResponseEntity.notFound().build()
+        }
+    }
+}
+
+// V2 controller — new version, new controller, shared service
+@RestController
+@RequestMapping("/api/v2/users")
+class UserV2Controller(private val userService: UserService) {
+
+    @GetMapping("/{id}")
+    fun getUser(@PathVariable id: UUID): ResponseEntity<UserV2Response> {
+        return when (val result = userService.getById(id)) {
+            is UserResult.Found -> ResponseEntity.ok(result.user.toV2Response())
+            is UserResult.NotFound -> ResponseEntity.notFound().build()
+        }
+    }
+}
+```
+
+Rules:
+
+- Create a new controller for each new version — do not modify the existing one
+- The service layer is shared across versions — only the controller and DTO
+  change
+- DTO mapper functions are version-specific: `toV1Response()`, `toV2Response()`
+- Never delete a versioned controller until after the sunset date
+
+### DTO versioning
+
+```kotlin
+// V1 — original shape
+data class UserV1Response(
+    val id: UUID,
+    val email: String,
+    val full_name: String
+)
+
+// V2 — breaking change: split full_name
+data class UserV2Response(
+    val id: UUID,
+    val email: String,
+    val first_name: String,
+    val last_name: String
+)
+
+// Extension functions for mapping
+fun User.toV1Response(): UserV1Response = UserV1Response(
+    id = id,
+    email = email,
+    full_name = "$firstName $lastName"
+)
+
+fun User.toV2Response(): UserV2Response = UserV2Response(
+    id = id,
+    email = email,
+    first_name = firstName,
+    last_name = lastName
+)
+```
+
+## Contract Testing
+
+Contract tests verify that your API does not break existing consumers before
+changes reach production.
+
+**When to run:** in CI, before merging any change that touches a controller,
+DTO, or OpenAPI spec.
+
+**Tool: Pact (consumer-driven contracts)**
+
+Consumer writes a pact:
+
+```kotlin
+// In the consumer service test
+@ExtendWith(PactConsumerTestExt::class)
+class UserServiceConsumerTest {
+
+    @Pact(consumer = "order-service", provider = "user-service")
+    fun getUserPact(builder: PactDslWithProvider): RequestResponsePact {
+        return builder
+            .given("user with id exists")
+            .uponReceiving("a request for user by id")
+            .path("/api/v1/users/123e4567-e89b-12d3-a456-426614174000")
+            .method("GET")
+            .willRespondWith()
+            .status(200)
+            .body(LambdaDsl.newJsonBody { body ->
+                body.uuid("id")
+                body.stringType("email")
+                body.stringType("full_name")
+            }.build())
+            .toPact()
+    }
+}
+```
+
+Provider verifies the pact:
+
+```kotlin
+@Provider("user-service")
+@PactFolder("pacts")
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+class UserServiceProviderTest {
+
+    @TestTarget
+    lateinit var target: HttpTestTarget
+
+    @BeforeEach
+    fun setUp(@LocalServerPort port: Int) {
+        target = HttpTestTarget("localhost", port)
+    }
+}
+```
+
+**Rule:** run contract tests in CI before any merge that touches an API surface.
+A broken contract test means a consumer will break in production.
+
+## Test Structure Per Version
+
+Each API version must have its own test class:
+
+```text
+src/test/kotlin/{package}/user/
+  controller/
+    UserV1ControllerTest.kt   # tests for v1 endpoints
+    UserV2ControllerTest.kt   # tests for v2 endpoints
+```
+
+Do not share test cases across versions. V1 behavior must be tested
+independently from V2 — they can diverge.

package/presets/agy/skills/astro/SKILL.md

@@ -0,0 +1,318 @@
+---
+id: astro
+name: astro
+description: >
+  Provides expert knowledge for building Astro 5+ sites with Islands Architecture, Content Collections, TypeScript, and performance-first rendering strategies.
+
+user-invokable: true
+license: MIT
+metadata:
+  author: lgzarturo
+  category: frontend
+
+compatibility:
+  tools: [claude, codex, gemini, agy, opencode]
+  stacks:
+    languages: []
+    frameworks: []
+
+risk:
+  level: low
+  can_execute_shell: false
+  can_modify_files: true
+  requires_network: false
+
+inputs: []
+
+outputs: []
+
+quality:
+  reviewed_by: codeconductor-core
+  version: 0.1.0
+---
+
+
+
+# Astro
+
+## Islands Architecture
+
+Astro renders everything to static HTML by default. JavaScript ships only for
+components that explicitly opt in — these are called Islands.
+
+### Hydration Directives
+
+| Directive | When JS loads | Use case |
+|-----------|--------------|----------|
+| `client:load` | On page load | Interactive above-the-fold UI |
+| `client:idle` | When browser is idle | Non-critical interactive widgets |
+| `client:visible` | When element enters viewport | Below-the-fold islands |
+| `client:media` | When CSS media query matches | Responsive interactive components |
+| `client:only` | Client-only, no SSR | Components that require the DOM (e.g., charting libs) |
+
+```astro
+---
+import Counter from '../components/Counter.tsx';
+import HeavyChart from '../components/HeavyChart.tsx';
+import MobileNav from '../components/MobileNav.tsx';
+---
+
+<!-- Hydrates immediately — user interacts right away -->
+<Counter client:load />
+
+<!-- Hydrates when scrolled into view — saves initial JS -->
+<HeavyChart client:visible />
+
+<!-- Only on mobile, only when query matches -->
+<MobileNav client:media="(max-width: 768px)" />
+```
+
+Rules:
+
+- Default to no hydration directive — most UI does not need JavaScript
+- `client:load` is the most expensive directive; use it sparingly
+- `client:only` skips server rendering entirely — the component receives no
+  props from the server; pass all data via props or fetch inside the component
+- Do not use `client:load` for components that could use `client:visible`
+
+### Framework Components Inside Astro
+
+```astro
+---
+import ReactButton from './Button.tsx';   // React island
+import VueWidget from './Widget.vue';     // Vue island
+---
+
+<!-- Both can coexist on the same page -->
+<ReactButton client:idle label="Click me" />
+<VueWidget client:visible />
+```
+
+Each framework ships its own runtime only when at least one island of that
+framework is on the page.
+
+## Content Collections
+
+Content Collections provide type-safe access to Markdown, MDX, and data files.
+Define schemas in `src/content/config.ts`.
+
+### Schema Definition
+
+```typescript
+// src/content/config.ts
+import { defineCollection, z } from 'astro:content';
+
+const blog = defineCollection({
+  type: 'content',   // .md or .mdx files
+  schema: z.object({
+    title: z.string(),
+    description: z.string(),
+    pubDate: z.coerce.date(),
+    updatedDate: z.coerce.date().optional(),
+    author: z.string().default('Anonymous'),
+    tags: z.array(z.string()).default([]),
+    draft: z.boolean().default(false),
+    image: z.object({
+      src: z.string(),
+      alt: z.string(),
+    }).optional(),
+  }),
+});
+
+const docs = defineCollection({
+  type: 'content',
+  schema: z.object({
+    title: z.string(),
+    order: z.number(),
+    section: z.enum(['guide', 'reference', 'tutorial']),
+  }),
+});
+
+export const collections = { blog, docs };
+```
+
+### Querying Collections
+
+```astro
+---
+import { getCollection, getEntry } from 'astro:content';
+
+// All published posts, sorted by date
+const posts = (await getCollection('blog', ({ data }) => !data.draft))
+  .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
+
+// Single entry by slug
+const post = await getEntry('blog', 'my-first-post');
+const { Content } = await post.render();
+---
+
+{posts.map(post => (
+  <article>
+    <h2><a href={`/blog/${post.slug}`}>{post.data.title}</a></h2>
+    <time>{post.data.pubDate.toLocaleDateString()}</time>
+  </article>
+))}
+```
+
+### Dynamic Routes from Collections
+
+```astro
+---
+// src/pages/blog/[slug].astro
+import { getCollection } from 'astro:content';
+
+export async function getStaticPaths() {
+  const posts = await getCollection('blog');
+  return posts.map(post => ({
+    params: { slug: post.slug },
+    props: { post },
+  }));
+}
+
+const { post } = Astro.props;
+const { Content, headings } = await post.render();
+---
+
+<article>
+  <h1>{post.data.title}</h1>
+  <Content />
+</article>
+```
+
+## Rendering Strategies
+
+### SSG (Static Site Generation) — default
+
+Every page is pre-rendered at build time. Best for content that does not change
+per request.
+
+```javascript
+// astro.config.mjs — no output config needed; SSG is the default
+export default defineConfig({
+  site: 'https://example.com',
+});
+```
+
+### SSR (Server-Side Rendering)
+
+Renders pages on each request. Required for: authenticated routes, personalized
+content, live data.
+
+```javascript
+// astro.config.mjs
+import node from '@astrojs/node';
+
+export default defineConfig({
+  output: 'server',
+  adapter: node({ mode: 'standalone' }),
+});
+```
+
+### Hybrid Mode
+
+Mix SSG and SSR on a per-page basis. Most pages are static; specific routes opt
+into server rendering.
+
+```javascript
+// astro.config.mjs
+export default defineConfig({
+  output: 'hybrid',
+  adapter: node({ mode: 'standalone' }),
+});
+```
+
+```astro
+---
+// src/pages/dashboard.astro — this page is server-rendered
+export const prerender = false;
+
+// src/pages/about.astro — this page is statically generated (hybrid default)
+export const prerender = true;
+---
+```
+
+Use hybrid mode when: most content is static but a few routes need auth or
+live data. Do not make everything `output: 'server'` — you lose the performance
+benefits of static generation.
+
+## Image Optimization
+
+Use the built-in `<Image>` and `<Picture>` components. Never use raw `<img>`
+for local assets — you lose automatic optimization.
+
+```astro
+---
+import { Image, Picture } from 'astro:assets';
+import heroImage from '../assets/hero.png';
+---
+
+<!-- Optimized single image -->
+<Image
+  src={heroImage}
+  alt="Hero illustration"
+  width={800}
+  height={600}
+  format="webp"
+  quality={80}
+/>
+
+<!-- Responsive with multiple formats -->
+<Picture
+  src={heroImage}
+  formats={['avif', 'webp']}
+  alt="Hero illustration"
+  widths={[400, 800, 1200]}
+  sizes="(max-width: 800px) 100vw, 800px"
+/>
+```
+
+Rules:
+
+- Always provide `alt` — empty string is acceptable only for decorative images
+- Prefer `avif` + `webp` fallback for best compression
+- Use `widths` + `sizes` on above-the-fold images to serve the right size per
+  viewport
+- Remote images require explicit `width` and `height` to prevent layout shift
+
+## Project Structure
+
+```text
+src/
+  assets/          — images and static assets processed by Astro
+  components/      — .astro components (and framework islands)
+  content/
+    blog/          — .md and .mdx files
+    config.ts      — collection schemas
+  layouts/         — page shell layouts
+  pages/           — file-based routing; every file is a route
+  styles/          — global CSS
+astro.config.mjs
+tsconfig.json
+```
+
+Colocation rule: put framework island components (`.tsx`, `.vue`) in
+`src/components/`. Do not scatter them in `src/pages/`.
+
+## TypeScript Conventions
+
+```json
+// tsconfig.json — use the strict Astro preset
+{
+  "extends": "astro/tsconfigs/strict"
+}
+```
+
+```astro
+---
+// Type props explicitly in the frontmatter
+interface Props {
+  title: string;
+  description?: string;
+  tags: string[];
+}
+
+const { title, description = '', tags } = Astro.props;
+---
+```
+
+Astro infers prop types from `interface Props` automatically. Do not use `any`.