@infinitedusky/indusk-mcp 1.5.8 → 1.5.9

package/dist/bin/commands/init.js

@@ -175,7 +175,67 @@ export async function init(projectRoot, options = {}) {
         cpSync(join(packageRoot, "templates/biome.template.json"), biomePath);
         console.info(`  ${existsSync(biomePath) ? "overwrite" : "create"}: biome.json`);
     }
-    // 7. Install gate enforcement hooks
+    // 7. Scaffold OpenTelemetry instrumentation
+    console.info("\n[OpenTelemetry]");
+    const otelTemplates = ["instrumentation.ts", "filtering-exporter.ts", "logger.ts"];
+    const isNextJs = existsSync(join(projectRoot, "next.config.js")) ||
+        existsSync(join(projectRoot, "next.config.ts")) ||
+        existsSync(join(projectRoot, "next.config.mjs"));
+    const isPython = existsSync(join(projectRoot, "requirements.txt")) ||
+        existsSync(join(projectRoot, "pyproject.toml"));
+    if (isPython) {
+        const pyTemplate = "instrumentation.py";
+        const targetFile = join(projectRoot, pyTemplate);
+        if (existsSync(targetFile) && !force) {
+            console.info(`  skip: ${pyTemplate} (already exists)`);
+        }
+        else {
+            cpSync(join(packageRoot, "templates", pyTemplate), targetFile);
+            console.info(`  create: ${pyTemplate}`);
+            console.info("  install: pip install opentelemetry-distro opentelemetry-instrumentation opentelemetry-exporter-otlp");
+            console.info("  run: opentelemetry-instrument python your_app.py");
+        }
+    }
+    else {
+        // Node.js or Next.js — copy TypeScript templates
+        const targetDir = isNextJs ? projectRoot : join(projectRoot, "src");
+        const srcDir = existsSync(join(projectRoot, "src")) ? join(projectRoot, "src") : projectRoot;
+        for (const template of otelTemplates) {
+            const targetFile = join(srcDir, template);
+            if (existsSync(targetFile) && !force) {
+                console.info(`  skip: ${template} (already exists)`);
+                continue;
+            }
+            cpSync(join(packageRoot, "templates", template), targetFile);
+            console.info(`  create: ${template}`);
+        }
+        // Set service name in instrumentation.ts
+        const instrPath = join(srcDir, "instrumentation.ts");
+        if (existsSync(instrPath)) {
+            const content = readFileSync(instrPath, "utf-8");
+            writeFileSync(instrPath, content.replace('"unknown-service"', `"${projectName}"`));
+        }
+        // Print instructions
+        const packages = [
+            "@opentelemetry/sdk-node",
+            "@opentelemetry/auto-instrumentations-node",
+            "@opentelemetry/exporter-trace-otlp-http",
+            "@opentelemetry/sdk-trace-base",
+            "@opentelemetry/resources",
+            "@opentelemetry/semantic-conventions",
+            "@opentelemetry/core",
+            "pino",
+            "pino-opentelemetry-transport",
+        ];
+        console.info(`  install: pnpm add ${packages.join(" ")}`);
+        if (isNextJs) {
+            console.info("  wire: Next.js instrumentation hook (instrumentation.ts in app root)");
+        }
+        else {
+            console.info("  wire: node -r ./src/instrumentation.ts src/index.ts");
+        }
+    }
+    // 8. Install gate enforcement hooks
     console.info("\n[Hooks]");
     const hooksSource = join(packageRoot, "hooks");
     const hooksTarget = join(projectRoot, ".claude/hooks");

package/extensions/otel/manifest.json

@@ -0,0 +1,23 @@
+{
+	"name": "otel",
+	"description": "OpenTelemetry instrumentation — auto-instrumentation, Pino structured logging, category-based filtering",
+	"provides": {
+		"skill": true,
+		"health_checks": [
+			{
+				"name": "otel-instrumentation-exists",
+				"command": "test -f instrumentation.ts || test -f src/instrumentation.ts || test -f instrumentation.py"
+			},
+			{
+				"name": "otel-packages-installed",
+				"command": "node -e \"require('@opentelemetry/sdk-node')\" 2>/dev/null || python -c \"import opentelemetry\" 2>/dev/null"
+			}
+		],
+		"verification": [
+			"test -f instrumentation.ts || test -f src/instrumentation.ts || test -f instrumentation.py"
+		]
+	},
+	"detect": {
+		"file": "instrumentation.ts"
+	}
+}

package/extensions/otel/skill.md

@@ -0,0 +1,153 @@
+# OpenTelemetry
+
+Every service is instrumented from day one. `init` creates the instrumentation files. This skill teaches you how to use them.
+
+## What's Already Set Up
+
+After `init`, your project has:
+- `instrumentation.ts` — auto-instruments HTTP, database, and framework calls
+- `filtering-exporter.ts` — controls which span categories get exported
+- `logger.ts` — Pino structured logger with stdout + OTLP dual output
+
+## When to Add Manual Spans
+
+Auto-instrumentation covers HTTP requests and database queries. You need manual spans for:
+
+- **Business events**: `poker.hand.deal`, `auth.session.create`, `order.checkout.complete`
+- **State transitions**: `game.state.waiting_to_active`, `payment.status.pending_to_settled`
+- **Inference calls**: `inference.gemini.generate`, `inference.embedding.create`
+- **Batch operations**: `migration.run`, `cron.cleanup.expired_sessions`
+
+If it's a meaningful action that you'd want to see in a trace, add a span.
+
+## Span Naming
+
+Use `{domain}.{entity}.{action}`:
+
+```typescript
+const tracer = trace.getTracer('my-service');
+
+// Good
+tracer.startSpan('poker.hand.deal');
+tracer.startSpan('auth.session.create');
+tracer.startSpan('settlement.receipt.sign');
+
+// Bad
+tracer.startSpan('processRequest');
+tracer.startSpan('handle');
+tracer.startSpan('doThing');
+```
+
+## Custom Attributes
+
+Always add domain-specific data to spans:
+
+```typescript
+const span = tracer.startSpan('poker.hand.deal');
+span.setAttribute('otel.category', 'business');
+span.setAttribute('room.code', roomCode);
+span.setAttribute('hand.number', handNumber);
+span.setAttribute('player.count', players.length);
+// ... do work ...
+span.end();
+```
+
+## Categories
+
+Every manual span should get an `otel.category` attribute. This controls whether it gets exported:
+
+| Category | What it covers | Examples |
+|----------|---------------|----------|
+| `http` | HTTP server/client requests | Auto-instrumented |
+| `db` | Database queries | Auto-instrumented |
+| `business` | Domain events | hand dealt, user registered, payment processed |
+| `inference` | LLM/AI calls | Gemini generate, embedding create |
+| `state` | State transitions | game started, order status changed |
+| `system` | Infrastructure | health checks, cron jobs, queue processing |
+
+Control which categories are exported via `OTEL_ENABLED_CATEGORIES`:
+
+```bash
+# Export only HTTP and business spans
+OTEL_ENABLED_CATEGORIES=http,business node -r ./instrumentation.ts src/index.ts
+
+# Export everything (default)
+node -r ./instrumentation.ts src/index.ts
+```
+
+## Structured Logging with Pino
+
+Use the project logger, not `console.log`:
+
+```typescript
+import { logger } from './logger';
+
+// Good — structured, with context
+logger.info({ roomCode, players: players.length }, 'hand started');
+logger.error({ err, traceId: span.spanContext().traceId }, 'settlement failed');
+logger.warn({ queueDepth: 150, threshold: 100 }, 'queue depth approaching limit');
+
+// Bad — unstructured string
+console.log('Hand started for room ' + roomCode);
+console.log('Error: ' + err.message);
+```
+
+### Log Levels
+
+| Level | Meaning | When to use |
+|-------|---------|------------|
+| `error` | Something is broken | Unhandled errors, failed operations that should succeed |
+| `warn` | Degraded but functional | Approaching limits, fallback behavior triggered |
+| `info` | Business events | State transitions, user actions, completed operations |
+| `debug` | Development details | Variable values, flow tracing — disable in production |
+
+## Error Propagation
+
+Errors must always include trace context:
+
+```typescript
+try {
+  await processSettlement(hand);
+} catch (err) {
+  span.recordException(err);
+  span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+  logger.error({ err, traceId: span.spanContext().traceId }, 'settlement failed');
+  throw err; // re-throw with context preserved
+}
+```
+
+Never swallow errors silently. Every catch block should either:
+1. Re-throw with context
+2. Log with trace correlation and handle completely
+
+## Framework-Specific Notes
+
+### Next.js
+The `instrumentation.ts` file in the app root is loaded via the Next.js instrumentation hook (13.4+). No `-r` flag needed.
+
+### Python
+Use the `opentelemetry-instrument` CLI wrapper:
+```bash
+opentelemetry-instrument python your_app.py
+```
+Or import the instrumentation module before your app code.
+
+## Environment Variables
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `OTEL_SERVICE_NAME` | Service name in traces | Project name (set by init) |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Backend URL | Not set (uses console exporter) |
+| `OTEL_EXPORTER_OTLP_HEADERS` | Auth headers for backend | Not set |
+| `OTEL_ENABLED_CATEGORIES` | Comma-separated active categories | All enabled |
+| `LOG_LEVEL` | Pino log level | `info` |
+
+When no `OTEL_EXPORTER_OTLP_ENDPOINT` is set, traces go to the console exporter (stdout). Enable a backend (like Dash0) to send traces remotely.
+
+## Verification
+
+During `/work`, check:
+- Are new endpoints/business logic instrumented?
+- Do manual spans have meaningful names and category attributes?
+- Are errors recorded with trace context?
+- Is structured logging used (not console.log)?

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@infinitedusky/indusk-mcp",
-	"version": "1.5.8",
+	"version": "1.5.9",
 	"description": "InDusk development system — skills, MCP tools, and CLI for structured AI-assisted development",
 	"type": "module",
 	"files": [

package/templates/filtering-exporter.ts

@@ -0,0 +1,82 @@
+/**
+ * FilteringExporter — Category-based span filtering for OpenTelemetry.
+ *
+ * Wraps a real SpanExporter and drops spans from disabled categories
+ * before they reach the backend. This lets you instrument aggressively
+ * and control export volume at runtime.
+ *
+ * Categories are set via the `otel.category` span attribute.
+ * Spans without a category are always exported.
+ *
+ * Control which categories are active via OTEL_ENABLED_CATEGORIES env var:
+ *   OTEL_ENABLED_CATEGORIES=http,business,inference
+ *
+ * If OTEL_ENABLED_CATEGORIES is not set, all categories are exported.
+ */
+
+import type {
+	ExportResult,
+	ExportResultCode,
+} from "@opentelemetry/core";
+import type { ReadableSpan, SpanExporter } from "@opentelemetry/sdk-trace-base";
+
+export const ALL_CATEGORIES = [
+	"http",
+	"db",
+	"business",
+	"inference",
+	"state",
+	"system",
+] as const;
+
+export type OtelCategory = (typeof ALL_CATEGORIES)[number];
+
+function getEnabledCategories(): Set<string> {
+	const env = process.env.OTEL_ENABLED_CATEGORIES;
+	if (!env) return new Set(ALL_CATEGORIES);
+	return new Set(
+		env
+			.split(",")
+			.map((c) => c.trim())
+			.filter(Boolean),
+	);
+}
+
+export class FilteringExporter implements SpanExporter {
+	private enabledCategories: Set<string>;
+
+	constructor(private inner: SpanExporter) {
+		this.enabledCategories = getEnabledCategories();
+	}
+
+	export(
+		spans: ReadableSpan[],
+		resultCallback: (result: ExportResult) => void,
+	): void {
+		const filtered = spans.filter((span) => {
+			const category = span.attributes["otel.category"] as string | undefined;
+			// Spans without a category are always exported
+			if (!category) return true;
+			return this.enabledCategories.has(category);
+		});
+
+		if (filtered.length > 0) {
+			this.inner.export(filtered, resultCallback);
+		} else {
+			resultCallback({ code: 0 as ExportResultCode });
+		}
+	}
+
+	async shutdown(): Promise<void> {
+		return this.inner.shutdown();
+	}
+
+	async forceFlush(): Promise<void> {
+		return this.inner.forceFlush?.() ?? Promise.resolve();
+	}
+
+	/** Re-read OTEL_ENABLED_CATEGORIES from env. Call after changing the env var at runtime. */
+	refreshCategories(): void {
+		this.enabledCategories = getEnabledCategories();
+	}
+}

package/templates/instrumentation.py

@@ -0,0 +1,65 @@
+"""
+OpenTelemetry Auto-Instrumentation for Python
+
+Run your application with the auto-instrumentation wrapper:
+
+    opentelemetry-instrument python your_app.py
+
+Or import this module before your application code:
+
+    import instrumentation  # noqa: F401
+    from your_app import main
+    main()
+
+Configuration via environment variables:
+    OTEL_SERVICE_NAME              — service name (defaults to "unknown-service")
+    OTEL_EXPORTER_OTLP_ENDPOINT   — OTLP backend URL
+    OTEL_EXPORTER_OTLP_HEADERS    — auth headers (e.g., "Authorization=Bearer xxx")
+    OTEL_PYTHON_LOG_CORRELATION   — set to "true" for trace context in logs (default)
+
+Install required packages:
+    pip install opentelemetry-distro opentelemetry-instrumentation opentelemetry-exporter-otlp
+
+Then auto-install all available instrumentations:
+    opentelemetry-bootstrap --action=install
+"""
+
+import os
+import logging
+
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import (
+    BatchSpanProcessor,
+    ConsoleSpanExporter,
+)
+from opentelemetry.sdk.resources import Resource, SERVICE_NAME
+
+# Configure resource with service name
+resource = Resource.create(
+    {SERVICE_NAME: os.environ.get("OTEL_SERVICE_NAME", "unknown-service")}
+)
+
+provider = TracerProvider(resource=resource)
+
+# Use OTLP exporter if endpoint is configured, otherwise console
+otlp_endpoint = os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT")
+if otlp_endpoint:
+    from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
+        OTLPSpanExporter,
+    )
+
+    provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
+else:
+    provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
+
+trace.set_tracer_provider(provider)
+
+# Enable trace context correlation in Python logging
+os.environ.setdefault("OTEL_PYTHON_LOG_CORRELATION", "true")
+
+# Configure structured logging
+logging.basicConfig(
+    level=os.environ.get("LOG_LEVEL", "INFO").upper(),
+    format="%(asctime)s %(levelname)s [%(name)s] [trace_id=%(otelTraceID)s span_id=%(otelSpanID)s] %(message)s",
+)

package/templates/instrumentation.ts

@@ -0,0 +1,63 @@
+/**
+ * OpenTelemetry Auto-Instrumentation
+ *
+ * This file sets up automatic tracing for HTTP, database, and framework calls.
+ * Load it before your application code:
+ *
+ *   node -r ./instrumentation.ts src/index.ts
+ *
+ * Or for Next.js, this file is automatically loaded via the instrumentation hook.
+ *
+ * Configuration via environment variables:
+ *   OTEL_SERVICE_NAME          — service name (defaults to "unknown-service")
+ *   OTEL_EXPORTER_OTLP_ENDPOINT — OTLP backend URL (if not set, uses console exporter)
+ *   OTEL_EXPORTER_OTLP_HEADERS  — auth headers for the backend (e.g., "Authorization=Bearer xxx")
+ *   OTEL_ENABLED_CATEGORIES     — comma-separated categories to export (default: all)
+ */
+
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import {
+	ConsoleSpanExporter,
+	BatchSpanProcessor,
+	SimpleSpanProcessor,
+} from "@opentelemetry/sdk-trace-base";
+import { Resource } from "@opentelemetry/resources";
+import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import { FilteringExporter } from "./filtering-exporter";
+
+// Determine the span exporter based on whether an OTLP endpoint is configured
+function createSpanProcessor() {
+	if (process.env.OTEL_EXPORTER_OTLP_ENDPOINT) {
+		// OTLP endpoint configured — send traces to backend, filtered by category
+		const otlpExporter = new OTLPTraceExporter();
+		const filtered = new FilteringExporter(otlpExporter);
+		return new BatchSpanProcessor(filtered);
+	}
+	// No backend — use console exporter for local development
+	return new SimpleSpanProcessor(new ConsoleSpanExporter());
+}
+
+const sdk = new NodeSDK({
+	resource: new Resource({
+		[ATTR_SERVICE_NAME]:
+			process.env.OTEL_SERVICE_NAME ?? "unknown-service",
+	}),
+	spanProcessors: [createSpanProcessor()],
+	instrumentations: [
+		getNodeAutoInstrumentations({
+			// Disable fs instrumentation — too noisy, not useful for most apps
+			"@opentelemetry/instrumentation-fs": { enabled: false },
+			// Disable dns — rarely useful, adds noise
+			"@opentelemetry/instrumentation-dns": { enabled: false },
+		}),
+	],
+});
+
+sdk.start();
+
+// Graceful shutdown on process exit
+process.on("SIGTERM", () => {
+	sdk.shutdown().finally(() => process.exit(0));
+});

package/templates/logger.ts

@@ -0,0 +1,51 @@
+/**
+ * Structured Logger — Pino with OpenTelemetry transport
+ *
+ * Dual output:
+ *   1. stdout — always, for local dev and Docker logs
+ *   2. OTLP — when OTEL_EXPORTER_OTLP_ENDPOINT is set, sends logs to backend
+ *
+ * Usage:
+ *   import { logger } from './logger';
+ *   logger.info({ roomCode, players }, 'hand started');
+ *   logger.error({ err, traceId }, 'settlement failed');
+ *
+ * Log levels:
+ *   ERROR — something is broken, needs immediate attention
+ *   WARN  — degraded but functional, investigate soon
+ *   INFO  — business events, state transitions (the useful stuff)
+ *   DEBUG — development details, disable in production
+ */
+
+import pino from "pino";
+import type { TransportTargetOptions } from "pino";
+
+const targets: TransportTargetOptions[] = [
+	// Always log to stdout
+	{
+		target: "pino/file",
+		options: { destination: 1 },
+	},
+];
+
+// If an OTLP endpoint is configured, also send logs there
+if (process.env.OTEL_EXPORTER_OTLP_ENDPOINT) {
+	targets.push({
+		target: "pino-opentelemetry-transport",
+		options: {
+			logRecordProcessorOptions: [
+				{
+					recordProcessorType: "batch",
+					exporterOptions: {
+						protocol: "http",
+					},
+				},
+			],
+		},
+	});
+}
+
+export const logger = pino({
+	level: process.env.LOG_LEVEL ?? "info",
+	transport: { targets },
+});