docs(flows): DoD obligatorio con user-facing surface + abrir issues 0100-0103 (taxonomia, frontmatter migration, dev_console, work dashboard)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-17 00:07:03 +02:00
parent a03675113a
commit 6ad82167bb
72 changed files with 3920 additions and 303 deletions
@@ -3,7 +3,7 @@ name: launch_cpp_app_windows
 kind: function
 lang: bash
 domain: infra
-version: "1.0.0"
+version: "1.1.0"
 purity: impure
 signature: "launch_cpp_app_windows(app_name: string, [desktop_dir: string]) -> void"
 description: "Lanza un binario .exe en Windows desde WSL2. Asume que deploy_cpp_exe_to_windows ya copió el exe a Desktop/apps/<app_name>/. Usa cmd.exe /c start para desacoplar el proceso y retornar inmediatamente."
@@ -68,3 +68,13 @@ launch_cpp_app_windows "registry_dashboard"
 ```

 No se incluyen tests automatizados porque requieren entorno WSL2 con Windows activo y no son automatizables en CI.
+
+## Gotchas
+
+- Si `FN_REGISTRY_ROOT_WSL` no es tu ruta default de fn_registry (`/home/<user>/fn_registry`), setea la variable antes de invocar esta función: `FN_REGISTRY_ROOT_WSL=/ruta/custom launch_cpp_app_windows <app>`.
+- El proceso hijo hereda `FN_REGISTRY_ROOT` como path Windows (backslashes) y `FN_REGISTRY_ROOT_WSL` como path Linux. En el exe C++, `py_resolve_interpreter()` usa `FN_REGISTRY_ROOT_WSL` para construir el invocation `wsl.exe -- /path/python3`.
+- PowerShell escapa `$` con `\$` para evitar expansión de variables en el string del comando.
+
+## Capability growth log
+
+- v1.1.0 (2026-05-16) — auto-propaga `FN_REGISTRY_ROOT` (Windows path) + `FN_REGISTRY_ROOT_WSL` (Linux path) al proceso hijo para que pueda invocar WSL python via `wsl.exe`.
@@ -1,6 +1,8 @@
 #!/usr/bin/env bash
-# launch_cpp_app_windows — Lanza un .exe en Windows desde WSL2 via cmd.exe /c start.
+# launch_cpp_app_windows v1.1.0 — Lanza un .exe en Windows desde WSL2 via PowerShell.
 # Asume que el exe ya fue copiado por deploy_cpp_exe_to_windows al escritorio.
+# v1.1.0: propaga FN_REGISTRY_ROOT (Windows path) y FN_REGISTRY_ROOT_WSL (Linux path)
+#         al proceso hijo para que pueda invocar WSL python via wsl.exe.

 launch_cpp_app_windows() {
    local app="${1:-}"
@@ -26,10 +28,18 @@ launch_cpp_app_windows() {
    win_app_dir=$(wslpath -w "$desktop_dir/apps/$app")
    win_exe="$win_app_dir\\$app.exe"

+    # Deducir raiz del registry en Linux (WSL) y traducir a Windows path.
+    # FN_REGISTRY_ROOT_WSL puede sobreescribirse en el entorno del llamante.
+    local linux_root win_root
+    linux_root="${FN_REGISTRY_ROOT_WSL:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)}"
+    win_root=$(wslpath -w "$linux_root")
+
    # Start-Process detacha (equivale a `start` de cmd) y respeta -WorkingDirectory.
    # Las comillas simples en PowerShell son literales — no procesa \ ni $.
+    # Se inyectan FN_REGISTRY_ROOT (Windows path) y FN_REGISTRY_ROOT_WSL (Linux path)
+    # para que el exe pueda localizar el venv WSL y hacer: wsl.exe -- python3 ...
    powershell.exe -NoProfile -Command \
-        "Start-Process -FilePath '$win_exe' -WorkingDirectory '$win_app_dir'" \
+        "\$env:FN_REGISTRY_ROOT='$win_root'; \$env:FN_REGISTRY_ROOT_WSL='$linux_root'; Start-Process -FilePath '$win_exe' -WorkingDirectory '$win_app_dir'" \
        >/dev/null 2>&1

    local ts
@@ -0,0 +1,58 @@
+---
+name: refresh_windows_icon_cache
+kind: function
+lang: bash
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "refresh_windows_icon_cache() -> void"
+description: "Fuerza a Windows Explorer a recargar la cache de iconos desde WSL2 via ie4uinit.exe. Best-effort: nunca aborta, retorna 0 si alguna estrategia tuvo exito."
+tags: [windows, wsl, deploy, shell, icons, cpp-windows]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+tested: false
+tests: []
+test_file_path: ""
+file_path: "bash/functions/infra/refresh_windows_icon_cache.sh"
+params: []
+output: "0 si al menos una estrategia tuvo exito, non-zero si todas fallaron. Imprime una linea de estado en stdout."
+---
+
+## Ejemplo
+
+```bash
+source bash/functions/infra/refresh_windows_icon_cache.sh
+refresh_windows_icon_cache
+# icon cache refresh: ok via ie4uinit -show
+```
+
+O directamente via `fn run`:
+
+```bash
+./fn run refresh_windows_icon_cache_bash_infra
+```
+
+Uso tipico en un pipeline de redeploy tras reconstruir el `.exe`:
+
+```bash
+source bash/functions/infra/deploy_cpp_exe_to_windows.sh
+source bash/functions/infra/refresh_windows_icon_cache.sh
+
+deploy_cpp_exe_to_windows "registry_dashboard" "apps/registry_dashboard"
+refresh_windows_icon_cache
+```
+
+## Cuando usarla
+
+Despues de redeployar un `.exe` Windows cuyo `appicon.ico` cambio (via windres embebido en el build), antes de que Windows muestre el icono nuevo en taskbar, Alt+Tab y File Explorer. Sin esta llamada Windows puede tardar minutos en reflejar el icono actualizado, o no actualizarlo hasta reiniciar Explorer.
+
+## Gotchas
+
+- `ie4uinit.exe` debe estar en el PATH de WSL2 (normalmente via `/mnt/c/Windows/System32/`). Si Windows esta muy roto puede no encontrarse — la funcion retornara 1 con mensaje de error.
+- El cambio puede tardar 1-2 segundos en propagarse visualmente despues de que la funcion retorne.
+- Algunos casos extremos (icono cacheado en el dockable taskbar previamente fijado) requieren desanclar y volver a anclar el ejecutable, o reiniciar `explorer.exe`. Esta funcion no mata Explorer — seria demasiado disruptivo.
+- Solo funciona desde WSL2 con acceso a herramientas Windows (`/mnt/c/Windows/System32/` en PATH). No tiene efecto en Linux nativo.
@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# refresh_windows_icon_cache — Fuerza a Windows Explorer a recargar la cache
+# de iconos desde WSL2. Best-effort: nunca aborta, retorna 0 si alguna
+# estrategia tuvo exito.
+
+refresh_windows_icon_cache() {
+    # Estrategia 1: ie4uinit.exe -show (Windows 10/11 — emite SHCNE_ASSOCCHANGED)
+    if command -v ie4uinit.exe >/dev/null 2>&1; then
+        if ie4uinit.exe -show >/dev/null 2>&1; then
+            echo "icon cache refresh: ok via ie4uinit -show"
+            return 0
+        fi
+
+        # Estrategia 2: ie4uinit.exe -ClearIconCache (fallback para builds viejos)
+        if ie4uinit.exe -ClearIconCache >/dev/null 2>&1; then
+            echo "icon cache refresh: ok via ie4uinit -ClearIconCache"
+            return 0
+        fi
+    fi
+
+    echo "icon cache refresh: failed (ie4uinit.exe not found or all strategies failed)"
+    return 1
+}
+
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    refresh_windows_icon_cache "$@"
+fi
@@ -3,16 +3,17 @@ name: redeploy_cpp_app_windows
 kind: pipeline
 lang: bash
 domain: pipelines
-version: "1.0.0"
+version: "1.1.0"
 purity: impure
 signature: "redeploy_cpp_app_windows(app_name: string, app_dir: string, [--build]) -> void"
-description: "Pipeline orquestador para redeployar una app C++ en Windows desde WSL2 en un solo comando. Reemplaza la secuencia manual taskkill+copy+launch+verify."
+description: "Pipeline orquestador para redeployar una app C++ en Windows desde WSL2 en un solo comando. Reemplaza la secuencia manual taskkill+copy+launch+verify e incluye refresh del icon cache del shell."
 tags: [cpp, windows, redeploy, pipeline, wsl, launcher, cpp-windows]
 uses_functions:
  - build_cpp_windows_bash_infra
  - deploy_cpp_exe_to_windows_bash_infra
  - launch_cpp_app_windows_bash_infra
  - is_cpp_app_running_windows_bash_infra
+  - refresh_windows_icon_cache_bash_infra
 uses_types: []
 returns: []
 returns_optional: false
@@ -47,6 +48,7 @@ redeploy_cpp_app_windows "chart_demo" "/home/lucas/fn_registry/cpp/apps/chart_de
 1. **Parsear flag `--build`** (default off, opt-in).
 2. **Si `--build`**: invocar `build_cpp_windows <app_name>` para compilar `cpp/build/windows/apps/<app_name>/<app_name>.exe`. Si falla, exit 1 sin tocar el Desktop.
 3. **Deploy**: invocar `deploy_cpp_exe_to_windows "<app_name>" "<app_dir>"`. Esta función mata el proceso si está vivo (taskkill.exe pre-autorizado), copia exe + DLLs + assets + runtime + enrichers, y preserva `local_files/`.
+3b. **Refresh icon cache** (v1.1.0+): invocar `refresh_windows_icon_cache` (best-effort). Llama `ie4uinit.exe -show` para que Explorer recargue `iconcache.db` sin esperar al timestamp. Si falla, no aborta el pipeline.
 4. **Launch**: invocar `launch_cpp_app_windows "<app_name>"` para arrancar la app en Windows.
 5. **Wait**: `sleep 1` — espera arranque corto.
 6. **Verify**: invocar `is_cpp_app_running_windows "<app_name>"`. Si NO está vivo → exit 1 con mensaje claro.
@@ -7,6 +7,7 @@ source "$SCRIPT_DIR/../infra/build_cpp_windows.sh"
 source "$SCRIPT_DIR/../infra/deploy_cpp_exe_to_windows.sh"
 source "$SCRIPT_DIR/../infra/launch_cpp_app_windows.sh"
 source "$SCRIPT_DIR/../infra/is_cpp_app_running_windows.sh"
+source "$SCRIPT_DIR/../infra/refresh_windows_icon_cache.sh"

 redeploy_cpp_app_windows() {
    local app_name=""
@@ -63,6 +64,12 @@ redeploy_cpp_app_windows() {
    fi
    echo "[2/4] Deploy OK"

+    # Refrescar cache de iconos del shell. Sin esto el .exe nuevo puede salir
+    # con el icono generico (Windows cachea por timestamp/path en iconcache.db
+    # y a veces no detecta el cambio inmediatamente). Best-effort: si falla
+    # no abortamos el redeploy.
+    refresh_windows_icon_cache || true
+
    # Paso 3: lanzar la app
    echo "[3/4] Launching $app_name..."
    if ! launch_cpp_app_windows "$app_name"; then