@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/gemini-cli/nuxt-state-management/SKILL.md

@@ -0,0 +1,162 @@
+# Nuxt State Management
+
+> Share reactive state across components with SSR-safe useState and Pinia store hydration
+
+## When to Use
+
+- You need state that persists across navigation without re-fetching (user session, cart, theme)
+- You are seeing hydration mismatch errors caused by state divergence between server and client
+- You want to use Pinia stores in a Nuxt SSR context with proper server-to-client serialization
+- You need to share state between unrelated components without prop-drilling
+
+## Instructions
+
+**useState — built-in SSR-safe state:**
+
+1. Use `useState` instead of `ref` for any state that must be consistent between server and client renders. `useState` is keyed: the same key always returns the same reactive reference:
+
+```typescript
+// composables/useCounter.ts
+export const useCounter = () => useState<number>('counter', () => 0);
+```
+
+```html
+<!-- pages/index.vue -->
+<script setup>
+  const counter = useCounter();
+</script>
+<template>
+  <button @click="counter++">{{ counter }}</button>
+</template>
+```
+
+2. The second argument to `useState` is an initializer factory — it runs only once on the server and is never called again on the client (state is transferred via payload):
+
+```typescript
+const user = useState<User | null>('current-user', () => null);
+```
+
+3. Always provide a unique, descriptive key to avoid collisions across different composables:
+
+```typescript
+// Prefer namespaced keys for large apps
+const cartItems = useState<CartItem[]>('cart:items', () => []);
+const cartTotal = useState<number>('cart:total', () => 0);
+```
+
+4. Reset state on the server-per-request boundary using `clearNuxtState` — useful for user-specific data:
+
+```typescript
+// plugins/reset-state.ts
+export default defineNuxtPlugin(() => {
+  addRouteMiddleware(() => {
+    clearNuxtState(['cart:items', 'cart:total']);
+  });
+});
+```
+
+**Pinia — structured stores:**
+
+5. Install `@pinia/nuxt` and add it to `modules` in `nuxt.config.ts`:
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@pinia/nuxt'],
+});
+```
+
+6. Define stores using `defineStore` — they are auto-imported when placed in `stores/` (with `imports.dirs` configured):
+
+```typescript
+// stores/useAuthStore.ts
+export const useAuthStore = defineStore('auth', () => {
+  const user = ref<User | null>(null);
+  const isAuthenticated = computed(() => !!user.value);
+
+  async function login(credentials: Credentials) {
+    user.value = await $fetch('/api/auth/login', { method: 'POST', body: credentials });
+  }
+
+  function logout() {
+    user.value = null;
+  }
+
+  return { user, isAuthenticated, login, logout };
+});
+```
+
+7. Hydrate Pinia stores server-side using `useAsyncData` within the store or in the page:
+
+```typescript
+// Hydrate in page
+const authStore = useAuthStore();
+await useAsyncData('auth', () => authStore.fetchCurrentUser());
+```
+
+8. Use `pinia.state.value` in server plugins to initialize store state from server-side sources:
+
+```typescript
+// plugins/init-state.server.ts
+export default defineNuxtPlugin(async (nuxtApp) => {
+  const authStore = useAuthStore(nuxtApp.$pinia);
+  const sessionUser = await getSessionUser(useRequestEvent());
+  authStore.user = sessionUser;
+});
+```
+
+## Details
+
+**Why `ref` causes hydration mismatches:**
+
+A plain `ref` in a composable creates a new reactive instance per component call. During SSR, the server renders with its own instance; on the client, a fresh ref initializes to the default value — causing a mismatch. `useState` solves this by storing state in Nuxt's SSR payload and rehydrating from it on the client.
+
+**useState vs. Pinia:**
+
+| Concern                         | useState | Pinia          |
+| ------------------------------- | -------- | -------------- |
+| Simple scalar/object state      | Best fit | Overkill       |
+| Complex logic, actions, getters | Awkward  | Best fit       |
+| DevTools time-travel            | No       | Yes            |
+| Plugin ecosystem                | None     | Rich           |
+| SSR safety                      | Built-in | Requires setup |
+
+**Serialization requirements:**
+
+State transferred via the SSR payload must be JSON-serializable. Do not store class instances, functions, or circular references in `useState` or Pinia stores. Use plain objects and primitives.
+
+**Pinia store persistence (client-only):**
+
+Use `pinia-plugin-persistedstate` for localStorage sync. Mark it `client-only` to avoid SSR issues:
+
+```typescript
+// plugins/pinia-persist.client.ts
+import piniaPluginPersistedstate from 'pinia-plugin-persistedstate';
+export default defineNuxtPlugin(({ $pinia }) => {
+  $pinia.use(piniaPluginPersistedstate);
+});
+```
+
+**Avoiding state pollution between requests:**
+
+In SSR, all requests share the same module scope. Never use module-level `ref` or `reactive` for per-user state — it leaks between requests. Always use `useState` (keyed per request) or Pinia (reset via `$reset()` in server middleware).
+
+## Source
+
+https://nuxt.com/docs/getting-started/state-management
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/gemini-cli/nuxt-state-management/skill.yaml

@@ -0,0 +1,43 @@
+name: nuxt-state-management
+version: '1.0.0'
+description: Manage SSR-safe shared state with useState and Pinia in Nuxt applications
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - 'nuxt.config.*'
+  - '**/composables/**'
+  - '**/stores/**'
+  - '**/pages/**/*.vue'
+related_skills:
+  - nuxt-composables-pattern
+  - nuxt-auto-imports
+  - nuxt-plugins-pattern
+stack_signals:
+  - nuxt
+  - vue
+  - typescript
+  - pinia
+keywords:
+  - state-management
+  - useState
+  - pinia
+  - SSR
+  - hydration
+  - store
+  - shared-state
+metadata:
+  author: nuxt.com
+  upstream: 'nuxt.com/docs/getting-started/state-management'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/nuxt-testing-patterns/SKILL.md

@@ -0,0 +1,203 @@
+# Nuxt Testing Patterns
+
+> Test Nuxt components, composables, and pages using @nuxt/test-utils with full Nuxt context including auto-imports
+
+## When to Use
+
+- You are writing unit or integration tests for Nuxt components or pages that use Nuxt composables
+- You need to mock `useFetch`, `useRoute`, or other Nuxt auto-imports in tests
+- You are testing async components that use `<Suspense>` or `useAsyncData`
+- You need end-to-end tests against a running Nuxt server using Playwright
+
+## Instructions
+
+**Setup:**
+
+1. Install `@nuxt/test-utils` and configure Vitest with the Nuxt environment:
+
+```typescript
+// vitest.config.ts
+import { defineVitestConfig } from '@nuxt/test-utils/config';
+
+export default defineVitestConfig({
+  test: {
+    environment: 'nuxt',
+    environmentOptions: {
+      nuxt: {
+        rootDir: '.',
+      },
+    },
+  },
+});
+```
+
+**Mounting components:**
+
+2. Use `mountSuspended` instead of `mount` for components that use `useAsyncData`, `useFetch`, or other async composables. It wraps the component in `<Suspense>` and waits for resolution:
+
+```typescript
+import { mountSuspended } from '@nuxt/test-utils/runtime';
+import MyComponent from '~/components/MyComponent.vue';
+
+it('renders user data', async () => {
+  const wrapper = await mountSuspended(MyComponent, {
+    props: { userId: '123' },
+  });
+  expect(wrapper.text()).toContain('John Doe');
+});
+```
+
+3. Use `renderSuspended` for testing with `@testing-library/vue` patterns:
+
+```typescript
+import { renderSuspended } from '@nuxt/test-utils/runtime';
+import { screen } from '@testing-library/vue';
+
+it('shows the title', async () => {
+  await renderSuspended(MyPage);
+  expect(screen.getByRole('heading')).toHaveTextContent('Dashboard');
+});
+```
+
+**Mocking Nuxt composables:**
+
+4. Use `mockNuxtImport` to mock any auto-imported composable. Call it once at the top of the test file — it persists across the file:
+
+```typescript
+import { mockNuxtImport } from '@nuxt/test-utils/runtime';
+
+mockNuxtImport('useFetch', () => {
+  return () => ({
+    data: ref({ users: [{ id: 1, name: 'Alice' }] }),
+    error: ref(null),
+    pending: ref(false),
+  });
+});
+```
+
+5. Mock `useRoute` to simulate navigation params:
+
+```typescript
+mockNuxtImport('useRoute', () => {
+  return () => ({
+    params: { id: '42' },
+    query: { tab: 'settings' },
+    path: '/users/42',
+  });
+});
+```
+
+6. Use `vi.mocked` with `mockNuxtImport` for per-test overrides:
+
+```typescript
+const { useFetch } = vi.hoisted(() => ({ useFetch: vi.fn() }));
+
+mockNuxtImport('useFetch', () => useFetch);
+
+beforeEach(() => {
+  useFetch.mockReturnValue({
+    data: ref(null),
+    error: ref('Network error'),
+    pending: ref(false),
+  });
+});
+```
+
+**Testing server routes:**
+
+7. Use `$fetch` from `@nuxt/test-utils` to make real HTTP requests against a test Nuxt server:
+
+```typescript
+import { setup, $fetch } from '@nuxt/test-utils/e2e';
+
+describe('Server routes', async () => {
+  await setup({ rootDir: '.' });
+
+  it('returns users', async () => {
+    const users = await $fetch('/api/users');
+    expect(users).toHaveLength(3);
+  });
+});
+```
+
+**End-to-end testing with Playwright:**
+
+8. Configure Playwright E2E tests that boot a real Nuxt dev server:
+
+```typescript
+// tests/e2e/home.spec.ts
+import { setup, createPage, url } from '@nuxt/test-utils/e2e';
+import { test, expect } from '@playwright/test';
+
+await setup({ rootDir: '.', browser: true });
+
+test('home page loads', async () => {
+  const page = await createPage('/');
+  await expect(page.locator('h1')).toHaveText('Welcome');
+});
+```
+
+## Details
+
+**Why not use plain Vitest + @vue/test-utils?**
+
+Standard Vue Test Utils doesn't know about Nuxt's auto-import layer. Composables like `useNuxtApp`, `useFetch`, `useRoute` will throw "not in Nuxt context" errors. `@nuxt/test-utils` sets up a minimal Nuxt environment that makes auto-imports available in tests.
+
+**`mountSuspended` vs. `mount`:**
+
+- `mount` — synchronous, works for components with no async composables
+- `mountSuspended` — wraps in `<Suspense>`, awaits all `useAsyncData`/`useFetch` calls, returns after data is resolved
+
+Always prefer `mountSuspended` for page components or any component using `useAsyncData`.
+
+**Mocking modules vs. mocking composables:**
+
+`mockNuxtImport` mocks at the auto-import resolution layer. It's different from `vi.mock('~/composables/useMyThing')` — the latter only works for explicit imports. Use `mockNuxtImport` for anything that's auto-imported.
+
+**Test file organization:**
+
+```
+tests/
+  unit/
+    components/    ← mountSuspended tests
+    composables/   ← plain Vitest + vue's renderHook
+  integration/
+    server/        ← $fetch API tests
+  e2e/             ← Playwright tests
+```
+
+**Nuxt test environment options:**
+
+```typescript
+// vitest.config.ts
+environment: 'nuxt',
+environmentOptions: {
+  nuxt: {
+    rootDir: '.',
+    overrides: {
+      // Override nuxt.config.ts for tests
+      runtimeConfig: { public: { apiBase: 'http://localhost:3000' } }
+    }
+  }
+}
+```
+
+## Source
+
+https://nuxt.com/docs/getting-started/testing
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/gemini-cli/nuxt-testing-patterns/skill.yaml

@@ -0,0 +1,45 @@
+name: nuxt-testing-patterns
+version: '1.0.0'
+description: Test Nuxt components and pages using @nuxt/test-utils, mountSuspended, and mockNuxtImport
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - 'nuxt.config.*'
+  - '**/*.test.ts'
+  - '**/*.spec.ts'
+  - '**/tests/**'
+  - 'vitest.config.*'
+related_skills:
+  - nuxt-composables-pattern
+  - nuxt-auto-imports
+  - nuxt-server-routes
+stack_signals:
+  - nuxt
+  - vue
+  - typescript
+  - vitest
+keywords:
+  - testing
+  - nuxt-test-utils
+  - mountSuspended
+  - mockNuxtImport
+  - vitest
+  - E2E
+  - playwright
+  - unit-testing
+metadata:
+  author: nuxt.com
+  upstream: 'nuxt.com/docs/getting-started/testing'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/otel-context-propagation/SKILL.md

@@ -0,0 +1,152 @@
+# OpenTelemetry Context Propagation
+
+> Propagate trace context across service boundaries using W3C TraceContext headers and baggage
+
+## When to Use
+
+- Linking traces across microservices into a single distributed trace
+- Passing metadata (tenant ID, feature flags) across service boundaries without modifying APIs
+- Integrating services using different languages/frameworks into one trace view
+- Debugging why context is lost between services (broken traces)
+
+## Instructions
+
+1. Register propagators in the SDK setup. W3C TraceContext is the default and recommended standard.
+2. HTTP auto-instrumentation handles propagation automatically for most frameworks. Verify it works before adding manual propagation.
+3. For non-HTTP transports (queues, gRPC metadata, custom protocols), inject context into carrier objects manually.
+4. Use Baggage to pass key-value pairs across service boundaries (tenant ID, request priority).
+5. Ensure all services in the chain use the same propagation format (W3C, B3, or both via composite propagator).
+
+```typescript
+// SDK setup — configure propagators
+import { W3CTraceContextPropagator } from '@opentelemetry/core';
+import { W3CBaggagePropagator } from '@opentelemetry/core';
+import { CompositePropagator } from '@opentelemetry/core';
+
+const sdk = new NodeSDK({
+  textMapPropagator: new CompositePropagator({
+    propagators: [
+      new W3CTraceContextPropagator(), // traceparent + tracestate headers
+      new W3CBaggagePropagator(), // baggage header
+    ],
+  }),
+  // ... rest of config
+});
+```
+
+```typescript
+// Manual propagation for message queues
+import { context, propagation, trace } from '@opentelemetry/api';
+
+// Producer — inject context into message headers
+function publishMessage(queue: string, payload: object): void {
+  const headers: Record<string, string> = {};
+  propagation.inject(context.active(), headers);
+
+  messageQueue.publish(queue, {
+    body: payload,
+    headers, // Contains traceparent, tracestate, baggage
+  });
+}
+
+// Consumer — extract context from message headers
+async function consumeMessage(message: QueueMessage): Promise<void> {
+  const parentContext = propagation.extract(context.active(), message.headers);
+
+  const tracer = trace.getTracer('consumer');
+  await context.with(parentContext, async () => {
+    await tracer.startActiveSpan(
+      'process.message',
+      {
+        kind: SpanKind.CONSUMER,
+        attributes: { 'messaging.system': 'rabbitmq', 'messaging.destination': message.queue },
+      },
+      async (span) => {
+        try {
+          await processMessage(message.body);
+        } finally {
+          span.end();
+        }
+      }
+    );
+  });
+}
+```
+
+```typescript
+// Baggage — pass metadata across services
+import { propagation, context, BaggageEntry } from '@opentelemetry/api';
+
+// Set baggage in the upstream service
+function setTenantContext(tenantId: string) {
+  const baggage = propagation.createBaggage({
+    'tenant.id': { value: tenantId },
+    'request.priority': { value: 'high' },
+  });
+  return propagation.setBaggage(context.active(), baggage);
+}
+
+// Read baggage in the downstream service
+function getTenantId(): string | undefined {
+  const baggage = propagation.getBaggage(context.active());
+  return baggage?.getEntry('tenant.id')?.value;
+}
+```
+
+## Details
+
+**W3C TraceContext headers:**
+
+- `traceparent: 00-<traceId>-<spanId>-<flags>` — the core propagation header
+- `tracestate: vendor1=value1,vendor2=value2` — vendor-specific trace information
+- `baggage: tenant.id=abc,priority=high` — application-level key-value pairs
+
+**Auto-propagation:** The HTTP instrumentation automatically injects `traceparent` on outgoing requests and extracts it on incoming requests. You typically do NOT need manual propagation for HTTP.
+
+**When you need manual propagation:**
+
+- Message queues (RabbitMQ, Kafka, SQS)
+- gRPC metadata
+- WebSocket messages
+- Custom RPC protocols
+- Cron jobs that should link to the triggering request
+
+**B3 compatibility:** If some services use Zipkin B3 headers, add the B3 propagator:
+
+```typescript
+import { B3Propagator } from '@opentelemetry/propagator-b3';
+
+new CompositePropagator({
+  propagators: [
+    new W3CTraceContextPropagator(),
+    new B3Propagator(), // Also understands X-B3-TraceId headers
+  ],
+});
+```
+
+**Debugging broken traces:** If traces are disconnected across services:
+
+1. Check that both services use the same propagation format
+2. Verify the HTTP client is instrumented (auto-instrumentation must be loaded)
+3. Check for reverse proxies stripping `traceparent` headers
+4. For async operations, verify context is passed through `context.with()`
+
+## Source
+
+https://opentelemetry.io/docs/concepts/context-propagation/
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/gemini-cli/otel-context-propagation/skill.yaml

@@ -0,0 +1,39 @@
+name: otel-context-propagation
+version: '1.0.0'
+description: Propagate trace context across service boundaries with W3C TraceContext and baggage
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/instrumentation/**'
+  - '**/middleware/**'
+  - '**/telemetry/**'
+related_skills:
+  - otel-tracing-pattern
+  - otel-sdk-setup
+  - otel-custom-instrumentation
+stack_signals:
+  - opentelemetry
+  - nodejs
+  - typescript
+keywords:
+  - context-propagation
+  - W3C-TraceContext
+  - traceparent
+  - baggage
+  - cross-service
+metadata:
+  author: community
+  upstream: 'opentelemetry/docs/context-propagation'
+state:
+  persistent: false
+  files: []
+depends_on: []