@harness-engineering/cli 1.23.1 → 1.24.0

package/dist/agents/skills/cursor/microservices-service-discovery/SKILL.md

@@ -0,0 +1,186 @@
+# Microservices: Service Discovery
+
+> Implement service registration and dynamic discovery with health checks in microservices.
+
+## When to Use
+
+- Services are deployed dynamically (Kubernetes, ECS, auto-scaling groups) and their IPs change
+- You need services to find each other without hardcoded hostnames
+- You want health-check-aware routing — only route to healthy instances
+- You're scaling services horizontally and need load balancing across instances
+
+## Instructions
+
+**Kubernetes DNS-based discovery (most common — no code needed):**
+
+```yaml
+# Kubernetes handles discovery automatically via DNS
+# Service A calls Service B using the DNS name: http://order-service:8080
+# Kubernetes resolves this to the correct pod IPs
+
+apiVersion: v1
+kind: Service
+metadata:
+  name: order-service
+  namespace: production
+spec:
+  selector:
+    app: order-service
+  ports:
+    - port: 8080
+      targetPort: 8080
+  type: ClusterIP # internal only
+
+---
+# In your app code — just use the DNS name
+const ORDER_SERVICE_URL = process.env.ORDER_SERVICE_URL ?? 'http://order-service:8080';
+```
+
+**Consul-based service registration (for non-Kubernetes environments):**
+
+```typescript
+import Consul from 'consul';
+
+const consul = new Consul({ host: process.env.CONSUL_HOST ?? 'consul' });
+
+async function registerService(): Promise<void> {
+  const serviceId = `order-service-${process.env.POD_NAME ?? process.env.HOSTNAME}`;
+
+  await consul.agent.service.register({
+    id: serviceId,
+    name: 'order-service',
+    port: parseInt(process.env.PORT ?? '8080'),
+    address: process.env.POD_IP ?? '0.0.0.0',
+    tags: ['v1', 'production'],
+    check: {
+      http: `http://${process.env.POD_IP}:${process.env.PORT}/health`,
+      interval: '10s',
+      timeout: '5s',
+      deregistercriticalserviceafter: '30s',
+    },
+  });
+
+  console.log(`Registered service: ${serviceId}`);
+
+  // Deregister gracefully on shutdown
+  const cleanup = async () => {
+    await consul.agent.service.deregister(serviceId);
+    process.exit(0);
+  };
+
+  process.on('SIGTERM', cleanup);
+  process.on('SIGINT', cleanup);
+}
+
+// Client-side discovery — resolve service address from Consul
+async function resolveService(name: string): Promise<string> {
+  const services = await consul.health.service({
+    service: name,
+    passing: true, // only healthy instances
+  });
+
+  if (services.length === 0) throw new Error(`No healthy instances of ${name}`);
+
+  // Simple round-robin
+  const instance = services[Math.floor(Math.random() * services.length)];
+  return `http://${instance.Service.Address}:${instance.Service.Port}`;
+}
+
+// Usage
+const orderServiceUrl = await resolveService('order-service');
+const order = await fetch(`${orderServiceUrl}/orders/${orderId}`);
+```
+
+**Service discovery with caching (avoid per-request lookup):**
+
+```typescript
+class ServiceRegistry {
+  private cache = new Map<string, { url: string; expiresAt: number }>();
+  private readonly ttlMs = 30_000; // cache for 30 seconds
+
+  async resolve(serviceName: string): Promise<string> {
+    const cached = this.cache.get(serviceName);
+    if (cached && Date.now() < cached.expiresAt) return cached.url;
+
+    const url = await this.lookup(serviceName);
+    this.cache.set(serviceName, { url, expiresAt: Date.now() + this.ttlMs });
+    return url;
+  }
+
+  private async lookup(name: string): Promise<string> {
+    // Could be Consul, etcd, or DNS
+    return resolveService(name);
+  }
+
+  invalidate(serviceName: string): void {
+    this.cache.delete(serviceName);
+  }
+}
+
+const registry = new ServiceRegistry();
+
+// Use in HTTP client
+async function callOrderService(path: string): Promise<Response> {
+  const baseUrl = await registry.resolve('order-service');
+  const response = await fetch(`${baseUrl}${path}`);
+
+  if (response.status === 503) {
+    // Service may have moved — invalidate cache and retry once
+    registry.invalidate('order-service');
+    const freshUrl = await registry.resolve('order-service');
+    return fetch(`${freshUrl}${path}`);
+  }
+
+  return response;
+}
+```
+
+## Details
+
+**Client-side vs. server-side discovery:**
+| | Client-Side | Server-Side |
+|---|---|---|
+| Who resolves | Each service | Load balancer / gateway |
+| Example | Consul + client library | AWS ALB, Kubernetes Service |
+| Complexity | Higher (each service implements) | Lower (transparent) |
+| Flexibility | More control | Less control |
+
+In Kubernetes, prefer server-side discovery — Services and DNS handle it for you.
+
+**Health checks are required:** Discovery without health checks routes traffic to dead instances. Register health check endpoints and ensure Consul/k8s removes unhealthy instances quickly (see `microservices-health-check` skill).
+
+**Anti-patterns:**
+
+- Hardcoding service IPs or hostnames — breaks on any deployment change
+- Resolving service addresses on every request without caching — hammers the registry
+- No graceful deregistration on shutdown — registry keeps routing to the dead instance until health check catches it
+
+**Environment variable pattern for configuration:**
+
+```typescript
+// Use environment variables for service URLs in all environments
+// Development: http://localhost:8081
+// Staging/Production: http://order-service (Kubernetes DNS)
+const ORDER_SERVICE_URL = process.env.ORDER_SERVICE_URL;
+if (!ORDER_SERVICE_URL) throw new Error('ORDER_SERVICE_URL is required');
+```
+
+## Source
+
+microservices.io/patterns/service-registry.html
+
+## 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/cursor/microservices-service-discovery/skill.yaml

@@ -0,0 +1,39 @@
+name: microservices-service-discovery
+version: "1.0.0"
+description: Implement service registration and dynamic discovery with health checks in microservices
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/services/**"
+  - "**/gateway/**"
+  - "**/api-gateway/**"
+  - "docker-compose.*"
+related_skills:
+  - microservices-api-gateway
+  - microservices-health-check
+stack_signals:
+  - microservices
+  - nodejs
+  - typescript
+keywords:
+  - service-discovery
+  - service-registry
+  - client-side-discovery
+  - server-side-discovery
+  - health-checks
+metadata:
+  author: community
+  upstream: microservices.io/patterns/service-registry.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/microservices-sidecar-pattern/SKILL.md

@@ -0,0 +1,187 @@
+# Microservices: Sidecar Pattern
+
+> Inject cross-cutting concerns like observability and security via a sidecar proxy.
+
+## When to Use
+
+- You need to add cross-cutting infrastructure concerns (TLS, metrics, logging, tracing, auth) to services without changing service code
+- You're running a heterogeneous system (multiple languages/runtimes) and want consistent infrastructure
+- You're adopting a service mesh (Istio, Linkerd, Envoy) for mTLS and traffic management
+- You want to update cross-cutting concerns (e.g., rotate TLS certs, update rate limiting config) without redeploying services
+
+## Instructions
+
+**What the sidecar handles:**
+
+```yaml
+# In Kubernetes: sidecar runs as a second container in the same pod
+# They share the same network namespace (localhost:port)
+
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: order-service
+spec:
+  template:
+    spec:
+      containers:
+        # Main application
+        - name: order-service
+          image: myapp/order-service:1.2.3
+          ports:
+            - containerPort: 8080
+          env:
+            # App talks to its dependencies via localhost (sidecar intercepts)
+            - name: DATABASE_URL
+              value: 'postgresql://localhost:5432/orders' # sidecar handles auth
+
+        # Sidecar proxy (e.g., Envoy)
+        - name: envoy-proxy
+          image: envoyproxy/envoy:v1.28
+          ports:
+            - containerPort: 9901 # admin
+            - containerPort: 15000 # outbound
+            - containerPort: 15001 # inbound
+          volumeMounts:
+            - name: envoy-config
+              mountPath: /etc/envoy
+      volumes:
+        - name: envoy-config
+          configMap:
+            name: envoy-config
+```
+
+**Envoy sidecar configuration for mTLS + rate limiting:**
+
+```yaml
+# envoy-config.yaml
+static_resources:
+  listeners:
+    # Intercept inbound traffic on port 80 → add mTLS
+    - name: inbound
+      address: { socket_address: { address: 0.0.0.0, port_value: 80 } }
+      filter_chains:
+        - transport_socket:
+            name: envoy.transport_sockets.tls
+            typed_config:
+              '@type': type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
+              require_client_certificate: true
+          filters:
+            - name: envoy.filters.network.http_connection_manager
+              typed_config:
+                route_config:
+                  virtual_hosts:
+                    - domains: ['*']
+                      routes:
+                        - match: { prefix: '/' }
+                          route: { cluster: local_app }
+                http_filters:
+                  - name: envoy.filters.http.local_ratelimit
+                    # 100 req/s per service
+                  - name: envoy.filters.http.router
+
+  clusters:
+    - name: local_app
+      connect_timeout: 5s
+      load_assignment:
+        cluster_name: local_app
+        endpoints:
+          - lb_endpoints:
+              - endpoint:
+                  address: { socket_address: { address: 127.0.0.1, port_value: 8080 } }
+```
+
+**Application-side sidecar (Node.js example — Datadog agent pattern):**
+
+```typescript
+// The application doesn't directly call observability APIs
+// It sends metrics/traces to localhost (sidecar agent) using lightweight protocols
+import { StatsD } from 'node-statsd';
+import { tracer } from 'dd-trace'; // auto-instruments at startup
+
+// StatsD client sends to localhost:8125 — Datadog agent (sidecar) forwards to cloud
+const statsd = new StatsD({ host: '127.0.0.1', port: 8125 });
+
+// Metrics automatically forwarded to Datadog by the sidecar agent
+statsd.increment('orders.created');
+statsd.timing('orders.processing_time', durationMs);
+statsd.gauge('orders.queue_depth', depth);
+
+// Traces automatically forwarded too
+const span = tracer.startSpan('process-order');
+span.setTag('order.id', orderId);
+try {
+  await processOrder(orderId);
+  span.finish();
+} catch (err) {
+  span.setTag('error', true);
+  span.finish();
+  throw err;
+}
+```
+
+**Configuring Istio sidecar injection:**
+
+```yaml
+# Enable automatic sidecar injection for a namespace
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: production
+  labels:
+    istio-injection: enabled # Istio auto-injects Envoy into every pod
+
+---
+# Per-pod annotation override (opt-out)
+spec:
+  template:
+    metadata:
+      annotations:
+        sidecar.istio.io/inject: 'false' # disable for this pod
+```
+
+**Capabilities the sidecar adds without code changes:**
+
+```
+mTLS between services: Envoy/Istio handles certificate rotation and mutual auth
+Traffic shaping: canary deployments, A/B testing, fault injection for testing
+Retries and timeouts: configured in service mesh, not application code
+Distributed tracing: trace context propagated across services automatically
+Rate limiting: per-service, per-client limits enforced at the proxy
+Circuit breaking: configured in mesh control plane
+Access control: policy-based authorization at the mesh layer
+```
+
+## Details
+
+**When NOT to use a sidecar:** If you have a small, homogeneous system (one language, one team), implementing cross-cutting concerns in a shared library is simpler and has lower overhead. Sidecar/service mesh adds operational complexity that only pays off at scale or with heterogeneous tech stacks.
+
+**Sidecar vs. Library:** Library approach: each service imports and configures the observability/security library. Sidecar: the infrastructure concerns live outside the service. Library is simpler; sidecar gives uniform enforcement across polyglot services.
+
+**Anti-patterns:**
+
+- Sidecar that does business logic — it should only handle infrastructure concerns
+- Not understanding the performance overhead — Envoy adds ~1-3ms latency per hop; measure before adopting
+- Deploying service mesh without a platform team to manage it — the complexity is significant
+
+**Startup sequencing:** The application must not start processing until the sidecar is ready (especially for mTLS). Use init containers or readiness probes to ensure the sidecar is healthy before the main container starts accepting traffic.
+
+## Source
+
+microservices.io/patterns/deployment/sidecar.html
+
+## 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/cursor/microservices-sidecar-pattern/skill.yaml

@@ -0,0 +1,39 @@
+name: microservices-sidecar-pattern
+version: "1.0.0"
+description: Inject cross-cutting concerns like observability and security via a sidecar proxy
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/services/**"
+  - "**/gateway/**"
+  - "**/api-gateway/**"
+  - "docker-compose.*"
+related_skills:
+  - microservices-distributed-tracing
+  - microservices-service-discovery
+stack_signals:
+  - microservices
+  - nodejs
+  - typescript
+keywords:
+  - sidecar
+  - service-mesh
+  - Envoy
+  - cross-cutting-concerns
+  - proxy-injection
+metadata:
+  author: community
+  upstream: microservices.io/patterns/deployment/sidecar.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/microservices-strangler-fig/SKILL.md

@@ -0,0 +1,204 @@
+# Microservices: Strangler Fig
+
+> Migrate monoliths incrementally using the strangler fig pattern with facade routing.
+
+## When to Use
+
+- You need to migrate a monolith to microservices without a big-bang rewrite
+- You want to extract features one at a time with zero downtime
+- You want to run new and old implementations in parallel for validation before cutting over
+- You need to reduce risk by allowing rollback per feature, not per entire system
+
+## Instructions
+
+**Phase 1: Add a facade (gateway) in front of the monolith:**
+
+```typescript
+// The facade routes ALL traffic — monolith handles everything initially
+// Gradually, you move routes to new services one by one
+
+import express from 'express';
+import { createProxyMiddleware } from 'http-proxy-middleware';
+
+const app = express();
+const MONOLITH_URL = process.env.MONOLITH_URL!;
+
+// Flag store to control which routes go to which target
+class FeatureRouter {
+  private flags: Map<string, boolean>;
+
+  constructor() {
+    this.flags = new Map([
+      ['use-new-catalog-service', false],
+      ['use-new-user-service', false],
+      ['use-new-payment-service', false],
+    ]);
+  }
+
+  isEnabled(flag: string): boolean {
+    return this.flags.get(flag) ?? false;
+  }
+
+  // Loaded from DB/config at runtime — allows instant rollback
+  async reload(): Promise<void> {
+    const config = await db.featureFlags.findMany();
+    for (const { key, enabled } of config) {
+      this.flags.set(key, enabled);
+    }
+  }
+}
+
+const router = new FeatureRouter();
+
+// Catalog routes — gradually migrated
+app.use('/api/catalog', async (req, res, next) => {
+  if (router.isEnabled('use-new-catalog-service')) {
+    return createProxyMiddleware({
+      target: process.env.CATALOG_SERVICE_URL,
+      changeOrigin: true,
+      pathRewrite: { '^/api/catalog': '' },
+    })(req, res, next);
+  }
+  // Falls through to monolith proxy below
+  next();
+});
+
+// Everything else goes to the monolith
+app.use(
+  '/',
+  createProxyMiddleware({
+    target: MONOLITH_URL,
+    changeOrigin: true,
+  })
+);
+```
+
+**Phase 2: Extract a service with parallel-run validation:**
+
+```typescript
+// Before full cutover, run both implementations and compare
+app.get('/api/catalog/products/:id', async (req, res) => {
+  const [monolithResult, newServiceResult] = await Promise.allSettled([
+    fetch(`${MONOLITH_URL}/products/${req.params.id}`).then((r) => r.json()),
+    fetch(`${CATALOG_SERVICE_URL}/products/${req.params.id}`).then((r) => r.json()),
+  ]);
+
+  if (monolithResult.status === 'fulfilled' && newServiceResult.status === 'fulfilled') {
+    const diff = deepDiff(monolithResult.value, newServiceResult.value);
+    if (diff.length > 0) {
+      logger.warn('Response mismatch', { productId: req.params.id, diff });
+      metrics.increment('strangler.response_mismatch', { route: 'product_detail' });
+    }
+  }
+
+  // Always return monolith response during parallel run
+  if (monolithResult.status === 'fulfilled') {
+    res.json(monolithResult.value);
+  } else {
+    res.status(500).json({ error: 'Failed' });
+  }
+});
+```
+
+**Phase 3: Full cutover with instant rollback:**
+
+```typescript
+// Feature flag controls routing — flip it to cut over
+app.use(
+  '/api/catalog',
+  dynamicRouter(async (req, res, next) => {
+    const enabled = await featureFlags.get('use-new-catalog-service');
+    if (enabled) {
+      proxyToService(CATALOG_SERVICE_URL)(req, res, next);
+    } else {
+      proxyToService(MONOLITH_URL)(req, res, next);
+    }
+  })
+);
+
+// Rollback = flip the flag back
+// No deployment needed
+```
+
+**Migration checklist per feature:**
+
+```typescript
+const MIGRATION_STEPS = [
+  '1. Identify the feature to extract (bounded context)',
+  '2. Create the new service with its own database',
+  '3. Set up data sync (dual-write or ETL) from monolith DB to new DB',
+  '4. Deploy the facade in front of the monolith',
+  '5. Run in parallel — route to both, compare responses',
+  '6. Validate parity (no response diffs, same performance)',
+  '7. Enable feature flag — route to new service',
+  '8. Monitor for 1-2 weeks with instant rollback available',
+  '9. Disable data sync from monolith',
+  '10. Delete monolith code for this feature',
+];
+```
+
+**Database migration strategy:**
+
+```typescript
+// During migration: dual-write to keep both DBs in sync
+async function createProduct(data: CreateProductInput): Promise<Product> {
+  // Write to monolith DB (source of truth during migration)
+  const product = await monolithDb.query('INSERT INTO products ... RETURNING *', [
+    data.name,
+    data.price,
+  ]);
+
+  // Also write to new catalog service's DB (eventually will be primary)
+  await catalogDb.product.create({ data: { ...product, migrated: true } }).catch((err) => {
+    logger.error('Dual-write to catalog DB failed', { productId: product.id, err });
+    // Don't fail the request — monolith is still source of truth
+  });
+
+  return product;
+}
+```
+
+## Details
+
+**Strangler Fig metaphor:** The strangler fig tree grows around a host tree, eventually replacing it. You build the new system around the old one, gradually replacing it piece by piece until the old system is gone.
+
+**What to extract first:**
+
+1. Most actively developed area (reduces developer friction fastest)
+2. Independently scalable pieces (immediate operational benefit)
+3. Areas with the clearest domain boundaries (lower risk)
+4. Avoid: tightly coupled modules, shared database tables without clear ownership
+
+**Anti-patterns:**
+
+- Big bang migration (rewriting everything at once) — high risk, long feedback cycle
+- Extracting without a facade — clients must change to call new service URLs
+- Not having a rollback plan — always keep the monolith path available during migration
+- Migrating data before migrating the service — the data migration is the hardest part; do it last
+
+**Seam finding:** Look for natural boundaries in the monolith:
+
+- Separate URL prefixes (`/catalog/`, `/orders/`)
+- Database tables accessed by only one module
+- Teams that work on separate features
+- Performance hotspots that need independent scaling
+
+## Source
+
+microservices.io/patterns/refactoring/strangler-application.html
+
+## 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/cursor/microservices-strangler-fig/skill.yaml

@@ -0,0 +1,41 @@
+name: microservices-strangler-fig
+version: "1.0.0"
+description: Migrate monoliths incrementally using the strangler fig pattern with facade routing
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/services/**"
+  - "**/gateway/**"
+  - "**/api-gateway/**"
+  - "docker-compose.*"
+related_skills:
+  - microservices-decomposition
+  - microservices-api-gateway
+  - gof-facade-pattern
+stack_signals:
+  - microservices
+  - nodejs
+  - typescript
+keywords:
+  - strangler-fig
+  - migration
+  - monolith
+  - incremental
+  - facade-routing
+  - parallel-run
+metadata:
+  author: community
+  upstream: microservices.io/patterns/refactoring/strangler-application.html
+state:
+  persistent: false
+  files: []
+depends_on: []