@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/codex/perf-svg-optimization/SKILL.md

@@ -0,0 +1,249 @@
+# SVG Optimization
+
+> Master SVG optimization — automated minification with SVGO, inline versus external delivery trade-offs, SVG sprite sheet systems, accessibility patterns, rendering performance for complex vector graphics, and icon system architecture.
+
+## When to Use
+
+- SVGs exported from design tools contain unnecessary metadata, comments, and editor artifacts
+- An icon system uses individual SVG files causing many HTTP requests
+- Inline SVGs bloat HTML document size and prevent caching
+- Complex SVGs with many paths cause rendering jank during scrolling or animation
+- Lighthouse flags large SVG assets that could be optimized
+- SVG icons lack accessibility attributes (title, role, aria-label)
+- A design system needs a scalable, performant icon delivery strategy
+- SVGs contain embedded raster images or fonts that inflate file size
+- SVG animations cause high CPU usage on lower-powered devices
+- Migrating from icon fonts to SVG icons for better accessibility and rendering
+
+## Instructions
+
+1. **Optimize SVGs with SVGO.** SVGO removes editor metadata, simplifies paths, and reduces file size by 30-80%:
+
+   ```bash
+   # Install and run SVGO
+   npx svgo icon.svg -o icon.min.svg
+
+   # Batch optimize a directory
+   npx svgo -f src/icons/ -o dist/icons/
+
+   # Show detailed savings
+   npx svgo icon.svg --pretty --indent=2
+   ```
+
+   ```javascript
+   // svgo.config.js — recommended configuration
+   module.exports = {
+     multipass: true,
+     plugins: [
+       'preset-default',
+       'removeDimensions', // use viewBox instead of width/height
+       'sortAttrs',
+       {
+         name: 'removeAttrs',
+         params: { attrs: ['data-name', 'class'] }, // remove editor cruft
+       },
+       {
+         name: 'preset-default',
+         params: {
+           overrides: {
+             removeViewBox: false, // keep viewBox for scalability
+             cleanupIds: {
+               minify: true,
+               remove: false, // keep IDs for sprite references
+             },
+           },
+         },
+       },
+     ],
+   };
+   ```
+
+2. **Choose the right delivery method.** Each approach has specific trade-offs:
+
+   ```
+   Method           | Cacheable | Styleable | HTTP Requests | HTML Size
+   -----------------|-----------|-----------|---------------|----------
+   Inline SVG       | No        | Full CSS  | 0             | Increases
+   External <img>   | Yes       | None      | 1 per icon    | Minimal
+   SVG sprite <use> | Yes       | Limited   | 1 total       | Minimal
+   CSS background   | Yes       | None      | 1 per icon    | Minimal
+   Data URI         | No        | None      | 0             | Increases
+   ```
+
+   **Inline SVG** for icons that need CSS styling (color, hover states) and appear above the fold. **SVG sprites** for icon systems with many icons across the site. **External `<img>`** for complex illustrations that benefit from caching.
+
+3. **Build an SVG sprite sheet.** Combine icons into a single file referenced via `<use>`:
+
+   ```bash
+   # Generate sprite with svg-sprite
+   npx svg-sprite --symbol --symbol-dest=dist --symbol-sprite=icons.svg src/icons/*.svg
+   ```
+
+   ```html
+   <!-- icons.svg sprite file -->
+   <svg xmlns="http://www.w3.org/2000/svg" style="display:none">
+     <symbol id="icon-search" viewBox="0 0 24 24">
+       <path d="M15.5 14h-.79l-.28-.27A6.47..." />
+     </symbol>
+     <symbol id="icon-close" viewBox="0 0 24 24">
+       <path d="M19 6.41L17.59 5 12 10.59..." />
+     </symbol>
+   </svg>
+
+   <!-- Reference icons anywhere in the page -->
+   <svg width="24" height="24" aria-hidden="true">
+     <use href="/icons.svg#icon-search"></use>
+   </svg>
+   ```
+
+4. **Make SVGs accessible.** Icons need proper ARIA attributes depending on their role:
+
+   ```html
+   <!-- Decorative icon (next to text label): hide from screen readers -->
+   <button>
+     <svg width="20" height="20" aria-hidden="true" focusable="false">
+       <use href="#icon-search"></use>
+     </svg>
+     Search
+   </button>
+
+   <!-- Informational icon (no visible label): provide accessible name -->
+   <button aria-label="Search">
+     <svg width="20" height="20" role="img" aria-label="Search" focusable="false">
+       <use href="#icon-search"></use>
+     </svg>
+   </button>
+
+   <!-- Complex illustration: use title and desc -->
+   <svg role="img" aria-labelledby="chart-title chart-desc">
+     <title id="chart-title">Revenue Growth 2024</title>
+     <desc id="chart-desc">Bar chart showing 23% year-over-year revenue growth</desc>
+     <!-- chart paths -->
+   </svg>
+   ```
+
+5. **Optimize complex SVGs for rendering performance.** SVGs with thousands of paths cause layout and paint cost:
+
+   ```html
+   <!-- Contain rendering cost of complex SVGs -->
+   <div style="contain: layout paint; will-change: transform;">
+     <svg viewBox="0 0 1000 1000">
+       <!-- complex illustration with many paths -->
+     </svg>
+   </div>
+
+   <!-- Simplify paths: reduce control points -->
+   <!-- Before: <path d="M 10.123456 20.789012 C 30.111111..."> -->
+   <!-- After:  <path d="M 10.1 20.8 C 30.1..."> -->
+   ```
+
+   ```javascript
+   // SVGO: reduce path precision
+   module.exports = {
+     plugins: [
+       {
+         name: 'preset-default',
+         params: {
+           overrides: {
+             cleanupNumericValues: { floatPrecision: 1 },
+             convertPathData: { floatPrecision: 1 },
+           },
+         },
+       },
+     ],
+   };
+   ```
+
+6. **Implement an icon component for consistent delivery.** Abstract the sprite reference into a reusable component:
+
+   ```typescript
+   interface IconProps {
+     name: string;
+     size?: number;
+     className?: string;
+     title?: string;
+   }
+
+   function Icon({ name, size = 24, className, title }: IconProps) {
+     const hasTitle = Boolean(title);
+     return (
+       <svg
+         width={size}
+         height={size}
+         className={className}
+         role={hasTitle ? 'img' : undefined}
+         aria-label={hasTitle ? title : undefined}
+         aria-hidden={hasTitle ? undefined : true}
+         focusable="false"
+       >
+         {hasTitle && <title>{title}</title>}
+         <use href={`/icons.svg#icon-${name}`} />
+       </svg>
+     );
+   }
+
+   // Usage
+   <Icon name="search" />
+   <Icon name="close" title="Close dialog" />
+   ```
+
+7. **Remove embedded raster images and fonts.** Design tools sometimes embed base64-encoded PNGs or font subsets inside SVGs:
+
+   ```bash
+   # Find SVGs with embedded images
+   grep -rl 'image.*base64' src/icons/
+   grep -rl '<font' src/icons/
+
+   # These need to be re-exported from the design tool
+   # without "include images" or "outline fonts" options
+   ```
+
+## Details
+
+### SVG vs Icon Font Comparison
+
+Icon fonts (Font Awesome, Material Icons) were the standard icon delivery method before SVG systems matured. SVGs are superior in every dimension: per-icon loading (icon fonts are all-or-nothing), multi-color support, CSS animation control, accessibility (icon fonts use pseudo-elements that screen readers handle inconsistently), and rendering precision (icon fonts suffer from anti-aliasing artifacts at certain sizes). The only advantage of icon fonts is simpler setup — a single CSS include.
+
+### Worked Example: GitHub Octicons
+
+GitHub's Octicons icon system uses inline SVGs for above-the-fold icons (navigation, status indicators) and an SVG sprite for the full icon set. Each icon is optimized with SVGO to under 500 bytes. The sprite file (~15KB for 250+ icons) is loaded once and cached with a content-hashed filename. Icons use `aria-hidden="true"` when adjacent to text labels and `aria-label` when standalone. The Icon React component enforces these accessibility patterns, making incorrect usage a lint error. Total icon overhead per page: ~2KB inline + 15KB sprite (cached).
+
+### Worked Example: Figma to Production Pipeline
+
+Figma exports SVGs with editor metadata (`data-name`, Figma-specific attributes) that double file size. A production pipeline runs: (1) Export from Figma via API, (2) SVGO with custom config that strips Figma metadata and reduces precision to 1 decimal, (3) Generate sprite sheet with svg-sprite, (4) Generate TypeScript icon name union type from the sprite for type safety. This automated pipeline runs in CI when designers push to the Figma file, ensuring icons are always optimized and type-safe.
+
+### Anti-Patterns
+
+**Inlining large SVGs in every page.** A 20KB inline SVG illustration on every page adds 20KB to every HTML response and is never cached. Use `<img>` or `<object>` for illustrations larger than 2KB so the browser can cache them.
+
+**Using SVGs with embedded raster images.** An SVG containing a base64-encoded PNG is worse than serving the PNG directly: larger file, no responsive image benefits, and the SVG wrapper adds parse overhead.
+
+**Animating SVG properties that trigger layout.** Animating `width`, `height`, `x`, `y`, or path `d` attributes causes layout recalculation on every frame. Use `transform` (translate, scale, rotate) and `opacity` for smooth 60fps animations.
+
+**Not setting viewBox on SVG elements.** Without `viewBox`, SVGs cannot scale proportionally. Always include `viewBox` and remove fixed `width`/`height` attributes (set dimensions via CSS or the parent element instead).
+
+## Source
+
+- SVGO — https://github.com/svg/svgo
+- svg-sprite — https://github.com/svg-sprite/svg-sprite
+- SVG Accessibility Best Practices — https://www.w3.org/WAI/tutorials/images/complex/
+- web.dev: SVG optimization — https://web.dev/articles/reduce-network-payloads-using-text-compression
+
+## 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
+
+- All SVGs are processed through SVGO with appropriate configuration.
+- Icon system uses SVG sprites for efficient delivery and caching.
+- SVG icons include correct accessibility attributes (aria-hidden or aria-label).
+- No SVGs contain embedded raster images or font data.
+- Complex SVGs use CSS containment to limit rendering cost.

package/dist/agents/skills/codex/perf-svg-optimization/skill.yaml

@@ -0,0 +1,37 @@
+name: perf-svg-optimization
+version: '1.0.0'
+description: SVG optimization — Minification, inline vs external strategies, sprite sheets, accessibility, and rendering performance
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-image-formats
+  - perf-critical-rendering-path
+  - perf-compression
+  - css-performance-patterns
+stack_signals: []
+keywords:
+  - svg optimization
+  - svgo
+  - svg sprite
+  - inline svg
+  - svg minification
+  - icon system
+  - svg accessibility
+  - vector graphics
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/perf-tree-shaking/SKILL.md

@@ -0,0 +1,225 @@
+# Tree Shaking
+
+> Master tree shaking and dead code elimination — ESM static analysis requirements, sideEffects configuration, barrel file pitfalls, library authoring for tree-shakability, and debugging why unused code survives bundling.
+
+## When to Use
+
+- Bundle includes entire libraries when only a few functions are imported
+- Importing from a barrel file (index.ts) pulls in the entire module graph
+- Webpack Bundle Analyzer shows large modules where only a fraction is used
+- Library consumers report your package is not tree-shakable
+- Switching from CommonJS to ESM to enable dead code elimination
+- Bundle size grows disproportionately to feature additions
+- Lodash, moment.js, or similar utility libraries inflate the bundle
+- You need to configure sideEffects in package.json for a library
+- TypeScript compilation output uses CommonJS require() instead of ESM import
+- Production build includes development-only code paths
+
+## Instructions
+
+1. **Verify ESM output is configured.** Tree shaking requires ES module syntax (import/export). CommonJS (require/module.exports) is opaque to static analysis:
+
+   ```json
+   // tsconfig.json — ensure ESM output
+   {
+     "compilerOptions": {
+       "module": "esnext",
+       "moduleResolution": "bundler",
+       "target": "es2020"
+     }
+   }
+   ```
+
+   ```json
+   // package.json — declare ESM for consumers
+   {
+     "type": "module",
+     "main": "./dist/index.cjs",
+     "module": "./dist/index.mjs",
+     "exports": {
+       ".": {
+         "import": "./dist/index.mjs",
+         "require": "./dist/index.cjs"
+       },
+       "./utils": {
+         "import": "./dist/utils.mjs"
+       }
+     }
+   }
+   ```
+
+2. **Configure sideEffects in package.json.** The `sideEffects` field tells bundlers which files are safe to eliminate when their exports are unused:
+
+   ```json
+   // package.json — mark the package as side-effect-free
+   {
+     "sideEffects": false
+   }
+
+   // Or specify files that DO have side effects
+   {
+     "sideEffects": [
+       "*.css",
+       "./src/polyfills.ts",
+       "./src/global-setup.ts"
+     ]
+   }
+   ```
+
+   A side effect is code that executes at import time and affects global state: CSS imports, polyfills, global event listeners, prototype modifications.
+
+3. **Avoid barrel file anti-patterns.** Barrel files (re-export everything from index.ts) defeat tree shaking in many bundler configurations:
+
+   ```typescript
+   // BAD: barrel file that re-exports everything
+   // src/utils/index.ts
+   export { formatDate } from './date';
+   export { formatCurrency } from './currency';
+   export { heavyParser } from './parser'; // 50KB — included even if unused
+
+   // Importing one function may pull in all three:
+   import { formatDate } from './utils';
+
+   // GOOD: import directly from the source module
+   import { formatDate } from './utils/date';
+   ```
+
+4. **Use named exports over default exports.** Named exports are statically analyzable. Default exports can inhibit tree shaking in some configurations:
+
+   ```typescript
+   // Preferred: named exports — each can be independently eliminated
+   export function createUser() {
+     /* ... */
+   }
+   export function deleteUser() {
+     /* ... */
+   }
+   export function updateUser() {
+     /* ... */
+   }
+
+   // Avoid: default export of object — entire object retained
+   export default {
+     createUser() {
+       /* ... */
+     },
+     deleteUser() {
+       /* ... */
+     },
+     updateUser() {
+       /* ... */
+     },
+   };
+   ```
+
+5. **Replace tree-shaking-hostile libraries.** Some libraries ship only CommonJS or use patterns that prevent elimination:
+
+   ```javascript
+   // Before: lodash (CommonJS, entire library bundled)
+   import { debounce } from 'lodash'; // ~70KB gzipped
+
+   // After: lodash-es (ESM, tree-shakable)
+   import { debounce } from 'lodash-es'; // ~1KB gzipped
+
+   // Or: direct path import
+   import debounce from 'lodash/debounce'; // ~1KB gzipped
+
+   // Before: moment.js (not tree-shakable, includes all locales)
+   import moment from 'moment'; // ~67KB gzipped
+
+   // After: date-fns (ESM, tree-shakable, per-function imports)
+   import { format, parseISO } from 'date-fns'; // ~2KB gzipped
+   ```
+
+6. **Debug tree shaking failures.** When code survives that should be eliminated:
+
+   ```bash
+   # Webpack: analyze why a module is included
+   npx webpack --stats-modules-space 999 | grep "module-name"
+
+   # Webpack: check sideEffects optimization
+   npx webpack --stats-optimization-bailout
+
+   # Rollup: use the treeshake.moduleSideEffects option
+   # rollup.config.js
+   export default {
+     treeshake: {
+       moduleSideEffects: false,  // assume all modules are side-effect-free
+     },
+   };
+   ```
+
+7. **Eliminate dead code paths with define/replace.** Replace environment variables at build time to enable dead code elimination of development-only branches:
+
+   ```javascript
+   // webpack.config.js
+   const webpack = require('webpack');
+   module.exports = {
+     plugins: [
+       new webpack.DefinePlugin({
+         'process.env.NODE_ENV': JSON.stringify('production'),
+         __DEV__: false,
+       }),
+     ],
+   };
+
+   // Source code — the `if (__DEV__)` block is eliminated entirely in production
+   if (__DEV__) {
+     validateProps(props);
+     console.log('Debug:', state);
+   }
+   ```
+
+## Details
+
+### How Tree Shaking Works
+
+Tree shaking is a form of dead code elimination that operates on the ES module graph. The bundler builds a dependency graph from import/export statements, marks which exports are actually used (starting from entry points), and eliminates modules and exports that are never referenced. This works because ESM imports and exports are statically analyzable — they cannot be computed at runtime (unlike CommonJS `require(variable)`).
+
+### The sideEffects Mechanism
+
+Without `"sideEffects": false`, bundlers must assume that importing any module might execute code with observable effects. Even if no exports are used, the module stays in the bundle because removing it might remove a needed side effect. Setting `"sideEffects": false` tells the bundler: "if none of this module's exports are used, the entire module can be safely removed."
+
+### Worked Example: Material UI Import Optimization
+
+Material UI v4 used deep path imports (`@material-ui/core/Button`) because their barrel file re-exported 100+ components, and tree shaking was unreliable across bundler configurations. In v5 (MUI), they restructured with proper `sideEffects` configuration and subpath exports, allowing `import { Button } from '@mui/material'` to tree-shake correctly in webpack 5 and Rollup. This reduced typical bundle sizes by 30-40% compared to v4 barrel imports without deep paths.
+
+### Worked Example: Vercel Commerce
+
+Vercel's commerce starter uses Next.js with SWC compilation, which outputs ESM and enables aggressive tree shaking. Their utility library marks `"sideEffects": false` and uses granular named exports. The result: importing 3 utility functions from a 50-function library adds only 2KB instead of the full 45KB. Combined with Next.js automatic code splitting, the initial page load ships only the JavaScript required for the visible route.
+
+### Anti-Patterns
+
+**Re-exporting CommonJS modules through ESM barrels.** If a barrel file re-exports a CommonJS module, the bundler cannot tree-shake the CommonJS internals. The entire CJS module is included even if only one export is used.
+
+**Class-based APIs with prototype mutation.** Classes with methods added via prototype assignment are side-effectful at the module level. Bundlers cannot safely eliminate unused classes if the class definition mutates prototypes.
+
+**Relying on minifier-only dead code elimination.** Terser/uglify can remove unreachable code (`if (false) { ... }`), but this is not tree shaking. Minifier DCE cannot remove unused module exports or entire unused modules from the graph.
+
+**Importing for type-only usage without `import type`.** In TypeScript, `import { SomeType } from './module'` may cause the bundler to include the module. Use `import type { SomeType } from './module'` to ensure the import is erased at compile time.
+
+## Source
+
+- webpack: Tree Shaking — https://webpack.js.org/guides/tree-shaking/
+- Rollup: Tree Shaking — https://rollupjs.org/introduction/#tree-shaking
+- MDN: ES Modules — https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
+- Node.js: Package Exports — https://nodejs.org/api/packages.html#exports
+
+## 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
+
+- All application code uses ESM import/export syntax.
+- Package.json includes correct sideEffects configuration.
+- No barrel file imports pull in unused modules (verified via bundle analyzer).
+- Library dependencies are tree-shakable (ESM with sideEffects declared).
+- Production bundle contains no development-only code paths.

package/dist/agents/skills/codex/perf-tree-shaking/skill.yaml

@@ -0,0 +1,38 @@
+name: perf-tree-shaking
+version: '1.0.0'
+description: Tree shaking — Dead code elimination, side-effect configuration, ESM requirements, and module-level optimization
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-code-splitting
+  - perf-bundle-analysis
+  - perf-lazy-loading
+  - ts-performance-patterns
+stack_signals: []
+keywords:
+  - tree shaking
+  - dead code elimination
+  - sideEffects
+  - ESM
+  - es modules
+  - unused exports
+  - bundle size
+  - webpack
+  - rollup
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []