---
name: report_execution_json
kind: function
lang: bash
domain: shell
version: "2.0.0"
purity: pure
signature: "report_execution_json(flow_name: string, status: string, exit_code: int, started_at: string, ended_at: string, duration_ms: int, steps_file: string) -> string"
description: "Genera un JSON de reporte de ejecucion siguiendo el estandar fn-registry (docs/execution_standard.md). Recibe los metadatos del flujo y un archivo TSV con resultados de pasos (columnas: name, action, status, elapsed_ms, output, error). Imprime el JSON completo a stdout. Usa jq si esta disponible, con fallback a printf. Funcion pura: sin efectos secundarios ni I/O adicional."
tags: [execution, json, report, standard, shell, pure]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: []
params:
  - name: flow_name
    desc: "nombre del flujo ejecutado"
  - name: status
    desc: "estado final: success, failure, o partial"
  - name: exit_code
    desc: "código de salida: 0, 1, o 2"
  - name: started_at
    desc: "timestamp ISO8601 de inicio"
  - name: ended_at
    desc: "timestamp ISO8601 de fin"
  - name: duration_ms
    desc: "duración total en milisegundos"
  - name: steps_file
    desc: "archivo TSV con resultados de cada paso"
output: "JSON estructurado con metadatos de ejecución y array de pasos"
tested: false
tests: []
test_file_path: ""
file_path: "bash/functions/shell/report_execution_json.sh"
---

## Ejemplo

```bash
source bash/functions/shell/report_execution_json.sh

# Crear archivo de pasos (TSV sin cabecera, 6 columnas)
cat > /tmp/steps.tsv <<'EOF'
check_db	command	ok	10	exists
backup	command	ok	450	done
push	command	error	2540		remote rejected
EOF

report_execution_json \
    "backup_db" "partial" 2 \
    "2026-04-01T02:00:00Z" "2026-04-01T02:00:03Z" 3000 \
    /tmp/steps.tsv
```

Output esperado:

```json
{"name":"backup_db","status":"partial","exit_code":2,"started_at":"2026-04-01T02:00:00Z","ended_at":"2026-04-01T02:00:03Z","duration_ms":3000,"steps_total":3,"steps_ok":2,"steps_failed":1,"steps":[{"name":"check_db","action":"command","status":"ok","elapsed_ms":10,"output":"exists"},{"name":"backup","action":"command","status":"ok","elapsed_ms":450,"output":"done"},{"name":"push","action":"command","status":"error","elapsed_ms":2540,"error":"remote rejected"}]}
```

## Notas

Funcion pura: solo lee el archivo de pasos y escribe JSON a stdout, sin efectos secundarios ni I/O adicional mas alla de leer el steps_file.

Formato TSV: 6 columnas separadas por tabulador real (sin cabecera): name, action, status (ok|error), elapsed_ms, output, error. Los campos output y error pueden estar vacios; se omiten del JSON si no tienen valor, siguiendo el estandar de output estructurado.

El caller es responsable de calcular status (success|failure|partial) y exit_code (0|1|2) segun las reglas del estandar. Ver exit_with_status_bash_shell para esa logica.

Compatibilidad dual: con jq construye el JSON de forma robusta (maneja caracteres especiales y saltos de linea en output/error). Sin jq, el fallback con printf escapa backslash, comillas dobles y caracteres de control basicos.

Puede ejecutarse directamente: `bash report_execution_json.sh <args>`.