@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/claude-code/next-data-fetching/skill.yaml

@@ -0,0 +1,44 @@
+name: next-data-fetching
+version: "1.0.0"
+description: Server-side data patterns, avoiding waterfalls, sequential vs parallel fetching
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "next.config.*"
+  - "**/app/**/*.tsx"
+  - "**/app/**/*.ts"
+  - "**/pages/**/*.tsx"
+related_skills:
+  - next-server-components
+  - next-caching-strategies
+  - next-streaming-suspense
+  - tanstack-prefetching
+  - tanstack-dependent-queries
+stack_signals:
+  - nextjs
+  - react
+  - typescript
+keywords:
+  - data-fetching
+  - waterfall
+  - parallel-fetch
+  - Promise.all
+  - server-component
+  - async-component
+  - request-deduplication
+metadata:
+  author: community
+  upstream: https://nextjs.org/docs/app/building-your-application/data-fetching/fetching
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/next-deployment-optimization/SKILL.md

@@ -0,0 +1,92 @@
+# Next.js Deployment Optimization
+
+> Reduce bundle size, split code strategically, and optimize runtime performance for production
+
+## When to Use
+
+- Reducing JavaScript bundle size to improve Time to Interactive (TTI)
+- Lazy loading heavy components (rich text editors, chart libraries, maps) that are not needed on first paint
+- Analyzing which modules contribute most to bundle size
+- Optimizing for Vercel, Docker, or self-hosted deployments
+- Reducing cold start times for serverless functions
+
+## Instructions
+
+1. Run `ANALYZE=true next build` with `@next/bundle-analyzer` to identify large modules in the bundle.
+2. Use `next/dynamic` to lazy load Client Components that are not needed for initial render.
+3. Pass `{ ssr: false }` to `next/dynamic` for components that use browser-only APIs (`window`, `document`, `navigator`).
+4. Use `import()` directly inside Server Components for code splitting without `next/dynamic`.
+5. Move large libraries (PDF generators, Excel parsers, video processors) to Route Handlers or Server Actions to keep them off the client bundle entirely.
+6. Set `experimental.optimizePackageImports` in `next.config.ts` for icon and component libraries to tree-shake unused exports.
+7. Use `next/font` to self-host fonts with zero layout shift — fonts are downloaded at build time.
+8. Enable compression and set proper cache headers in your deployment infrastructure for static assets.
+
+```typescript
+// next.config.ts — bundle analyzer and package optimization
+import type { NextConfig } from 'next';
+import bundleAnalyzer from '@next/bundle-analyzer';
+
+const withBundleAnalyzer = bundleAnalyzer({
+  enabled: process.env.ANALYZE === 'true',
+});
+
+const config: NextConfig = {
+  experimental: {
+    optimizePackageImports: ['lucide-react', '@radix-ui/react-icons', 'date-fns'],
+  },
+};
+
+export default withBundleAnalyzer(config);
+
+// app/editor/page.tsx — lazy load heavy Client Component
+import dynamic from 'next/dynamic';
+
+const RichTextEditor = dynamic(() => import('@/components/rich-text-editor'), {
+  loading: () => <p>Loading editor...</p>,
+  ssr: false, // editor uses window APIs
+});
+
+export default function EditorPage() {
+  return <RichTextEditor />;
+}
+
+// app/fonts.ts — self-hosted fonts
+import { Inter, Fira_Code } from 'next/font/google';
+
+export const inter = Inter({ subsets: ['latin'], variable: '--font-inter' });
+export const firaCode = Fira_Code({ subsets: ['latin'], variable: '--font-fira-code' });
+```
+
+## Details
+
+Next.js performs automatic code splitting at the route level — each page only loads its own JavaScript. Additional optimization opportunities exist at the component and library level.
+
+**Bundle analyzer workflow:** Install `@next/bundle-analyzer`, add it to `next.config.ts`, run `ANALYZE=true next build`. Two treemaps open (client and server bundles). Look for unexpectedly large modules, duplicated libraries (two versions of the same package), and server-only code in the client bundle.
+
+**`next/dynamic` vs React.lazy:** `next/dynamic` wraps `React.lazy` and adds Next.js-specific features: `ssr: false`, loading components, and named export support. Use `next/dynamic` in Next.js projects — `React.lazy` works too but lacks these features.
+
+**`ssr: false` use cases:** Components that import browser APIs at module level (not just in event handlers) must use `ssr: false`. Common examples: maps (Leaflet, Mapbox), rich text editors (Quill, TipTap), WebGL renderers.
+
+**`optimizePackageImports`:** Icon libraries like `lucide-react` export hundreds of icons. Without tree-shaking, importing one icon pulls in the entire library. `optimizePackageImports` tells Next.js to rewrite imports to their direct module paths, enabling tree-shaking.
+
+**Standalone output:** For Docker deployments, set `output: 'standalone'` in `next.config.ts`. This produces a minimal build artifact with only the production dependencies needed, significantly reducing Docker image size.
+
+## Source
+
+https://nextjs.org/docs/app/building-your-application/optimizing
+
+## 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/claude-code/next-deployment-optimization/skill.yaml

@@ -0,0 +1,42 @@
+name: next-deployment-optimization
+version: "1.0.0"
+description: Bundle analysis, code splitting, dynamic imports, and next/dynamic optimization
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "next.config.*"
+  - "**/app/**/*.tsx"
+  - "**/pages/**/*.tsx"
+related_skills:
+  - next-static-generation
+  - next-image-optimization
+  - next-environment-config
+  - next-app-router
+stack_signals:
+  - nextjs
+  - react
+  - typescript
+keywords:
+  - bundle-analysis
+  - code-splitting
+  - dynamic-import
+  - next-dynamic
+  - tree-shaking
+  - lazy-loading
+  - performance
+metadata:
+  author: community
+  upstream: https://nextjs.org/docs/app/building-your-application/optimizing
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/next-environment-config/SKILL.md

@@ -0,0 +1,92 @@
+# Next.js Environment Configuration
+
+> Manage environment variables, runtime config, and server-only module boundaries safely
+
+## When to Use
+
+- Configuring API keys, database URLs, and secrets for server-side code
+- Exposing safe configuration values to the browser via `NEXT_PUBLIC_` prefix
+- Validating environment variables at build time to catch misconfiguration early
+- Preventing server-only secrets from leaking into the client bundle
+- Configuring different behavior for development, staging, and production environments
+
+## Instructions
+
+1. Prefix environment variables with `NEXT_PUBLIC_` to expose them to the browser — all other variables are server-only.
+2. Never put secrets (API keys, database URLs, private keys) in `NEXT_PUBLIC_` variables — they are inlined into the client bundle.
+3. Use `t3-env` or `@t3-oss/env-nextjs` to validate environment variables at build time with Zod schemas.
+4. Create `src/env.ts` (or `lib/env.ts`) as the single source of truth for env var access — import env values from here, never from `process.env` directly in components.
+5. Add `import 'server-only'` to any module that accesses server-only env vars to prevent accidental client import.
+6. Use `.env.local` for local development secrets — it is gitignored by default. Use `.env.development` and `.env.production` for non-secret environment-specific values.
+7. Wrap `next.config.ts` with your env validation so the build fails immediately on missing required variables.
+8. Access runtime environment variables in `next.config.ts` via `process.env` — variables set in hosting dashboards (Vercel, Railway) are available at runtime.
+
+```typescript
+// src/env.ts — validated env with t3-env
+import { createEnv } from '@t3-oss/env-nextjs';
+import { z } from 'zod';
+
+export const env = createEnv({
+  server: {
+    DATABASE_URL: z.string().url(),
+    NEXTAUTH_SECRET: z.string().min(32),
+    STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
+  },
+  client: {
+    NEXT_PUBLIC_APP_URL: z.string().url(),
+    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: z.string().startsWith('pk_'),
+  },
+  runtimeEnv: {
+    DATABASE_URL: process.env.DATABASE_URL,
+    NEXTAUTH_SECRET: process.env.NEXTAUTH_SECRET,
+    STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,
+    NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
+    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
+  },
+});
+
+// lib/db.ts — import 'server-only' prevents client bundle inclusion
+import 'server-only';
+import { env } from '@/env';
+import { drizzle } from 'drizzle-orm/postgres-js';
+import postgres from 'postgres';
+
+const client = postgres(env.DATABASE_URL);
+export const db = drizzle(client);
+```
+
+## Details
+
+Next.js treats environment variables differently depending on when and where they are accessed:
+
+**Build-time inlining:** `NEXT_PUBLIC_` variables are replaced with their literal values at build time (`process.env.NEXT_PUBLIC_API_URL` becomes `"https://api.example.com"` in the bundle). This means the value is fixed at build time and cannot change at runtime without rebuilding.
+
+**Server-only variables:** Variables without `NEXT_PUBLIC_` are only available in Server Components, Route Handlers, and other server-side code. Accessing them in a Client Component returns `undefined` and does not leak the value — it simply does not work.
+
+**`.env` file priority:** Next.js loads `.env`, `.env.local`, `.env.development`/`.env.production`, and `.env.development.local`/`.env.production.local`. More specific files override less specific ones. `.local` files take highest priority and should be in `.gitignore`.
+
+**Runtime vs build-time:** Variables set in the Vercel dashboard are available at runtime in server-side code. However, `NEXT_PUBLIC_` variables must be set at build time in Vercel — setting them in the dashboard alone requires a rebuild.
+
+**t3-env benefits:** Without validation, a missing `DATABASE_URL` crashes the app at the first database query — potentially after deployment. `t3-env` fails the build or server startup immediately with a clear error listing every missing or invalid variable.
+
+**`server-only` package:** `import 'server-only'` causes a build error if the module is imported in a Client Component. Use it in any module that accesses secrets, database clients, or other server-only resources. Pair with `client-only` for the inverse — marking browser-only modules.
+
+## Source
+
+https://nextjs.org/docs/app/building-your-application/configuring/environment-variables
+
+## 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/claude-code/next-environment-config/skill.yaml

@@ -0,0 +1,43 @@
+name: next-environment-config
+version: "1.0.0"
+description: Environment variables, next.config.ts, and server-only module boundaries
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "next.config.*"
+  - ".env*"
+  - "**/env.ts"
+  - "**/env.mjs"
+related_skills:
+  - next-app-router
+  - next-server-components
+  - next-deployment-optimization
+  - ts-utility-types
+stack_signals:
+  - nextjs
+  - react
+  - typescript
+keywords:
+  - environment-variables
+  - NEXT_PUBLIC
+  - server-only
+  - next.config
+  - env-validation
+  - t3-env
+  - runtime-config
+metadata:
+  author: community
+  upstream: https://nextjs.org/docs/app/building-your-application/configuring/environment-variables
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/next-error-boundaries/SKILL.md

@@ -0,0 +1,96 @@
+# Next.js Error Boundaries
+
+> Handle runtime errors and missing routes gracefully with error.tsx and not-found.tsx
+
+## When to Use
+
+- Displaying a user-friendly error UI when a route segment throws during rendering or data fetching
+- Providing a recovery mechanism (retry button) without reloading the entire page
+- Customizing the 404 page for missing routes or resources
+- Isolating errors so one failing segment does not crash the entire application
+- Handling global uncaught errors at the root layout level
+
+## Instructions
+
+1. Create `error.tsx` in a route segment directory to catch errors thrown by that segment's `page.tsx` or its Server Components.
+2. Mark `error.tsx` as a Client Component with `'use client'` — error boundaries must be Client Components.
+3. Accept `error: Error & { digest?: string }` and `reset: () => void` props — `digest` is a server-side error ID for log correlation; `reset` re-renders the segment.
+4. Create `global-error.tsx` in `app/` to catch errors from the root layout — it replaces the entire layout including `<html>` and `<body>`, so include them.
+5. Call `notFound()` from `next/navigation` inside any Server Component to trigger the nearest `not-found.tsx`.
+6. Create `not-found.tsx` in `app/` for a global 404 page, or in any route segment for segment-specific 404s.
+7. Nest `error.tsx` closer to the throwing component to limit the error UI scope — a top-level `error.tsx` catches all descendant errors but shows a large recovery region.
+8. Log the `error.digest` to your error monitoring service (Sentry, Datadog) to correlate client-visible errors with server logs.
+
+```typescript
+// app/dashboard/error.tsx — segment error boundary
+'use client';
+
+export default function DashboardError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  return (
+    <div role="alert">
+      <h2>Something went wrong loading the dashboard</h2>
+      <p className="text-sm text-gray-500">Error ID: {error.digest}</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+
+// app/posts/[slug]/not-found.tsx — segment-specific 404
+export default function PostNotFound() {
+  return (
+    <div>
+      <h1>Post not found</h1>
+      <p>The post you are looking for does not exist or has been removed.</p>
+    </div>
+  );
+}
+
+// app/posts/[slug]/page.tsx — triggering not-found
+import { notFound } from 'next/navigation';
+
+export default async function PostPage({ params }: { params: { slug: string } }) {
+  const post = await fetchPost(params.slug);
+  if (!post) notFound(); // triggers not-found.tsx
+  return <article>{post.content}</article>;
+}
+```
+
+## Details
+
+Next.js automatically wraps each route segment in a React error boundary when `error.tsx` exists. The error boundary catches errors thrown during rendering, in event handlers, or in asynchronous data fetching within that segment.
+
+**Error propagation:** Errors bubble up through React's component tree until they reach an error boundary. Without `error.tsx`, unhandled errors propagate to the root and show the default Next.js error page (development) or a blank white screen (production).
+
+**`reset()` function:** Calling `reset()` attempts to re-render the content within the error boundary. If the underlying error was transient (e.g., a network blip), the reset succeeds. If the error persists, the error boundary catches it again. Combine with a retry counter to avoid infinite loops.
+
+**`global-error.tsx` vs `error.tsx`:** `error.tsx` in `app/` catches errors from the root page but not from the root layout. `global-error.tsx` catches errors from the root layout itself (e.g., a broken navigation component). `global-error.tsx` must render `<html>` and `<body>` because it replaces the entire document.
+
+**Server vs client error messages:** In production, error messages thrown on the server are not forwarded to the client to avoid leaking sensitive details. Only the `digest` ID is passed. In development, full error details are shown. This asymmetry is intentional — use the digest to look up errors in server logs.
+
+**not-found.tsx placement:** A `not-found.tsx` in a segment catches `notFound()` calls from that segment only. A `not-found.tsx` in `app/` serves as the global 404 fallback for all routes.
+
+## Source
+
+https://nextjs.org/docs/app/building-your-application/routing/error-handling
+
+## 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/claude-code/next-error-boundaries/skill.yaml

@@ -0,0 +1,44 @@
+name: next-error-boundaries
+version: "1.0.0"
+description: error.tsx, global-error.tsx, not-found.tsx, and error recovery patterns
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "next.config.*"
+  - "**/app/**/error.tsx"
+  - "**/app/**/not-found.tsx"
+  - "**/app/**/global-error.tsx"
+  - "**/app/**/*.tsx"
+related_skills:
+  - next-app-router
+  - next-streaming-suspense
+  - next-data-fetching
+  - react-hooks-pattern
+stack_signals:
+  - nextjs
+  - react
+  - typescript
+keywords:
+  - error-boundary
+  - error.tsx
+  - not-found.tsx
+  - global-error
+  - reset
+  - "404"
+  - error-recovery
+metadata:
+  author: community
+  upstream: https://nextjs.org/docs/app/building-your-application/routing/error-handling
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/next-image-optimization/SKILL.md

@@ -0,0 +1,91 @@
+# Next.js Image Optimization
+
+> Serve optimized, correctly sized images automatically with next/image
+
+## When to Use
+
+- Displaying images in any Next.js page or component
+- Improving Core Web Vitals (LCP, CLS) by preventing layout shift and lazy loading images
+- Serving modern formats (WebP, AVIF) without manual conversion
+- Building responsive images that adapt to viewport and container size
+- Loading above-the-fold images with priority to improve LCP score
+
+## Instructions
+
+1. Import `Image` from `next/image` instead of the HTML `<img>` tag for all content images.
+2. Always provide `width` and `height` props for images with known dimensions to prevent layout shift (CLS).
+3. Use `fill` prop with a positioned parent (`position: relative`) for images that should fill their container — omit `width` and `height` when using `fill`.
+4. Add `priority` to the first image visible in the viewport (the LCP element) to disable lazy loading and preload it.
+5. Use the `sizes` prop to tell the browser how wide the image will be at each breakpoint — this enables accurate `srcset` selection.
+6. Add remote domains to `images.remotePatterns` in `next.config.ts` before using external image URLs.
+7. Use `placeholder="blur"` with `blurDataURL` for a low-quality preview while the image loads.
+8. For static imports, Next.js generates `blurDataURL` automatically — `import logo from './logo.png'` and pass the imported object.
+
+```typescript
+// next.config.ts
+const config = {
+  images: {
+    remotePatterns: [
+      { protocol: 'https', hostname: 'cdn.example.com', pathname: '/images/**' },
+    ],
+  },
+};
+
+// app/products/[id]/page.tsx
+import Image from 'next/image';
+import heroImage from '@/public/hero.jpg'; // static import — dimensions known
+
+export default function ProductPage() {
+  return (
+    <div>
+      {/* Static import — auto blur placeholder, auto width/height */}
+      <Image src={heroImage} alt="Hero" priority placeholder="blur" />
+
+      {/* Remote image — fill mode for responsive container */}
+      <div className="relative h-64 w-full">
+        <Image
+          src="https://cdn.example.com/images/product.jpg"
+          alt="Product"
+          fill
+          sizes="(max-width: 768px) 100vw, 50vw"
+          className="object-cover"
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+## Details
+
+`next/image` wraps the HTML `<img>` element with automatic size optimization, format conversion, and lazy loading. The optimization pipeline runs server-side: Next.js resizes and converts images to WebP or AVIF on first request and caches the result.
+
+**`sizes` attribute importance:** Without `sizes`, the browser assumes the image is `100vw` wide and downloads a larger source than necessary. Providing accurate `sizes` (e.g., `"(max-width: 640px) 100vw, 640px"`) reduces bandwidth significantly.
+
+**fill mode:** Use `fill` when the image dimensions are unknown or when the image should fill a CSS-controlled container. The parent must have `position: relative` (or `absolute`/`fixed`). Use `className="object-cover"` or `className="object-contain"` on the Image to control aspect ratio.
+
+**priority vs lazy:** All images are lazy-loaded by default (loaded when they enter the viewport). The `priority` prop disables lazy loading and adds a `<link rel="preload">` — use it for the LCP image only. Adding `priority` to multiple images defeats its purpose.
+
+**Layout shift (CLS):** Providing `width` and `height` lets the browser reserve space before the image loads, preventing layout shift. The `fill` prop avoids this by letting CSS control the container dimensions.
+
+**Remote patterns:** The `remotePatterns` config (replacing the deprecated `domains`) supports wildcards and pathnames. Misconfigured patterns cause 400 errors on image optimization requests.
+
+## Source
+
+https://nextjs.org/docs/app/api-reference/components/image
+
+## 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/claude-code/next-image-optimization/skill.yaml

@@ -0,0 +1,41 @@
+name: next-image-optimization
+version: "1.0.0"
+description: next/image component, responsive images, priority loading, and sizes configuration
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "next.config.*"
+  - "**/app/**/*.tsx"
+  - "**/pages/**/*.tsx"
+related_skills:
+  - next-app-router
+  - next-deployment-optimization
+  - next-static-generation
+stack_signals:
+  - nextjs
+  - react
+  - typescript
+keywords:
+  - next-image
+  - image-optimization
+  - responsive-images
+  - priority
+  - sizes
+  - blur-placeholder
+  - LCP
+metadata:
+  author: community
+  upstream: https://nextjs.org/docs/app/api-reference/components/image
+state:
+  persistent: false
+  files: []
+depends_on: []