@kabran-tecnologia/kabran-config 1.7.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kabran-tecnologia/kabran-config",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Shared quality configurations, enforcement scripts, and CI/CD tooling for Kabran projects",
   "author": "Kabran",
   "license": "MIT",
@@ -11,7 +11,9 @@
   "bin": {
     "kabran-setup": "src/scripts/setup.mjs",
     "kabran-ci": "src/scripts/ci/ci-runner.sh",
-    "kabran-pr-comment": "src/scripts/pr-quality-comment.mjs"
+    "kabran-pr-comment": "src/scripts/pr-quality-comment.mjs",
+    "kabran-traceability": "src/scripts/traceability/validate-traceability.sh",
+    "kabran-coverage": "src/scripts/traceability/coverage-report.sh"
   },
   "exports": {
     "./eslint": "./src/eslint.mjs",
@@ -29,6 +31,7 @@
     "./scripts/env-validator": "./src/scripts/env-validator.mjs",
     "./scripts/ci/*": "./src/scripts/ci/*",
     "./scripts/deploy/*": "./src/scripts/deploy/*",
+    "./scripts/traceability/*": "./src/scripts/traceability/*",
     "./scripts/setup": "./src/scripts/setup.mjs",
     "./scripts/quality-standard-validator": "./src/scripts/quality-standard-validator.mjs",
     "./scripts/generate-ci-result": "./src/scripts/generate-ci-result.mjs",

package/src/scripts/ci/ci-core.sh

@@ -27,6 +27,8 @@ NC='\033[0m'
 declare -a ERRORS=()
 declare -a STEP_RESULTS=()
 CI_START_TIME=""
+CI_TRACE_ID=""
+CI_SPAN_ID=""
 
 # ==============================================================================
 # Logging Functions
@@ -58,6 +60,128 @@ log_debug() {
   fi
 }
 
+# ==============================================================================
+# Trace Context Functions (OpenTelemetry W3C Trace Context)
+# ==============================================================================
+
+# Generate a random hex string of specified length
+# Usage: generate_hex_string 32
+generate_hex_string() {
+  local length="${1:-32}"
+  # Try multiple methods for generating random hex
+  if command -v openssl &>/dev/null; then
+    openssl rand -hex "$((length / 2))" 2>/dev/null
+  elif [ -r /dev/urandom ]; then
+    head -c "$((length / 2))" /dev/urandom | od -An -tx1 | tr -d ' \n' | head -c "$length"
+  else
+    # Fallback: use date + process ID + random
+    local seed="$$$(date +%s%N 2>/dev/null || date +%s)"
+    echo "$seed" | md5sum 2>/dev/null | head -c "$length" || echo "$seed" | head -c "$length"
+  fi
+}
+
+# Generate a W3C trace ID (32 hex chars = 128 bits)
+# Usage: generate_trace_id
+generate_trace_id() {
+  generate_hex_string 32
+}
+
+# Generate a W3C span ID (16 hex chars = 64 bits)
+# Usage: generate_span_id
+generate_span_id() {
+  generate_hex_string 16
+}
+
+# Initialize trace context for the CI run
+# Sets TRACEPARENT env var if not already set
+# Format: 00-{trace_id}-{span_id}-{flags}
+# Usage: setup_trace_context
+setup_trace_context() {
+  # Check if trace context already exists from environment
+  if [ -n "${TRACEPARENT:-}" ]; then
+    log_debug "Using existing TRACEPARENT: $TRACEPARENT"
+    # Extract trace_id and span_id from existing TRACEPARENT
+    CI_TRACE_ID=$(echo "$TRACEPARENT" | cut -d'-' -f2)
+    CI_SPAN_ID=$(echo "$TRACEPARENT" | cut -d'-' -f3)
+    return 0
+  fi
+
+  # Check for direct trace ID from environment
+  if [ -n "${OTEL_TRACE_ID:-}" ]; then
+    log_debug "Using OTEL_TRACE_ID: $OTEL_TRACE_ID"
+    CI_TRACE_ID="$OTEL_TRACE_ID"
+    CI_SPAN_ID=$(generate_span_id)
+    TRACEPARENT="00-${CI_TRACE_ID}-${CI_SPAN_ID}-01"
+    export TRACEPARENT
+    return 0
+  fi
+
+  # Check for GitHub Actions run ID (use as fallback correlation)
+  if [ -n "${GITHUB_RUN_ID:-}" ]; then
+    log_debug "Using GitHub run ID for trace correlation"
+    # Create deterministic trace_id from GitHub run info
+    local gh_seed="${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT:-1}"
+    CI_TRACE_ID=$(echo "$gh_seed" | md5sum | head -c 32)
+    CI_SPAN_ID=$(generate_span_id)
+    TRACEPARENT="00-${CI_TRACE_ID}-${CI_SPAN_ID}-01"
+    export TRACEPARENT
+    log_debug "Generated TRACEPARENT from GitHub: $TRACEPARENT"
+    return 0
+  fi
+
+  # Generate new trace context for local execution
+  log_debug "Generating new trace context for local CI run"
+  CI_TRACE_ID=$(generate_trace_id)
+  CI_SPAN_ID=$(generate_span_id)
+  TRACEPARENT="00-${CI_TRACE_ID}-${CI_SPAN_ID}-01"
+  export TRACEPARENT
+
+  log_info "Trace ID: ${CI_TRACE_ID:0:8}... (local)"
+  log_debug "Full TRACEPARENT: $TRACEPARENT"
+  return 0
+}
+
+# Get the current trace ID
+# Usage: get_trace_id
+get_trace_id() {
+  echo "${CI_TRACE_ID:-}"
+}
+
+# Get trace context info for metadata
+# Usage: get_trace_context_json
+get_trace_context_json() {
+  local trace_id="${CI_TRACE_ID:-}"
+  local span_id="${CI_SPAN_ID:-}"
+  local traceparent="${TRACEPARENT:-}"
+
+  if [ -z "$trace_id" ]; then
+    echo "null"
+    return
+  fi
+
+  # Determine source of trace context
+  local source="local"
+  if [ -n "${GITHUB_RUN_ID:-}" ]; then
+    source="github"
+  elif [ -n "${OTEL_TRACE_ID:-}" ]; then
+    source="otel_env"
+  elif [ -n "${TRACEPARENT:-}" ] && [ "${CI_TRACE_ID:-}" != "$(echo "$TRACEPARENT" | cut -d'-' -f2)" ]; then
+    source="external"
+  fi
+
+  jq -n \
+    --arg trace_id "$trace_id" \
+    --arg span_id "$span_id" \
+    --arg traceparent "$traceparent" \
+    --arg source "$source" \
+    '{
+      trace_id: $trace_id,
+      span_id: $span_id,
+      traceparent: $traceparent,
+      source: $source
+    }'
+}
+
 # ==============================================================================
 # Version Compatibility Check
 # ==============================================================================
@@ -432,6 +556,10 @@ export_ci_data() {
   # Get scope
   local scope="${CI_SCOPE:-all}"
 
+  # Get trace context
+  local trace_context
+  trace_context=$(get_trace_context_json)
+
   # Generate intermediate data file for Node.js generator
   jq -n \
     --argjson steps "$steps_json" \
@@ -441,6 +569,7 @@ export_ci_data() {
     --arg finished_at "$now" \
     --arg project_name "$project_name" \
     --arg scope "$scope" \
+    --argjson trace_context "$trace_context" \
     '{
       steps: $steps,
       errors: $errors,
@@ -454,7 +583,8 @@ export_ci_data() {
       },
       metadata: {
         scope: $scope
-      }
+      },
+      trace_context: $trace_context
     }' > "$output_file"
 
   log_debug "CI data exported to: $output_file"

package/src/scripts/ci/ci-runner.sh

@@ -171,6 +171,9 @@ if [ "$CI_SCOPE" != "all" ]; then
 fi
 echo ""
 
+# Setup trace context (generates trace_id if not provided externally)
+setup_trace_context
+
 # Start timing
 ci_start
 

package/src/scripts/generate-ci-result.mjs

@@ -177,8 +177,9 @@ export function generateCiResult(input) {
   // Determine exit code
   const exitCode = executionStats.steps_failed > 0 ? 1 : 0
 
-  // Get trace ID if available
-  const traceId = getTraceId()
+  // Get trace ID - prefer trace_context from input (shell-generated) over env vars
+  const traceContext = input.trace_context || {}
+  const traceId = traceContext.trace_id || getTraceId()
 
   // Build meta object
   const meta = {
@@ -198,7 +199,19 @@ export function generateCiResult(input) {
   // Build extensions with telemetry if trace_id exists
   const extensions = { ...(metadata.extensions || {}) }
   if (traceId) {
-    extensions.telemetry = buildTelemetryExtension(traceId)
+    // Count errors from failed steps
+    const errorsRecorded = executionStats.steps_failed || 0
+
+    extensions.telemetry = buildTelemetryExtension(traceId, {
+      errorsRecorded,
+      // spans_exported remains 0 until we implement actual OTel export (GAP-004/Q12)
+      spansExported: 0,
+    })
+
+    // Add trace source info if available
+    if (traceContext.source) {
+      extensions.telemetry.trace_source = traceContext.source
+    }
   }
 
   // Build result object

package/src/scripts/traceability/coverage-report.sh

@@ -0,0 +1,222 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# Kabran Traceability Coverage Report
+# Part of @kabran-owner/kabran-config
+# Implements PROP-006: JSDoc Traceability Tags
+#
+# Generates a report of spec coverage in the codebase.
+# Shows which specs have code implementing them and which ACs are covered.
+# ==============================================================================
+
+set -euo pipefail
+
+# Source core functions
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=traceability-core.sh
+source "$SCRIPT_DIR/traceability-core.sh"
+
+# ==============================================================================
+# Configuration
+# ==============================================================================
+
+SEARCH_PATH="${1:-.}"
+SPEC_FILTER="${2:-}"
+OUTPUT_FORMAT="${OUTPUT_FORMAT:-text}"
+
+# ==============================================================================
+# Report Functions
+# ==============================================================================
+
+# Generate report for a specific spec
+report_spec() {
+  local spec="$1"
+  local files
+
+  files=$(grep -rl "@spec $spec" --include="*.ts" --include="*.tsx" "$SEARCH_PATH" 2>/dev/null || true)
+
+  if [ -z "$files" ]; then
+    return
+  fi
+
+  echo ""
+  echo "=== $spec ==="
+  echo ""
+  echo "Files:"
+  echo "$files" | while read -r file; do
+    [ -n "$file" ] && echo "  - $file"
+  done
+
+  echo ""
+  echo "ACs Implemented:"
+  echo "$files" | while read -r file; do
+    [ -n "$file" ] && extract_implements "$file"
+  done | sort -u | while read -r ac; do
+    [ -n "$ac" ] && echo "  - $ac"
+  done
+}
+
+# Generate summary report
+report_summary() {
+  log_section "Traceability Coverage Report v${TRACEABILITY_VERSION}"
+  log_info "Search path: $SEARCH_PATH"
+  echo ""
+
+  local total_files
+  local tagged_files
+  local specs
+
+  total_files=$(count_total_files "$SEARCH_PATH")
+  tagged_files=$(count_tagged_files "$SEARCH_PATH")
+
+  echo "## Overview"
+  echo ""
+  echo "| Metric | Value |"
+  echo "|--------|-------|"
+  echo "| Total TypeScript files | $total_files |"
+  echo "| Files with @spec | $tagged_files |"
+
+  if [ "$total_files" -gt 0 ]; then
+    local coverage=$((tagged_files * 100 / total_files))
+    echo "| Coverage | $coverage% |"
+  fi
+
+  echo ""
+  echo "## Specs Found"
+  echo ""
+
+  # Find all unique specs
+  specs=$(grep -roh '@spec S[0-9]*' --include="*.ts" --include="*.tsx" "$SEARCH_PATH" 2>/dev/null | sed 's/@spec //' | sort -u || true)
+
+  if [ -z "$specs" ]; then
+    echo "No @spec tags found in codebase."
+    return
+  fi
+
+  echo "$specs" | while read -r spec; do
+    if [ -n "$spec" ]; then
+      local file_count
+      file_count=$(grep -rl "@spec $spec" --include="*.ts" --include="*.tsx" "$SEARCH_PATH" 2>/dev/null | wc -l)
+      echo "- **$spec**: $file_count files"
+    fi
+  done
+}
+
+# Generate detailed report for all specs
+report_detailed() {
+  report_summary
+
+  echo ""
+  echo "## Detailed Coverage"
+
+  local specs
+  specs=$(grep -roh '@spec S[0-9]*' --include="*.ts" --include="*.tsx" "$SEARCH_PATH" 2>/dev/null | sed 's/@spec //' | sort -u || true)
+
+  if [ -n "$specs" ]; then
+    echo "$specs" | while read -r spec; do
+      [ -n "$spec" ] && report_spec "$spec"
+    done
+  fi
+}
+
+# Generate JSON report
+report_json() {
+  local total_files
+  local tagged_files
+  local specs
+
+  total_files=$(count_total_files "$SEARCH_PATH")
+  tagged_files=$(count_tagged_files "$SEARCH_PATH")
+  specs=$(grep -roh '@spec S[0-9]*' --include="*.ts" --include="*.tsx" "$SEARCH_PATH" 2>/dev/null | sed 's/@spec //' | sort -u || true)
+
+  local coverage=0
+  if [ "$total_files" -gt 0 ]; then
+    coverage=$((tagged_files * 100 / total_files))
+  fi
+
+  echo "{"
+  echo "  \"version\": \"${TRACEABILITY_VERSION}\","
+  echo "  \"searchPath\": \"$SEARCH_PATH\","
+  echo "  \"totalFiles\": $total_files,"
+  echo "  \"taggedFiles\": $tagged_files,"
+  echo "  \"coverage\": $coverage,"
+  echo "  \"specs\": ["
+
+  local first=true
+  if [ -n "$specs" ]; then
+    echo "$specs" | while read -r spec; do
+      if [ -n "$spec" ]; then
+        local file_count
+        file_count=$(grep -rl "@spec $spec" --include="*.ts" --include="*.tsx" "$SEARCH_PATH" 2>/dev/null | wc -l)
+        if [ "$first" = true ]; then
+          first=false
+        else
+          echo ","
+        fi
+        echo -n "    { \"id\": \"$spec\", \"files\": $file_count }"
+      fi
+    done
+  fi
+
+  echo ""
+  echo "  ]"
+  echo "}"
+}
+
+# ==============================================================================
+# Help
+# ==============================================================================
+
+show_help() {
+  cat << EOF
+Kabran Traceability Coverage Report v${TRACEABILITY_VERSION}
+
+Usage: coverage-report.sh [path] [spec] [options]
+
+Arguments:
+  path              Directory to scan (default: current directory)
+  spec              Filter by specific spec ID (e.g., S25)
+
+Environment Variables:
+  OUTPUT_FORMAT     Output format: text, detailed, json (default: text)
+
+Examples:
+  coverage-report.sh ./src
+  coverage-report.sh ./src S25
+  OUTPUT_FORMAT=json coverage-report.sh ./src
+  OUTPUT_FORMAT=detailed coverage-report.sh ./src
+
+Output Formats:
+  text              Summary with spec counts
+  detailed          Full breakdown with files and ACs per spec
+  json              Machine-readable JSON output
+
+EOF
+}
+
+# ==============================================================================
+# Entry Point
+# ==============================================================================
+
+if [[ "${1:-}" == "--help" ]] || [[ "${1:-}" == "-h" ]]; then
+  show_help
+  exit 0
+fi
+
+# Handle specific spec filter
+if [ -n "$SPEC_FILTER" ]; then
+  report_spec "$SPEC_FILTER"
+  exit 0
+fi
+
+# Generate report based on format
+case "$OUTPUT_FORMAT" in
+  json)
+    report_json
+    ;;
+  detailed)
+    report_detailed
+    ;;
+  *)
+    report_summary
+    ;;
+esac

package/src/scripts/traceability/traceability-core.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# Kabran Traceability Core - Shared Functions
+# Part of @kabran-owner/kabran-config
+# Implements PROP-006: JSDoc Traceability Tags
+# ==============================================================================
+
+# Version - Dynamically resolve from package.json
+_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+_PKG_JSON="$_SCRIPT_DIR/../../../package.json"
+if [ -f "$_PKG_JSON" ]; then
+  TRACEABILITY_VERSION=$(grep '"version":' "$_PKG_JSON" | head -1 | sed -E 's/.*"version": "([^"]+)".*/\1/')
+else
+  TRACEABILITY_VERSION="unknown"
+fi
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+GRAY='\033[0;90m'
+NC='\033[0m'
+
+# ==============================================================================
+# Logging Functions
+# ==============================================================================
+
+log_info() {
+  echo -e "${BLUE}[INFO]${NC} $1"
+}
+
+log_success() {
+  echo -e "${GREEN}[PASS]${NC} $1"
+}
+
+log_error() {
+  echo -e "${RED}[FAIL]${NC} $1"
+}
+
+log_warn() {
+  echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+log_section() {
+  echo -e "\n${BLUE}====${NC} $1 ${BLUE}====${NC}"
+}
+
+# ==============================================================================
+# Tag Patterns (PROP-006 Standard)
+# ==============================================================================
+
+# Valid @spec format: @spec SXX (ID only, not full name)
+PATTERN_SPEC_VALID='@spec S[0-9]+'
+PATTERN_SPEC_INVALID='@spec S[0-9]+-'
+
+# Valid @implements format: @implements AC-XX or @implements SXX:AC-XX
+PATTERN_IMPLEMENTS='@implements'
+
+# Valid @task format: @task XXX-NNN
+PATTERN_TASK='@task [A-Z]+-[0-9]+'
+
+# Valid @prd format: @prd RF-XXX or @prd RNF-XXX
+PATTERN_PRD='@prd R(N)?F-[0-9]+'
+
+# ==============================================================================
+# Validation Functions
+# ==============================================================================
+
+# Check if a file has @implements without @spec (integrity error)
+# Usage: check_orphan_implements "path/to/file.ts"
+# Returns: 0 if valid, 1 if orphan found
+check_orphan_implements() {
+  local file="$1"
+
+  if grep -qE "$PATTERN_IMPLEMENTS" "$file" 2>/dev/null; then
+    if ! grep -qE "$PATTERN_SPEC_VALID" "$file" 2>/dev/null; then
+      return 1  # Orphan found
+    fi
+  fi
+  return 0  # Valid
+}
+
+# Check if a file uses invalid @spec format (full name instead of ID)
+# Usage: check_spec_format "path/to/file.ts"
+# Returns: 0 if valid, 1 if invalid format found
+check_spec_format() {
+  local file="$1"
+
+  if grep -qE "$PATTERN_SPEC_INVALID" "$file" 2>/dev/null; then
+    return 1  # Invalid format
+  fi
+  return 0  # Valid
+}
+
+# Extract all @spec tags from a file
+# Usage: extract_specs "path/to/file.ts"
+extract_specs() {
+  local file="$1"
+  grep -oE '@spec S[0-9]+' "$file" 2>/dev/null | sed 's/@spec //' | sort -u
+}
+
+# Extract all @implements tags from a file
+# Usage: extract_implements "path/to/file.ts"
+extract_implements() {
+  local file="$1"
+  grep -oE '@implements [^*]+' "$file" 2>/dev/null | sed 's/@implements //' | tr ',' '\n' | sed 's/^ *//' | sort -u
+}
+
+# Count files with traceability tags
+# Usage: count_tagged_files "path/to/search"
+count_tagged_files() {
+  local search_path="${1:-.}"
+  grep -rl "@spec" --include="*.ts" --include="*.tsx" "$search_path" 2>/dev/null | wc -l
+}
+
+# Count total TypeScript files
+# Usage: count_total_files "path/to/search"
+count_total_files() {
+  local search_path="${1:-.}"
+  find "$search_path" -type f \( -name "*.ts" -o -name "*.tsx" \) 2>/dev/null | wc -l
+}

package/src/scripts/traceability/validate-traceability.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# Kabran Traceability Validator
+# Part of @kabran-owner/kabran-config
+# Implements PROP-006: JSDoc Traceability Tags
+#
+# Validates FORMAT of traceability tags (not presence).
+# Tags are optional - this script only checks:
+# 1. @implements without @spec (integrity error)
+# 2. @spec with full name instead of ID (format warning)
+# ==============================================================================
+
+set -uo pipefail
+
+# Source core functions
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=traceability-core.sh
+source "$SCRIPT_DIR/traceability-core.sh"
+
+# ==============================================================================
+# Configuration
+# ==============================================================================
+
+SEARCH_PATH="${1:-.}"
+STRICT_MODE="${STRICT_MODE:-false}"
+EXIT_CODE=0
+
+# ==============================================================================
+# Main Validation
+# ==============================================================================
+
+main() {
+  log_section "Traceability Validation v${TRACEABILITY_VERSION}"
+  log_info "Search path: $SEARCH_PATH"
+  log_info "Strict mode: $STRICT_MODE"
+
+  local orphan_count=0
+  local format_count=0
+  local files_checked=0
+
+  # Find all TypeScript files
+  local files
+  files=$(find "$SEARCH_PATH" -type f \( -name "*.ts" -o -name "*.tsx" \) 2>/dev/null || true)
+
+  if [ -z "$files" ]; then
+    log_info "No TypeScript files found"
+    return 0
+  fi
+
+  while IFS= read -r file; do
+    [ -z "$file" ] && continue
+    files_checked=$((files_checked + 1))
+
+    # Check for orphan @implements (ERROR)
+    if ! check_orphan_implements "$file"; then
+      log_error "Orphan @implements (no @spec): $file"
+      orphan_count=$((orphan_count + 1))
+    fi
+
+    # Check for invalid @spec format (WARNING)
+    if ! check_spec_format "$file"; then
+      log_warn "Invalid @spec format (use ID only): $file"
+      format_count=$((format_count + 1))
+    fi
+
+  done <<< "$files"
+
+  # Summary
+  log_section "Validation Summary"
+  log_info "Files checked: $files_checked"
+
+  if [ "$orphan_count" -gt 0 ]; then
+    log_error "Orphan @implements found: $orphan_count"
+    EXIT_CODE=1
+  else
+    log_success "No orphan @implements found"
+  fi
+
+  if [ "$format_count" -gt 0 ]; then
+    log_warn "Invalid @spec format: $format_count"
+    if [ "$STRICT_MODE" = "true" ]; then
+      EXIT_CODE=1
+    fi
+  else
+    log_success "All @spec tags use correct format"
+  fi
+
+  # Coverage stats (informational)
+  local tagged_files
+  local total_files
+  tagged_files=$(count_tagged_files "$SEARCH_PATH")
+  total_files=$(count_total_files "$SEARCH_PATH")
+
+  if [ "$total_files" -gt 0 ]; then
+    local coverage=$((tagged_files * 100 / total_files))
+    log_info "Traceability coverage: $tagged_files/$total_files files ($coverage%)"
+  fi
+
+  return $EXIT_CODE
+}
+
+# ==============================================================================
+# Help
+# ==============================================================================
+
+show_help() {
+  cat << EOF
+Kabran Traceability Validator v${TRACEABILITY_VERSION}
+
+Usage: validate-traceability.sh [path] [options]
+
+Arguments:
+  path              Directory to validate (default: current directory)
+
+Environment Variables:
+  STRICT_MODE       If "true", format warnings become errors (default: false)
+
+Exit Codes:
+  0                 Validation passed
+  1                 Validation failed (orphan @implements or strict mode violations)
+
+Examples:
+  validate-traceability.sh ./src
+  STRICT_MODE=true validate-traceability.sh ./src
+
+Tags Validated (PROP-006):
+  @spec S25         Link to spec (ID only, not full name)
+  @implements AC-01 Acceptance criteria implemented
+  @task AGT-123     Link to Linear task
+  @prd RF-007       Link to PRD requirement
+
+Rules:
+  - All tags are OPTIONAL
+  - @implements WITHOUT @spec is an ERROR
+  - @spec with full name (S25-name) is a WARNING
+
+EOF
+}
+
+# ==============================================================================
+# Entry Point
+# ==============================================================================
+
+if [[ "${1:-}" == "--help" ]] || [[ "${1:-}" == "-h" ]]; then
+  show_help
+  exit 0
+fi
+
+main
+exit $EXIT_CODE

package/src/telemetry/README.md

@@ -0,0 +1,407 @@
+# @kabran-tecnologia/kabran-config/telemetry
+
+Unified telemetry package for Kabran projects using OpenTelemetry.
+
+## Features
+
+- **Multi-runtime support**: Node.js, Frontend (Browser), Edge/Serverless
+- **OpenTelemetry integration**: W3C Trace Context, OTLP export
+- **Zero-config defaults**: Works out of the box with sensible defaults
+- **Structured logging**: Logger with automatic trace correlation
+- **Tree-shakeable**: Import only what you need
+
+## Installation
+
+The telemetry modules are included in `@kabran-tecnologia/kabran-config`. Install the package and the required OpenTelemetry peer dependencies:
+
+```bash
+# Install kabran-config
+npm install @kabran-tecnologia/kabran-config
+
+# Install required peer dependencies (pick based on your runtime)
+
+# For Node.js:
+npm install @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources @opentelemetry/semantic-conventions
+
+# For Frontend:
+npm install @opentelemetry/api @opentelemetry/sdk-trace-web @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources @opentelemetry/semantic-conventions @opentelemetry/instrumentation-fetch @opentelemetry/instrumentation-document-load @opentelemetry/instrumentation-user-interaction
+
+# For Edge/Serverless:
+npm install @opentelemetry/api @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources @opentelemetry/semantic-conventions
+```
+
+## Quick Start
+
+### Node.js (Express/Fastify)
+
+```javascript
+// instrumentation.js - Import this FIRST in your app
+import { initTelemetry, telemetryMiddleware, shutdownTelemetry } from '@kabran-tecnologia/kabran-config/telemetry/node'
+
+// Initialize telemetry
+initTelemetry({
+  serviceName: 'my-api',
+  serviceVersion: '1.0.0',
+})
+
+// In your Express app
+import express from 'express'
+const app = express()
+
+// Add telemetry middleware (creates spans for each request)
+app.use(telemetryMiddleware())
+
+app.get('/api/users', (req, res) => {
+  // Your handler - automatically traced
+  res.json({ users: [] })
+})
+
+// Graceful shutdown
+process.on('SIGTERM', async () => {
+  await shutdownTelemetry()
+  process.exit(0)
+})
+```
+
+### Frontend (React/Vite)
+
+```typescript
+// main.tsx
+import { initTelemetry } from '@kabran-tecnologia/kabran-config/telemetry/frontend'
+
+// Initialize before rendering
+initTelemetry({
+  serviceName: 'my-frontend',
+  serviceVersion: '1.0.0',
+  // Optional: customize which events to trace
+  instrumentation: {
+    userInteractionEvents: ['click', 'submit'],
+  },
+})
+
+// Your React app renders normally
+import { createRoot } from 'react-dom/client'
+import App from './App'
+
+createRoot(document.getElementById('root')!).render(<App />)
+```
+
+### Edge/Serverless (Supabase Functions)
+
+```typescript
+// supabase/functions/my-function/index.ts
+import { withTelemetry, traceSupabaseQuery } from '@kabran-tecnologia/kabran-config/telemetry/edge'
+import { createClient } from '@supabase/supabase-js'
+
+const supabase = createClient(
+  Deno.env.get('SUPABASE_URL')!,
+  Deno.env.get('SUPABASE_ANON_KEY')!
+)
+
+// Wrap your handler with telemetry
+Deno.serve(withTelemetry(
+  {
+    serviceName: 'my-edge-function',
+    serviceVersion: '1.0.0',
+  },
+  async (req) => {
+    // Trace Supabase queries
+    const { data, error } = await traceSupabaseQuery(
+      'select-users',
+      () => supabase.from('users').select('*')
+    )
+
+    return new Response(JSON.stringify({ data, error }), {
+      headers: { 'Content-Type': 'application/json' },
+    })
+  }
+))
+```
+
+## Structured Logging
+
+The logger automatically includes trace context in log output:
+
+```javascript
+import { createLogger } from '@kabran-tecnologia/kabran-config/telemetry/logger'
+
+const log = createLogger()
+
+log.info('User logged in', { userId: '123' })
+// Output (JSON in production):
+// {"level":"info","message":"User logged in","userId":"123","trace_id":"abc123...","span_id":"def456...","timestamp":"2024-01-13T..."}
+
+// Output (pretty in development):
+// 2024-01-13T12:00:00.000Z [INFO] User logged in [trace:abc123...] {"userId":"123"}
+```
+
+### Span-bound Logger
+
+```javascript
+import { trace } from '@opentelemetry/api'
+import { createSpanLogger } from '@kabran-tecnologia/kabran-config/telemetry/logger'
+
+const span = trace.getActiveSpan()
+const log = createSpanLogger(span)
+
+log.info('Processing order', { orderId: '456' })
+// Logs are also added as span events for visibility in traces
+```
+
+## Configuration
+
+### Environment Variables
+
+All configuration can be set via environment variables:
+
+```bash
+# Core
+SERVICE_NAME=my-service              # Required: Your service name
+SERVICE_VERSION=1.0.0                # Service version (default: 1.0.0)
+ENVIRONMENT=production               # Environment name (default: from NODE_ENV)
+OTEL_NAMESPACE=kabran                # Service namespace (default: kabran)
+
+# OTLP Exporter
+OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.kabran.com.br  # Collector endpoint
+OTEL_EXPORTER_OTLP_TIMEOUT=10000     # Export timeout in ms (default: 10000)
+
+# Sampling
+OTEL_SAMPLE_RATE=0.1                 # Sampling rate 0.0-1.0 (default: 0.1 = 10%)
+
+# Enable/Disable
+OTEL_ENABLED=true                    # Enable telemetry (default: true in production)
+
+# Logger
+OTEL_LOG_TRACE_ID_LENGTH=8           # Trace ID length in logs (default: 8)
+NO_COLOR=1                           # Disable ANSI colors in logs
+```
+
+### Programmatic Configuration
+
+```javascript
+import { initTelemetry } from '@kabran-tecnologia/kabran-config/telemetry/node'
+
+initTelemetry({
+  // Required
+  serviceName: 'my-service',
+
+  // Optional (all have sensible defaults)
+  serviceVersion: '1.0.0',
+  environment: 'production',
+  endpoint: 'https://otel.kabran.com.br',
+  sampleRate: 0.1,
+  enabled: true,
+
+  // Resource attributes (added to all spans)
+  resourceAttributes: {
+    'deployment.environment': 'production',
+    'service.instance.id': process.env.POD_NAME,
+  },
+
+  // Batch processor settings (Node.js only)
+  batchProcessor: {
+    maxQueueSize: 2048,
+    maxExportBatchSize: 512,
+    scheduledDelayMillis: 5000,
+  },
+})
+```
+
+## Module Reference
+
+### `telemetry/node`
+
+For Node.js servers and long-running processes.
+
+```javascript
+import {
+  initTelemetry,      // Initialize the tracer
+  shutdownTelemetry,  // Graceful shutdown
+  telemetryMiddleware,// Express/Fastify middleware
+  isInitialized,      // Check if initialized
+  getTracer,          // Get the tracer instance
+  getConfig,          // Get resolved config
+} from '@kabran-tecnologia/kabran-config/telemetry/node'
+```
+
+### `telemetry/frontend`
+
+For browser applications (React, Vue, vanilla JS).
+
+```javascript
+import {
+  initTelemetry,      // Initialize the tracer
+  shutdownTelemetry,  // Flush pending spans
+  isInitialized,      // Check if initialized
+  getTracer,          // Get the tracer instance
+  getConfig,          // Get resolved config
+} from '@kabran-tecnologia/kabran-config/telemetry/frontend'
+```
+
+### `telemetry/edge`
+
+For Edge Functions and serverless (Supabase, Deno Deploy, Cloudflare Workers).
+
+```javascript
+import {
+  withTelemetry,      // Handler wrapper with auto-tracing
+  traceSupabaseQuery, // Trace Supabase queries
+  shutdownTelemetry,  // Flush pending spans
+  isInitialized,      // Check if initialized
+  getConfig,          // Get resolved config
+} from '@kabran-tecnologia/kabran-config/telemetry/edge'
+```
+
+### `telemetry/logger`
+
+Structured logger with trace correlation.
+
+```javascript
+import {
+  createLogger,       // Create a logger instance
+  createSpanLogger,   // Create a span-bound logger
+  log,                // Default logger instance
+  getTraceContext,    // Get current trace context
+} from '@kabran-tecnologia/kabran-config/telemetry/logger'
+```
+
+### `telemetry/config`
+
+Configuration utilities.
+
+```javascript
+import {
+  defineTelemetryConfig,  // Create a type-safe config
+  resolveConfig,          // Resolve config with defaults and env vars
+  validateConfig,         // Validate config object
+  detectEnabled,          // Check if telemetry should be enabled
+} from '@kabran-tecnologia/kabran-config/telemetry/config'
+```
+
+### `telemetry/shared`
+
+Shared utilities and types.
+
+```javascript
+import {
+  setAttributes,         // Set multiple span attributes
+  formatDuration,        // Format milliseconds to human-readable
+  generateInvocationId,  // Generate unique invocation ID
+  safeWarn,              // Safe console.warn
+  safeLog,               // Safe console.log
+} from '@kabran-tecnologia/kabran-config/telemetry/shared'
+```
+
+## Integration with Kosmos Observability
+
+This package is designed to work with the Kosmos observability stack:
+
+- **Traces** → Grafana Tempo
+- **Logs** → Grafana Loki (via stdout/Promtail or direct export)
+- **Metrics** → Prometheus (planned, see [GAP-006])
+
+Default endpoint: `https://otel.kabran.com.br`
+
+### Viewing Traces
+
+1. Open Grafana at your Kosmos instance
+2. Go to Explore → Select Tempo
+3. Search by service name or trace ID
+
+## Best Practices
+
+### 1. Initialize Early
+
+Initialize telemetry as early as possible in your application:
+
+```javascript
+// This should be the FIRST import
+import './instrumentation.js'
+
+// Then your app code
+import express from 'express'
+```
+
+### 2. Use Meaningful Span Names
+
+```javascript
+// Good
+span.updateName('user.create')
+span.updateName('order.process')
+
+// Bad
+span.updateName('handler')
+span.updateName('function1')
+```
+
+### 3. Add Relevant Attributes
+
+```javascript
+import { trace } from '@opentelemetry/api'
+
+const span = trace.getActiveSpan()
+span?.setAttributes({
+  'user.id': userId,
+  'order.id': orderId,
+  'order.total': total,
+})
+```
+
+### 4. Handle Errors Properly
+
+```javascript
+import { trace, SpanStatusCode } from '@opentelemetry/api'
+
+try {
+  // Your code
+} catch (error) {
+  const span = trace.getActiveSpan()
+  span?.recordException(error)
+  span?.setStatus({ code: SpanStatusCode.ERROR, message: error.message })
+  throw error
+}
+```
+
+### 5. Graceful Shutdown
+
+Always flush pending spans before shutdown:
+
+```javascript
+process.on('SIGTERM', async () => {
+  await shutdownTelemetry()
+  process.exit(0)
+})
+```
+
+## Troubleshooting
+
+### Traces not appearing
+
+1. Check `OTEL_ENABLED` is not set to `false`
+2. Verify `SERVICE_NAME` is set
+3. Check network connectivity to the collector endpoint
+4. Verify sampling rate (default is 10%)
+
+### Missing trace correlation in logs
+
+1. Ensure telemetry is initialized before logging
+2. Check that you're within an active span context
+
+### High memory usage
+
+Reduce batch processor queue size:
+
+```javascript
+initTelemetry({
+  serviceName: 'my-service',
+  batchProcessor: {
+    maxQueueSize: 512,  // Lower from default 2048
+  },
+})
+```
+
+## Related Documentation
+
+- [OpenTelemetry JavaScript](https://opentelemetry.io/docs/languages/js/)
+- [W3C Trace Context](https://www.w3.org/TR/trace-context/)
+- [Kosmos Observability Stack](https://github.com/kabran-owner/kosmos/tree/main/services/observability)