@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/gemini-cli/astro-integration-pattern/SKILL.md

@@ -0,0 +1,164 @@
+# Astro Integration Pattern
+
+> Build or consume Astro integrations to extend the build pipeline — add renderers, inject routes, modify Vite config, and hook into build lifecycle events.
+
+## When to Use
+
+- You are adding an official Astro integration (`@astrojs/react`, `@astrojs/tailwind`, `@astrojs/sitemap`) to a project
+- You are writing a custom integration to encapsulate shared configuration across multiple Astro projects
+- You need to inject a virtual route, a client-side script, or an additional Vite plugin
+- You are authoring a third-party integration for the Astro ecosystem
+- You want to understand what an integration's hooks are doing to debug build issues
+
+## Instructions
+
+1. Add official integrations in `astro.config.mjs` using the `integrations` array. Call each integration as a function:
+
+```javascript
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import react from '@astrojs/react';
+import tailwind from '@astrojs/tailwind';
+import sitemap from '@astrojs/sitemap';
+
+export default defineConfig({
+  site: 'https://example.com',
+  integrations: [react(), tailwind({ applyBaseStyles: false }), sitemap()],
+});
+```
+
+2. Create a custom integration as a plain function that returns an object with a `name` and `hooks`:
+
+```typescript
+// my-integration.ts
+import type { AstroIntegration } from 'astro';
+
+export function myIntegration(options: { debug?: boolean } = {}): AstroIntegration {
+  return {
+    name: 'my-integration',
+    hooks: {
+      'astro:config:setup': ({ updateConfig, injectRoute, injectScript, addWatchFile, logger }) => {
+        // Modify Vite config
+        updateConfig({
+          vite: {
+            plugins: [myVitePlugin()],
+            define: { __DEBUG__: options.debug ?? false },
+          },
+        });
+
+        // Inject a virtual route
+        injectRoute({
+          pattern: '/my-integration-page',
+          entrypoint: './src/my-integration/page.astro',
+        });
+
+        // Inject a script on every page
+        injectScript('page', `console.log('Integration active');`);
+
+        logger.info('My integration configured');
+      },
+
+      'astro:build:done': ({ dir, routes, logger }) => {
+        logger.info(`Build complete. ${routes.length} routes generated.`);
+      },
+    },
+  };
+}
+```
+
+3. Use the correct hook for each type of work:
+
+| Hook                 | When it runs                                | Common uses                                                  |
+| -------------------- | ------------------------------------------- | ------------------------------------------------------------ |
+| `astro:config:setup` | Before build starts                         | `updateConfig`, `injectRoute`, `injectScript`, `addRenderer` |
+| `astro:config:done`  | After all integrations have modified config | Read the final resolved config                               |
+| `astro:server:setup` | Dev server created                          | Add Vite dev server middleware                               |
+| `astro:server:start` | Dev server listening                        | Log the dev URL                                              |
+| `astro:build:start`  | Build starts                                | Initialize build-time resources                              |
+| `astro:build:done`   | All pages/assets generated                  | Post-process output files, generate sitemaps                 |
+
+4. Add a custom renderer (for a new UI framework) with `addRenderer()` inside `astro:config:setup`:
+
+```typescript
+'astro:config:setup': ({ addRenderer }) => {
+  addRenderer({
+    name: 'my-framework',
+    serverEntrypoint: 'my-framework/server.js',
+    clientEntrypoint: 'my-framework/client.js',
+    jsxImportSource: 'my-framework',
+    jsxTransformOptions: async () => ({
+      plugins: [['@babel/plugin-transform-react-jsx', { runtime: 'automatic' }]],
+    }),
+  });
+}
+```
+
+5. Use `addWatchFile()` to trigger HMR when config files outside the project root change:
+
+```typescript
+'astro:config:setup': ({ addWatchFile, config }) => {
+  addWatchFile(new URL('./my-config.json', config.root));
+}
+```
+
+6. Read the user's final resolved Astro config in `astro:config:done` — this is after all integrations have run and the config is finalized:
+
+```typescript
+'astro:config:done': ({ config }) => {
+  if (config.output === 'static') {
+    // perform SSG-specific setup
+  }
+}
+```
+
+7. Export your integration alongside `defineConfig` in `astro.config.mjs` for colocation, or publish it as a separate npm package following the `astro-*` naming convention.
+
+## Details
+
+Astro integrations are the official extensibility mechanism. They are synchronous or async functions that hook into well-defined lifecycle points in the Astro build pipeline. Unlike Vite plugins (which are lower-level), Astro integrations have access to Astro-specific primitives like `injectRoute`, `addRenderer`, and the Astro config object.
+
+**Integration execution order:**
+
+Integrations are executed in the order they appear in the `integrations` array. Hook calls within each lifecycle event are also ordered. This matters when integrations modify shared config (e.g., Vite plugins) — later integrations see the changes made by earlier ones.
+
+**`updateConfig` merging:**
+
+`updateConfig()` does a deep merge with the existing config. Call it multiple times if needed — each call merges on top of the previous state. Be careful with arrays (like `vite.plugins`) — they are concatenated, not replaced.
+
+**`injectRoute` and virtual modules:**
+
+`injectRoute` adds a route to the Astro router backed by an actual file. For truly virtual content (generated at build time), pair it with a Vite virtual module plugin to serve the file from memory.
+
+**Integration API stability:**
+
+The `astro:config:setup` and `astro:build:done` hooks are stable. Hooks prefixed with `astro:server:*` are available only in development. The full hooks API is documented in the Astro Integrations Reference.
+
+**Official integration patterns to study:**
+
+- `@astrojs/sitemap` — minimal integration that generates files in `astro:build:done`
+- `@astrojs/tailwind` — adds a Vite plugin via `updateConfig`
+- `@astrojs/react` — uses `addRenderer` plus `updateConfig` for JSX transform
+
+**Publishing guidelines:**
+
+Name your package `astro-<feature>`. Add `astro` and `astro-component` to `keywords` in `package.json`. Export the integration as the default export. Add `"astro"` to `peerDependencies`.
+
+## Source
+
+https://docs.astro.build/en/reference/integrations-reference
+
+## 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/astro-integration-pattern/skill.yaml

@@ -0,0 +1,45 @@
+name: astro-integration-pattern
+version: '1.0.0'
+description: Add official and custom Astro integrations using hooks, the integration API, and addRenderer
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - 'astro.config.*'
+  - '**/*.astro'
+  - '**/src/pages/**'
+  - '**/src/content/**'
+related_skills:
+  - astro-multi-framework
+  - astro-deployment-config
+  - astro-ssr-hybrid
+stack_signals:
+  - astro
+  - typescript
+keywords:
+  - astro-integration
+  - integration-hooks
+  - astro:config:setup
+  - astro:build:done
+  - addRenderer
+  - injectRoute
+  - injectScript
+  - updateConfig
+  - official-integrations
+  - custom-integration
+metadata:
+  author: docs.astro.build
+  upstream: 'docs.astro.build/en/reference/integrations-reference'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/astro-islands-architecture/SKILL.md

@@ -0,0 +1,103 @@
+# Astro Islands Architecture
+
+> Ship zero JavaScript by default — hydrate only the interactive components that need it, exactly when they need it.
+
+## When to Use
+
+- You are building a page that mixes static content with interactive UI components
+- You need to choose the right `client:*` directive for a framework component (React, Vue, Svelte, Solid, Preact)
+- A page is shipping more JavaScript than necessary and you want to audit hydration
+- You are deciding whether a component should be a static `.astro` component or a hydrated island
+- You want to defer expensive component hydration until the user actually needs it
+
+## Instructions
+
+1. Default to `.astro` components for all non-interactive UI. They render to pure HTML with zero JS shipped to the browser.
+
+2. Use framework components (React, Vue, Svelte, etc.) only when client-side interactivity is required (event handlers, stateful UI, browser APIs).
+
+3. Apply a `client:*` directive to every framework component that must hydrate. Without a directive, the component renders as static HTML only.
+
+4. Choose the directive that matches when the component becomes interactive:
+   - `client:load` — hydrate immediately on page load. Use for above-the-fold critical UI (navigation menus, login forms).
+   - `client:idle` — hydrate after the browser's `requestIdleCallback`. Use for non-critical interactive widgets.
+   - `client:visible` — hydrate when the component scrolls into the viewport (Intersection Observer). Use for below-the-fold content, carousels, comment sections.
+   - `client:media="(max-width: 768px)"` — hydrate only when a CSS media query matches. Use for mobile-only components.
+   - `client:only="react"` — skip SSR entirely, render and hydrate on the client only. Use for components that depend on browser-only APIs (`window`, `localStorage`, WebGL).
+
+5. Never use `client:load` as a default for all interactive components. Prefer `client:idle` or `client:visible` whenever the component is not immediately visible.
+
+6. Pass data into islands via props. Islands are isolated — they do not share state automatically.
+
+```astro
+---
+// src/pages/index.astro
+import StaticHeader from '../components/StaticHeader.astro';
+import Counter from '../components/Counter.jsx';
+import HeavyChart from '../components/HeavyChart.jsx';
+import MobileMenu from '../components/MobileMenu.jsx';
+---
+
+<!-- Zero JS: pure static HTML -->
+<StaticHeader />
+
+<!-- Critical interactive: hydrate immediately -->
+<Counter client:load initialCount={0} />
+
+<!-- Below the fold: hydrate when visible -->
+<HeavyChart client:visible data={chartData} />
+
+<!-- Mobile only: skip on desktop entirely -->
+<MobileMenu client:media="(max-width: 768px)" />
+```
+
+7. Audit your islands by running the build and inspecting the `dist/` output. Each `client:*` directive produces a separate JS chunk. Large chunks indicate over-hydration.
+
+8. Use `transition:persist` from the View Transitions API to keep an island alive across page navigations — avoiding a re-hydration cost.
+
+## Details
+
+Islands Architecture was coined by Katie Sylor-Miller and popularized by Jason Miller. The central idea: treat the page as a sea of static HTML with interactive "islands" embedded within it. Each island is an independently hydrated component — its JavaScript is fetched and executed only for that component, not for the whole page.
+
+**Why this matters:** A traditional SPA ships a full JavaScript bundle and hydrates the entire page. Astro's island approach means a content-heavy page (blog post, marketing landing page, documentation) ships zero JavaScript unless you explicitly add `client:*` to a component. This dramatically improves Time to Interactive (TTI) and Largest Contentful Paint (LCP).
+
+**How hydration works under the hood:**
+
+Astro serializes the component's props into the HTML at build time. When the browser loads the page, Astro's tiny runtime reads the directive, waits for the right moment (load, idle, visible, media match), then dynamically imports the component's framework bundle and hydrates it with the serialized props. Each island is fully independent.
+
+**Trade-offs:**
+
+- Islands cannot directly share React state with each other. Cross-island state requires nanostores or a shared URL/storage mechanism.
+- `client:only` components are invisible to SEO crawlers and do not SSR. Use with care for content that should be indexed.
+- `client:visible` adds an Intersection Observer per island — negligible cost, but be aware on pages with hundreds of islands.
+- Passing non-serializable props (class instances, functions, symbols) to islands will fail. Props must be plain JSON-serializable values.
+
+**Island communication patterns:**
+
+- Use nanostores (`@nanostores/react`, `@nanostores/vue`, etc.) for shared reactive state across islands.
+- Use custom events (`window.dispatchEvent` / `window.addEventListener`) for lightweight cross-island messaging.
+- Use URL search params or `localStorage` for state that must survive navigation.
+
+**Partial hydration vs. progressive enhancement:**
+
+Islands Architecture is a form of partial hydration — you hydrate parts of the page, not all of it. This differs from progressive enhancement, which starts with fully functional HTML and layers JS on top. In practice, combine both: your `.astro` components are always progressive-enhancement-friendly, and your islands add richer interactivity.
+
+## Source
+
+https://docs.astro.build/en/concepts/islands
+
+## 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/astro-islands-architecture/skill.yaml

@@ -0,0 +1,45 @@
+name: astro-islands-architecture
+version: '1.0.0'
+description: Apply Islands Architecture with client directives and partial hydration to ship minimal JavaScript
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - 'astro.config.*'
+  - '**/*.astro'
+  - '**/src/pages/**'
+  - '**/src/content/**'
+related_skills:
+  - astro-component-pattern
+  - astro-multi-framework
+  - react-hooks-pattern
+stack_signals:
+  - astro
+  - typescript
+keywords:
+  - islands
+  - partial-hydration
+  - client-directives
+  - client-load
+  - client-idle
+  - client-visible
+  - client-media
+  - client-only
+  - zero-js
+  - interactive-components
+metadata:
+  author: docs.astro.build
+  upstream: 'docs.astro.build/en/guides/client-side-scripts'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/astro-multi-framework/SKILL.md

@@ -0,0 +1,161 @@
+# Astro Multi-Framework
+
+> Run React, Vue, Svelte, Solid, and Preact side-by-side in one Astro project with full framework isolation and shared reactive state via nanostores.
+
+## When to Use
+
+- You are migrating from one framework to another and want to run both during the transition period
+- Your team has component libraries in multiple frameworks and you want to compose them in one site
+- You need a specialized component (a React data-grid, a Vue date-picker) alongside your primary framework
+- You want to share state between framework components on the same page without a global store library tied to one framework
+- You are evaluating different frameworks for different sections of a large site
+
+## Instructions
+
+1. Install the official integration for each framework you need. Each integration adds the renderer and Vite transform:
+
+```bash
+npx astro add react vue svelte solid
+```
+
+This updates `astro.config.mjs` automatically:
+
+```javascript
+import { defineConfig } from 'astro/config';
+import react from '@astrojs/react';
+import vue from '@astrojs/vue';
+import svelte from '@astrojs/svelte';
+import solid from '@astrojs/solid-js';
+
+export default defineConfig({
+  integrations: [react(), vue(), svelte(), solid()],
+});
+```
+
+2. Import and use components from any framework in a `.astro` file. Apply `client:*` directives as normal:
+
+```astro
+---
+import ReactCounter from './ReactCounter.jsx';
+import VueDatePicker from './VueDatePicker.vue';
+import SvelteModal from './SvelteModal.svelte';
+---
+
+<!-- Each island hydrates independently -->
+<ReactCounter client:load initialCount={0} />
+<VueDatePicker client:idle />
+<SvelteModal client:visible triggerText="Open" />
+```
+
+3. Framework components are fully isolated. A React component cannot import a Vue component directly. Cross-framework composition must happen at the `.astro` level — use `.astro` as the orchestration layer.
+
+4. Share reactive state between framework components using nanostores. Install framework-specific adapters:
+
+```bash
+npm install nanostores @nanostores/react @nanostores/vue
+```
+
+```typescript
+// src/stores/cart.ts
+import { atom, computed } from 'nanostores';
+
+export const cartItems = atom<CartItem[]>([]);
+export const cartCount = computed(cartItems, (items) => items.length);
+
+export function addToCart(item: CartItem) {
+  cartItems.set([...cartItems.get(), item]);
+}
+```
+
+5. Use the framework-specific adapter to read and subscribe to nanostores in each component:
+
+```jsx
+// React: src/components/CartBadge.jsx
+import { useStore } from '@nanostores/react';
+import { cartCount } from '../stores/cart';
+
+export function CartBadge() {
+  const count = useStore(cartCount);
+  return <span className="badge">{count}</span>;
+}
+```
+
+```vue
+<!-- Vue: src/components/CartBadge.vue -->
+<script setup>
+import { useStore } from '@nanostores/vue';
+import { cartCount } from '../stores/cart';
+const count = useStore(cartCount);
+</script>
+<template>
+  <span class="badge">{{ count }}</span>
+</template>
+```
+
+```svelte
+<!-- Svelte: src/components/CartBadge.svelte -->
+<script>
+import { cartItems } from '../stores/cart';
+</script>
+<span class="badge">{$cartItems.length}</span>
+```
+
+6. For state that does not need reactivity, use `localStorage` or URL params as a simple shared medium between islands. For complex cross-island workflows, prefer nanostores over custom events.
+
+7. When mixing React and Solid, disambiguate JSX transforms in `tsconfig.json` using `include`/`exclude` or separate tsconfig files per framework directory. Both use JSX but with different transforms.
+
+8. Use `client:only="react"` (or the relevant framework) for components that rely heavily on browser APIs and should not attempt SSR from the wrong framework context.
+
+## Details
+
+Astro's multi-framework support is powered by its renderer abstraction. Each framework integration (`@astrojs/react`, etc.) registers a renderer that tells Astro's build system how to SSR and hydrate components of that type. The renderers are completely independent — React's `useState` and Vue's `ref` never conflict because they hydrate in separate DOM trees.
+
+**Why nanostores?**
+
+Nanostores is framework-agnostic by design. Each atom is a tiny observable that any framework adapter can subscribe to. When a nanostore value changes, only the components subscribed to that specific atom re-render — regardless of which framework they use. This is exactly the right primitive for cross-island communication.
+
+Alternatives and their trade-offs:
+
+- Redux / Zustand — React-specific; cannot be used in Vue or Svelte components without wrapper hacks
+- Pinia — Vue-specific
+- Custom events (`window.dispatchEvent`) — works everywhere but requires manual subscription management and is not reactive in the framework sense
+- URL params — works but requires navigation or `history.pushState` to trigger re-renders
+
+**JSX disambiguation:**
+
+When React and Solid coexist, both use JSX syntax but with different runtime imports. Astro uses the file extension to determine which renderer to use (`.jsx`/`.tsx` for React, `.jsx`/`.tsx` in a `/solid/` directory for Solid). Configure `jsxImportSource` per directory in `tsconfig.json` if you have both React and Solid `.tsx` files:
+
+```json
+// tsconfig.json (for React default)
+{ "compilerOptions": { "jsxImportSource": "react" } }
+```
+
+Use `/** @jsxImportSource solid-js */` pragma at the top of Solid files when in a mixed project.
+
+**Bundle implications:**
+
+Each framework ships its own runtime bundle. Having React + Vue + Svelte + Solid on the same page means shipping all four runtimes to the client (when using `client:*` directives from all four). Be strategic: prefer one primary framework for most interactive islands, and use secondary frameworks only for specific components that justify the added bytes.
+
+**Migration pattern:**
+
+Multi-framework support is ideal for incremental migrations. Start with your legacy framework (Vue 2, say), add the new framework (`@astrojs/react`), and rewrite components one at a time. Both frameworks work in production throughout the migration.
+
+## Source
+
+https://docs.astro.build/en/guides/framework-components
+
+## 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/astro-multi-framework/skill.yaml

@@ -0,0 +1,47 @@
+name: astro-multi-framework
+version: '1.0.0'
+description: Mix React, Vue, Svelte, and Solid components in one Astro project with framework isolation and shared state via nanostores
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - 'astro.config.*'
+  - '**/*.astro'
+  - '**/src/pages/**'
+  - '**/src/content/**'
+  - '**/src/layouts/**'
+related_skills:
+  - astro-islands-architecture
+  - astro-integration-pattern
+  - react-hooks-pattern
+stack_signals:
+  - astro
+  - typescript
+keywords:
+  - multi-framework
+  - framework-isolation
+  - nanostores
+  - react
+  - vue
+  - svelte
+  - solid
+  - shared-state
+  - cross-framework
+  - useStore
+  - atom
+metadata:
+  author: docs.astro.build
+  upstream: 'docs.astro.build/en/guides/framework-components'
+state:
+  persistent: false
+  files: []
+depends_on: []