diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index ccde91b6..fa4005c1 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -150,7 +150,7 @@ Cualquier `SELECT ... FROM functions/types/apps/proposals WHERE ...` plano se ha **functions** — columnas: `id, name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, example, tested, tests, test_file_path, file_path, created_at, updated_at, props, emits, has_state, framework, variant, notes, documentation, code, content_hash, source_repo, source_license, source_file, params_schema` - `params_schema`: JSON con semántica de inputs/outputs. Formato: `{"params":[{"name":"x","desc":"..."}],"output":"..."}`. Buscable via FTS5. - Enums: `kind`(function|pipeline|component) `purity`(pure|impure) `lang`(go|py|bash|ps) -- Dominios: core, infra, finance, datascience, cybersecurity, shell, tui, pipelines, browser +- Dominios: core, infra, finance, datascience, cybersecurity, shell, tui, pipelines, browser, obsidian **types** — columnas: `id, name, lang, domain, version, algebraic, definition, description, tags, uses_types, file_path, created_at, updated_at, examples, notes, documentation, code, content_hash, source_repo, source_license, source_file` - Enums: `algebraic`(product|sum) diff --git a/bash/functions/infra/ensure_project_gitignore.md b/bash/functions/infra/ensure_project_gitignore.md new file mode 100644 index 00000000..c9da66f7 --- /dev/null +++ b/bash/functions/infra/ensure_project_gitignore.md @@ -0,0 +1,58 @@ +--- +name: ensure_project_gitignore +kind: function +lang: bash +domain: infra +version: "1.0.0" +purity: impure +signature: "ensure_project_gitignore(project_dir: string) -> void" +description: "Garantiza de forma idempotente que el .gitignore de un directorio de project contiene las lineas canonicas que excluyen del repo del project el contenido de sus sub-repos hijos (apps y analyses son repos Gitea independientes) y sus vaults (datos fuera de git). Evita el doble-tracking al hacer push del project." +tags: [git, gitignore, projects, infra] +params: + - name: project_dir + desc: "Ruta al directorio del project (p. ej. projects/aurgi). Debe existir; si no, error a stderr y return 1. El .gitignore se escribe/actualiza en /.gitignore." +output: "Sin salida en stdout. A stderr informa de la accion realizada: 'created' si creo el .gitignore, 'updated: anadidas N lineas' si anadio lineas faltantes, u 'ok: ya completo' si nada cambiaba. Codigo de salida 0 en exito, 1 si project_dir falta o no existe." +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/ensure_project_gitignore.sh" +--- + +## Ejemplo + +```bash +source bash/functions/infra/ensure_project_gitignore.sh + +# Asegura que projects/aurgi/.gitignore excluye el contenido de sus hijos. +ensure_project_gitignore projects/aurgi +# stderr: ensure_project_gitignore: created projects/aurgi/.gitignore +# (o: updated: anadidas 2 lineas / ok: ya completo) +``` + +Las lineas canonicas que la funcion garantiza son: + +``` +apps/*/ +analysis/*/ +vaults/* +!vaults/.gitkeep +!vaults/vault.yaml +``` + +## Cuando usarla + +Llamala justo despues de crear un project nuevo (`mkdir -p projects//{apps,analysis,vaults}`) y antes de inicializar su repo Gitea con `ensure_repo_synced`, para que el repo del project nunca trackee el contenido de sus sub-repos hijos. Tambien al adoptar un project existente que aun no tiene estas exclusiones, o como paso de saneamiento cuando `git status` del project muestra contenido de `apps/`/`analysis/` que deberia estar ignorado. + +## Gotchas + +- La funcion modifica el filesystem (escribe en `/.gitignore`): es impura. No commitea ni hace push — solo deja el `.gitignore` correcto. +- La comparacion para no duplicar es linea-exacta (`grep -Fxq`). Una linea equivalente pero con espacios extra, comentario adjunto o glob distinto (p. ej. `apps/*` sin la barra final) NO se considera presente y la canonica se anade igualmente; podrian quedar ambas formas. Mantener el `.gitignore` con las lineas canonicas tal cual evita ruido. +- Si el `.gitignore` existente no termina en salto de linea, la funcion anade uno antes de apendar para no pegar la primera linea nueva al final de la ultima existente. +- Solo gestiona las exclusiones de sub-repos hijos y vaults del nivel-project; no toca otras reglas que el `.gitignore` ya contenga ni las reordena. +- Si una linea canonica ya existia con su forma exacta, no se vuelve a anadir (idempotente): re-ejecutar es seguro. diff --git a/bash/functions/infra/ensure_project_gitignore.sh b/bash/functions/infra/ensure_project_gitignore.sh new file mode 100644 index 00000000..9ae9ecad --- /dev/null +++ b/bash/functions/infra/ensure_project_gitignore.sh @@ -0,0 +1,76 @@ +#!/usr/bin/env bash +# ensure_project_gitignore — Garantiza de forma idempotente que el .gitignore de +# un directorio de project (projects//) contiene las lineas canonicas que +# excluyen del repo del project el contenido de sus sub-repos hijos (apps y +# analyses son repos Gitea independientes) y sus vaults (datos fuera de git). +# +# Esto evita que al hacer push del project se trackee por error el contenido de +# los hijos (doble-tracking). Ver .claude/rules/apps_subrepo.md y +# .claude/rules/projects.md. +# +# Uso: +# ensure_project_gitignore +# +# Salida: +# stdout vacio. A stderr informa de la accion realizada (created / updated / ok). + +ensure_project_gitignore() { + local project_dir="$1" + + if [[ -z "$project_dir" ]]; then + echo "ensure_project_gitignore: se requiere project_dir" >&2 + return 1 + fi + if [[ ! -d "$project_dir" ]]; then + echo "ensure_project_gitignore: directorio '$project_dir' no existe" >&2 + return 1 + fi + + local gitignore="$project_dir/.gitignore" + + # Lineas canonicas que deben estar presentes (orden de referencia). + local -a canonical=( + "apps/*/" + "analysis/*/" + "vaults/*" + "!vaults/.gitkeep" + "!vaults/vault.yaml" + ) + + # Caso 1: el .gitignore no existe — crearlo con el contenido canonico. + if [[ ! -f "$gitignore" ]]; then + printf '%s\n' "${canonical[@]}" > "$gitignore" + echo "ensure_project_gitignore: created $gitignore" >&2 + return 0 + fi + + # Caso 2: existe — anadir solo las lineas que falten (comparacion linea-exacta), + # preservando el contenido y el orden existentes. + # Si el archivo no termina en newline, anadir uno antes de apendar para no + # pegar la primera linea nueva al final de la ultima existente. + if [[ -s "$gitignore" && -n "$(tail -c 1 "$gitignore")" ]]; then + printf '\n' >> "$gitignore" + fi + + local line added=0 + for line in "${canonical[@]}"; do + # grep -F -x: match literal de linea completa, sin interpretar metacaracteres. + if ! grep -Fxq -- "$line" "$gitignore"; then + printf '%s\n' "$line" >> "$gitignore" + added=$((added + 1)) + fi + done + + if [[ $added -gt 0 ]]; then + echo "ensure_project_gitignore: updated: anadidas $added lineas a $gitignore" >&2 + else + echo "ensure_project_gitignore: ok: ya completo $gitignore" >&2 + fi + + return 0 +} + +# Si se invoca como script (no source), ejecutar la funcion. +if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then + ensure_project_gitignore "$@" +fi diff --git a/bash/functions/pipelines/full_git_pull.md b/bash/functions/pipelines/full_git_pull.md index 4144cb83..d8969060 100644 --- a/bash/functions/pipelines/full_git_pull.md +++ b/bash/functions/pipelines/full_git_pull.md @@ -3,14 +3,15 @@ name: full_git_pull kind: pipeline lang: bash domain: pipelines -version: "1.0.0" +version: "1.1.0" purity: impure signature: "full_git_pull() -> stdout: tabla resumen" -description: "Pull automatico de fn_registry + todos los sub-repos locales + submodules + fn sync. Descubre repos locales, stashea dirty trees antes de pullear, hace pull --ff-only, actualiza submodulos del repo principal, pulla ~/.password-store, regenera registry.db con fn index y ejecuta fn sync." +description: "Pull automatico de fn_registry + todos los sub-repos locales + submodules + fn sync. Descubre repos locales, stashea dirty trees antes de pullear, hace pull --ff-only, actualiza submodulos del repo principal, pulla ~/.password-store, regenera registry.db con fn index, ejecuta fn sync y reclona los sub-repos hijos faltantes de cada project (apps/analysis) via clone_project_subrepos." tags: [git, pull, sync, registry, pipeline, pendiente-usar] uses_functions: - discover_git_repos_bash_infra - git_pull_with_stash_bash_infra + - clone_project_subrepos_bash_pipelines - pass_get_bash_infra uses_types: [] returns: [] @@ -51,4 +52,10 @@ bash bash/functions/pipelines/full_git_pull.sh ## Notas -Solo hace pull fast-forward — nunca rebase ni merge automatico. Los repos con divergencia o conflicto de stash se listan al final del resumen para intervencion manual, pero el pipeline no aborta por ellos. No clona repos faltantes: cada PC tiene el subset que le interesa (clonar manualmente si se necesita uno nuevo). Modo completamente no-interactivo. +Solo hace pull fast-forward — nunca rebase ni merge automatico. Los repos con divergencia o conflicto de stash se listan al final del resumen para intervencion manual, pero el pipeline no aborta por ellos. Modo completamente no-interactivo. + +Desde v1.1.0 SI reclona los sub-repos hijos faltantes de cada project: tras `fn sync` (que trae a `registry.db` las filas de apps/analysis de todos los PCs), itera los projects y llama `clone_project_subrepos` para traer al disco los hijos que falten, re-indexando si clono alguno. `registry.db` actua como manifest de sub-repos, asi que clonar el project paraguas + `/full-git-pull` reconstruye su arbol entero sin adivinar nombres. Los repos sueltos (sin project) siguen sin auto-clonarse: cada PC tiene el subset que le interesa. + +## Capability growth log + +- v1.1.0 (2026-06-10) — anade el paso 6: reclonado de sub-repos hijos de cada project via `clone_project_subrepos` tras `fn sync`, con re-index si clona alguno. Permite reconstruir el arbol completo de un project en un PC nuevo (issue 0171). diff --git a/bash/functions/pipelines/full_git_pull.sh b/bash/functions/pipelines/full_git_pull.sh index 382a0d04..4ef4787d 100644 --- a/bash/functions/pipelines/full_git_pull.sh +++ b/bash/functions/pipelines/full_git_pull.sh @@ -149,6 +149,42 @@ full_git_pull() { fi fi + # --- Paso 6: Reclonar sub-repos hijos de cada project (issue 0171) --- + # Tras fn sync, registry.db contiene las filas apps/analysis de TODOS los PCs. + # clone_project_subrepos clona en este disco los hijos que falten (skip si ya + # existen). Asi, clonar el project paraguas y correr /full-git-pull reconstruye + # su arbol entero sin adivinar nombres de sub-repos: registry.db ES el manifest. + echo "" >&2 + echo "[6/6] Reclonando sub-repos de projects..." >&2 + local reclone_summary=" [skip] sin projects o registry.db" + if [[ -f "$registry_root/registry.db" ]] && command -v sqlite3 >/dev/null 2>&1; then + export FN_REGISTRY_ROOT="$registry_root" + export GITEA_URL="${GITEA_URL:-$(pass_get agentes/gitea-url | head -n1 2>/dev/null || true)}" + local clone_script="$SCRIPT_DIR/clone_project_subrepos.sh" + local any_cloned=0 + if [[ -f "$clone_script" ]]; then + while IFS= read -r proj_id; do + [[ -z "$proj_id" ]] && continue + local clone_out + clone_out=$(bash "$clone_script" "$proj_id" 2>&1 || true) + if echo "$clone_out" | grep -q '\[cloned\]'; then + any_cloned=1 + echo " $proj_id: nuevos sub-repos clonados" >&2 + fi + done < <(sqlite3 "$registry_root/registry.db" "SELECT id FROM projects;" 2>/dev/null) + if [[ "$any_cloned" -eq 1 ]]; then + echo " re-index tras clonado..." >&2 + [[ -x "$fn_bin" ]] && CGO_ENABLED=1 "$fn_bin" index >/dev/null 2>&1 || true + reclone_summary=" OK: nuevos sub-repos clonados + re-index" + else + reclone_summary=" OK: nada que clonar (todo presente)" + fi + else + reclone_summary=" [skip] clone_project_subrepos.sh no encontrado" + fi + fi + echo " $reclone_summary" >&2 + # --- Resumen --- echo "" echo "===== RESUMEN full_git_pull =====" @@ -171,6 +207,9 @@ full_git_pull() { echo "" echo "fn sync:" echo "$sync_summary" + echo "" + echo "Reclonado sub-repos de projects:" + echo "$reclone_summary" if [[ ${#diverged[@]} -gt 0 || ${#conflicts[@]} -gt 0 ]]; then echo "" diff --git a/bash/functions/pipelines/full_git_push.md b/bash/functions/pipelines/full_git_push.md index d975ba5c..e84cfed2 100644 --- a/bash/functions/pipelines/full_git_push.md +++ b/bash/functions/pipelines/full_git_push.md @@ -3,10 +3,10 @@ name: full_git_push kind: pipeline lang: bash domain: pipelines -version: "1.0.0" +version: "1.1.0" purity: impure signature: "full_git_push(commit_message?: string) -> stdout: tabla resumen" -description: "Push automatico de fn_registry + todos los sub-repos + fn sync. Descubre repos, escanea secrets (aborta si detecta), auto-inicializa apps/analyses sin .git via ensure_repo_synced, auto-commitea dirty trees, pushea solo repos adelantados, pushea ~/.password-store sin commitear, y ejecuta fn sync." +description: "Push automatico de fn_registry + todos los sub-repos + fn sync. Descubre repos, escanea secrets (aborta si detecta), auto-inicializa apps/analyses Y projects paraguas sin .git via ensure_repo_synced (asegurando el .gitignore canonico del project antes), auto-commitea dirty trees, pushea solo repos adelantados, pushea ~/.password-store sin commitear, y ejecuta fn sync." tags: [git, push, sync, registry, pipeline, pendiente-usar] uses_functions: - discover_git_repos_bash_infra @@ -14,6 +14,7 @@ uses_functions: - git_auto_commit_dirty_bash_infra - git_push_if_ahead_bash_infra - ensure_repo_synced_bash_infra + - ensure_project_gitignore_bash_infra - pass_get_bash_infra uses_types: [] returns: [] @@ -62,3 +63,7 @@ bash bash/functions/pipelines/full_git_push.sh "feat: nueva funcion" ## Notas El unico motivo para abortar antes de commitear es la deteccion de secrets. Cualquier otro error (push rechazado por non-fast-forward, fn sync no disponible) se reporta en el resumen y el pipeline continua con el resto de repos. Modo completamente no-interactivo. + +## Capability growth log + +- v1.1.0 (2026-06-10) — auto-inicializa tambien los projects paraguas (`projects/

/`) sin repo Gitea, no solo apps/analyses. Antes de pushear cada project asegura su `.gitignore` canonico via `ensure_project_gitignore` para no trackear el contenido de los sub-repos hijos. Cierra el agujero por el que projects como aurgi/obsidian/osint vivian solo en disco y se perdian al borrar el PC (issue 0171). diff --git a/bash/functions/pipelines/full_git_push.sh b/bash/functions/pipelines/full_git_push.sh index caeb4891..40828902 100644 --- a/bash/functions/pipelines/full_git_push.sh +++ b/bash/functions/pipelines/full_git_push.sh @@ -13,6 +13,7 @@ source "$INFRA_DIR/git_auto_commit_dirty.sh" source "$INFRA_DIR/git_push_if_ahead.sh" source "$INFRA_DIR/pass_get.sh" source "$INFRA_DIR/ensure_repo_synced.sh" +source "$INFRA_DIR/ensure_project_gitignore.sh" source "$CYBERSEC_DIR/scan_secrets_in_dirty.sh" full_git_push() { @@ -65,6 +66,32 @@ full_git_push() { ensure_repo_synced "$d" dataforge "$(basename "$d")" master "chore: initial sync" || \ echo " [warn] fallo inicializando $d" >&2 done < <(sqlite3 "$registry_root/registry.db" "SELECT dir_path FROM apps WHERE dir_path != '' UNION SELECT dir_path FROM analysis WHERE dir_path != '';" 2>/dev/null) + + # Paso 1c: Auto-inicializar los PROJECTS paraguas sin .git (issue 0171). + # El directorio projects/

/ versiona SOLO las docs de nivel-project + # (project.md, vault.yaml, CONVENTIONS.md, tools/...). Sus hijos apps/* y + # analysis/* son sub-repos Gitea independientes, excluidos por el .gitignore + # canonico que ensure_project_gitignore garantiza ANTES del push para no + # trackear su contenido (doble-tracking). Sin esto, un project sin repo + # (aurgi, obsidian, osint) vivia solo en disco y se perdia al borrar el PC. + if [[ -f "$registry_root/registry.db" ]] && command -v sqlite3 >/dev/null 2>&1; then + while IFS= read -r proj_dir; do + [[ -z "$proj_dir" ]] && continue + local pd="$registry_root/$proj_dir" + [[ -d "$pd" ]] || continue + # Garantizar el .gitignore canonico ANTES de cualquier git add -A. + ensure_project_gitignore "$pd" || \ + echo " [warn] no se pudo asegurar .gitignore de $pd" >&2 + if [[ -d "$pd/.git" ]]; then + git -C "$pd" remote get-url origin >/dev/null 2>&1 && continue + echo " fix-remote: $pd (.git sin origin)" >&2 + else + echo " auto-init project: $pd" >&2 + fi + ensure_repo_synced "$pd" dataforge "$(basename "$pd")" master "chore: initial sync project" || \ + echo " [warn] fallo inicializando project $pd" >&2 + done < <(sqlite3 "$registry_root/registry.db" "SELECT CASE WHEN dir_path != '' THEN dir_path ELSE 'projects/'||id END FROM projects;" 2>/dev/null) + fi else echo " [warn] registry.db o sqlite3 no disponibles — omitiendo auto-init BD-driven" >&2 fi diff --git a/cmd/fn/doctor.go b/cmd/fn/doctor.go index bee22663..c5109f9e 100644 --- a/cmd/fn/doctor.go +++ b/cmd/fn/doctor.go @@ -70,6 +70,8 @@ func cmdDoctor(args []string) { doctorDod(r, jsonOut) case "e2e-coverage": doctorE2ECoverage(r, jsonOut) + case "projects": + doctorProjects(r, jsonOut) default: fmt.Fprintf(os.Stderr, "unknown doctor subcommand: %s\n", sub) doctorUsage() @@ -100,6 +102,7 @@ Subcommands: modules Drift entre uses_modules (app.md) y fn_module_ link calls (CMakeLists.txt) - issue 0097 dod Audita bloque dod_evidence_schema en dev/issues/ y dev/flows/ (issue 0114) e2e-coverage Porcentaje de apps con e2e_checks declarado en su app.md (issue 0121b) + projects Cobertura de projects vs sub-repos Gitea (repo propio + hijos clonables) (issue 0171) Flags: --json Salida JSON (para scripting/agentes) @@ -505,6 +508,29 @@ func doctorML(root string, jsonOut bool) { fmt.Printf("\nOverall ML environment: %s\n", overall) } +func doctorProjects(root string, jsonOut bool) { + rows, err := infra.AuditProjectsCoverage(root) + if err != nil { + fmt.Fprintf(os.Stderr, "error: %v\n", err) + os.Exit(1) + } + orphans, oerr := infra.FindOrphanProjectRefs(root) + if oerr != nil { + fmt.Fprintf(os.Stderr, "error: %v\n", oerr) + os.Exit(1) + } + if jsonOut { + emit(map[string]any{ + "coverage": rows, + "orphan_project_ids": orphans, + }) + return + } + fmt.Print(infra.FormatProjectsCoverage(rows)) + fmt.Println("\n--- Check inverso: project_id huérfanos (apps/analysis sin project declarado) ---") + fmt.Print(infra.FormatOrphanProjectRefs(orphans)) +} + func emit(v any) { b, err := json.MarshalIndent(v, "", " ") if err != nil { diff --git a/dev/issues/0171-project-subrepo-manifest-and-reclone.md b/dev/issues/0171-project-subrepo-manifest-and-reclone.md new file mode 100644 index 00000000..24924afe --- /dev/null +++ b/dev/issues/0171-project-subrepo-manifest-and-reclone.md @@ -0,0 +1,199 @@ +--- +id: "0171" +title: "Manifest de sub-repos por project + re-clonado y auditoría de cobertura en Gitea" +status: pendiente +type: enhancement +domain: + - registry-quality + - infra +scope: registry-only +priority: alta +depends: [] +blocks: [] +related: ["0166"] +created: 2026-06-10 +updated: 2026-06-10 +tags: [projects, subrepo, gitea, clone, backup, manifest, fn-doctor] +--- + +> **Actualización 10/06/2026 — implementado el núcleo (enfoque KISS).** El manifest +> `subrepos.yaml` propuesto abajo se **descartó**: `registry.db` (tablas `apps`/`analysis` +> con `project_id`, propagadas entre PCs por `fn sync`) **ya es** el manifest de sub-repos, y +> `clone_project_subrepos_bash_pipelines` ya lo consume. No hace falta un archivo nuevo. Lo que +> faltaba era integración + auditoría. Ver `## Estado de implementación` al final. +# 0171 — Manifest de sub-repos por project + re-clonado y auditoría de cobertura en Gitea + +## APP Metadata + +| Campo | Valor | +|-------|-------| +| **ID** | 0171 | +| **Estado** | pendiente | +| **Prioridad** | alta (riesgo de pérdida de datos) | +| **Tipo** | enhancement — metadata de projects + `/full-git-pull` + `fn doctor` | + +## Contexto + +El 10/06/2026, al preparar un dashboard sobre el project `aurgi`, se descubrió que el project +paraguas **no existía en Gitea** (`dataforge/aurgi` → 404). Sus 3 analyses sí estaban a salvo como +sub-repos independientes (`dataforge/venta_web`, `dataforge/sale_prices_comprobation`, +`dataforge/presupuestos_callcenter`), pero **el `project.md`, `vault.yaml` y `CONVENTIONS.md` de +nivel-project no estaban versionados en ningún sitio**. Reconstruir el project obligó a *adivinar* +los nombres de los sub-repos hijos uno a uno desde la lista completa de repos de Gitea. + +Una auditoría de cobertura `projects ↔ Gitea` confirmó el agujero: + +| Project | Repo Gitea | Riesgo | +|---|---|---| +| fleet_monitoring, fn_monitoring, message_bus, web_scraping | ✅ | ninguno | +| **obsidian**, **osint** | ❌ (solo en disco local) | alto — resuelto en esta sesión (subidos a `dataforge/obsidian`, `dataforge/osint`) | +| **aurgi** | ❌ (404, paraguas inexistente) | pendiente — analyses salvados, docs nivel-project no | + +Dos problemas estructurales quedan abiertos: + +1. **Projects sin repo Gitea**: su contenido de nivel-project vive solo en disco. Si se borra el + disco (o el project no se sincroniza a otro PC), se pierde. La regla `projects.md` dice que cada + project debe ser su propio repo Gitea, pero no hay nada que lo **verifique ni lo fuerce**. + +2. **Sub-repos hijos no referenciados**: el `.gitignore` de cada project excluye `apps/*/` y + `analysis/*/` (son sub-repos independientes). Por tanto, **un clon fresco del project NO trae sus + hijos**, y no existe ningún manifest que diga *qué hijos clonar*. Hoy `/full-git-pull` solo + descubre repos vía `discover_git_repos_bash_infra` (busca `.git` ya presentes en disco): si el + hijo nunca se clonó, es invisible. Resultado: para reconstruir un project en una máquina nueva hay + que adivinar sus sub-repos (exactamente lo que pasó con aurgi). + +## Objetivo + +Que **todo project** (a) tenga su repo Gitea garantizado y (b) **referencie declarativamente sus +sub-repos hijos** (apps + analyses), de modo que clonar el project en cualquier PC permita +re-clonar automáticamente todo su árbol sin adivinar nada. + +## Propuesta + +### 1. Manifest de sub-repos por project + +Añadir a cada project un manifest declarativo de sus hijos. Dos opciones de formato (decidir una): + +- **Opción A (KISS, preferida): `subrepos.yaml`** en la raíz del project, análogo a `vault.yaml`: + + ```yaml + # projects/

/subrepos.yaml — sub-repos hijos de este project (apps + analyses) + subrepos: + - kind: analysis # app | analysis + name: venta_web + path: analysis/venta_web + repo: dataforge/venta_web + url: https://gitea-.../dataforge/venta_web + - kind: analysis + name: sale_prices_comprobation + path: analysis/sale_prices_comprobation + repo: dataforge/sale_prices_comprobation + url: https://gitea-.../dataforge/sale_prices_comprobation + ``` + +- **Opción B: sección `## Sub-repos`** en `project.md` con una tabla `kind | name | path | url`. + +`subrepos.yaml` (Opción A) es más fácil de parsear por las funciones de git y se versiona con el +project (no está en el `.gitignore`). El manifest se **autogenera/actualiza** escaneando los `.git` +hijos presentes en disco + su `remote get-url origin` (reusar `discover_git_repos_bash_infra`). + +### 2. Generación y mantenimiento del manifest + +Función/pipeline nueva (delegar a `fn-constructor`, grupo `infra`/git) que, dado un project: +- Escanea `apps/*/.git` y `analysis/*/.git`, lee su remote origin. +- Escribe/actualiza `subrepos.yaml`. +- Idempotente. Se invoca dentro de `/full-git-push` (o `fn index`) para mantener el manifest al día. + +### 3. Re-clonado desde el manifest en `/full-git-pull` + +Extender `/full-git-pull` para que, tras actualizar cada project, lea su `subrepos.yaml` y **clone +los hijos que falten** (`url` → `path`). Así, en un PC nuevo: clonar `dataforge/` → +`/full-git-pull` → reconstruye apps + analyses automáticamente. Requiere una función +`clone_missing_subrepos_bash_infra(project_dir)` (delegar a `fn-constructor`). + +### 4. Garantizar repo Gitea de cada project + auditoría en `fn doctor` + +- Subcomando nuevo `fn doctor projects` (función `audit_projects_coverage_go_infra`): por cada + project en disco reporta `repo_gitea` (existe en Gitea sí/no), `repo_url` (declarado en project.md + sí/no), y `subrepos_manifest` (presente + cuántos hijos en disco sin entrada / en manifest sin + clonar). Salida `--json`. Cero hallazgos = sano. +- Acción derivada documentada: `repo_gitea=no` → `ensure_repo_synced_bash_infra projects/

+ dataforge

master "init: project

"`. + +### 5. Backfill inicial + +- `aurgi`: traer su `project.md` / `vault.yaml` / `CONVENTIONS.md` de `aurgi-pc` (o `home-wsl`) y + crear `dataforge/aurgi` + `subrepos.yaml` con los 3 analyses ya conocidos. **No** reconstruir a + mano un `project.md` mínimo (divergiría del real). +- Resto de projects con hijos (`fleet_monitoring`, `fn_monitoring`, `message_bus`, `web_scraping`): + generar su `subrepos.yaml` con la función del punto 2. + +## Definition of Done + +| Escenario | Tipo | Comando / evidencia | Resultado esperado | +|---|---|---|---| +| Golden: clon fresco reconstruye árbol | e2e | clonar `dataforge/

` en dir limpio → `/full-git-pull` | apps + analyses del project re-clonados desde `subrepos.yaml` | +| Edge: project sin hijos (obsidian) | e2e | generar manifest | `subrepos.yaml` válido y vacío (o ausente), sin error | +| Edge: hijo en disco sin `.git` | unit | auditoría | `fn doctor projects` lo reporta como "hijo sin sub-repo" | +| Error: project sin repo Gitea | e2e | `fn doctor projects --json` | lo marca `repo_gitea=false`, sugiere `ensure_repo_synced` | +| Cobertura | audit | `fn doctor projects` | 0 projects sin repo, 0 hijos sin referenciar | + +## Decisiones abiertas + +1. **Formato del manifest**: `subrepos.yaml` (A) vs. sección en `project.md` (B). Recomendado A. +2. **¿Auto-generar el manifest en `fn index`** o solo en `/full-git-push`? (evitar I/O de red en + `fn index`; preferible en push). +3. **aurgi**: ¿traer de `aurgi-pc` por SSH ahora, o dejarlo para cuando el project se sincronice? + +## Notas + +En esta sesión ya se resolvió el riesgo inmediato: `obsidian` y `osint` se subieron a Gitea +(`dataforge/obsidian`, `dataforge/osint`) con `ensure_repo_synced_bash_infra` y se les añadió +`repo_url` en su `project.md`. Este issue cubre la solución **estructural y reutilizable** para que +el caso no vuelva a ocurrir con ningún project. Relacionado con #0166 (dependencias app→app para +build reproducible): ambos persiguen que clonar el ecosistema en un PC nuevo sea determinista. + +## Estado de implementación (10/06/2026) + +Implementado con enfoque KISS, **sin** `subrepos.yaml` (registry.db + `fn sync` ya cumplen esa +función). Cambios: + +**Funciones nuevas:** +- `ensure_project_gitignore_bash_infra` — garantiza idempotente el `.gitignore` canónico de un + project (`apps/*/`, `analysis/*/`, `vaults/*` + excepciones) antes de cualquier `git add -A`, + para no trackear el contenido de los sub-repos hijos. +- `audit_projects_coverage_go_infra` (+ `FormatProjectsCoverage`) — motor de `fn doctor projects`. + Reporta por project: `git`/`remote`/`repo_url`/`children (cloned/inDB)` + issues + (`no_gitea_repo`, `children_missing`, `dir_not_found`). Solo git local + registry.db, sin red. + +**Integraciones:** +- `full_git_push` v1.1.0 — paso 1c: auto-inicializa y pushea los **projects paraguas** sin repo + (antes solo apps/analyses), asegurando el `.gitignore` canónico primero. Cierra el agujero + aurgi/obsidian/osint. +- `full_git_pull` v1.1.0 — paso 6: tras `fn sync`, reclona los sub-repos hijos faltantes de cada + project con `clone_project_subrepos` + re-index. Clonar el paraguas + `/full-git-pull` reconstruye + el árbol entero. +- `fn doctor projects` — nuevo subcomando (`cmd/fn/doctor.go`). Hoy reporta **0 projects con + problemas**. + +**Hecho aparte (riesgo inmediato):** `dataforge/obsidian` + `dataforge/osint` creados, `repo_url` +en sus `project.md`. + +### Pendientes (no bloquean el núcleo) + +1. **Check inverso — HECHO (10/06/2026).** `FindOrphanProjectRefs` + `FormatOrphanProjectRefs` en + `audit_projects_coverage_go_infra`, enchufado en `fn doctor projects`. Detecta apps/analysis con + `project_id` sin fila en `projects`. Hoy reporta 4 paraguas huérfanos (existen en otro PC, nunca + subidos a Gitea — mismo caso que aurgi): + - `element_agents` (6 apps: agents_and_robots, agents_dashboard, device_agent, element_matrix_chat, + matrix_admin_panel, matrix_client_pc) + - `imagegen` (image_to_3d_studio) + - `osint_graph` (graph_explorer) + - `aurgi` (sus analyses sí están en Gitea; el paraguas no) +2. **Fix de datos de los 4 paraguas huérfanos — pendiente, requiere el PC origen.** No están en disco + ni en Gitea en este PC (`lucas-linux`), así que no se pueden reconstruir aquí sin inventar. El fix + correcto: correr `/full-git-push` en el PC donde cada paraguas existe en disco (`aurgi-pc` / + `home-wsl`). Con `full_git_push` v1.1.0 (paso 1c) eso ya los crea en Gitea automáticamente. Tras + eso, `/full-git-pull` aquí (paso 6) los traerá. NO reconstruir un `project.md` mínimo a mano. +3. **DoD vida útil**: validar el reclonado en un PC nuevo real (clon limpio del paraguas → + `/full-git-pull` → árbol reconstruido) antes de declarar el issue cerrado. diff --git a/dev/issues/0172-osint-web-graph-explorer.md b/dev/issues/0172-osint-web-graph-explorer.md new file mode 100644 index 00000000..1396f9e2 --- /dev/null +++ b/dev/issues/0172-osint-web-graph-explorer.md @@ -0,0 +1,184 @@ +--- +id: "0172" +title: "App web OSINT: grafo sigma.js + tablas por tipo + fichas con imágenes sobre el vault osint" +status: pendiente +type: app +domain: + - osint + - frontend +scope: app-scoped +priority: media +depends: [] +blocks: [] +related: ["0171"] +created: 2026-06-10 +updated: 2026-06-10 +tags: [osint, web, sigma, graph, mantine, obsidian, vault, dashboard] +--- +# 0172 — App web OSINT: grafo sigma.js + tablas por tipo + fichas con imágenes + +## APP Metadata + +| Campo | Valor | +|-------|-------| +| **ID** | 0172 | +| **Estado** | pendiente (solo plan — se construye cuando el vault tenga más datos) | +| **Prioridad** | media | +| **Tipo** | app — nueva app web en `projects/osint/apps/osint_web` | +| **Project** | osint (`projects/osint/`) | + +## Contexto + +El project `osint` guarda sus investigaciones en el vault de Obsidian +`/home/enmanuel/Obsidian/osint` (sub-repo `dataforge/osint`). Hoy ese vault tiene: + +- **~82 nodos** repartidos en carpetas tipadas: `personas/` (45), `organizaciones/` (25), + `lugares/` (10), `dominios/` (1), `casos/` (1). +- **Datos tabulares** en el frontmatter YAML de cada ficha: `tipo`, `nombre`, `sexo`, + `fecha_nacimiento`, `dni`, `direccion`, `pais`, `aliases`, `tags`, etc. +- **Aristas implícitas**: los wikilinks `[[...]]` en las secciones `Relaciones`, `Lugares` y + `Documentos` conectan unas fichas con otras (y con sus attachments). +- **~240 attachments**: fotos, DNIs, certificados y PDFs en `attachments///`, + embebidos en las notas con `![[...]]`. + +Obsidian es bueno para *escribir* la investigación, pero malo para *explorarla* de un vistazo: +no da un grafo navegable de todos los objetivos, ni una tabla filtrable, ni una ficha-resumen +con la galería de imágenes de cada persona. Metabase/Grafana no encajan: leen BD SQL (no `.md`), +y no muestran ni grafo de nodos ni imágenes inline. + +Decisión del usuario (10/06/2026): construir una **app web propia** que lea el vault y ofrezca +tres vistas — **grafo explorable con sigma.js**, **tablas filtradas por tipo**, y **fichas con +imágenes**. Este issue es **solo el plan**: la recopilación de datos en Obsidian continúa primero; +la app se implementa cuando haya suficiente material que justifique la inversión. + +## Objetivo + +Una app web local que, leyendo directamente los `.md` del vault `osint` (sin BD intermedia +obligatoria en v1), permita: + +1. **Explorar el grafo** de nodos (personas, organizaciones, lugares, dominios, casos) y sus + conexiones por wikilinks, con sigma.js: zoom, pan, click en nodo → ficha, colores por tipo, + filtro de tipos visibles, búsqueda de nodo. +2. **Ver tablas filtradas por tipo**: una tabla por categoría (personas, organizaciones, ...) + con las columnas del frontmatter, ordenable y filtrable (por dni, lugar, fecha, tag). +3. **Abrir la ficha** de cualquier nodo: frontmatter renderizado + cuerpo Markdown + galería de + sus attachments (fotos, DNIs, PDFs) servidos por el backend. + +## Arquitectura propuesta + +``` +projects/osint/apps/osint_web/ (sub-repo Gitea dataforge/osint_web) + app.md frontmatter de registro (framework: react-vite-mantine) + server/ backend Python (lee el vault, sirve JSON + attachments) + main.py FastAPI o stdlib http + frontend/ React + Vite + Mantine + sigma.js + src/ + views/GraphView.tsx sigma.js + graphology + views/TablesView.tsx Mantine DataTable filtrable por tipo + views/NodeCard.tsx ficha + galería de attachments +``` + +### Backend (Python — máximo reuso del grupo `obsidian`) + +Python porque el grupo de capacidad `obsidian` (11 funciones, dominio `obsidian`) ya cubre casi +todo el parseo del vault. **Registry-first**: el backend orquesta estas funciones, no reimplementa +el parseo. + +Funciones del registry a reutilizar: + +| Función | Uso en la app | +|---|---| +| `list_obsidian_notes_py_obsidian` | enumerar nodos por carpeta/tipo | +| `read_obsidian_note_py_obsidian` | leer ficha: `{frontmatter, body, wikilinks, tags}` | +| `parse_obsidian_frontmatter_py_obsidian` | datos tabulares de cada nodo | +| `extract_obsidian_wikilinks_py_obsidian` | aristas del grafo | +| `extract_obsidian_embeds_py_obsidian` | attachments embebidos en cada nota | +| `resolve_obsidian_embed_py_obsidian` | resolver `![[foto.jpg]]` → path real en disco para servir la imagen | +| `slugify_obsidian_name_py_obsidian` | normalizar nombre de wikilink → id de nodo | +| `search_obsidian_notes_py_obsidian` | búsqueda global en el grafo | + +Funciones **nuevas** a delegar a `fn-constructor` (no escribir inline en la app): + +- `build_obsidian_graph_py_obsidian` (impure) — dado `vault_dir`, devuelve + `{"nodes": [{id, tipo, label, frontmatter}], "edges": [{source, target, kind}]}`. + Resuelve cada wikilink a un nodo existente (vía slug / nombre de archivo); los wikilinks que + no resuelven a un `.md` del vault se marcan como aristas "dangling" o se descartan según flag. + Tag de grupo: `obsidian`. Es la pieza que el grupo declara como frontera no cubierta + ("No indexa el grafo agregado") — esta función la cierra. + +Endpoints HTTP (JSON salvo el de attachments): + +| Método | Ruta | Devuelve | +|---|---|---| +| GET | `/api/graph` | grafo completo `{nodes, edges}` para sigma.js | +| GET | `/api/nodes?tipo=persona` | filas de la tabla de ese tipo (frontmatter aplanado) | +| GET | `/api/node/{slug}` | ficha: frontmatter + body (HTML/markdown) + lista de attachments | +| GET | `/api/attachment?path=...` | sirve el binario del attachment (image/pdf), con allowlist al vault | +| GET | `/api/search?q=...` | nodos que matchean | + +Seguridad: el backend solo sirve archivos **dentro** del vault osint (path traversal bloqueado). +El vault contiene datos personales sensibles (DNIs) → la app escucha **solo en `127.0.0.1`**, sin +exponer a red. No es un service desplegable a VPS. + +### Frontend (React + Vite + Mantine + sigma.js) + +- Sistema del registry: React + Vite + Mantine v9 + `@fn_library` (grupo `mantine`, 63 funciones). + Componentes propios de `@fn_library` antes que HTML nativo (regla `frontend_theming.md`). +- **Grafo**: `sigma.js` + `graphology`. Color por `tipo`, tamaño por grado, layout + force-directed (graphology-layout-forceatlas2). Click en nodo → abre `NodeCard`. Panel lateral + con toggles de tipos visibles y caja de búsqueda. +- **Tablas**: una pestaña por tipo, Mantine `Table`/DataTable con columnas del frontmatter, + orden y filtro por columna (dni, lugar, fecha_nacimiento, tags). +- **Fichas**: `NodeCard` con frontmatter en formato clave-valor (fechas en formato europeo + DD/MM/AAAA — memoria `formato-fecha-europeo`), cuerpo Markdown, y galería de attachments + (imágenes con lightbox; PDFs como enlace/embed). + +`sigma.js` y `graphology` son dependencias nuevas del frontend (no en `@fn_library`). KISS: +añadir solo esas dos; el resto (tabla, layout, modales) sale de Mantine/`@fn_library`. + +## Decisiones abiertas + +1. **¿BD intermedia o lectura directa del vault?** v1 lee el vault en cada arranque (cachea el + grafo en memoria). Si el vault crece mucho o se quiere histórico/diff, evaluar un + `operations.db` con `entities`/`relations` (encaja con el bucle reactivo). Recomendado: + empezar sin BD (KISS), añadirla solo si el rendimiento o un caso de uso lo exige. +2. **Backend FastAPI vs stdlib http**: FastAPI da validación y OpenAPI gratis; stdlib evita una + dependencia. Como el backend es fino (orquesta funciones del registry), decidir al construir. +3. **Live-reload del vault**: ¿re-escanear bajo demanda (botón "refrescar") o watcher de + filesystem? v1: botón refrescar (simple). Watcher si molesta. +4. **Aristas dangling**: wikilinks a notas que aún no existen — ¿mostrarlos como nodos fantasma + (útil para ver "objetivos pendientes de fichar") o esconderlos? Propuesta: nodo fantasma con + estilo atenuado, toggle para ocultar. + +## Definition of Done + +| Escenario | Tipo | Comando / evidencia | Resultado esperado | +|---|---|---|---| +| Golden: grafo carga el vault | e2e | `GET /api/graph` con el vault osint real | `nodes` ≥ nº de `.md`, `edges` con los wikilinks resueltos; sigma.js los pinta | +| Golden: ficha con imágenes | e2e | `GET /api/node/` + abrir NodeCard | frontmatter + cuerpo + galería con las imágenes de `attachments/personas//` | +| Edge: tabla filtrada por tipo | e2e | `GET /api/nodes?tipo=organizacion` | solo nodos de ese tipo, columnas del frontmatter | +| Edge: wikilink dangling | unit | nota con `[[Persona-Inexistente]]` | arista marcada dangling / nodo fantasma, sin crash | +| Edge: nombre con mayúsculas/acentos | unit | wikilink `[[María del Mar]]` → slug | resuelve a `maria-del-mar-...md` vía `slugify_obsidian_name` | +| Error: path traversal en attachment | e2e | `GET /api/attachment?path=../../etc/passwd` | 403/404, jamás sirve fuera del vault | +| Error: vault inexistente | e2e | arrancar con `--vault /no/existe` | error claro al arrancar, no 500 silencioso | +| Cobertura | audit | `uses_functions` del `app.md` | declara todas las funciones del grupo `obsidian` consumidas | + +Vida útil (cuando se construya): usar la app de verdad sobre el vault osint durante ≥7 días en +investigaciones reales; medir que el grafo sigue cargando sin romperse al crecer el vault. + +## Notas + +**Estado actual: solo plan.** No construir todavía — la recopilación de datos en Obsidian +continúa; cuando el vault tenga masa crítica de objetivos/relaciones, se arranca con +`/new-cpp-app` no aplica (es web): se hace `git init` del sub-repo `dataforge/osint_web` dentro de +`projects/osint/apps/osint_web/` antes de limpiar cualquier worktree (regla `apps_subrepo.md`), +scaffolding de frontend con el stack Mantine del registry, y backend Python orquestando el grupo +`obsidian`. + +Onboarding (para cuando exista): arrancar backend `python server/main.py --vault +/home/enmanuel/Obsidian/osint --port 8470` y `pnpm dev` en `frontend/`; abrir +`http://127.0.0.1:5173`. Pestañas: Grafo / Tablas / (ficha al click). Solo localhost por los +datos sensibles del vault. + +Relación con #0171 (manifest de sub-repos): cuando esta app exista será un hijo del project +`osint` y debe entrar en su `subrepos.yaml` para re-clonarse en otros PCs. diff --git a/docs/capabilities/INDEX.md b/docs/capabilities/INDEX.md index 7c035680..0ba8cfc3 100644 --- a/docs/capabilities/INDEX.md +++ b/docs/capabilities/INDEX.md @@ -25,6 +25,7 @@ Indice de grupos de capacidades del registry. Cada grupo agrupa >=3 funciones qu | [android](android.md) | 37 | Toolbelt Android desde WSL2: adb, emuladores AVD, APK build/install, Capacitor, logcat | | [web-proxy](web-proxy.md) | 5 | Captura de trafico HTTP/HTTPS liviana (mitmproxy): proxy con rotacion, navegador proxeado, consulta de capturas, tee del SSE de claude. Alternativa ligera a ZAP/Burp | | [flow-replay](flow-replay.md) | 3 | Guardar un flujo web (login, reiniciar server, formulario) como funcion reproducible: destila un HAR a call specs y lo reproduce sin navegador (HTTP puro), con fallback a chromium headless/visible. Consume las capturas de web-proxy | +| [hoppscotch](hoppscotch.md) | 7 | Operar Hoppscotch SELF-HOSTED (docker en selfhost/) via API GraphQL: login (magic link headless via mailpit), CRUD de requests (create/update/delete/list), set_environment (idempotente, resuelve secretos pass:). El agente crea/edita y el humano lo ve en vivo en su GUI (subscriptions). build es helper interno de serializacion. Modo .json local ELIMINADO | | [metabase](metabase.md) | 106 | Operar Metabase via API REST: auth, cards, dashboards, collections, snippets, permissions | | [doctor](doctor.md) | 11 | Diagnostico read-only del registry: artefactos, servicios, drift, funciones huerfanas | | [notebook](notebook.md) | 5 | Operar Jupyter Lab colaborativo (discover/read/exec/write/kernel) | @@ -49,6 +50,9 @@ Indice de grupos de capacidades del registry. Cada grupo agrupa >=3 funciones qu | [mesh-3d](mesh-3d.md) | 3 | Carga y upload a GPU de meshes 3D (OBJ, GLB/glTF 2.0): loaders CPU + mesh_gpu_upload OpenGL | | [terminal-capture](terminal-capture.md) | 6 | Automatizar y capturar el texto de una CLI/TUI interactiva via PTY headless: spawn+input scripteado (one-shot y streaming), render del layout 2D (emulador VT), strip ANSI, delta por prefijo, y parseo de la TUI de claude a datos | | [claude-direct](claude-direct.md) | 3 | Hablar directamente con la API de Anthropic Messages usando el token OAuth de Claude Code (Claude Max): leer token, stream SSE, bucle agentico de tool-use | +| [obsidian](obsidian.md) | 14 | CRUD headless de vaults y notas Obsidian como Markdown plano (frontmatter YAML + wikilinks): parse/format, read/create/update/delete/list/search notas, list/create vaults, slugify/embeds/resolve. Sin app GUI | +| [osint-passive](osint-passive.md) | 8 | Recoleccion OSINT pasiva (fuentes publicas, no intrusiva): EXIF/PDF metadata, whois RDAP, DNS, subdominios crt.sh, guess emails, username enumeration, search dorks | +| [osint-enrich](osint-enrich.md) | 3 | Orquestadores de enriquecimiento OSINT: componen osint-passive para aumentar datapoints de personas (emails/usernames/dorks), orgs (whois+dns+subdominios) y metadatos de attachments | ## Como anadir grupo diff --git a/docs/capabilities/hoppscotch.md b/docs/capabilities/hoppscotch.md new file mode 100644 index 00000000..e7540ef3 --- /dev/null +++ b/docs/capabilities/hoppscotch.md @@ -0,0 +1,83 @@ +# Capability group: `hoppscotch` + +Operar una instancia **self-hosted de Hoppscotch** (consola de APIs, alternativa open-source a +Postman) desde el registry, vía su **API GraphQL**. El agente crea/edita requests, colecciones y +environments por la API; el humano los ve **en vivo** en su GUI (subscriptions = hot-reload real). +Las requests viven en la base de datos del self-host (Postgres), compartida entre el agente y la GUI. + +Este es el **flujo canónico**. El antiguo modo "archivo `.json` local" (funciones +`parse_*` / `run_*` / `add_hoppscotch_request`) **fue eliminado**: escribía un `.json` en disco que +NO subía al workspace, así que el humano no lo veía en la GUI. No lo reintroduzcas. + +## Stack self-host + +Vive en `projects/web_scraping/hoppscotch/selfhost/` (docker compose: AIO + Postgres + mailpit). + +| Servicio | URL | Para qué | +|---|---|---| +| App (cliente) | `http://localhost:3009` | la GUI donde el humano usa las colecciones (instalable como PWA) | +| Admin dashboard | `http://localhost:3100` | gestión (usuarios, config) | +| Backend GraphQL | `http://localhost:3170/graphql` | la API que usan las funciones | +| Mailpit | `http://localhost:8025` | captura el magic link del login (SMTP de pruebas, sin correo real) | + +Levantar: `cd selfhost && docker compose up -d`. Team de trabajo: **"registry"**. Cuenta: `admin@example.com`. + +## Funciones + +| ID | Firma corta | Qué hace | +|---|---|---| +| `hoppscotch_login_py_infra` | `(email, *, backend_url, mailpit_url) -> {access_token,...}` | login por magic link headless (lee el link de mailpit) → JWT | +| `hoppscotch_create_request_py_infra` | `(collection_id, method, url, *, title, headers, body, body_type, team_id, access_token) -> dict` | crea una request en una colección de la team | +| `hoppscotch_update_request_py_infra` | `(request_id, method, url, *, title, headers, body, body_type, access_token) -> dict` | actualiza una request | +| `hoppscotch_delete_request_py_infra` | `(request_id, *, access_token) -> dict` | borra una request | +| `hoppscotch_list_requests_py_infra` | `(collection_id, *, access_token) -> {requests:[...]}` | lista las requests de una colección | +| `hoppscotch_set_environment_py_infra` | `(team_id, name, variables, *, access_token) -> dict` | crea/actualiza (idempotente) el environment de la team; resuelve secretos `pass:` | +| `build_hoppscotch_collection_py_infra` | `(calls, *, name, request_names) -> dict` | **helper interno** de create/update: serializa call specs al formato HoppRESTRequest. NO para escribir `.json` a mano | +| `pass_get_secret_py_infra` | `(path, *, line) -> {value}` | lee un secreto de `pass` (lo consume `set_environment` para no hardcodear keys) | + +`access_token` se pasa como **cookie**, no header `Authorization`. Caduca a 24h → re-login con `hoppscotch_login`. + +## Ejemplo canónico (end-to-end) + +```python +import sys, os +sys.path.insert(0, os.path.join(os.path.expanduser("~/fn_registry"), "python", "functions")) +from infra.hoppscotch_login import hoppscotch_login +from infra.hoppscotch_create_request import hoppscotch_create_request +from infra.hoppscotch_set_environment import hoppscotch_set_environment + +TEAM = "cmq8kn0v500030xls1nvminjy" # team "registry" +COLL = "cmq8knppc00040xlskt4ist27" # colección registry_api (de hoppscotch_list/DB) + +tok = hoppscotch_login("admin@example.com")["access_token"] + +# 1. Variables del workspace (secreto resuelto desde pass, no hardcodeado) +hoppscotch_set_environment(TEAM, "registry", [ + {"key": "baseURL", "value": "https://registry.organic-machine.com", "secret": False}, + {"key": "api_key", "value": "pass:apis/registry", "secret": True}, # pass: -> pass_get_secret +], access_token=tok) + +# 2. Crear una request → aparece EN VIVO en la GUI del humano (subscriptions) +hoppscotch_create_request( + COLL, "GET", "<>/api/status", + title="status", headers={"Accept": "application/json"}, + team_id=TEAM, access_token=tok, +) +``` + +## Fronteras (qué NO cubre) + +- **No es modo archivo**: no escribe colecciones `.json` locales como fuente. Las requests viven en el + Postgres del self-host. (Los `.json` en `collections/` son solo respaldo/semilla importable.) +- **No automatiza la GUI**: opera por la API; la GUI la mira el humano. +- **No gestiona usuarios/teams del dashboard**: eso es el admin dashboard (`:3100`). +- **No ejecuta los scripts pre/post-request JS** de Hoppscotch. + +## Gotchas + +- `access_token` como **cookie** (`cookies={"access_token": tok}`), no `Authorization`. 24h de vida. +- `createRequestInCollection` de esta instancia **exige `team_id`** en el input (no solo el collectionID). +- Variables `<>` se resuelven con el environment de la team (subscriptions las propagan a la GUI). +- Secretos: usa `value="pass:"` en `set_environment` → se resuelve de `pass`, nunca se hardcodea + ni se logea en crudo. +- El secreto viaja en claro al backend local por GraphQL — es local (`127.0.0.1`), aceptable. diff --git a/docs/capabilities/obsidian.md b/docs/capabilities/obsidian.md new file mode 100644 index 00000000..9a3176bc --- /dev/null +++ b/docs/capabilities/obsidian.md @@ -0,0 +1,80 @@ +# Capability: obsidian + +CRUD headless de vaults y notas de Obsidian, tratadas como Markdown plano con frontmatter YAML y wikilinks `[[...]]`. NO depende de la app GUI de Obsidian ni de su URI scheme — manipula los archivos `.md` directamente en disco. Scriptable, rapido, con telemetria del registry. + +Los vaults de Obsidian del usuario viven en `/home/enmanuel/Obsidian/` y estan enlazados como vaults del registry en el project `obsidian` (`projects/obsidian/vaults/`). Ver `projects/obsidian/project.md`. + +## Funciones + +| ID | Firma | Que hace | +|---|---|---| +| `parse_obsidian_frontmatter_py_obsidian` | `parse_obsidian_frontmatter(content: str) -> {"frontmatter": dict, "body": str}` | **Pure.** Separa el frontmatter YAML (bloque `---` inicial) del cuerpo. Si no hay frontmatter valido devuelve `{}` + el contenido completo. | +| `extract_obsidian_wikilinks_py_obsidian` | `extract_obsidian_wikilinks(body: str) -> list` | **Pure.** Extrae los targets de los wikilinks `[[...]]` y embeds `![[...]]`. Normaliza `[[nota\|alias]]`, `[[nota#heading]]`, `[[nota#^block]]` -> `nota`. Dedup preservando orden. | +| `format_obsidian_note_py_obsidian` | `format_obsidian_note(frontmatter: dict, body: str) -> str` | **Pure.** Inversa de parse: serializa frontmatter (YAML entre `---`) + body a una nota `.md` completa. | +| `read_obsidian_note_py_obsidian` | `read_obsidian_note(path: str) -> dict` | Lee una nota: `{path, frontmatter, body, wikilinks, tags}`. Compone parse + extract. | +| `create_obsidian_note_py_obsidian` | `create_obsidian_note(vault_dir, rel_path, body="", frontmatter=None, overwrite=False) -> str` | Crea nota nueva (crea dirs padre, añade `.md`). Error si existe y `overwrite=False`. | +| `update_obsidian_note_py_obsidian` | `update_obsidian_note(path, body=None, set_frontmatter=None, append=None) -> str` | Edita nota existente: merge de frontmatter, reemplazo de body, o append al final. | +| `delete_obsidian_note_py_obsidian` | `delete_obsidian_note(path: str) -> bool` | Borra una nota (solo archivo, nunca directorio). Error si no existe. | +| `list_obsidian_notes_py_obsidian` | `list_obsidian_notes(vault_dir, subfolder="", tag="") -> list` | Lista paths de notas `.md` (recursivo). Excluye `.obsidian/` y `.trash/`. Filtro opcional por tag de frontmatter. | +| `search_obsidian_notes_py_obsidian` | `search_obsidian_notes(vault_dir, query, in_body=True, in_frontmatter=True) -> list` | Busca substring (case-insensitive) en las notas. Devuelve `[{path, matches:[{line, text}]}]`. | +| `list_obsidian_vaults_py_obsidian` | `list_obsidian_vaults(base_dir: str) -> list` | Lista los vaults (subdirs con `.obsidian/`) bajo `base_dir`. `[{name, path}]`. | +| `create_obsidian_vault_py_obsidian` | `create_obsidian_vault(parent_dir, name) -> str` | Crea un vault nuevo: carpeta + `.obsidian/app.json` minimo. Error si ya existe. | + +## Ejemplo canonico + +Componer varias funciones del grupo se hace por heredoc importando del registry (las funciones se importan, no se reescriben): + +```bash +cd /home/enmanuel/fn_registry +python/.venv/bin/python3 - <<'PYEOF' +import sys +sys.path.insert(0, "python/functions") +from obsidian import ( + list_obsidian_vaults, list_obsidian_notes, search_obsidian_notes, + create_obsidian_note, read_obsidian_note, update_obsidian_note, delete_obsidian_note, +) + +# 1. Descubrir vaults del usuario +vaults = list_obsidian_vaults("/home/enmanuel/Obsidian") +print("vaults:", [v["name"] for v in vaults]) + +# 2. Listar y buscar notas en un vault +finanzas = "/home/enmanuel/Obsidian/Finanzas" +print("notas:", len(list_obsidian_notes(finanzas))) +print("hits:", [h["path"] for h in search_obsidian_notes(finanzas, "presupuesto")][:5]) + +# 3. CRUD de una nota (crear -> leer -> editar -> borrar) +p = create_obsidian_note(finanzas, "inbox/idea_x", body="Primera linea", + frontmatter={"tags": ["inbox"], "created": "2026-06-09"}) +note = read_obsidian_note(p) +print("creada:", note["path"], note["frontmatter"], note["wikilinks"]) +update_obsidian_note(p, set_frontmatter={"status": "done"}, append="Ver [[Otra Nota]]") +delete_obsidian_note(p) +PYEOF +``` + +Para una sola operacion con un id conocido, `fn run` tambien sirve: + +```bash +./fn run list_obsidian_vaults /home/enmanuel/Obsidian +./fn run list_obsidian_notes /home/enmanuel/Obsidian/Finanzas +``` + +## Cuando usar el grupo + +- Crear/editar/leer notas de cualquier vault de Obsidian desde un agente o script, sin abrir la app. +- Buscar o listar notas por contenido o tag (ingesta, migracion, reporting sobre el vault). +- Crear vaults nuevos o inventariar los existentes. + +## Fronteras (que NO cubre) + +- **No habla con la app GUI** (no usa el URI scheme `obsidian://`, no abre notas en la interfaz, no dispara plugins). Si la app esta abierta, escribir en disco puede chocar con sus locks/cache — cerrar la app o refrescar manualmente. +- **No resuelve wikilinks a paths** automaticamente (devuelve los targets crudos). Resolver `[[nota]]` -> archivo real es responsabilidad del caller (busqueda por nombre en el vault). +- **No renderiza Markdown** ni evalua Dataview/templating. Trata las notas como texto + frontmatter. +- **No indexa el grafo** de enlaces entre notas (solo extrae links por nota). Para grafo agregado, componer sobre `list_obsidian_notes` + `extract_obsidian_wikilinks`. + +## Gotchas + +- Vaults grandes son caros: `NotasDeObsidian` pesa ~554M. `list_obsidian_notes` / `search_obsidian_notes` recorren todo el arbol — filtra por `subfolder` cuando puedas. +- `delete_obsidian_note` borra de verdad (no manda a `.trash/`). Para acciones destructivas masivas, listar primero y confirmar. +- El frontmatter `tags` puede venir como lista o como CSV string; `read_obsidian_note` lo normaliza a lista. diff --git a/docs/capabilities/osint-enrich.md b/docs/capabilities/osint-enrich.md new file mode 100644 index 00000000..c69ddb28 --- /dev/null +++ b/docs/capabilities/osint-enrich.md @@ -0,0 +1,51 @@ +# Capability: osint-enrich + +Orquestadores de enriquecimiento OSINT: componen las funciones atómicas de +[osint-passive](osint-passive.md) para aumentar los datapoints de una entidad (persona u +organización) del vault `osint` a partir de fuentes públicas. No tocan al objetivo de forma +intrusiva. Mismo encuadre dual-use que `osint-passive`: solo investigación autorizada. + +## Funciones + +| ID | Firma | Qué hace | +|---|---|---| +| `scan_ficha_attachments_metadata_py_cybersecurity` | `scan_ficha_attachments_metadata(attachments_dir) -> dict` | Escanea los attachments de una ficha (imágenes + PDFs), extrae EXIF/PDF metadata y agrega GPS y fechas. | +| `enrich_person_passive_py_cybersecurity` | `enrich_person_passive(nombre, apellidos, dominios=None, usernames=None) -> dict` | Candidatos para una persona: emails (guess), username hits, dorks. No verifica ni ejecuta. | +| `enrich_org_passive_py_cybersecurity` | `enrich_org_passive(dominio) -> dict` | Perfil pasivo de una org: whois + dns + subdominios. Resiliente a fallo parcial (campo `errors`). | + +## Ejemplo canónico + +```bash +cd /home/enmanuel/fn_registry +python/.venv/bin/python3 - <<'PYEOF' +import sys; sys.path.insert(0, "python/functions") +from cybersecurity import (scan_ficha_attachments_metadata, + enrich_person_passive, enrich_org_passive) + +# 1. Metadatos de los documentos ya guardados de una persona (datos propios) +m = scan_ficha_attachments_metadata( + "/home/enmanuel/Obsidian/osint/attachments/personas/enmanuel-gutierrez-perez") +print(m["summary"]) # {n_files, n_images, n_pdfs, n_gps_points, n_dates, errors} + +# 2. Candidatos de enriquecimiento de una persona (no toca al objetivo) +p = enrich_person_passive("Enmanuel", "Gutierrez Perez", + dominios=["gmail.com"], usernames=["enmanuelgp"]) +print(p["email_candidates"][:5], len(p["dorks"])) + +# 3. Perfil pasivo de una organización por su dominio +o = enrich_org_passive("organic-machine.com") +print(o["whois"].get("registrar"), o["dns"].get("A"), len(o["subdomains"]), o["errors"]) +PYEOF +``` + +## Fronteras + +- Compone solo funciones `osint-passive`. Para activa (port scan, fingerprint) haría falta + `osint-active` (no construido). +- Devuelve candidatos/datos crudos; **decidir qué escribir en la ficha** (y verificar) es del + caller. Encaja con el reporte de `projects/osint/tools/person_datapoints.py`. + +## Gotchas + +- `enrich_org_passive` nunca peta por una fuente lenta (crt.sh): el fallo va a `errors`. +- `enrich_person_passive` puede tardar por `enumerate_username_sites` (un request por sitio). diff --git a/docs/capabilities/osint-passive.md b/docs/capabilities/osint-passive.md new file mode 100644 index 00000000..993df9c6 --- /dev/null +++ b/docs/capabilities/osint-passive.md @@ -0,0 +1,64 @@ +# Capability: osint-passive + +Recolección OSINT **pasiva**: obtener información sin interactuar de forma intrusiva con el +objetivo, usando solo fuentes públicas (DNS público, RDAP, Certificate Transparency, metadatos +de documentos propios, servicios de perfil públicos). Pensado para investigación autorizada, +due diligence, pentest con permiso y enriquecimiento de las fichas del vault `osint`. + +**Encuadre:** dual-use. Úsese solo contra objetivos propios o con autorización. Las funciones +que tocan servicios públicos (`enumerate_username_sites`, `enum_subdomains_crtsh`) dejan una +huella mínima (un request a cada servicio); respeta sus rate limits. + +## Funciones + +| ID | Firma | Qué hace | +|---|---|---| +| `extract_exif_metadata_py_cybersecurity` | `extract_exif_metadata(image_path) -> dict` | EXIF de una imagen (fecha, cámara, software, GPS decimal) vía Pillow. | +| `extract_pdf_metadata_py_cybersecurity` | `extract_pdf_metadata(pdf_path) -> dict` | Document Info de un PDF (autor, fechas, software, páginas) vía pypdf. | +| `guess_email_formats_py_cybersecurity` | `guess_email_formats(nombre, apellidos, dominio) -> list` | **Pure.** Candidatos de email comunes a partir de nombre + dominio. | +| `enumerate_username_sites_py_cybersecurity` | `enumerate_username_sites(username, ...) -> list` | ¿Existe un username en ~12 redes públicas? (sherlock ligero, por código HTTP). | +| `build_search_dorks_py_cybersecurity` | `build_search_dorks(target, tipo, ...) -> list` | **Pure.** Genera dorks de motor de búsqueda (persona/email/dominio/usuario). | +| `dns_records_py_cybersecurity` | `dns_records(dominio, types=None) -> dict` | Registros DNS (A/AAAA/MX/TXT/NS/CNAME) vía `dig`. | +| `whois_lookup_py_cybersecurity` | `whois_lookup(dominio, ...) -> dict` | Datos de registro vía RDAP (WHOIS moderno HTTP/JSON, sin CLI). | +| `enum_subdomains_crtsh_py_cybersecurity` | `enum_subdomains_crtsh(dominio, ...) -> list` | Subdominios desde Certificate Transparency (crt.sh). | + +Orquestadores (grupo [osint-enrich](osint-enrich.md)): `scan_ficha_attachments_metadata`, +`enrich_person_passive`, `enrich_org_passive`. + +## Ejemplo canónico + +```bash +cd /home/enmanuel/fn_registry +python/.venv/bin/python3 - <<'PYEOF' +import sys; sys.path.insert(0, "python/functions") +from cybersecurity import (dns_records, whois_lookup, enum_subdomains_crtsh, + guess_email_formats, build_search_dorks, extract_exif_metadata) + +# Dominio (org) +print(whois_lookup("organic-machine.com")["registrar"]) # OVH sas +print(dns_records("organic-machine.com")["A"]) # ['135.125.201.30'] +print(enum_subdomains_crtsh("organic-machine.com")[:5]) + +# Persona +print(guess_email_formats("Enmanuel", "Gutierrez Perez", "gmail.com")[:5]) +print(build_search_dorks("Enmanuel Gutierrez Perez", "persona")[:3]) + +# Metadatos de un documento propio +print(extract_exif_metadata("/home/enmanuel/Obsidian/osint/attachments/personas/enmanuel-gutierrez-perez/dni-1.jpg")) +PYEOF +``` + +## Fronteras (qué NO es) + +- **No es recolección activa**: no hace port scan, dns brute, ni sondea la infra del objetivo. + Eso sería el grupo `osint-active` (no construido todavía). +- **No verifica** los candidatos: `guess_email_formats` propone, no confirma que el email exista. +- **No ejecuta** los dorks: `build_search_dorks` los genera; ejecutarlos es otro paso (browser). +- **No incluye breach/leak lookup** (HIBP requiere API key de pago) — pendiente. + +## Gotchas + +- `crt.sh` va lento / rate-limitado y a veces responde 404; los orquestadores lo capturan en + `errors` y siguen. +- `enumerate_username_sites` da falsos positivos/negativos por anti-bot de algunos sitios. +- El GPS de EXIF revela ubicación — dato sensible; trátese como PII. diff --git a/functions/infra/audit_projects_coverage.go b/functions/infra/audit_projects_coverage.go new file mode 100644 index 00000000..08d5bdd5 --- /dev/null +++ b/functions/infra/audit_projects_coverage.go @@ -0,0 +1,347 @@ +package infra + +import ( + "database/sql" + "fmt" + "os/exec" + "path/filepath" + "sort" + "strings" + "text/tabwriter" + + _ "github.com/mattn/go-sqlite3" +) + +// ProjectCoverage reports how well a project registered in registry.db is +// backed by a Gitea sub-repo and how many of its children (apps + analyses) +// are actually cloned on disk. It is the engine of `fn doctor projects`. +// +// The audit only touches the local filesystem and registry.db: it never hits +// the network nor the Gitea API, so it runs fast and requires no token. +type ProjectCoverage struct { + ProjectID string `json:"project_id"` + DirPath string `json:"dir_path"` + HasGit bool `json:"has_git"` // //.git exists as a directory + HasRemote bool `json:"has_remote"` // git -C

remote get-url origin returned a non-empty url + RepoURLDeclared bool `json:"repo_url_declared"` // projects.repo_url != "" + ChildrenInDB int `json:"children_in_db"` // apps + analyses with project_id = ProjectID + ChildrenCloned int `json:"children_cloned"` // of those, how many have a .git on disk + ChildrenMissing int `json:"children_missing"` // ChildrenInDB - ChildrenCloned (at risk when re-cloning) + Issues []string `json:"issues"` // e.g. "dir_not_found", "no_gitea_repo", "children_missing" +} + +// AuditProjectsCoverage walks every row in the projects table and reports, per +// project, whether it has a local git repo, whether that repo declares a remote +// origin, whether its repo_url is filled in registry.db, and how many of its +// children (apps + analyses) are cloned versus only known to the database. +// +// registryRoot is the repository root (the directory that holds registry.db). +// All relative dir_path values are resolved against it. +// +// Returns an error only if registry.db cannot be opened or queried. Projects +// whose directory is missing on disk are still reported, flagged with the +// "dir_not_found" issue, so the caller can surface them rather than silently +// dropping them. +func AuditProjectsCoverage(registryRoot string) ([]ProjectCoverage, error) { + dbPath := filepath.Join(registryRoot, "registry.db") + dsn := fmt.Sprintf("file:%s?mode=ro&_foreign_keys=on", dbPath) + db, err := sql.Open("sqlite3", dsn) + if err != nil { + return nil, fmt.Errorf("audit_projects_coverage: open db: %w", err) + } + defer db.Close() + if err := db.Ping(); err != nil { + return nil, fmt.Errorf("audit_projects_coverage: ping db: %w", err) + } + + rows, err := db.Query(`SELECT id, COALESCE(dir_path,''), COALESCE(repo_url,'') FROM projects ORDER BY id`) + if err != nil { + return nil, fmt.Errorf("audit_projects_coverage: query projects: %w", err) + } + defer rows.Close() + + var out []ProjectCoverage + for rows.Next() { + var pc ProjectCoverage + var dirPath, repoURL string + if err := rows.Scan(&pc.ProjectID, &dirPath, &repoURL); err != nil { + return nil, fmt.Errorf("audit_projects_coverage: scan project: %w", err) + } + + // DirPath: use projects.dir_path; if empty, derive projects/. + if dirPath == "" { + dirPath = filepath.Join("projects", pc.ProjectID) + } + pc.DirPath = dirPath + pc.RepoURLDeclared = repoURL != "" + + absDir := dirPath + if !filepath.IsAbs(absDir) { + absDir = filepath.Join(registryRoot, dirPath) + } + + dirFound := dirExists(absDir) + if !dirFound { + pc.Issues = append(pc.Issues, "dir_not_found") + } else { + pc.HasGit = dirExists(filepath.Join(absDir, ".git")) + if pc.HasGit { + pc.HasRemote = gitHasRemoteOrigin(absDir) + } + } + + // Children: apps + analyses with this project_id. + children, err := projectChildren(db, pc.ProjectID) + if err != nil { + return nil, err + } + pc.ChildrenInDB = len(children) + for _, childDir := range children { + absChild := childDir + if !filepath.IsAbs(absChild) { + absChild = filepath.Join(registryRoot, childDir) + } + if dirExists(filepath.Join(absChild, ".git")) { + pc.ChildrenCloned++ + } + } + pc.ChildrenMissing = pc.ChildrenInDB - pc.ChildrenCloned + + // Issues derived from the gathered state. + if !pc.HasRemote && !pc.RepoURLDeclared { + pc.Issues = append(pc.Issues, "no_gitea_repo") + } + if pc.ChildrenMissing > 0 { + pc.Issues = append(pc.Issues, "children_missing") + } + + out = append(out, pc) + } + return out, rows.Err() +} + +// projectChildren returns the dir_path of every app and analysis whose +// project_id matches the given project id. +func projectChildren(db *sql.DB, projectID string) ([]string, error) { + var dirs []string + for _, table := range []string{"apps", "analysis"} { + q := fmt.Sprintf(`SELECT COALESCE(dir_path,'') FROM %s WHERE project_id = ?`, table) + rows, err := db.Query(q, projectID) + if err != nil { + return nil, fmt.Errorf("audit_projects_coverage: query %s children: %w", table, err) + } + for rows.Next() { + var dp string + if err := rows.Scan(&dp); err != nil { + rows.Close() + return nil, fmt.Errorf("audit_projects_coverage: scan %s child: %w", table, err) + } + if dp != "" { + dirs = append(dirs, dp) + } + } + if err := rows.Err(); err != nil { + rows.Close() + return nil, err + } + rows.Close() + } + return dirs, nil +} + +// gitHasRemoteOrigin reports whether the git repo at dir declares an origin +// remote with a non-empty URL. It shells out to `git -C remote get-url +// origin` and treats exit 0 with non-empty output as success. Any error +// (no origin, not a repo, git missing) is reported as false. +func gitHasRemoteOrigin(dir string) bool { + cmd := exec.Command("git", "-C", dir, "remote", "get-url", "origin") + outBytes, err := cmd.Output() + if err != nil { + return false + } + return strings.TrimSpace(string(outBytes)) != "" +} + +// FormatProjectsCoverage renders a tabwriter table, one row per project, with +// git / remote / repo_url presence, children cloned vs declared, and the +// issues list. When no project has coverage problems it makes that explicit. +func FormatProjectsCoverage(rows []ProjectCoverage) string { + var sb strings.Builder + w := tabwriter.NewWriter(&sb, 0, 0, 2, ' ', 0) + fmt.Fprintln(w, "PROJECT\tGIT\tREMOTE\tREPO_URL\tCHILDREN\tISSUES") + + withIssues := 0 + for _, r := range rows { + issues := "-" + if len(r.Issues) > 0 { + issues = strings.Join(r.Issues, "; ") + withIssues++ + } + fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%d/%d\t%s\n", + r.ProjectID, + checkMark(r.HasGit), + checkMark(r.HasRemote), + checkMark(r.RepoURLDeclared), + r.ChildrenCloned, r.ChildrenInDB, + issues, + ) + } + w.Flush() + + if len(rows) == 0 { + sb.WriteString("\nNo projects registered.\n") + return sb.String() + } + if withIssues == 0 { + sb.WriteString("\n0 projects con problemas de cobertura.\n") + } else { + fmt.Fprintf(&sb, "\n%d/%d projects con problemas de cobertura.\n", withIssues, len(rows)) + } + return sb.String() +} + +// checkMark returns ✓ for true, ✗ for false. +func checkMark(b bool) string { + if b { + return "✓" + } + return "✗" +} + +// OrphanProjectRef describes a project_id that one or more children (apps and +// analyses) reference in registry.db but for which no row exists in the projects +// table. This is the inverse drift of AuditProjectsCoverage: instead of a +// registered project whose children are not cloned, it surfaces an umbrella +// project that was never synced to this PC (or never created here at all), so +// the children are pointing at a project that this registry does not know about. +// That is a data-loss risk: the umbrella project may exist on another machine +// and the link would be silently broken on a clone/sync into this one. +type OrphanProjectRef struct { + ProjectID string `json:"project_id"` // referenced by children but missing from projects + Apps []string `json:"apps"` // ids of apps that reference it (sorted) + Analyses []string `json:"analyses"` // ids of analyses that reference it (sorted) +} + +// FindOrphanProjectRefs scans every app and analysis that declares a non-empty +// project_id and reports those project_id values that have no matching row in +// the projects table. Each orphan groups the ids of the apps and analyses that +// reference it. +// +// registryRoot is the repository root (the directory that holds registry.db). +// +// The result is sorted by ProjectID, and within each entry the Apps and +// Analyses lists are sorted alphabetically. When every child references a known +// project, an empty (non-nil) slice is returned with a nil error. +// +// Like AuditProjectsCoverage it only reads registry.db (opened read-only) and +// never touches the network nor the Gitea API. Returns an error only when +// registry.db cannot be opened or queried. +func FindOrphanProjectRefs(registryRoot string) ([]OrphanProjectRef, error) { + dbPath := filepath.Join(registryRoot, "registry.db") + dsn := fmt.Sprintf("file:%s?mode=ro&_foreign_keys=on", dbPath) + db, err := sql.Open("sqlite3", dsn) + if err != nil { + return nil, fmt.Errorf("find_orphan_project_refs: open db: %w", err) + } + defer db.Close() + if err := db.Ping(); err != nil { + return nil, fmt.Errorf("find_orphan_project_refs: ping db: %w", err) + } + + // Set of known project ids. + known := map[string]bool{} + prows, err := db.Query(`SELECT id FROM projects`) + if err != nil { + return nil, fmt.Errorf("find_orphan_project_refs: query projects: %w", err) + } + for prows.Next() { + var id string + if err := prows.Scan(&id); err != nil { + prows.Close() + return nil, fmt.Errorf("find_orphan_project_refs: scan project: %w", err) + } + known[id] = true + } + if err := prows.Err(); err != nil { + prows.Close() + return nil, err + } + prows.Close() + + // Accumulate orphan references from apps and analyses. + orphans := map[string]*OrphanProjectRef{} + + get := func(pid string) *OrphanProjectRef { + o, ok := orphans[pid] + if !ok { + o = &OrphanProjectRef{ProjectID: pid} + orphans[pid] = o + } + return o + } + + for _, table := range []string{"apps", "analysis"} { + q := fmt.Sprintf(`SELECT id, project_id FROM %s WHERE project_id != ''`, table) + rows, err := db.Query(q) + if err != nil { + return nil, fmt.Errorf("find_orphan_project_refs: query %s: %w", table, err) + } + for rows.Next() { + var id, pid string + if err := rows.Scan(&id, &pid); err != nil { + rows.Close() + return nil, fmt.Errorf("find_orphan_project_refs: scan %s row: %w", table, err) + } + if known[pid] { + continue + } + o := get(pid) + if table == "apps" { + o.Apps = append(o.Apps, id) + } else { + o.Analyses = append(o.Analyses, id) + } + } + if err := rows.Err(); err != nil { + rows.Close() + return nil, err + } + rows.Close() + } + + out := make([]OrphanProjectRef, 0, len(orphans)) + for _, o := range orphans { + sort.Strings(o.Apps) + sort.Strings(o.Analyses) + out = append(out, *o) + } + sort.Slice(out, func(i, j int) bool { return out[i].ProjectID < out[j].ProjectID }) + return out, nil +} + +// FormatOrphanProjectRefs renders a human-readable report of orphan project_id +// references, one block per orphan, listing how many apps and analyses point at +// the missing project plus their ids. When there are no orphans it makes that +// explicit on a single line. +func FormatOrphanProjectRefs(rows []OrphanProjectRef) string { + if len(rows) == 0 { + return "0 project_id huérfanos (todos los hijos tienen project declarado)\n" + } + + var sb strings.Builder + w := tabwriter.NewWriter(&sb, 0, 0, 2, ' ', 0) + fmt.Fprintln(w, "PROJECT_ID\tAPPS\tANALYSES\tREFERENCED_BY") + for _, r := range rows { + refs := append(append([]string{}, r.Apps...), r.Analyses...) + refStr := strings.Join(refs, ", ") + if refStr == "" { + refStr = "-" + } + fmt.Fprintf(w, "%s\t%d\t%d\t%s\n", + r.ProjectID, len(r.Apps), len(r.Analyses), refStr) + } + w.Flush() + + fmt.Fprintf(&sb, "\n%d project_id huérfanos (referenciados por hijos pero sin fila en projects).\n", len(rows)) + return sb.String() +} diff --git a/functions/infra/audit_projects_coverage.md b/functions/infra/audit_projects_coverage.md new file mode 100644 index 00000000..1cf5e9e7 --- /dev/null +++ b/functions/infra/audit_projects_coverage.md @@ -0,0 +1,109 @@ +--- +name: audit_projects_coverage +kind: function +lang: go +domain: infra +version: "1.0.0" +purity: impure +signature: "func AuditProjectsCoverage(registryRoot string) ([]ProjectCoverage, error)" +description: "Audita la cobertura de los projects del registry frente a sus sub-repos Gitea: comprueba si cada project tiene .git local, remote origin y repo_url declarado, y cuantos de sus hijos (apps + analyses) estan clonados en disco versus solo conocidos por la BD. Motor del subcomando fn doctor projects. Solo lee registry.db + filesystem + git local, nunca la red ni la API de Gitea. Incluye FindOrphanProjectRefs, el check inverso: detecta apps o analyses que declaran un project_id sin fila en la tabla projects (project paraguas huerfano, riesgo de perdida al sincronizar)." +tags: [projects, gitea, subrepo, audit, infra, fn-doctor, doctor] +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: ["database/sql", "os/exec", "path/filepath", "strings", "text/tabwriter", "github.com/mattn/go-sqlite3"] +tested: true +tests: ["healthy project con un hijo sin clonar marca children_missing", "project sin repo_url ni remote marca no_gitea_repo", "project sin directorio en disco marca dir_not_found", "error si registry.db no existe", "repo con origin devuelve true", "repo sin origin devuelve false", "sin issues lo deja claro", "con issues cuenta los afectados", "app con project_id huerfano lo detecta y agrupa ordenado", "app con project_id valido no aparece", "sin huerfanos devuelve slice vacio sin error", "sin huerfanos lo deja claro", "con huerfanos lista ids y cuenta"] +test_file_path: "functions/infra/audit_projects_coverage_test.go" +file_path: "functions/infra/audit_projects_coverage.go" +params: + - name: registryRoot + desc: "Raiz del repositorio (el directorio que contiene registry.db). Los dir_path relativos de projects, apps y analysis se resuelven contra esta raiz." +output: "Slice de ProjectCoverage, una entrada por fila de la tabla projects, con flags de git/remote/repo_url, conteos de hijos clonados vs declarados, y la lista de issues detectados. La funcion de formato FormatProjectsCoverage produce una tabla de texto humano." +--- + +## Ejemplo + +```go +package main + +import ( + "fmt" + + "fn-registry/functions/infra" +) + +func main() { + rows, err := infra.AuditProjectsCoverage("/home/enmanuel/fn_registry") + if err != nil { + panic(err) + } + fmt.Print(infra.FormatProjectsCoverage(rows)) +} +``` + +Salida típica: + +``` +PROJECT GIT REMOTE REPO_URL CHILDREN ISSUES +fleet_monitoring ✓ ✓ ✓ 2/2 - +fn_monitoring ✓ ✓ ✓ 3/3 - +message_bus ✓ ✓ ✓ 3/4 children_missing +web_scraping ✗ ✗ ✗ 0/3 no_gitea_repo; children_missing + +1/4 projects con problemas de cobertura. +``` + +## Check inverso: FindOrphanProjectRefs + +Mientras `AuditProjectsCoverage` parte de la tabla `projects` y mira hacia abajo (¿están sus hijos clonados?), `FindOrphanProjectRefs` recorre el grafo en sentido contrario: parte de las apps y analyses y mira hacia arriba (¿existe el project paraguas que declaran?). Detecta el drift inverso, apps o analyses cuyo `project_id` no tiene ninguna fila en la tabla `projects`. Es un project huérfano: existe en otro PC y nunca se sincronizó a este, o nunca se creó aquí. Es un riesgo de pérdida silenciosa, porque el enlace del hijo apunta a un project que este registro no conoce. + +```go +package main + +import ( + "fmt" + + "fn-registry/functions/infra" +) + +func main() { + orphans, err := infra.FindOrphanProjectRefs("/home/enmanuel/fn_registry") + if err != nil { + panic(err) + } + fmt.Print(infra.FormatOrphanProjectRefs(orphans)) +} +``` + +La firma es `func FindOrphanProjectRefs(registryRoot string) ([]OrphanProjectRef, error)`. Cada `OrphanProjectRef` agrupa, por `ProjectID` huérfano, los ids de las apps (`Apps`) y analyses (`Analyses`) que lo referencian, ambas listas ordenadas alfabéticamente y el slice resultante ordenado por `ProjectID`. Cuando todos los hijos apuntan a un project conocido devuelve un slice vacío (no nil) sin error. `FormatOrphanProjectRefs` produce una tabla de texto humano con el `project_id`, cuántas apps y analyses lo referencian y sus ids; si no hay huérfanos imprime una sola línea dejándolo claro. + +Caso real detectado en este registro: apps con `project_id` ∈ {`element_agents`, `imagegen`, `osint_graph`} sin fila correspondiente en `projects`. + +Salida típica con huérfanos: + +``` +PROJECT_ID APPS ANALYSES REFERENCED_BY +element_agents 1 0 shell_agent +imagegen 1 0 imagegen_ui +osint_graph 2 1 graph_explorer, scraper, gliner_glirel_tuning + +3 project_id huérfanos (referenciados por hijos pero sin fila en projects). +``` + +## Cuando usarla + +Úsala antes de un `/full-git-pull` masivo o tras clonar el registry en un PC nuevo para saber qué projects están realmente respaldados por su sub-repo Gitea y cuántos de sus hijos (apps y analyses) quedarían sin clonar. También como motor del futuro subcomando `fn doctor projects`: el caller la enchufa desde `cmd/fn/doctor.go` igual que `AuditUsesFunctions` o `AuditServicesSpec`, formatea con `FormatProjectsCoverage` para texto humano y serializa el slice directamente para `--json`. + +## Gotchas + +- Es **impura**: lee `registry.db` (abierto en modo read-only `?mode=ro`), recorre el filesystem y ejecuta `git -C remote get-url origin`. No toca la red ni la API de Gitea, así que no necesita token y es rápida. +- `HasRemote` solo se evalúa cuando el project tiene `.git` local; si no hay `.git`, queda `false` sin intentar el comando git. +- `gitHasRemoteOrigin` devuelve `false` ante cualquier error (no hay remote `origin`, no es un repo, git no instalado). No distingue "sin origin" de "git ausente"; si necesitas esa distinción, comprueba `git` por separado. +- El issue `no_gitea_repo` se emite solo cuando faltan **ambos** indicadores (`!HasRemote && !RepoURLDeclared`). Un project con `repo_url` declarado pero sin clonar (`dir_not_found`) NO se marca `no_gitea_repo` — el repo existe en Gitea, simplemente no está en este disco. +- `ChildrenMissing` cuenta los hijos (apps + analyses con ese `project_id`) cuya carpeta no tiene `.git` en disco: son los que se perderían o habría que reclonar. Cero hijos en la BD produce `0/0` y no genera issue. +- Si `projects.dir_path` está vacío, se deriva `projects/`. Los `dir_path` ya absolutos se respetan tal cual. +- Devuelve error únicamente si `registry.db` no puede abrirse o consultarse. Los projects cuyo directorio no existe SÍ aparecen en el resultado, marcados con `dir_not_found`, para que el caller los muestre en vez de descartarlos en silencio. +- `FindOrphanProjectRefs` también es **impura**: lee `registry.db` en modo read-only (`?mode=ro`), pero no toca el filesystem ni git, solo cruza las tablas `projects`, `apps` y `analysis`. Ignora los hijos con `project_id` vacío (no son huérfanos, simplemente no pertenecen a ningún project). Devuelve un slice vacío no-nil cuando no hay huérfanos, así que el caller puede distinguir "sin huérfanos" (slice vacío, error nil) de "fallo al leer la BD" (error no nil). diff --git a/functions/infra/audit_projects_coverage_test.go b/functions/infra/audit_projects_coverage_test.go new file mode 100644 index 00000000..eade9d84 --- /dev/null +++ b/functions/infra/audit_projects_coverage_test.go @@ -0,0 +1,417 @@ +package infra + +import ( + "database/sql" + "os" + "os/exec" + "path/filepath" + "testing" + + _ "github.com/mattn/go-sqlite3" +) + +// seedProjectsRegistry builds a temp registry.db with the columns +// AuditProjectsCoverage reads, plus a handful of on-disk directories that +// model the cloned/missing states. +func seedProjectsRegistry(t *testing.T) string { + t.Helper() + dir := t.TempDir() + dbPath := filepath.Join(dir, "registry.db") + + db, err := sql.Open("sqlite3", dbPath) + if err != nil { + t.Fatalf("open temp db: %v", err) + } + defer db.Close() + + _, err = db.Exec(` + CREATE TABLE projects ( + id TEXT PRIMARY KEY, + dir_path TEXT NOT NULL DEFAULT '', + repo_url TEXT NOT NULL DEFAULT '' + ); + CREATE TABLE apps ( + id TEXT PRIMARY KEY, + dir_path TEXT NOT NULL DEFAULT '', + project_id TEXT NOT NULL DEFAULT '' + ); + CREATE TABLE analysis ( + id TEXT PRIMARY KEY, + dir_path TEXT NOT NULL DEFAULT '', + project_id TEXT NOT NULL DEFAULT '' + ); + `) + if err != nil { + t.Fatalf("create schema: %v", err) + } + + _, err = db.Exec(` + INSERT INTO projects VALUES + ('healthy', 'projects/healthy', 'https://gitea.example/dataforge/healthy'), + ('no_repo', 'projects/no_repo', ''), + ('missing', 'projects/missing', 'https://gitea.example/dataforge/missing'); + INSERT INTO apps VALUES + ('app_cloned', 'projects/healthy/apps/app_cloned', 'healthy'), + ('app_orphan', 'projects/healthy/apps/app_orphan', 'healthy'); + INSERT INTO analysis VALUES + ('an_cloned', 'projects/healthy/analysis/an_cloned', 'healthy'); + `) + if err != nil { + t.Fatalf("seed data: %v", err) + } + + // healthy: directory + .git present; one child cloned, one missing. + mkGitDir(t, dir, "projects/healthy") + mkGitDir(t, dir, "projects/healthy/apps/app_cloned") + mkGitDir(t, dir, "projects/healthy/analysis/an_cloned") + // app_orphan has no .git on disk → counts as missing. + + // no_repo: directory exists, no .git. + if err := os.MkdirAll(filepath.Join(dir, "projects/no_repo"), 0o755); err != nil { + t.Fatalf("mkdir no_repo: %v", err) + } + + // missing: no directory at all on disk. + + return dir +} + +// mkGitDir creates //.git so dirExists treats it as a git repo. +func mkGitDir(t *testing.T, root, rel string) { + t.Helper() + if err := os.MkdirAll(filepath.Join(root, rel, ".git"), 0o755); err != nil { + t.Fatalf("mkdir %s/.git: %v", rel, err) + } +} + +func findCoverage(rows []ProjectCoverage, id string) *ProjectCoverage { + for i := range rows { + if rows[i].ProjectID == id { + return &rows[i] + } + } + return nil +} + +func hasIssue(pc *ProjectCoverage, issue string) bool { + for _, i := range pc.Issues { + if i == issue { + return true + } + } + return false +} + +func TestAuditProjectsCoverage(t *testing.T) { + t.Run("healthy project con un hijo sin clonar marca children_missing", func(t *testing.T) { + dir := seedProjectsRegistry(t) + rows, err := AuditProjectsCoverage(dir) + if err != nil { + t.Fatalf("AuditProjectsCoverage error: %v", err) + } + pc := findCoverage(rows, "healthy") + if pc == nil { + t.Fatal("project 'healthy' missing from results") + } + if !pc.HasGit { + t.Error("expected HasGit=true for healthy") + } + if !pc.RepoURLDeclared { + t.Error("expected RepoURLDeclared=true for healthy") + } + if pc.ChildrenInDB != 3 { + t.Errorf("expected 3 children in db, got %d", pc.ChildrenInDB) + } + if pc.ChildrenCloned != 2 { + t.Errorf("expected 2 cloned children, got %d", pc.ChildrenCloned) + } + if pc.ChildrenMissing != 1 { + t.Errorf("expected 1 missing child, got %d", pc.ChildrenMissing) + } + if !hasIssue(pc, "children_missing") { + t.Errorf("expected children_missing issue, got %v", pc.Issues) + } + }) + + t.Run("project sin repo_url ni remote marca no_gitea_repo", func(t *testing.T) { + dir := seedProjectsRegistry(t) + rows, err := AuditProjectsCoverage(dir) + if err != nil { + t.Fatalf("error: %v", err) + } + pc := findCoverage(rows, "no_repo") + if pc == nil { + t.Fatal("project 'no_repo' missing") + } + if pc.HasGit { + t.Error("expected HasGit=false for no_repo") + } + if pc.RepoURLDeclared { + t.Error("expected RepoURLDeclared=false for no_repo") + } + if !hasIssue(pc, "no_gitea_repo") { + t.Errorf("expected no_gitea_repo issue, got %v", pc.Issues) + } + }) + + t.Run("project sin directorio en disco marca dir_not_found", func(t *testing.T) { + dir := seedProjectsRegistry(t) + rows, err := AuditProjectsCoverage(dir) + if err != nil { + t.Fatalf("error: %v", err) + } + pc := findCoverage(rows, "missing") + if pc == nil { + t.Fatal("project 'missing' missing") + } + if !hasIssue(pc, "dir_not_found") { + t.Errorf("expected dir_not_found issue, got %v", pc.Issues) + } + if pc.HasGit { + t.Error("expected HasGit=false when dir not found") + } + }) + + t.Run("error si registry.db no existe", func(t *testing.T) { + dir := t.TempDir() + if _, err := AuditProjectsCoverage(dir); err == nil { + t.Error("expected error for missing db, got nil") + } + }) +} + +func TestGitHasRemoteOrigin(t *testing.T) { + if _, err := exec.LookPath("git"); err != nil { + t.Skip("git not available") + } + t.Run("repo con origin devuelve true", func(t *testing.T) { + dir := t.TempDir() + runGit(t, dir, "init", "-q") + runGit(t, dir, "remote", "add", "origin", "https://example.com/x.git") + if !gitHasRemoteOrigin(dir) { + t.Error("expected true for repo with origin") + } + }) + t.Run("repo sin origin devuelve false", func(t *testing.T) { + dir := t.TempDir() + runGit(t, dir, "init", "-q") + if gitHasRemoteOrigin(dir) { + t.Error("expected false for repo without origin") + } + }) +} + +func runGit(t *testing.T, dir string, args ...string) { + t.Helper() + cmd := exec.Command("git", append([]string{"-C", dir}, args...)...) + if out, err := cmd.CombinedOutput(); err != nil { + t.Fatalf("git %v: %v\n%s", args, err, out) + } +} + +// seedOrphanRefsRegistry builds a temp registry.db where some children declare +// a project_id with no matching row in the projects table (orphan refs) while +// others reference a valid project. It returns the registry root directory. +func seedOrphanRefsRegistry(t *testing.T, withOrphans bool) string { + t.Helper() + dir := t.TempDir() + dbPath := filepath.Join(dir, "registry.db") + + db, err := sql.Open("sqlite3", dbPath) + if err != nil { + t.Fatalf("open temp db: %v", err) + } + defer db.Close() + + _, err = db.Exec(` + CREATE TABLE projects ( + id TEXT PRIMARY KEY, + dir_path TEXT NOT NULL DEFAULT '', + repo_url TEXT NOT NULL DEFAULT '' + ); + CREATE TABLE apps ( + id TEXT PRIMARY KEY, + dir_path TEXT NOT NULL DEFAULT '', + project_id TEXT NOT NULL DEFAULT '' + ); + CREATE TABLE analysis ( + id TEXT PRIMARY KEY, + dir_path TEXT NOT NULL DEFAULT '', + project_id TEXT NOT NULL DEFAULT '' + ); + `) + if err != nil { + t.Fatalf("create schema: %v", err) + } + + // One known project exists in the projects table. + if _, err := db.Exec(`INSERT INTO projects VALUES ('known', 'projects/known', '')`); err != nil { + t.Fatalf("seed projects: %v", err) + } + + // app_valid + an_valid reference the known project: never orphans. + if _, err := db.Exec(` + INSERT INTO apps VALUES ('app_valid', 'projects/known/apps/app_valid', 'known'); + INSERT INTO analysis VALUES ('an_valid', 'projects/known/analysis/an_valid', 'known'); + `); err != nil { + t.Fatalf("seed valid children: %v", err) + } + + // app_no_project has an empty project_id: must be ignored. + if _, err := db.Exec(`INSERT INTO apps VALUES ('app_no_project', 'apps/app_no_project', '')`); err != nil { + t.Fatalf("seed no-project app: %v", err) + } + + if withOrphans { + // Two apps + one analysis pointing at 'ghost' (missing from projects), + // plus one app pointing at 'specter' (also missing). Insert the apps for + // 'ghost' out of alphabetical order to exercise sorting. + if _, err := db.Exec(` + INSERT INTO apps VALUES ('app_zeta', 'apps/app_zeta', 'ghost'); + INSERT INTO apps VALUES ('app_alpha', 'apps/app_alpha', 'ghost'); + INSERT INTO analysis VALUES ('an_ghost', 'analysis/an_ghost', 'ghost'); + INSERT INTO apps VALUES ('app_specter', 'apps/app_specter', 'specter'); + `); err != nil { + t.Fatalf("seed orphan children: %v", err) + } + } + + return dir +} + +func findOrphan(rows []OrphanProjectRef, id string) *OrphanProjectRef { + for i := range rows { + if rows[i].ProjectID == id { + return &rows[i] + } + } + return nil +} + +func TestFindOrphanProjectRefs(t *testing.T) { + t.Run("app con project_id huerfano lo detecta y agrupa ordenado", func(t *testing.T) { + dir := seedOrphanRefsRegistry(t, true) + rows, err := FindOrphanProjectRefs(dir) + if err != nil { + t.Fatalf("FindOrphanProjectRefs error: %v", err) + } + if len(rows) != 2 { + t.Fatalf("expected 2 orphan refs, got %d: %+v", len(rows), rows) + } + // Sorted by ProjectID: ghost before specter. + if rows[0].ProjectID != "ghost" || rows[1].ProjectID != "specter" { + t.Fatalf("expected [ghost specter], got [%s %s]", rows[0].ProjectID, rows[1].ProjectID) + } + + ghost := findOrphan(rows, "ghost") + if ghost == nil { + t.Fatal("orphan 'ghost' missing") + } + wantApps := []string{"app_alpha", "app_zeta"} // alphabetical + if len(ghost.Apps) != 2 || ghost.Apps[0] != wantApps[0] || ghost.Apps[1] != wantApps[1] { + t.Errorf("expected ghost.Apps=%v, got %v", wantApps, ghost.Apps) + } + if len(ghost.Analyses) != 1 || ghost.Analyses[0] != "an_ghost" { + t.Errorf("expected ghost.Analyses=[an_ghost], got %v", ghost.Analyses) + } + + specter := findOrphan(rows, "specter") + if specter == nil { + t.Fatal("orphan 'specter' missing") + } + if len(specter.Apps) != 1 || specter.Apps[0] != "app_specter" { + t.Errorf("expected specter.Apps=[app_specter], got %v", specter.Apps) + } + if len(specter.Analyses) != 0 { + t.Errorf("expected specter.Analyses empty, got %v", specter.Analyses) + } + }) + + t.Run("app con project_id valido no aparece", func(t *testing.T) { + dir := seedOrphanRefsRegistry(t, true) + rows, err := FindOrphanProjectRefs(dir) + if err != nil { + t.Fatalf("error: %v", err) + } + if findOrphan(rows, "known") != nil { + t.Error("valid project 'known' should not appear as orphan") + } + // Children of 'known' must never be listed in any orphan entry. + for _, r := range rows { + for _, a := range append(append([]string{}, r.Apps...), r.Analyses...) { + if a == "app_valid" || a == "an_valid" || a == "app_no_project" { + t.Errorf("child %q with valid/empty project leaked into orphan %q", a, r.ProjectID) + } + } + } + }) + + t.Run("sin huerfanos devuelve slice vacio sin error", func(t *testing.T) { + dir := seedOrphanRefsRegistry(t, false) + rows, err := FindOrphanProjectRefs(dir) + if err != nil { + t.Fatalf("error: %v", err) + } + if rows == nil { + t.Fatal("expected non-nil empty slice, got nil") + } + if len(rows) != 0 { + t.Errorf("expected 0 orphans, got %d: %+v", len(rows), rows) + } + }) + + t.Run("error si registry.db no existe", func(t *testing.T) { + dir := t.TempDir() + if _, err := FindOrphanProjectRefs(dir); err == nil { + t.Error("expected error for missing db, got nil") + } + }) +} + +func TestFormatOrphanProjectRefs(t *testing.T) { + t.Run("sin huerfanos lo deja claro", func(t *testing.T) { + out := FormatOrphanProjectRefs(nil) + if !contains(out, "0 project_id huérfanos") { + t.Errorf("expected clean message, got:\n%s", out) + } + }) + + t.Run("con huerfanos lista ids y cuenta", func(t *testing.T) { + rows := []OrphanProjectRef{ + {ProjectID: "ghost", Apps: []string{"app_alpha", "app_zeta"}, Analyses: []string{"an_ghost"}}, + } + out := FormatOrphanProjectRefs(rows) + if !contains(out, "ghost") { + t.Errorf("expected project_id in output, got:\n%s", out) + } + if !contains(out, "app_alpha") || !contains(out, "an_ghost") { + t.Errorf("expected referencing ids in output, got:\n%s", out) + } + if !contains(out, "1 project_id huérfanos") { + t.Errorf("expected count line, got:\n%s", out) + } + }) +} + +func TestFormatProjectsCoverage(t *testing.T) { + t.Run("sin issues lo deja claro", func(t *testing.T) { + rows := []ProjectCoverage{ + {ProjectID: "ok", HasGit: true, HasRemote: true, RepoURLDeclared: true, ChildrenInDB: 2, ChildrenCloned: 2}, + } + out := FormatProjectsCoverage(rows) + if !contains(out, "0 projects con problemas de cobertura") { + t.Errorf("expected clean message, got:\n%s", out) + } + }) + + t.Run("con issues cuenta los afectados", func(t *testing.T) { + rows := []ProjectCoverage{ + {ProjectID: "bad", Issues: []string{"no_gitea_repo"}}, + {ProjectID: "ok", HasGit: true, HasRemote: true, RepoURLDeclared: true}, + } + out := FormatProjectsCoverage(rows) + if !contains(out, "1/2 projects con problemas de cobertura") { + t.Errorf("expected 1/2 count, got:\n%s", out) + } + }) +} diff --git a/projects/fn_monitoring/project.md b/projects/fn_monitoring/project.md deleted file mode 100644 index d84be5d6..00000000 --- a/projects/fn_monitoring/project.md +++ /dev/null @@ -1,281 +0,0 @@ ---- -name: fn_monitoring -description: "Monitoreo y visualizacion del estado del fn_registry. API HTTP read-only sobre las bases de datos SQLite y dashboard ImGui que consume la API." -tags: [monitoring, api, dashboard, sqlite, visualization] -repo_url: "https://gitea-dgg044oo04woo4ggcsws4gk0.organic-machine.com/dataforge/fn_monitoring" ---- - -## Apps - -| App | Lang | Descripcion | -|-----|------|-------------| -| [sqlite_api](apps/sqlite_api/app.md) | Go | API REST HTTP read-only sobre `registry.db` y todas las `operations.db`. Puerto `8484`. | -| [registry_dashboard](apps/registry_dashboard/app.md) | C++ / ImGui | Dashboard con KPIs, charts y tablas del registry. Consume `sqlite_api` (HTTP) con fallback a SQLite directo. | - -Cada `app.md` es la referencia canonica del binario — endpoints completos, flags, dependencias. Este documento cubre **como operar el proyecto como un todo**: arranque, service, flujo de datos, troubleshooting. - ---- - -## Arquitectura - -``` - registry.db (raiz) - apps/*/operations.db - projects/*/apps/*/operations.db - │ (read-only, mode=ro) - ▼ - ┌──────────────────────────────────────────────┐ - │ sqlite_api (Go net/http, :8484) │ - │ /health │ - │ /api/databases │ - │ /api/databases/:db/tables │ - │ /api/databases/:db/schema │ - │ /api/databases/:db/query (POST, SELECT) │ - │ /api/databases/:db/fts │ - └──────────────────────────────────────────────┘ - ▲ - │ HTTP GET/POST - │ (cpp-httplib + nlohmann/json) - │ - ┌──────────────────────────────────────────────┐ - │ registry_dashboard (C++ / ImGui + ImPlot) │ - │ main.cpp → reload_data() │ - │ data_http.cpp (primario, HTTP) │ - │ data.cpp (fallback, SQLite C API) │ - │ views.cpp → KPI row, charts, tables │ - └──────────────────────────────────────────────┘ -``` - -**Separacion de responsabilidades:** - -- `sqlite_api` **no conoce el dashboard**. Es una API generica: expone cualquier DB SQLite de `fn_registry/` read-only con FTS5. -- `registry_dashboard` **no conoce la estructura de registry.db directamente**, solo a traves del JSON que devuelve la API. El modo SQLite directo es fallback para entornos sin red. - -**Puerto `8484`** — elegido para no colisionar con Metabase (3000), Jupyter (8888) ni deploy_server (9090). - ---- - -## Servicio sqlite_api - -### Modos de arranque - -| Modo | Comando | Cuando usarlo | -|------|---------|---------------| -| Dev (foreground, `go run`) | `cd projects/fn_monitoring/apps/sqlite_api && go run -tags fts5 .` | Iteracion rapida, ver logs en la terminal | -| Dev (background) | `./start.sh` (dentro de `apps/sqlite_api/`) | Probar el dashboard rapido sin systemd. Escribe PID en `sqlite_api.pid` y log en `sqlite_api.log` | -| Production (systemd) | `sudo systemctl start sqlite_api` | Arranque en boot, restart on failure, logs en journal | - -### Variables de entorno - -| Var | Valor | Proposito | -|-----|-------|-----------| -| `FN_REGISTRY_ROOT` | ruta absoluta a la raiz del registry | Evita que el binario busque `registry.db` subiendo por el cwd. Obligatoria bajo systemd. | - -### Instalar como servicio systemd (local) - -Usar el pipeline del registry `install_systemd_service_bash_pipelines`: - -```bash -cd /home/lucas/fn_registry - -# 1. Build del binario -CGO_ENABLED=1 go build -tags fts5 \ - -o projects/fn_monitoring/apps/sqlite_api/sqlite_api \ - ./projects/fn_monitoring/apps/sqlite_api/ - -# 2. Instalar unit + enable + start (requiere sudo sin password para systemctl) -source bash/functions/pipelines/install_systemd_service.sh -install_systemd_service \ - --name sqlite_api \ - --exec "$(pwd)/projects/fn_monitoring/apps/sqlite_api/sqlite_api" \ - --workdir "$(pwd)" \ - --env "FN_REGISTRY_ROOT=$(pwd)" \ - --description "fn_registry SQLite HTTP API" \ - --after network.target \ - --restart on-failure -``` - -### Operacion - -```bash -sudo systemctl status sqlite_api # estado + ultimas lineas del journal -sudo systemctl restart sqlite_api # tras rebuild del binario -sudo systemctl stop sqlite_api # parar -journalctl -u sqlite_api -f # logs en vivo -curl http://127.0.0.1:8484/health # health check -``` - -### Redeploy tras cambios en el codigo Go - -```bash -cd /home/lucas/fn_registry -CGO_ENABLED=1 go build -tags fts5 \ - -o projects/fn_monitoring/apps/sqlite_api/sqlite_api \ - ./projects/fn_monitoring/apps/sqlite_api/ -sudo systemctl restart sqlite_api -``` - -No hace falta reinstalar el unit — solo recompilar y reiniciar. - ---- - -## Dashboard registry_dashboard - -### Build - -```bash -cd cpp -cmake -B build/linux -S . -cmake --build build/linux --target registry_dashboard -j$(nproc) -``` - -El binario queda en `cpp/build/linux/registry_dashboard` (o `projects/fn_monitoring/apps/registry_dashboard/registry_dashboard.exe` en Windows). - -### Ejecucion - -```bash -# Modo API (por defecto, intenta localhost:8484) -./registry_dashboard - -# API remoto -./registry_dashboard --api http://192.168.1.10:8484 - -# API + fallback SQLite -./registry_dashboard --api http://127.0.0.1:8484 /home/lucas/fn_registry/registry.db - -# Solo SQLite (sin API) -./registry_dashboard /home/lucas/fn_registry/registry.db -``` - -La UI muestra en la cabecera de donde vienen los datos (HTTP vs SQLite). `F5` recarga. - -### Flujo de datos - -1. `main.cpp::reload_data()` intenta HTTP primero via `load_registry_data_http()`. -2. Si la API responde `200` y el JSON parsea, los datos pueblan `RegistryData`. -3. Si falla la API (timeout, 5xx, JSON invalido) y hay `--db`, cae a `load_registry_data()` (SQLite directo). -4. Si ninguno funciona, la UI muestra un mensaje de error y no hay reintento automatico — hay que pulsar reload. - -### Vistas - -| Seccion | Datos | Query subyacente | -|---------|-------|------------------| -| KPI row (8 cards) | totales y porcentajes | `SELECT COUNT(*)` sobre functions, types, apps, analysis, unit_tests, proposals + agregados tested/pure | -| Charts (bar + pie) | funciones por lang/domain, reparto pure/impure, kind | `GROUP BY lang`, `GROUP BY domain`, `GROUP BY purity`, `GROUP BY kind` | -| Tablas | ultimas 20 functions, apps, analysis, types | `ORDER BY updated_at DESC LIMIT 20` | - -Detalle de composicion de componentes viz en `apps/registry_dashboard/app.md`. - ---- - -## Troubleshooting - -| Sintoma | Causa probable | Verificacion / Fix | -|---------|----------------|--------------------| -| Dashboard dice "HTTP API failed, falling back to SQLite" | `sqlite_api` no esta corriendo | `curl http://127.0.0.1:8484/health` — si falla, `systemctl status sqlite_api` o `./start.sh` | -| `sqlite_api` arranca y muere inmediatamente | No encuentra `registry.db` | Exportar `FN_REGISTRY_ROOT=/home/lucas/fn_registry` o correr desde la raiz del registry | -| `systemctl start sqlite_api` pide password | Falta sudoers para systemctl | Ver `.claude/rules/deploy.md` — el usuario necesita `NOPASSWD` para `systemctl`, `mv` a `/etc/systemd/system/` | -| Dashboard abre pero todas las cifras son 0 | API conecta pero devuelve DB vacia | `curl -X POST http://127.0.0.1:8484/api/databases/registry/query -d '{"sql":"SELECT COUNT(*) FROM functions"}'` | -| API responde lento / timeout | Query pesada sobre FTS5 | Timeout hardcoded a 5s en `handlers.go`. Revisar la query en journal. | -| Bind rechazado (`address already in use`) | Otro proceso en `8484` | `ss -tlnp | grep 8484` — matar el huerfano o cambiar `--bind` | - -### Logs - -```bash -# systemd -journalctl -u sqlite_api -n 100 --no-pager -journalctl -u sqlite_api -f - -# start.sh -tail -f projects/fn_monitoring/apps/sqlite_api/sqlite_api.log -``` - ---- - -## Como extender - -### Anadir un endpoint a sqlite_api - -1. Registrar la ruta en `Server.Routes()` (`handlers.go`). -2. Handler lee `r.URL.Path` / `r.Body`, delega en `DBPool` para resolver la DB, ejecuta SQL read-only. -3. Test en `handlers_test.go` (patron: tabla de casos HTTP). -4. Rebuild + `systemctl restart sqlite_api`. -5. Documentar en `apps/sqlite_api/app.md` (tabla de endpoints). - -### Anadir una vista al dashboard - -1. Nuevo campo en `RegistryData` (`data.h`) + su equivalente en la respuesta JSON. -2. Parseo en `data_http.cpp` y carga SQL en `data.cpp` (ambos paths, para mantener el fallback). -3. Renderizado en `views.cpp` usando componentes del dominio `viz` (`kpi_card`, `bar_chart`, etc.) — ver regla `frontend_theming` analoga para C++: usar primitivos del registry antes que ImGui crudo. -4. Rebuild con CMake. - -### Anadir una DB nueva - -La descubre automaticamente `DiscoverDatabases()` escaneando `apps/*/operations.db` y `projects/*/apps/*/operations.db`. No hay que registrar nada — al reiniciar `sqlite_api` aparecen con alias `ops:{app_name}`. - ---- - -## Deploy en otros PCs - -Este proyecto se instala identico en cualquier maquina con el registry clonado: - -1. `fn sync` para traer los metadatos del proyecto. -2. Build + systemd install (seccion "Instalar como servicio systemd" arriba). -3. Build del dashboard. - -Los datos son los `.db` locales — cada PC ve su propio estado del registry y sus propias `operations.db`. No hay sincronizacion remota de datos en este servicio: para eso existe `fn sync` contra `registry_api` (proyecto diferente, ver memoria `project_registry_api`). - ---- - -## Estado actual - -### Fase — projects view + mutaciones desde el dashboard `[done 2026-04-25]` - -El dashboard pasa de read-only a manipular el registry via la API. Ampliacion en tres patas: - -**Backend (`sqlite_api`)** — endpoints nuevos en `handlers_projects.go` y `handlers_mutations.go`: - -| Metodo | Path | Que hace | -|---|---|---| -| `GET` | `/api/projects` | Lista con conteos `apps_count` / `analyses_count` / `vaults_count` por proyecto + bloque `orphans` (entidades con `project_id` vacio). | -| `GET` | `/api/projects/{id}` | Detalle: apps[], analyses[], vaults[]. Acepta `id="orphans"` para devolver las huerfanas. | -| `POST` | `/api/reindex` | Ejecuta `fn index` desde `registryRoot`, devuelve `{ok, output}`. | -| `POST` | `/api/add/app` | Body `{name, lang, domain, project, description}` → crea `apps/{name}/` o `projects/{p}/apps/{name}/` con `app.md` minimo + `fn index`. | -| `POST` | `/api/add/analysis` | Body `{name, project, packages[], description}` → invoca `fn run init_jupyter_analysis [--project p] name pkg1 pkg2 ...`. | -| `POST` | `/api/add/vault` | Body `{name, project, path, description}` → crea dir o symlink en `projects/{p}/vaults/` + entry append en `vault.yaml`. | - -`Server.registryRoot` se inyecta en `NewServer(pool, root)` (rebajado de `findRegistryRoot()` en `main.go`). Helpers `runFN()` y `runShell()` ejecutan con `cmd.Dir = registryRoot` y `FN_REGISTRY_ROOT` en el env. - -**Dashboard (`registry_dashboard`)** — actions bar + tab Projects + modal Add: - -- Toolbar nueva en el header (`fn_ui::toolbar`): boton `Reindex` (Primary) → dispara `http_post_reindex` via `process_runner`; boton `+ Add` → abre `modal_dialog`; boton `Reload`; `toast_inbox_button` con badge. -- Modal Add con `select` para kind (App / Analysis / Vault), `select` de proyecto (obligatorio para Vault, opcional para resto), `text_input` Name + Description y campos especificos por kind (lang/domain para App, packages CSV para Analysis, abs path para Vault). Submit dispara el endpoint correspondiente via `process_runner`. Toast al completar + reload automatico. -- Tab Projects con dos columnas: `tree_view` izquierda (proyectos + entrada "(orphans)" cuando hay entidades huerfanas), detalle derecha con tabs internas Apps / Analysis / Vaults. Click en un proyecto dispara `load_project_detail_http`. - -**Datos en `RegistryData`**: nuevos `projects[]`, `orphan_apps`, `orphan_analyses`, `orphan_vaults`. Tipos nuevos `ProjectRow`, `VaultRow`, `ProjectDetail`. `load_registry_data_http` llama a `load_projects_http` al final como best-effort (no fatal si falla). - -### Bug fix — vibracion al redimensionar `[done 2026-04-25]` - -Dos fuentes de "vibracion" durante drag-resize de la ventana: - -- `fullscreen_window_cpp_core` v0.2: anadido `NoScrollbar | NoScrollWithMouse`. Sin esto, si el contenido excedia por 1-2px aparecia un scrollbar fugaz que reducia el ancho ~14px y reflowaba todo. -- `views.cpp::draw_dashboard`: altura de charts pasa de `GetContentRegionAvail().y * 0.35` a constante 260 px. La proporcion relativa propagaba el resize a todos los plots. -- `kpi_card_cpp_viz` v1.2: altura fija 78 px (antes 108) + scale 1.4x (antes 1.8) + padding sm + `NoScrollbar`. El `AutoResizeY` con 8 cards generaba lag perceptible al redimensionar. - -### Bug fix — HTTP POST timeout en thread de background `[done 2026-04-25]` - -`http_client.cpp::request()` pasaba `struct timeval` a `setsockopt(SO_RCVTIMEO)` en Windows, donde MSDN especifica `DWORD` ms. Resultado: timeout efectivo de **5 ms** en lugar de **5 s**. Se nota especialmente en POST desde threads (background runners) porque la latencia de scheduling puede pasar de 5 ms. Fix: rama `_WIN32` con `DWORD timeout_ms`. Tambien `wsa_init` envuelto en `std::call_once` para evitar race entre main thread + runners. Mensajes de error formateados con ASCII (em dash U+2014 falla render con la fuente default). - -### Tooling sibling — primitives_gallery `[done 2026-04-25]` - -Nueva app dev en `cpp/apps/primitives_gallery/` (no es app del registry, vive en el source tree). Catalogo visual interactivo de los 19 primitivos UI de `cpp/functions/{core,viz}` con sidebar + panel + snippet por demo. Doble rol: smoke test visual al modificar tokens/componentes y build gate (esta en el CMake principal — si un primitivo rompe API la gallery no compila). - -Demo destacada: `graph_viewport` con sliders de Nodes (100-20 000), Clusters (2-16) y los tres parametros de `ForceLayoutConfig` (Repulsion / Attraction / Gravity) aplicados en vivo. Util tambien como benchmark de rendimiento del stack `graph_renderer` + `graph_force_layout` + `graph_spatial_hash`. - -`README.md` propio en `cpp/apps/primitives_gallery/README.md`. - -### Lo siguiente que pega - -- Tests unitarios de logica pura (Phase A del plan de tests): vendoreado de `doctest`, ~6 tests para `label_stride`, `slice_at`, `process_runner` transitions, `toast` queue, `tokens` sanity, `parse_url`. Cierra el ciclo gallery (visual) + ctest (logica). -- Para que algunos tests sean posibles hace falta exponer funciones internas de `bar_chart.cpp` y `pie_chart.cpp` (actualmente en namespace anonimo). -- `loginctl enable-linger lucas` para que el `sqlite_api.service` (user-level systemd) sobreviva al logout. Requiere sudo una vez. Decision pendiente del usuario. diff --git a/python/functions/cybersecurity/__init__.py b/python/functions/cybersecurity/__init__.py index 5b3eb4a1..096182b8 100644 --- a/python/functions/cybersecurity/__init__.py +++ b/python/functions/cybersecurity/__init__.py @@ -22,6 +22,21 @@ from .extract_mac_addresses import extract_mac_addresses from .extract_phone_numbers import extract_phone_numbers from .extract_iocs import extract_iocs +# OSINT passive atomic functions (grupo osint-passive). +from .extract_exif_metadata import extract_exif_metadata +from .extract_pdf_metadata import extract_pdf_metadata +from .guess_email_formats import guess_email_formats +from .enumerate_username_sites import enumerate_username_sites +from .build_search_dorks import build_search_dorks +from .whois_lookup import whois_lookup +from .dns_records import dns_records +from .enum_subdomains_crtsh import enum_subdomains_crtsh + +# OSINT passive enrichment orchestrators (grupo osint-enrich). +from .scan_ficha_attachments_metadata import scan_ficha_attachments_metadata +from .enrich_person_passive import enrich_person_passive +from .enrich_org_passive import enrich_org_passive + __all__ = [ "hash_sha256", "hash_md5", @@ -44,4 +59,15 @@ __all__ = [ "extract_mac_addresses", "extract_phone_numbers", "extract_iocs", + "extract_exif_metadata", + "extract_pdf_metadata", + "guess_email_formats", + "enumerate_username_sites", + "build_search_dorks", + "whois_lookup", + "dns_records", + "enum_subdomains_crtsh", + "scan_ficha_attachments_metadata", + "enrich_person_passive", + "enrich_org_passive", ] diff --git a/python/functions/cybersecurity/build_search_dorks.md b/python/functions/cybersecurity/build_search_dorks.md new file mode 100644 index 00000000..fc405f9d --- /dev/null +++ b/python/functions/cybersecurity/build_search_dorks.md @@ -0,0 +1,64 @@ +--- +name: build_search_dorks +kind: function +lang: py +domain: cybersecurity +version: "1.0.0" +purity: pure +signature: "def build_search_dorks(target: str, tipo: str = 'persona', extra_domains: list | None = None) -> list" +description: "Genera consultas (dorks) de motor de busqueda para investigar un target segun su tipo (persona|email|dominio|usuario): frase exacta, site:linkedin, filetype:pdf, intext con cv/curriculum, site: filetype:xlsx, dorks de leaks/pastebin para email, redes sociales para usuario, etc. extra_domains acota via site:. OSINT pasivo puro, sin red." +tags: [osint-passive, dork, search, recon, google-dork, cybersecurity, python] +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "" +imports: [] +params: + - name: target + desc: "Cadena objetivo: nombre de persona, email, dominio o username segun el tipo." + - name: tipo + desc: "Uno de 'persona', 'email', 'dominio', 'usuario'. Cualquier otro valor devuelve solo la frase exacta. Default 'persona'." + - name: extra_domains + desc: "Lista opcional de dominios para añadir dorks 'site: \"\"' independientemente del tipo." +output: "Lista de strings de dork listos para pegar en un buscador, en orden de generacion." +tested: true +tests: + - "test_persona_genera_dorks_esperados" + - "test_email_genera_dorks_esperados" + - "test_dominio_genera_site_dorks" + - "test_usuario_genera_redes_sociales" + - "test_extra_domains_acota_con_site" + - "test_tipo_desconocido_solo_frase_exacta" +test_file_path: "python/functions/cybersecurity/build_search_dorks_test.py" +file_path: "python/functions/cybersecurity/build_search_dorks.py" +--- + +## Ejemplo + +```python +build_search_dorks("Juan Perez", tipo="persona", extra_domains=["acme.com"]) +# ['"Juan Perez"', +# '"Juan Perez" filetype:pdf', +# 'site:linkedin.com/in "Juan Perez"', +# 'site:twitter.com "Juan Perez"', +# 'intext:"Juan Perez" (curriculum OR cv OR resume)', +# '"Juan Perez" (email OR correo OR contacto)', +# '"Juan Perez" filetype:doc OR "Juan Perez" filetype:docx', +# 'site:acme.com "Juan Perez"'] + +build_search_dorks("empresa.com", tipo="dominio") +# ['"empresa.com"', 'site:empresa.com', 'site:empresa.com filetype:pdf', +# 'site:empresa.com filetype:xlsx', 'site:empresa.com (login OR admin OR dashboard)', ...] +``` + +## Cuando usarla + +Usala cuando ya tengas un target identificado (persona, email, dominio o alias) y quieras una bateria de consultas de buscador listas para pegar manualmente y mapear documentos, perfiles y posibles filtraciones. Encaja despues de `guess_email_formats` (dorks de email) o `enumerate_username_sites` (dorks de usuario/persona) en una investigacion autorizada. + +## Gotchas + +- Funcion pura: solo genera strings de consulta, NO ejecuta busquedas ni toca la red. Los dorks se pegan a mano en el buscador. +- La sintaxis usa operadores de Google (site:, filetype:, intext:, inurl:); otros buscadores soportan un subconjunto distinto y algunos dorks no funcionaran igual. +- Para tipos no reconocidos devuelve unicamente la frase exacta entre comillas (mas los `extra_domains` si se pasan), no falla. +- Uso solo para investigacion OSINT autorizada; los dorks de leaks/breaches/pastebin pueden devolver datos sensibles cuyo tratamiento esta sujeto a ley. diff --git a/python/functions/cybersecurity/build_search_dorks.py b/python/functions/cybersecurity/build_search_dorks.py new file mode 100644 index 00000000..ba0753cc --- /dev/null +++ b/python/functions/cybersecurity/build_search_dorks.py @@ -0,0 +1,81 @@ +"""Genera consultas (dorks) de motor de busqueda para investigar un target. + +Funcion pura de OSINT pasivo: a partir de un target y su tipo (persona, +email, dominio o usuario) produce una lista de cadenas de busqueda listas +para pegar en un buscador. No toca la red. +""" + + +def build_search_dorks( + target: str, + tipo: str = "persona", + extra_domains: list | None = None, +) -> list: + """Genera dorks de motor de busqueda adaptados al tipo de target. + + Segun el tipo seleccionado produce las consultas mas utiles para + investigar: + + - persona: nombre exacto, en linkedin, con cv/curriculum, en ficheros. + - email: el email entre comillas, en pastebin/breaches, en filetypes. + - dominio: site:dominio, ficheros expuestos, subdominios, paneles. + - usuario: el alias en redes sociales y foros. + + `extra_domains` añade dorks `site: ""` para acotar la + busqueda a dominios concretos, independientemente del tipo. + + Args: + target: cadena objetivo (nombre, email, dominio o username). + tipo: uno de "persona", "email", "dominio", "usuario". Cualquier + otro valor cae al conjunto generico (solo la frase exacta). + extra_domains: lista opcional de dominios para acotar via site:. + + Returns: + lista de strings de dork en orden de generacion (sin deduplicar + salvo el dork de frase exacta, que es la base comun). + """ + q = f'"{target}"' # frase exacta, base de casi todo dork + dorks = [q] + t = tipo.strip().lower() + + if t == "persona": + dorks += [ + f"{q} filetype:pdf", + f'site:linkedin.com/in {q}', + f'site:twitter.com {q}', + f'intext:{q} (curriculum OR cv OR resume)', + f'{q} (email OR correo OR contacto)', + f'{q} filetype:doc OR {q} filetype:docx', + ] + elif t == "email": + dorks += [ + f'{q} site:pastebin.com', + f'{q} (leak OR breach OR dump OR password)', + f'{q} filetype:txt', + f'{q} filetype:csv', + f'{q} site:github.com', + ] + elif t == "dominio": + dorks += [ + f'site:{target}', + f'site:{target} filetype:pdf', + f'site:{target} filetype:xlsx', + f'site:{target} (login OR admin OR dashboard)', + f'site:{target} intext:(password OR contraseña)', + f'site:*.{target}', + f'-www site:{target}', + ] + elif t == "usuario": + dorks += [ + f'{q} site:github.com', + f'{q} site:reddit.com', + f'{q} (profile OR perfil OR user OR usuario)', + f'inurl:{target}', + ] + # Cualquier otro tipo: solo la frase exacta (ya añadida). + + if extra_domains: + for dom in extra_domains: + dorks.append(f'site:{dom} {q}') + + return dorks diff --git a/python/functions/cybersecurity/build_search_dorks_test.py b/python/functions/cybersecurity/build_search_dorks_test.py new file mode 100644 index 00000000..536eaf7a --- /dev/null +++ b/python/functions/cybersecurity/build_search_dorks_test.py @@ -0,0 +1,56 @@ +"""Tests para build_search_dorks.""" + +from build_search_dorks import build_search_dorks + + +def test_persona_genera_dorks_esperados(): + """El tipo persona produce frase exacta, linkedin, cv y filetypes.""" + out = build_search_dorks("Juan Perez", tipo="persona") + assert '"Juan Perez"' in out + assert '"Juan Perez" filetype:pdf' in out + assert any("linkedin.com" in d for d in out) + assert any("curriculum OR cv OR resume" in d for d in out) + + +def test_email_genera_dorks_esperados(): + """El tipo email busca en pastebin, breaches y filetypes.""" + out = build_search_dorks("bob@corp.com", tipo="email") + assert '"bob@corp.com"' in out + assert any("pastebin.com" in d for d in out) + assert any("leak OR breach OR dump OR password" in d for d in out) + assert '"bob@corp.com" filetype:csv' in out + + +def test_dominio_genera_site_dorks(): + """El tipo dominio produce site: y ficheros expuestos.""" + out = build_search_dorks("empresa.com", tipo="dominio") + assert "site:empresa.com" in out + assert "site:empresa.com filetype:xlsx" in out + assert any("login OR admin OR dashboard" in d for d in out) + assert "site:*.empresa.com" in out + + +def test_usuario_genera_redes_sociales(): + """El tipo usuario busca en github, reddit y por inurl.""" + out = build_search_dorks("jdoe", tipo="usuario") + assert '"jdoe"' in out + assert any("github.com" in d for d in out) + assert any("reddit.com" in d for d in out) + assert "inurl:jdoe" in out + + +def test_extra_domains_acota_con_site(): + """extra_domains añade dorks site: con la frase exacta.""" + out = build_search_dorks( + "Ana Ruiz", tipo="persona", extra_domains=["uni.edu", "gov.es"] + ) + assert 'site:uni.edu "Ana Ruiz"' in out + assert 'site:gov.es "Ana Ruiz"' in out + + +def test_tipo_desconocido_solo_frase_exacta(): + """Un tipo no reconocido devuelve solo la frase exacta (mas extras).""" + out = build_search_dorks("algo", tipo="otracosa") + assert out[0] == '"algo"' + # Sin extras y tipo desconocido, solo la frase base. + assert out == ['"algo"'] diff --git a/python/functions/cybersecurity/dns_records.md b/python/functions/cybersecurity/dns_records.md new file mode 100644 index 00000000..f3e3eba5 --- /dev/null +++ b/python/functions/cybersecurity/dns_records.md @@ -0,0 +1,58 @@ +--- +name: dns_records +kind: function +lang: py +domain: cybersecurity +version: "1.0.0" +purity: impure +signature: "def dns_records(dominio: str, types: list | None = None) -> dict" +description: "Recoleccion OSINT pasiva de registros DNS de un dominio ejecutando `dig +short ` por subprocess para cada tipo (default A, AAAA, MX, TXT, NS, CNAME). Parsea la salida (una linea por valor) y devuelve un dict {tipo: [valores]}. Pasivo: solo consulta DNS publico." +tags: [osint-passive, dns, recon, cybersecurity, dig] +params: + - name: dominio + desc: "Dominio a resolver, ej. organic-machine.com. Vacio lanza RuntimeError." + - name: types + desc: "Lista de tipos de registro DNS (ej. ['A','MX']). None usa los 6 defaults: A, AAAA, MX, TXT, NS, CNAME." +output: "dict {tipo: [valores]} con una clave por tipo consultado; cada valor es la lista de lineas devueltas por `dig +short` para ese tipo (lista vacia si no hay registro o el dominio no existe)." +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: [] +tested: true +tests: ["test_parsea_salida_de_dig", "test_dominio_inexistente_listas_vacias", "test_usa_tipos_default", "test_timeout_devuelve_lista_vacia", "test_dominio_vacio_lanza_error"] +test_file_path: "python/functions/cybersecurity/dns_records_test.py" +file_path: "python/functions/cybersecurity/dns_records.py" +--- + +## Ejemplo + +```python +import sys, os +sys.path.insert(0, os.path.join("python", "functions")) +from cybersecurity import dns_records + +# Resolver todos los tipos por defecto +records = dns_records("organic-machine.com") +print(records["A"]) # ['135.125.201.30'] +print(records["MX"]) # ['10 mail.organic-machine.com.', ...] + +# Solo los tipos que interesan +solo_a_mx = dns_records("organic-machine.com", types=["A", "MX"]) +``` + +## Cuando usarla + +Usala al iniciar el reconocimiento pasivo de un dominio para mapear su +infraestructura DNS publica (IPs, servidores de correo, nameservers, TXT con +SPF/DKIM/verificaciones). Es el primer paso barato antes de enumerar +subdominios o consultar RDAP. + +## Gotchas + +- Requiere el binario `dig` en PATH (paquete `dnsutils`/`bind-utils`). Si falta, lanza `RuntimeError`. +- Cada consulta tiene timeout de 10s; si una expira, esa clave queda como lista vacia y el resto continua. +- La salida es la de `dig +short` cruda: los MX incluyen prioridad ("10 mail..."), los nombres pueden venir con punto final (FQDN), y los TXT entre comillas. No se normaliza para mantener fidelidad. +- Un dominio inexistente o sin un registro concreto devuelve lista vacia (no error): distingue "sin datos" mirando las listas vacias. +- Resuelve contra el resolver configurado en el sistema; resultados pueden variar segun el DNS recursivo usado. diff --git a/python/functions/cybersecurity/dns_records.py b/python/functions/cybersecurity/dns_records.py new file mode 100644 index 00000000..108aae4c --- /dev/null +++ b/python/functions/cybersecurity/dns_records.py @@ -0,0 +1,63 @@ +"""Recoleccion OSINT pasiva de registros DNS via el binario `dig`. + +Funcion IMPURA: ejecuta `dig +short ` como subprocess para +cada tipo de registro y parsea la salida (una linea por valor). Es OSINT +pasivo: consulta DNS publico, no envia trafico intrusivo al objetivo. +""" + +import subprocess + +DEFAULT_TYPES = ["A", "AAAA", "MX", "TXT", "NS", "CNAME"] + + +def dns_records(dominio: str, types: list | None = None) -> dict: + """Resuelve registros DNS de un dominio ejecutando `dig +short`. + + Para cada tipo en ``types`` ejecuta ``dig +short `` y + parsea la salida: cada linea no vacia es un valor del registro. Un + dominio inexistente (o un registro ausente) produce una lista vacia. + + Args: + dominio: Dominio a resolver (ej. ``"organic-machine.com"``). + types: Lista de tipos de registro DNS (ej. ``["A", "MX"]``). Si es + None usa los defaults: A, AAAA, MX, TXT, NS, CNAME. + + Returns: + Dict ``{tipo: [valores]}`` con una clave por tipo consultado. Cada + valor es la lista de lineas devueltas por dig para ese tipo. + + Raises: + RuntimeError: Si el binario `dig` no esta instalado o el dominio + esta vacio. + """ + if not dominio or not dominio.strip(): + raise RuntimeError("dns_records: dominio vacio") + + query_types = types if types is not None else list(DEFAULT_TYPES) + result: dict = {} + + for record_type in query_types: + try: + proc = subprocess.run( + ["dig", "+short", record_type, dominio], + capture_output=True, + text=True, + timeout=10.0, + ) + except FileNotFoundError as e: + raise RuntimeError( + "dns_records: binario `dig` no encontrado en PATH" + ) from e + except subprocess.TimeoutExpired: + # Timeout en una consulta concreta: dejamos lista vacia y seguimos. + result[record_type] = [] + continue + + values = [ + line.strip() + for line in proc.stdout.splitlines() + if line.strip() + ] + result[record_type] = values + + return result diff --git a/python/functions/cybersecurity/dns_records_test.py b/python/functions/cybersecurity/dns_records_test.py new file mode 100644 index 00000000..5d5685bf --- /dev/null +++ b/python/functions/cybersecurity/dns_records_test.py @@ -0,0 +1,90 @@ +"""Tests para dns_records.""" + +import os +import subprocess +import sys + +sys.path.insert(0, os.path.dirname(__file__)) + +from dns_records import dns_records + + +class _FakeProc: + def __init__(self, stdout: str): + self.stdout = stdout + self.returncode = 0 + + +def test_parsea_salida_de_dig(monkeypatch): + """Cada linea no vacia de dig se convierte en un valor del registro.""" + fixtures = { + "A": "135.125.201.30\n", + "MX": "10 mail.organic-machine.com.\n20 mail2.organic-machine.com.\n", + "TXT": '"v=spf1 -all"\n', + } + + def fake_run(cmd, **kwargs): + record_type = cmd[2] + return _FakeProc(fixtures.get(record_type, "")) + + monkeypatch.setattr(subprocess, "run", fake_run) + + result = dns_records("organic-machine.com", types=["A", "MX", "TXT"]) + + assert result["A"] == ["135.125.201.30"] + assert result["MX"] == [ + "10 mail.organic-machine.com.", + "20 mail2.organic-machine.com.", + ] + assert result["TXT"] == ['"v=spf1 -all"'] + + +def test_dominio_inexistente_listas_vacias(monkeypatch): + """Salida vacia de dig (dominio inexistente) produce listas vacias.""" + + def fake_run(cmd, **kwargs): + return _FakeProc("") + + monkeypatch.setattr(subprocess, "run", fake_run) + + result = dns_records("nope-no-existe-xyz.invalid", types=["A", "AAAA"]) + + assert result == {"A": [], "AAAA": []} + + +def test_usa_tipos_default(monkeypatch): + """Sin types consulta los 6 tipos por defecto.""" + consultados = [] + + def fake_run(cmd, **kwargs): + consultados.append(cmd[2]) + return _FakeProc("") + + monkeypatch.setattr(subprocess, "run", fake_run) + + result = dns_records("organic-machine.com") + + assert set(result.keys()) == {"A", "AAAA", "MX", "TXT", "NS", "CNAME"} + assert consultados == ["A", "AAAA", "MX", "TXT", "NS", "CNAME"] + + +def test_timeout_devuelve_lista_vacia(monkeypatch): + """Un timeout en una consulta deja lista vacia y no aborta el resto.""" + + def fake_run(cmd, **kwargs): + raise subprocess.TimeoutExpired(cmd, 10.0) + + monkeypatch.setattr(subprocess, "run", fake_run) + + result = dns_records("organic-machine.com", types=["A"]) + + assert result == {"A": []} + + +def test_dominio_vacio_lanza_error(): + """Dominio vacio lanza RuntimeError.""" + try: + dns_records("") + assert False, "deberia haber lanzado RuntimeError" + except RuntimeError: + pass diff --git a/python/functions/cybersecurity/enrich_org_passive.md b/python/functions/cybersecurity/enrich_org_passive.md new file mode 100644 index 00000000..f5fcc314 --- /dev/null +++ b/python/functions/cybersecurity/enrich_org_passive.md @@ -0,0 +1,52 @@ +--- +name: enrich_org_passive +kind: function +lang: py +domain: cybersecurity +version: "1.0.0" +purity: impure +signature: "def enrich_org_passive(dominio: str) -> dict" +description: "Orquestador OSINT pasivo: perfil de una organizacion por su dominio usando solo fuentes publicas. Compone whois_lookup (registro WHOIS), dns_records (registros DNS) y enum_subdomains_crtsh (subdominios via Certificate Transparency / crt.sh). Devuelve whois + dns + subdomains." +tags: [osint-enrich, osint-passive, cybersecurity, org, whois, dns, subdomains] +uses_functions: [whois_lookup_py_cybersecurity, dns_records_py_cybersecurity, enum_subdomains_crtsh_py_cybersecurity] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: [] +params: + - name: dominio + desc: "dominio de la organizacion, p.ej. organic-machine.com. No puede estar vacio (ValueError). Se hace strip de espacios" +output: "dict con whois (salida de whois_lookup(dominio)), dns (salida de dns_records(dominio)) y subdomains (salida de enum_subdomains_crtsh(dominio))" +tested: true +tests: ["test_golden_compone_whois_dns_subdomains", "test_dominio_vacio_lanza", "test_dominio_con_espacios_se_normaliza"] +test_file_path: "python/functions/cybersecurity/enrich_org_passive_test.py" +file_path: "python/functions/cybersecurity/enrich_org_passive.py" +--- + +## Ejemplo + +```python +import sys, os +sys.path.insert(0, os.path.join("python", "functions")) +from cybersecurity import enrich_org_passive + +res = enrich_org_passive("organic-machine.com") + +print(res["whois"]["registrar"]) # registrar segun WHOIS +print(res["dns"].get("A")) # registros A del dominio +print(res["subdomains"][:5]) # primeros subdominios vistos en crt.sh +``` + +## Cuando usarla + +- Cuando arrancas la ficha OSINT de una organizacion y quieres su perfil pasivo (quien registro el dominio, su DNS y su superficie de subdominios) sin enviar trafico ofensivo a la infraestructura. +- Como reconocimiento previo, completamente pasivo, antes de cualquier evaluacion activa (que requeriria otra autorizacion explicita). +- Para mapear de un golpe la huella publica de un dominio: WHOIS + DNS + Certificate Transparency en una sola llamada. + +## Gotchas + +- **Uso solo para investigacion autorizada.** El reconocimiento de infraestructura ajena debe contar con permiso del propietario o ampararse en una base legitima. +- Funcion IMPURA: hace consultas de red (WHOIS, DNS y HTTP a crt.sh). Es pasiva respecto al objetivo (no le envia trafico ofensivo), pero **deja huella** en los servicios consultados (logs de crt.sh, resolvers DNS, servidores WHOIS). +- La salida depende de la disponibilidad y rate-limiting de las fuentes: WHOIS puede venir truncado/redactado (GDPR), crt.sh puede limitar o tardar, y algunos registros DNS pueden no existir. Maneja claves ausentes en el dict resultante. +- crt.sh solo ve subdominios que hayan emitido certificados TLS publicos: la lista NO es exhaustiva (no incluye subdominios sin cert o con certs privados). diff --git a/python/functions/cybersecurity/enrich_org_passive.py b/python/functions/cybersecurity/enrich_org_passive.py new file mode 100644 index 00000000..8651538e --- /dev/null +++ b/python/functions/cybersecurity/enrich_org_passive.py @@ -0,0 +1,47 @@ +"""Orquestador OSINT pasivo: perfil de una organizacion por su dominio. + +Compone funciones atomicas del registro (`whois_lookup`, `dns_records`, +`enum_subdomains_crtsh`) para construir un perfil pasivo de una organizacion a +partir de su dominio, usando solo fuentes publicas (WHOIS, DNS, Certificate +Transparency via crt.sh) sin contactar directamente con la infraestructura del +objetivo mas alla de las consultas DNS estandar. + +Funcion IMPURA: hace consultas de red (WHOIS, DNS, HTTP a crt.sh). +""" + +from cybersecurity import dns_records, enum_subdomains_crtsh, whois_lookup + + +def enrich_org_passive(dominio: str) -> dict: + """Construye un perfil OSINT pasivo de una organizacion por su dominio. + + Agrega tres fuentes publicas: el registro WHOIS del dominio, sus registros + DNS y los subdominios observados en Certificate Transparency (crt.sh). + + Args: + dominio: dominio de la organizacion, p.ej. `organic-machine.com`. + + Returns: + dict con las claves: + - whois: salida de whois_lookup(dominio). + - dns: salida de dns_records(dominio). + - subdomains: salida de enum_subdomains_crtsh(dominio). + + Raises: + ValueError: si el dominio esta vacio. + """ + if not (dominio or "").strip(): + raise ValueError("dominio no puede estar vacio") + + dominio = dominio.strip() + + # Resiliente a fallo parcial: si una fuente externa falla (p.ej. crt.sh lento o + # rate-limitado), se registra el error y se devuelven las demas igualmente. + result = {"whois": {}, "dns": {}, "subdomains": [], "errors": {}} + for key, fn in (("whois", whois_lookup), ("dns", dns_records), + ("subdomains", enum_subdomains_crtsh)): + try: + result[key] = fn(dominio) + except Exception as exc: # noqa: BLE001 — captura amplia a proposito por fuente + result["errors"][key] = f"{type(exc).__name__}: {exc}" + return result diff --git a/python/functions/cybersecurity/enrich_org_passive_test.py b/python/functions/cybersecurity/enrich_org_passive_test.py new file mode 100644 index 00000000..6db14d14 --- /dev/null +++ b/python/functions/cybersecurity/enrich_org_passive_test.py @@ -0,0 +1,87 @@ +"""Tests para enrich_org_passive. + +Las funciones compuestas (whois_lookup, dns_records, enum_subdomains_crtsh) se +monkeypatchean para no tocar la red. Solo se verifica la orquestacion: que +ensambla las tres fuentes bajo las claves correctas y normaliza el dominio. +""" + +import importlib +import os +import sys + +import pytest + +sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..")) + +from cybersecurity import enrich_org_passive + +# El paquete re-exporta la funcion bajo el mismo nombre que el submodulo; para +# parchear los globals del modulo lo tomamos via importlib. +mod = importlib.import_module("cybersecurity.enrich_org_passive") + + +def test_golden_compone_whois_dns_subdomains(monkeypatch): + monkeypatch.setattr(mod, "whois_lookup", lambda d: {"domain": d, "registrar": "OVH"}) + monkeypatch.setattr(mod, "dns_records", lambda d: {"A": ["1.2.3.4"], "MX": ["mx.x"]}) + monkeypatch.setattr(mod, "enum_subdomains_crtsh", lambda d: [f"www.{d}", f"api.{d}"]) + + res = enrich_org_passive("organic-machine.com") + + assert res["whois"] == {"domain": "organic-machine.com", "registrar": "OVH"} + assert res["dns"] == {"A": ["1.2.3.4"], "MX": ["mx.x"]} + assert res["subdomains"] == ["www.organic-machine.com", "api.organic-machine.com"] + assert set(res.keys()) == {"whois", "dns", "subdomains", "errors"} + assert res["errors"] == {} # sin fallos cuando todas las fuentes responden + + +def test_fuente_que_falla_se_captura_en_errors(monkeypatch): + """Si una fuente externa peta (p.ej. crt.sh), se registra en errors y el resto se devuelve.""" + monkeypatch.setattr(mod, "whois_lookup", lambda d: {"registrar": "OVH"}) + monkeypatch.setattr(mod, "dns_records", lambda d: {"A": ["1.2.3.4"]}) + + def boom(d): + raise RuntimeError("crt.sh 404") + monkeypatch.setattr(mod, "enum_subdomains_crtsh", boom) + + res = enrich_org_passive("organic-machine.com") + assert res["whois"] == {"registrar": "OVH"} + assert res["dns"] == {"A": ["1.2.3.4"]} + assert res["subdomains"] == [] + assert "subdomains" in res["errors"] and "crt.sh 404" in res["errors"]["subdomains"] + + +def test_dominio_vacio_lanza(monkeypatch): + monkeypatch.setattr(mod, "whois_lookup", lambda d: {}) + monkeypatch.setattr(mod, "dns_records", lambda d: {}) + monkeypatch.setattr(mod, "enum_subdomains_crtsh", lambda d: []) + with pytest.raises(ValueError): + enrich_org_passive(" ") + + +def test_dominio_con_espacios_se_normaliza(monkeypatch): + seen = {} + + def whois(d): + seen["whois"] = d + return {} + + def dns(d): + seen["dns"] = d + return {} + + def subs(d): + seen["subs"] = d + return [] + + monkeypatch.setattr(mod, "whois_lookup", whois) + monkeypatch.setattr(mod, "dns_records", dns) + monkeypatch.setattr(mod, "enum_subdomains_crtsh", subs) + + enrich_org_passive(" organic-machine.com ") + + # Las tres funciones reciben el dominio ya sin espacios. + assert seen == { + "whois": "organic-machine.com", + "dns": "organic-machine.com", + "subs": "organic-machine.com", + } diff --git a/python/functions/cybersecurity/enrich_person_passive.md b/python/functions/cybersecurity/enrich_person_passive.md new file mode 100644 index 00000000..115bff21 --- /dev/null +++ b/python/functions/cybersecurity/enrich_person_passive.md @@ -0,0 +1,64 @@ +--- +name: enrich_person_passive +kind: function +lang: py +domain: cybersecurity +version: "1.0.0" +purity: impure +signature: "def enrich_person_passive(nombre: str, apellidos: str, dominios: list | None = None, usernames: list | None = None) -> dict" +description: "Orquestador OSINT pasivo: genera candidatos de enriquecimiento de una persona SIN tocar al objetivo. Compone guess_email_formats (emails candidatos por cada dominio dado, o gmail/outlook por defecto), enumerate_username_sites (comprobacion de usernames en servicios publicos) y build_search_dorks (dorks tipo persona, que NO se ejecutan, solo se generan)." +tags: [osint-enrich, osint-passive, cybersecurity, person, email, username, dorks] +uses_functions: [guess_email_formats_py_cybersecurity, enumerate_username_sites_py_cybersecurity, build_search_dorks_py_cybersecurity] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: [] +params: + - name: nombre + desc: "nombre de pila de la persona" + - name: apellidos + desc: "apellido(s) de la persona. nombre y apellidos no pueden estar ambos vacios (ValueError)" + - name: dominios + desc: "lista de dominios de correo donde generar formatos de email candidatos. None o vacia => usa los dominios comunes gmail.com/outlook.com" + - name: usernames + desc: "lista de usernames a comprobar en sitios publicos via enumerate_username_sites. None o vacia => no se comprueba ningun username" +output: "dict con email_candidates (lista de emails candidatos NO verificados, deduplicada y ordenada), username_hits (lista de {username, hits} con el resultado de enumerate_username_sites por username) y dorks (lista de dorks de busqueda tipo persona generados pero NO ejecutados)" +tested: true +tests: ["test_golden_compone_emails_usernames_y_dorks", "test_sin_dominios_usa_comunes", "test_sin_usernames_no_comprueba", "test_nombre_y_apellidos_vacios_lanza", "test_emails_deduplicados"] +test_file_path: "python/functions/cybersecurity/enrich_person_passive_test.py" +file_path: "python/functions/cybersecurity/enrich_person_passive.py" +--- + +## Ejemplo + +```python +import sys, os +sys.path.insert(0, os.path.join("python", "functions")) +from cybersecurity import enrich_person_passive + +res = enrich_person_passive( + "Juan", "Perez", + dominios=["organic-machine.com"], + usernames=["jperez", "juanp"], +) + +print(res["email_candidates"]) # ['juan.perez@organic-machine.com', 'jperez@organic-machine.com', ...] +for u in res["username_hits"]: + print(u["username"], len(u["hits"])) # sitios publicos donde aparece cada username +print(res["dorks"]) # dorks listos para pegar en un buscador (no se ejecutan aqui) +``` + +## Cuando usarla + +- Cuando arrancas la ficha OSINT de una persona y quieres una primera tanda de candidatos (emails probables, presencia de usernames, dorks) sin enviar nada al objetivo ni a su correo. +- Antes de verificar manualmente: genera el espacio de candidatos para que despues confirmes cuales son reales. +- Como paso pasivo previo a cualquier accion activa (que requeriria otra autorizacion y otras funciones). + +## Gotchas + +- **Uso solo para investigacion autorizada.** Generar candidatos sobre una persona sin base legitima puede vulnerar privacidad/leyes de proteccion de datos. +- Los `email_candidates` son **candidatos NO verificados**: son permutaciones plausibles del nombre, NO emails confirmados. No asumas que existen ni los uses para envio. +- Funcion IMPURA: `enumerate_username_sites` consulta servicios publicos por red, lo que **deja una huella minima** (requests a esos sitios). `build_search_dorks` y `guess_email_formats` son locales. +- Los dorks se **generan pero NO se ejecutan** aqui: ejecutarlos en un buscador es un paso aparte y deja su propia huella. +- Si no aportas `dominios`, se usan gmail.com/outlook.com como heuristica; ajusta la lista a los dominios reales del entorno de la persona para candidatos utiles. diff --git a/python/functions/cybersecurity/enrich_person_passive.py b/python/functions/cybersecurity/enrich_person_passive.py new file mode 100644 index 00000000..92f73eaf --- /dev/null +++ b/python/functions/cybersecurity/enrich_person_passive.py @@ -0,0 +1,79 @@ +"""Orquestador OSINT pasivo: genera candidatos de enriquecimiento de una persona. + +Compone funciones atomicas del registro (`guess_email_formats`, +`enumerate_username_sites`, `build_search_dorks`) para producir candidatos OSINT +de una persona SIN contactar ni atacar al objetivo. Los dorks se generan pero +NO se ejecutan. + +Funcion IMPURA: `enumerate_username_sites` consulta servicios publicos (red). +""" + +from cybersecurity import ( + build_search_dorks, + enumerate_username_sites, + guess_email_formats, +) + +# Dominios de correo comunes usados cuando el caller no aporta dominios propios. +_COMMON_EMAIL_DOMAINS = ("gmail.com", "outlook.com") + + +def enrich_person_passive( + nombre: str, + apellidos: str, + dominios: list | None = None, + usernames: list | None = None, +) -> dict: + """Genera candidatos OSINT pasivos para una persona. + + Para cada dominio aportado (o los dominios comunes gmail/outlook si no se da + ninguno) genera los formatos de email candidatos. Para cada username + aportado comprueba en que sitios publicos existe. Ademas genera dorks de + busqueda de tipo persona (que NO se ejecutan, solo se devuelven). + + Args: + nombre: nombre de pila de la persona. + apellidos: apellido(s) de la persona. + dominios: lista de dominios de correo donde buscar formatos de email. + Si es None o vacia, se usan los dominios comunes gmail/outlook. + usernames: lista de usernames a comprobar en sitios publicos. Si es None + o vacia, no se realiza ninguna comprobacion de username. + + Returns: + dict con las claves: + - email_candidates: lista de emails candidatos (no verificados). + - username_hits: lista de resultados de enumerate_username_sites por + cada username comprobado. + - dorks: lista de dorks de busqueda generados (no ejecutados). + + Raises: + ValueError: si nombre y apellidos estan ambos vacios. + """ + if not (nombre or "").strip() and not (apellidos or "").strip(): + raise ValueError("nombre y apellidos no pueden estar ambos vacios") + + target_domains = [d for d in (dominios or []) if d] or list(_COMMON_EMAIL_DOMAINS) + + email_candidates: list = [] + for dominio in target_domains: + candidates = guess_email_formats(nombre, apellidos, dominio) + if candidates: + email_candidates.extend(candidates) + # Deduplicar preservando orden. + email_candidates = list(dict.fromkeys(email_candidates)) + + username_hits: list = [] + for username in usernames or []: + if not username: + continue + hits = enumerate_username_sites(username) + username_hits.append({"username": username, "hits": hits}) + + target = f"{nombre} {apellidos}".strip() + dorks = build_search_dorks(target, "persona") + + return { + "email_candidates": email_candidates, + "username_hits": username_hits, + "dorks": dorks, + } diff --git a/python/functions/cybersecurity/enrich_person_passive_test.py b/python/functions/cybersecurity/enrich_person_passive_test.py new file mode 100644 index 00000000..a898618d --- /dev/null +++ b/python/functions/cybersecurity/enrich_person_passive_test.py @@ -0,0 +1,97 @@ +"""Tests para enrich_person_passive. + +Las funciones compuestas (guess_email_formats, enumerate_username_sites, +build_search_dorks) se monkeypatchean. Solo se verifica la orquestacion: que +itera por dominios/usernames, deduplica emails, usa dominios comunes por +defecto y genera (sin ejecutar) los dorks. +""" + +import importlib +import os +import sys + +import pytest + +sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..")) + +from cybersecurity import enrich_person_passive + +# El paquete re-exporta la funcion bajo el mismo nombre que el submodulo; para +# parchear los globals del modulo lo tomamos via importlib. +mod = importlib.import_module("cybersecurity.enrich_person_passive") + + +def _patch(monkeypatch, *, emails_fn=None, usernames_fn=None, dorks_fn=None): + monkeypatch.setattr( + mod, + "guess_email_formats", + emails_fn or (lambda n, a, d: [f"{n.lower()}.{a.lower()}@{d}", f"{n[0].lower()}{a.lower()}@{d}"]), + ) + monkeypatch.setattr( + mod, + "enumerate_username_sites", + usernames_fn or (lambda u: [{"site": "github", "url": f"https://github.com/{u}", "exists": True}]), + ) + monkeypatch.setattr( + mod, + "build_search_dorks", + dorks_fn or (lambda target, tipo: [f'"{target}" {tipo}', f'intext:"{target}"']), + ) + + +def test_golden_compone_emails_usernames_y_dorks(monkeypatch): + _patch(monkeypatch) + + res = enrich_person_passive( + "Juan", "Perez", + dominios=["organic-machine.com"], + usernames=["jperez", "juanp"], + ) + + assert res["email_candidates"] == [ + "juan.perez@organic-machine.com", + "jperez@organic-machine.com", + ] + assert [u["username"] for u in res["username_hits"]] == ["jperez", "juanp"] + assert res["username_hits"][0]["hits"][0]["site"] == "github" + assert res["dorks"] == ['"Juan Perez" persona', 'intext:"Juan Perez"'] + + +def test_sin_dominios_usa_comunes(monkeypatch): + seen_domains = [] + + def emails(n, a, d): + seen_domains.append(d) + return [f"{n}@{d}"] + + _patch(monkeypatch, emails_fn=emails) + + res = enrich_person_passive("Ana", "Lopez") + + assert seen_domains == ["gmail.com", "outlook.com"] + assert res["email_candidates"] == ["Ana@gmail.com", "Ana@outlook.com"] + + +def test_sin_usernames_no_comprueba(monkeypatch): + called = [] + _patch(monkeypatch, usernames_fn=lambda u: called.append(u) or []) + + res = enrich_person_passive("Ana", "Lopez", dominios=["x.com"]) + + assert res["username_hits"] == [] + assert called == [] # enumerate_username_sites no se invoca + + +def test_nombre_y_apellidos_vacios_lanza(monkeypatch): + _patch(monkeypatch) + with pytest.raises(ValueError): + enrich_person_passive("", " ") + + +def test_emails_deduplicados(monkeypatch): + # Dos dominios distintos que devuelven el mismo email -> debe deduplicar. + _patch(monkeypatch, emails_fn=lambda n, a, d: ["dup@same.com", "dup@same.com"]) + + res = enrich_person_passive("Juan", "Perez", dominios=["a.com", "b.com"]) + + assert res["email_candidates"] == ["dup@same.com"] diff --git a/python/functions/cybersecurity/enum_subdomains_crtsh.md b/python/functions/cybersecurity/enum_subdomains_crtsh.md new file mode 100644 index 00000000..79dd7723 --- /dev/null +++ b/python/functions/cybersecurity/enum_subdomains_crtsh.md @@ -0,0 +1,66 @@ +--- +name: enum_subdomains_crtsh +kind: function +lang: py +domain: cybersecurity +version: "1.0.0" +purity: impure +signature: "def enum_subdomains_crtsh(dominio: str, timeout_s: float = 20.0) -> list" +description: "Enumeracion OSINT pasiva de subdominios desde Certificate Transparency (crt.sh). Consulta https://crt.sh/?q=%25.&output=json con http_get_json, extrae name_value de cada certificado, separa por saltos de linea, deduplica, filtra wildcards (*.) y devuelve la lista ordenada de subdominios unicos. Pasivo: no toca al objetivo, consulta logs CT publicos." +tags: [osint-passive, subdomains, crtsh, certificate-transparency, recon, cybersecurity] +params: + - name: dominio + desc: "Dominio base a enumerar, ej. organic-machine.com. Vacio lanza RuntimeError." + - name: timeout_s + desc: "Segundos maximo de espera de la peticion HTTP a crt.sh (default 20.0)." +output: "Lista ordenada de subdominios unicos (en minusculas, sin wildcards) que aparecen en certificados emitidos para el dominio. Lista vacia si crt.sh no devuelve resultados." +uses_functions: ["http_get_json_py_infra"] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: [] +tested: true +tests: ["test_dedup_y_orden", "test_filtra_wildcards", "test_respuesta_vacia", "test_respuesta_no_lista_lanza_error", "test_dominio_vacio_lanza_error"] +test_file_path: "python/functions/cybersecurity/enum_subdomains_crtsh_test.py" +file_path: "python/functions/cybersecurity/enum_subdomains_crtsh.py" +--- + +## Ejemplo + +```python +import sys, os +sys.path.insert(0, os.path.join("python", "functions")) +from cybersecurity import enum_subdomains_crtsh + +subs = enum_subdomains_crtsh("organic-machine.com") +for s in subs: + print(s) +# api.organic-machine.com +# mail.organic-machine.com +# organic-machine.com +# www.organic-machine.com +``` + +## Cuando usarla + +Usala para descubrir la superficie de subdominios de un objetivo sin enviarle +trafico: los logs de Certificate Transparency listan todos los nombres para +los que se han emitido certificados TLS. Complementa a `dns_records` +(resolucion) y `whois_lookup` (registro) en el reconocimiento pasivo inicial. + +## Gotchas + +- Es OSINT **pasivo**: consulta los logs CT publicos via crt.sh, NO toca al + dominio objetivo ni resuelve los subdominios encontrados (algunos pueden + estar muertos o no resolver). +- crt.sh suele ir lento o rate-limitear bajo carga; para dominios grandes la + respuesta puede tardar varios segundos o agotar el `timeout_s`. Subir el + timeout o reintentar si falla. +- Solo encuentra subdominios que han tenido certificado TLS emitido y logueado + en CT; subdominios internos sin certificado publico no apareceran. +- Los wildcards (`*.dominio`) se filtran porque no son hosts concretos. +- crt.sh devuelve un array JSON (no un objeto); por eso si la respuesta no es + una lista se lanza `RuntimeError`. +- Puede incluir subdominios de niveles arbitrarios y dominios relacionados que + compartieron certificado SAN; revisa la salida antes de usarla como verdad. diff --git a/python/functions/cybersecurity/enum_subdomains_crtsh.py b/python/functions/cybersecurity/enum_subdomains_crtsh.py new file mode 100644 index 00000000..7388f3d4 --- /dev/null +++ b/python/functions/cybersecurity/enum_subdomains_crtsh.py @@ -0,0 +1,68 @@ +"""Enumeracion OSINT pasiva de subdominios via Certificate Transparency (crt.sh). + +Funcion IMPURA: consulta los logs publicos de Certificate Transparency a +traves de crt.sh y extrae los subdominios que han aparecido en certificados +emitidos para el dominio. Es OSINT pasivo: no toca al dominio objetivo, solo +consulta registros CT publicos. +""" + +import os +import sys + +sys.path.insert( + 0, os.path.join(os.path.dirname(__file__), "..", "..", "functions") +) + +from infra.http_get_json import http_get_json # noqa: E402 + + +def enum_subdomains_crtsh(dominio: str, timeout_s: float = 20.0) -> list: + """Enumera subdominios de un dominio desde Certificate Transparency. + + Consulta ``https://crt.sh/?q=%25.&output=json`` (``%25`` = ``%``, + el wildcard de crt.sh) usando ``http_get_json`` del registry. crt.sh + devuelve un array JSON de certificados; de cada uno se toma el campo + ``name_value`` (que puede contener varios nombres separados por saltos de + linea, uno por SAN). Se separan, deduplican, se filtran los wildcards + (``*.``) y se devuelve la lista ordenada de subdominios unicos. + + Args: + dominio: Dominio base a enumerar (ej. ``"organic-machine.com"``). + timeout_s: Segundos maximo de espera de la peticion HTTP (default 20). + + Returns: + Lista ordenada de subdominios unicos (sin wildcards). Lista vacia si + crt.sh no devuelve resultados. + + Raises: + RuntimeError: Si el dominio esta vacio o la peticion HTTP falla. + """ + if not dominio or not dominio.strip(): + raise RuntimeError("enum_subdomains_crtsh: dominio vacio") + + dom = dominio.strip().lower() + # %25 es el wildcard '%' de crt.sh: busca cualquier nombre que termine en . + url = f"https://crt.sh/?q=%25.{dom}&output=json" + + data = http_get_json(url, timeout=timeout_s) + + if not isinstance(data, list): + raise RuntimeError( + f"enum_subdomains_crtsh: respuesta crt.sh inesperada " + f"(tipo {type(data).__name__})" + ) + + found: set = set() + for cert in data: + if not isinstance(cert, dict): + continue + name_value = cert.get("name_value", "") + for raw_name in name_value.split("\n"): + name = raw_name.strip().lower() + if not name: + continue + if name.startswith("*."): + continue + found.add(name) + + return sorted(found) diff --git a/python/functions/cybersecurity/enum_subdomains_crtsh_test.py b/python/functions/cybersecurity/enum_subdomains_crtsh_test.py new file mode 100644 index 00000000..72ebf559 --- /dev/null +++ b/python/functions/cybersecurity/enum_subdomains_crtsh_test.py @@ -0,0 +1,81 @@ +"""Tests para enum_subdomains_crtsh.""" + +import os +import sys + +sys.path.insert(0, os.path.dirname(__file__)) + +import enum_subdomains_crtsh as esc +from enum_subdomains_crtsh import enum_subdomains_crtsh + + +def _crtsh_sample() -> list: + # crt.sh devuelve un array; name_value puede traer varios SAN separados + # por '\n', con duplicados y wildcards. + return [ + {"name_value": "www.organic-machine.com\norganic-machine.com"}, + {"name_value": "api.organic-machine.com"}, + {"name_value": "www.organic-machine.com"}, # duplicado + {"name_value": "*.organic-machine.com"}, # wildcard, se filtra + {"name_value": "MAIL.Organic-Machine.com"}, # case distinto + ] + + +def test_dedup_y_orden(monkeypatch): + """Subdominios deduplicados, en minusculas y ordenados.""" + monkeypatch.setattr( + esc, "http_get_json", lambda url, timeout=20.0: _crtsh_sample() + ) + + result = enum_subdomains_crtsh("organic-machine.com") + + assert result == [ + "api.organic-machine.com", + "mail.organic-machine.com", + "organic-machine.com", + "www.organic-machine.com", + ] + + +def test_filtra_wildcards(monkeypatch): + """Las entradas '*.dominio' se descartan.""" + monkeypatch.setattr( + esc, + "http_get_json", + lambda url, timeout=20.0: [{"name_value": "*.organic-machine.com"}], + ) + + result = enum_subdomains_crtsh("organic-machine.com") + + assert result == [] + + +def test_respuesta_vacia(monkeypatch): + """crt.sh sin resultados devuelve lista vacia.""" + monkeypatch.setattr(esc, "http_get_json", lambda url, timeout=20.0: []) + + result = enum_subdomains_crtsh("organic-machine.com") + + assert result == [] + + +def test_respuesta_no_lista_lanza_error(monkeypatch): + """Una respuesta que no es lista lanza RuntimeError.""" + monkeypatch.setattr( + esc, "http_get_json", lambda url, timeout=20.0: {"unexpected": "obj"} + ) + + try: + enum_subdomains_crtsh("organic-machine.com") + assert False, "deberia haber lanzado RuntimeError" + except RuntimeError: + pass + + +def test_dominio_vacio_lanza_error(): + """Dominio vacio lanza RuntimeError.""" + try: + enum_subdomains_crtsh("") + assert False, "deberia haber lanzado RuntimeError" + except RuntimeError: + pass diff --git a/python/functions/cybersecurity/enumerate_username_sites.md b/python/functions/cybersecurity/enumerate_username_sites.md new file mode 100644 index 00000000..3bc6beac --- /dev/null +++ b/python/functions/cybersecurity/enumerate_username_sites.md @@ -0,0 +1,60 @@ +--- +name: enumerate_username_sites +kind: function +lang: py +domain: cybersecurity +version: "1.0.0" +purity: impure +signature: "def enumerate_username_sites(username: str, timeout_s: float = 8.0, sites: list | None = None) -> list" +description: "Comprueba si un username existe en ~12 sitios publicos (github, twitter/x, instagram, tiktok, reddit, gitlab, keybase, medium, telegram, youtube, pinterest, about.me) consultando la URL de perfil estilo sherlock ligero. Detecta por codigo HTTP (200 existe, 404 no existe). Cada sitio se consulta aislado en try/except con User-Agent de navegador y allow_redirects: un timeout no aborta el resto. OSINT pasivo." +tags: [osint-passive, username, enumeration, recon, identity, sherlock, cybersecurity, python] +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: [requests] +params: + - name: username + desc: "Nombre de usuario a buscar, sin arroba ni URL (ej. 'jdoe')." + - name: timeout_s + desc: "Timeout en segundos por peticion HTTP. Default 8.0." + - name: sites + desc: "Lista opcional de dicts {'site','url'} donde 'url' lleva el placeholder '{u}'. Si es None usa DEFAULT_SITES (~12 sitios)." +output: "Lista de dicts {'site','url','exists','status'} en el orden de los sitios. 'exists' es True/False/None y 'status' el codigo HTTP (int) o None si la peticion fallo." +tested: true +tests: + - "test_status_200_es_existe" + - "test_status_404_es_no_existe" + - "test_status_otro_es_indeterminado" + - "test_excepcion_por_sitio_no_aborta_el_resto" + - "test_estructura_y_url_formateada" + - "test_lista_por_defecto_tiene_doce_sitios" +test_file_path: "python/functions/cybersecurity/enumerate_username_sites_test.py" +file_path: "python/functions/cybersecurity/enumerate_username_sites.py" +--- + +## Ejemplo + +```python +enumerate_username_sites("torvalds", timeout_s=8.0) +# [{"site": "github", "url": "https://github.com/torvalds", "exists": True, "status": 200}, +# {"site": "twitter", "url": "https://x.com/torvalds", "exists": None, "status": 403}, +# {"site": "instagram","url": "https://www.instagram.com/torvalds/","exists": False, "status": 404}, +# ...] + +# Lista propia de sitios: +enumerate_username_sites("jdoe", sites=[{"site": "github", "url": "https://github.com/{u}"}]) +``` + +## Cuando usarla + +Usala cuando tengas un username (o alias) y quieras un barrido rapido de presencia en redes/plataformas publicas para mapear la huella digital de un objetivo en una investigacion autorizada. Util tras `guess_email_formats` para pivotar de identidad a perfiles, o como entrada para construir dorks con `build_search_dorks`. + +## Gotchas + +- **Deja huella**: aunque es recoleccion "pasiva" desde el punto de vista del objetivo, lanza una peticion HTTP real a cada sitio. Esas peticiones quedan en logs del sitio y pueden asociarse a tu IP. Usa proxy/VPN si la investigacion lo requiere. +- **Falsos positivos/negativos por anti-bot**: muchos sitios (instagram, tiktok, x) devuelven 200 con paginas de login/captcha o bloquean por User-Agent, dando exists=True erroneo o status indeterminado. El 200/404 no es garantia; verifica manualmente los hits relevantes. +- **Respeta rate limits**: lanzar muchas comprobaciones seguidas puede activar bloqueos o baneos temporales por IP. Espacia las consultas en barridos grandes. +- **Estados intermedios**: cualquier codigo distinto de 200/404 (301, 403, 429, 5xx) deja `exists=None`; un fallo de red por sitio deja `status=None` y `exists=None` sin abortar el resto. +- **Solo para investigacion autorizada.** No uses esta funcion para acoso, doxing ni vigilancia sin base legal. diff --git a/python/functions/cybersecurity/enumerate_username_sites.py b/python/functions/cybersecurity/enumerate_username_sites.py new file mode 100644 index 00000000..7d6c8fc3 --- /dev/null +++ b/python/functions/cybersecurity/enumerate_username_sites.py @@ -0,0 +1,91 @@ +"""Comprueba la existencia de un username en sitios publicos (sherlock ligero). + +OSINT pasivo: para un username dado, consulta la URL de perfil de una lista +de sitios conocidos y deduce si la cuenta existe por el codigo de estado +HTTP (200 = existe, 404 = no existe). Cada sitio se consulta de forma +aislada: un fallo (timeout, error de red) no aborta el resto. +""" + +import requests + +# Cada entrada describe un sitio: como construir la URL de perfil a partir +# del username. La deteccion es por codigo de estado (200 existe / 404 no). +DEFAULT_SITES = [ + {"site": "github", "url": "https://github.com/{u}"}, + {"site": "twitter", "url": "https://x.com/{u}"}, + {"site": "instagram", "url": "https://www.instagram.com/{u}/"}, + {"site": "tiktok", "url": "https://www.tiktok.com/@{u}"}, + {"site": "reddit", "url": "https://www.reddit.com/user/{u}"}, + {"site": "gitlab", "url": "https://gitlab.com/{u}"}, + {"site": "keybase", "url": "https://keybase.io/{u}"}, + {"site": "medium", "url": "https://medium.com/@{u}"}, + {"site": "telegram", "url": "https://t.me/{u}"}, + {"site": "youtube", "url": "https://www.youtube.com/@{u}"}, + {"site": "pinterest", "url": "https://www.pinterest.com/{u}/"}, + {"site": "about_me", "url": "https://about.me/{u}"}, +] + +_BROWSER_UA = ( + "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 " + "(KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36" +) + + +def enumerate_username_sites( + username: str, + timeout_s: float = 8.0, + sites: list | None = None, +) -> list: + """Comprueba si un username existe en una lista de sitios publicos. + + Para cada sitio construye la URL de perfil con el username y hace un + GET con User-Agent de navegador siguiendo redirecciones. Interpreta el + codigo de estado final: 200 -> existe, 404 -> no existe, cualquier otro + -> indeterminado (exists=None). Los errores de red por sitio (timeout, + conexion) se capturan y se reportan con status=None y exists=None sin + interrumpir la enumeracion del resto. + + Args: + username: nombre de usuario a buscar (sin arroba ni URL). + timeout_s: timeout en segundos por peticion. Default 8.0. + sites: lista opcional de dicts {"site", "url"} donde "url" contiene + el placeholder "{u}". Si es None se usa DEFAULT_SITES. + + Returns: + lista de dicts {"site", "url", "exists", "status"} en el mismo orden + que la lista de sitios. "exists" es True/False/None y "status" es el + codigo HTTP (int) o None si la peticion fallo. + """ + targets = sites if sites is not None else DEFAULT_SITES + headers = {"User-Agent": _BROWSER_UA} + results = [] + + for entry in targets: + site = entry.get("site", "") + url = entry["url"].format(u=username) + status = None + exists = None + try: + resp = requests.get( + url, + headers=headers, + timeout=timeout_s, + allow_redirects=True, + ) + status = resp.status_code + if status == 200: + exists = True + elif status == 404: + exists = False + else: + exists = None + except requests.RequestException: + # Timeout, error de conexion, demasiados redirects, etc. + status = None + exists = None + + results.append( + {"site": site, "url": url, "exists": exists, "status": status} + ) + + return results diff --git a/python/functions/cybersecurity/enumerate_username_sites_test.py b/python/functions/cybersecurity/enumerate_username_sites_test.py new file mode 100644 index 00000000..757b4a68 --- /dev/null +++ b/python/functions/cybersecurity/enumerate_username_sites_test.py @@ -0,0 +1,109 @@ +"""Tests para enumerate_username_sites (red mockeada con monkeypatch).""" + +import requests + +import enumerate_username_sites as mod +from enumerate_username_sites import enumerate_username_sites + + +class _FakeResp: + """Respuesta HTTP minima con solo status_code.""" + + def __init__(self, status_code): + self.status_code = status_code + + +def _make_get(status_by_url): + """Construye un fake de requests.get que devuelve status por URL.""" + + def _fake_get(url, **kwargs): + return _FakeResp(status_by_url[url]) + + return _fake_get + + +SITES = [ + {"site": "alpha", "url": "https://alpha.test/{u}"}, + {"site": "beta", "url": "https://beta.test/{u}"}, + {"site": "gamma", "url": "https://gamma.test/{u}"}, +] + + +def test_status_200_es_existe(monkeypatch): + """Un 200 marca exists=True.""" + status_map = { + "https://alpha.test/bob": 200, + "https://beta.test/bob": 200, + "https://gamma.test/bob": 200, + } + monkeypatch.setattr(requests, "get", _make_get(status_map)) + out = enumerate_username_sites("bob", sites=SITES) + assert all(r["exists"] is True for r in out) + assert all(r["status"] == 200 for r in out) + + +def test_status_404_es_no_existe(monkeypatch): + """Un 404 marca exists=False.""" + status_map = { + "https://alpha.test/ghost": 404, + "https://beta.test/ghost": 404, + "https://gamma.test/ghost": 404, + } + monkeypatch.setattr(requests, "get", _make_get(status_map)) + out = enumerate_username_sites("ghost", sites=SITES) + assert all(r["exists"] is False for r in out) + assert all(r["status"] == 404 for r in out) + + +def test_status_otro_es_indeterminado(monkeypatch): + """Un codigo distinto de 200/404 deja exists=None pero conserva status.""" + status_map = { + "https://alpha.test/x": 301, + "https://beta.test/x": 403, + "https://gamma.test/x": 500, + } + monkeypatch.setattr(requests, "get", _make_get(status_map)) + out = enumerate_username_sites("x", sites=SITES) + assert [r["exists"] for r in out] == [None, None, None] + assert [r["status"] for r in out] == [301, 403, 500] + + +def test_excepcion_por_sitio_no_aborta_el_resto(monkeypatch): + """Un fallo de red en un sitio no interrumpe la enumeracion.""" + + def _fake_get(url, **kwargs): + if "beta" in url: + raise requests.Timeout("simulado") + return _FakeResp(200) + + monkeypatch.setattr(requests, "get", _fake_get) + out = enumerate_username_sites("u", sites=SITES) + assert len(out) == 3 + by_site = {r["site"]: r for r in out} + assert by_site["alpha"]["exists"] is True + assert by_site["alpha"]["status"] == 200 + # El sitio que fallo queda con status/exists None. + assert by_site["beta"]["exists"] is None + assert by_site["beta"]["status"] is None + assert by_site["gamma"]["exists"] is True + + +def test_estructura_y_url_formateada(monkeypatch): + """Cada resultado lleva las claves esperadas y la URL con el username.""" + status_map = { + "https://alpha.test/neo": 200, + "https://beta.test/neo": 404, + "https://gamma.test/neo": 200, + } + monkeypatch.setattr(requests, "get", _make_get(status_map)) + out = enumerate_username_sites("neo", sites=SITES) + for r in out: + assert set(r.keys()) == {"site", "url", "exists", "status"} + assert "neo" in r["url"] + + +def test_lista_por_defecto_tiene_doce_sitios(): + """La lista DEFAULT_SITES cubre ~12 sitios publicos.""" + assert len(mod.DEFAULT_SITES) == 12 + sites = {s["site"] for s in mod.DEFAULT_SITES} + assert {"github", "instagram", "reddit", "telegram"} <= sites diff --git a/python/functions/cybersecurity/extract_exif_metadata.md b/python/functions/cybersecurity/extract_exif_metadata.md new file mode 100644 index 00000000..e0f62783 --- /dev/null +++ b/python/functions/cybersecurity/extract_exif_metadata.md @@ -0,0 +1,66 @@ +--- +name: extract_exif_metadata +kind: function +lang: py +domain: cybersecurity +version: "1.0.0" +purity: impure +signature: "def extract_exif_metadata(image_path: str) -> dict" +description: "Lee los metadatos EXIF de una imagen con Pillow y los devuelve normalizados (fecha, camara, software, GPS en grados decimales) mas el volcado completo de tags en `raw`. OSINT pasiva sobre documentos propios: revela cuando, con que dispositivo y donde se tomo una foto." +tags: [osint-passive, exif, metadata, image, gps, forensics, pillow, extract, cybersecurity, python] +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: [PIL] +params: + - name: image_path + desc: "ruta al archivo de imagen en disco (JPEG, PNG, TIFF, ...)" +output: "dict con datetime, camera_make, camera_model, software, gps_lat, gps_lon (grados decimales o None) y raw (dict con todos los tags EXIF legibles por nombre). Si la imagen no tiene EXIF, los campos van a None y raw={}." +tested: true +tests: + - "imagen sin EXIF (PNG) devuelve campos None y raw vacio" + - "imagen con EXIF devuelve camara, software y fecha" + - "GPSInfo DMS se convierte a grados decimales con signo por hemisferio" +test_file_path: "python/functions/cybersecurity/extract_exif_metadata_test.py" +file_path: "python/functions/cybersecurity/extract_exif_metadata.py" +--- + +## Ejemplo + +```python +import sys, os +sys.path.insert(0, os.path.join("python", "functions")) +from cybersecurity.extract_exif_metadata import extract_exif_metadata + +meta = extract_exif_metadata( + "/home/enmanuel/Obsidian/osint/attachments/personas/objetivo_01.jpg" +) +print(meta["datetime"]) # '2024:08:12 19:43:07' (cuando se tomo) +print(meta["camera_model"]) # 'iPhone 13 Pro' (con que dispositivo) +print(meta["gps_lat"], meta["gps_lon"]) # 40.4168 -3.7038 (donde) o None, None +``` + +## Cuando usarla + +Cuando recolectes inteligencia pasiva sobre una imagen propia o de un objetivo +y necesites saber cuando, con que dispositivo y desde donde se capturo, antes de +publicarla o compartirla. Usala tambien para auditar tus propios documentos y +detectar fugas de metadatos (geolocalizacion, modelo de telefono, software de +edicion) antes de subirlos a un sitio publico. + +## Gotchas + +- Funcion impura: abre el archivo del disco. Lanza si la ruta no existe o no es + una imagen valida (Pillow `UnidentifiedImageError` / `FileNotFoundError`). +- JPEG y HEIC de moviles suelen traer GPS embebido; PNG normalmente no lleva + EXIF y devolvera todos los campos en None con `raw={}`. +- El GPS revela la ubicacion fisica donde se tomo la foto — dato sensible. No + lo loguees ni lo compartas sin consentimiento. +- `DateTimeOriginal` vive en el sub-IFD EXIF, no en el IFD raiz; algunas + imagenes solo tienen `DateTime` (fecha de modificacion del archivo), que se + usa como fallback. +- Las coordenadas se convierten de DMS (grados/minutos/segundos) a grados + decimales y se les aplica el signo segun `GPSLatitudeRef`/`GPSLongitudeRef` + (S y W => negativo). diff --git a/python/functions/cybersecurity/extract_exif_metadata.py b/python/functions/cybersecurity/extract_exif_metadata.py new file mode 100644 index 00000000..0c27dfe0 --- /dev/null +++ b/python/functions/cybersecurity/extract_exif_metadata.py @@ -0,0 +1,99 @@ +"""Extrae metadatos EXIF de una imagen (OSINT pasiva sobre documentos propios).""" + +from PIL import ExifTags, Image + +# Mapa inverso nombre -> id no hace falta: usamos ExifTags.TAGS (id -> nombre). +_GPS_TAGS = ExifTags.GPSTAGS # id -> nombre para el sub-IFD de GPS. + + +def _to_degrees(value) -> float | None: + """Convierte una coordenada GPS en formato DMS (grados, minutos, segundos) a grados decimales. + + Pillow devuelve cada componente como un IFDRational o una tupla (num, den). + """ + try: + d, m, s = value + return float(d) + float(m) / 60.0 + float(s) / 3600.0 + except (TypeError, ValueError, ZeroDivisionError): + return None + + +def _extract_gps(gps_info: dict) -> tuple[float | None, float | None]: + """Devuelve (lat, lon) en grados decimales desde el sub-IFD GPSInfo, o (None, None).""" + if not gps_info: + return None, None + + named = {_GPS_TAGS.get(k, k): v for k, v in gps_info.items()} + + lat = _to_degrees(named.get("GPSLatitude")) if "GPSLatitude" in named else None + lon = _to_degrees(named.get("GPSLongitude")) if "GPSLongitude" in named else None + + if lat is not None and str(named.get("GPSLatitudeRef", "N")).upper() == "S": + lat = -lat + if lon is not None and str(named.get("GPSLongitudeRef", "E")).upper() == "W": + lon = -lon + + return lat, lon + + +def extract_exif_metadata(image_path: str) -> dict: + """Lee los metadatos EXIF de una imagen y los devuelve normalizados. + + Abre la imagen con Pillow y extrae los tags EXIF. Normaliza los campos + mas relevantes para OSINT (fecha, camara, software, GPS) y adjunta el + diccionario completo de tags legibles por nombre en `raw`. + + Args: + image_path: ruta al archivo de imagen (JPEG, PNG, TIFF, ...). + + Returns: + dict con las claves: datetime, camera_make, camera_model, software, + gps_lat, gps_lon (grados decimales o None) y raw (dict tag->valor). + Si la imagen no tiene EXIF, los campos van a None y raw queda {}. + """ + result = { + "datetime": None, + "camera_make": None, + "camera_model": None, + "software": None, + "gps_lat": None, + "gps_lon": None, + "raw": {}, + } + + with Image.open(image_path) as img: + exif = img.getexif() + + if not exif: + return result + + # Tags de nivel raiz por nombre. + raw = {ExifTags.TAGS.get(tag_id, tag_id): value for tag_id, value in exif.items()} + + # Sub-IFD EXIF (DateTimeOriginal vive aqui, no en el IFD raiz). + try: + exif_ifd = exif.get_ifd(ExifTags.IFD.Exif) + except (AttributeError, KeyError, ValueError): + exif_ifd = {} + for tag_id, value in exif_ifd.items(): + raw[ExifTags.TAGS.get(tag_id, tag_id)] = value + + # GPS IFD. + try: + gps_ifd = exif.get_ifd(ExifTags.IFD.GPSInfo) + except (AttributeError, KeyError, ValueError): + gps_ifd = {} + if gps_ifd: + raw["GPSInfo"] = {_GPS_TAGS.get(k, k): v for k, v in gps_ifd.items()} + + result["raw"] = raw + result["datetime"] = raw.get("DateTimeOriginal") or raw.get("DateTime") + result["camera_make"] = raw.get("Make") + result["camera_model"] = raw.get("Model") + result["software"] = raw.get("Software") + + lat, lon = _extract_gps(gps_ifd) + result["gps_lat"] = lat + result["gps_lon"] = lon + + return result diff --git a/python/functions/cybersecurity/extract_exif_metadata_test.py b/python/functions/cybersecurity/extract_exif_metadata_test.py new file mode 100644 index 00000000..fea54fae --- /dev/null +++ b/python/functions/cybersecurity/extract_exif_metadata_test.py @@ -0,0 +1,110 @@ +"""Tests para extract_exif_metadata.""" + +import os +import sys + +from PIL import Image +from PIL.ExifTags import Base, GPS, IFD +from PIL.TiffImagePlugin import IFDRational + +sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..")) + +from cybersecurity.extract_exif_metadata import extract_exif_metadata + + +def _make_png_without_exif(path: str) -> None: + """Crea un PNG pequeño sin EXIF.""" + Image.new("RGB", (4, 4), (10, 20, 30)).save(path, format="PNG") + + +def _make_jpeg_with_exif(path: str) -> None: + """Crea un JPEG pequeño con EXIF de camara/software/fecha.""" + img = Image.new("RGB", (4, 4), (200, 100, 50)) + exif = img.getexif() + exif[Base.Make.value] = "TestCam" + exif[Base.Model.value] = "Model X" + exif[Base.Software.value] = "PyTestRig 1.0" + exif[Base.DateTime.value] = "2024:08:12 19:43:07" + # DateTimeOriginal vive en el sub-IFD EXIF. + exif_ifd = exif.get_ifd(IFD.Exif) + exif_ifd[Base.DateTimeOriginal.value] = "2024:08:12 19:43:07" + img.save(path, format="JPEG", exif=exif) + + +def _make_jpeg_with_gps(path: str) -> None: + """Crea un JPEG con GPSInfo en DMS, hemisferio sur y oeste.""" + img = Image.new("RGB", (4, 4), (0, 128, 64)) + exif = img.getexif() + gps_ifd = exif.get_ifd(IFD.GPSInfo) + # 40 deg, 25 min, 0.48 seg => 40.41680 grados. + gps_ifd[GPS.GPSLatitude.value] = ( + IFDRational(40, 1), + IFDRational(25, 1), + IFDRational(48, 100), + ) + gps_ifd[GPS.GPSLatitudeRef.value] = "S" # hemisferio sur => negativo + # 3 deg, 42 min, 13.68 seg => 3.7038 grados. + gps_ifd[GPS.GPSLongitude.value] = ( + IFDRational(3, 1), + IFDRational(42, 1), + IFDRational(1368, 100), + ) + gps_ifd[GPS.GPSLongitudeRef.value] = "W" # oeste => negativo + img.save(path, format="JPEG", exif=exif) + + +def test_imagen_sin_exif_png_devuelve_none(tmp_path): + """imagen sin EXIF (PNG) devuelve campos None y raw vacio.""" + p = str(tmp_path / "plain.png") + _make_png_without_exif(p) + + meta = extract_exif_metadata(p) + + assert meta["datetime"] is None + assert meta["camera_make"] is None + assert meta["camera_model"] is None + assert meta["software"] is None + assert meta["gps_lat"] is None + assert meta["gps_lon"] is None + assert meta["raw"] == {} + + +def test_imagen_con_exif_devuelve_camara_software_fecha(tmp_path): + """imagen con EXIF devuelve camara, software y fecha.""" + p = str(tmp_path / "withexif.jpg") + _make_jpeg_with_exif(p) + + meta = extract_exif_metadata(p) + + assert meta["camera_make"] == "TestCam" + assert meta["camera_model"] == "Model X" + assert meta["software"] == "PyTestRig 1.0" + assert meta["datetime"] == "2024:08:12 19:43:07" + assert meta["raw"] # no vacio + + +def test_gps_dms_a_grados_decimales_con_signo(tmp_path): + """GPSInfo DMS se convierte a grados decimales con signo por hemisferio.""" + p = str(tmp_path / "withgps.jpg") + _make_jpeg_with_gps(p) + + meta = extract_exif_metadata(p) + + assert meta["gps_lat"] is not None + assert meta["gps_lon"] is not None + # Sur y Oeste => ambos negativos. + assert meta["gps_lat"] < 0 + assert meta["gps_lon"] < 0 + assert abs(meta["gps_lat"] - (-40.41680)) < 1e-4 + assert abs(meta["gps_lon"] - (-3.7038)) < 1e-4 + + +if __name__ == "__main__": + import tempfile + from pathlib import Path + + with tempfile.TemporaryDirectory() as d: + test_imagen_sin_exif_png_devuelve_none(Path(d)) + test_imagen_con_exif_devuelve_camara_software_fecha(Path(d)) + test_gps_dms_a_grados_decimales_con_signo(Path(d)) + print("Todos los tests pasaron.") diff --git a/python/functions/cybersecurity/extract_pdf_metadata.md b/python/functions/cybersecurity/extract_pdf_metadata.md new file mode 100644 index 00000000..9ddec48b --- /dev/null +++ b/python/functions/cybersecurity/extract_pdf_metadata.md @@ -0,0 +1,66 @@ +--- +name: extract_pdf_metadata +kind: function +lang: py +domain: cybersecurity +version: "1.0.0" +purity: impure +signature: "def extract_pdf_metadata(pdf_path: str) -> dict" +description: "Lee los metadatos del Document Info de un PDF con pypdf (titulo, autor, creador, productor, fechas, numero de paginas) mas el volcado completo en `raw`. OSINT pasiva sobre documentos propios: revela quien y con que software genero el documento. Tolerante a PDFs cifrados (no falla, rellena `error`)." +tags: [osint-passive, pdf, metadata, document, forensics, pypdf, extract, cybersecurity, python] +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: [pypdf] +params: + - name: pdf_path + desc: "ruta al archivo PDF en disco" +output: "dict con title, author, creator, producer, creation_date, mod_date (ISO 8601 si parseables, sino valor crudo), num_pages, raw (todo el doc info) y error (None si todo fue bien, mensaje en caso contrario)." +tested: true +tests: + - "PDF con metadatos devuelve titulo, autor y num_pages" + - "PDF sin doc info devuelve campos None sin petar" + - "fechas parseables se devuelven en ISO 8601" +test_file_path: "python/functions/cybersecurity/extract_pdf_metadata_test.py" +file_path: "python/functions/cybersecurity/extract_pdf_metadata.py" +--- + +## Ejemplo + +```python +import sys, os +sys.path.insert(0, os.path.join("python", "functions")) +from cybersecurity.extract_pdf_metadata import extract_pdf_metadata + +meta = extract_pdf_metadata( + "/home/enmanuel/Obsidian/osint/attachments/personas/cv_objetivo.pdf" +) +print(meta["author"]) # 'Enmanuel G.' (quien lo creo) +print(meta["producer"]) # 'Microsoft Word 2021' (con que software) +print(meta["creation_date"]) # '2024-03-11T10:22:00+01:00' +print(meta["num_pages"]) # 3 +``` + +## Cuando usarla + +Cuando recolectes inteligencia pasiva sobre un PDF propio o de un objetivo y +necesites saber quien lo creo, con que herramienta y cuando. Usala tambien para +auditar tus propios documentos antes de publicarlos: el campo `author` y +`producer` suelen filtrar el nombre real del usuario, la version del software y +la organizacion, datos que no quieres exponer. + +## Gotchas + +- Funcion impura: abre el archivo del disco. Captura la excepcion en lugar de + propagarla — si el PDF esta corrupto, cifrado o no es un PDF, devuelve el dict + con lo que pudo leer y un mensaje en `error` (no lanza). +- PDFs cifrados: intenta abrir con password vacio (caso comun de "restriccion + de copia"). Si requiere password real, `error` empieza por `encrypted:` y los + campos pueden quedar None. +- Muchas fechas de PDF vienen en formato `D:YYYYMMDDHHmmSS+ZZ`; se convierten a + ISO 8601 cuando pypdf las parsea, sino se devuelven crudas. +- `raw` serializa los valores a string para evitar tipos no JSON-friendly + (IndirectObject, ByteStringObject). Los campos normalizados conservan el + contenido textual. diff --git a/python/functions/cybersecurity/extract_pdf_metadata.py b/python/functions/cybersecurity/extract_pdf_metadata.py new file mode 100644 index 00000000..494f7399 --- /dev/null +++ b/python/functions/cybersecurity/extract_pdf_metadata.py @@ -0,0 +1,86 @@ +"""Extrae metadatos de un PDF con pypdf (OSINT pasiva sobre documentos propios).""" + +from pypdf import PdfReader + + +def _iso_or_raw(reader: PdfReader, getter_name: str, raw_value): + """Devuelve una fecha en ISO 8601 si pypdf la sabe parsear, sino el valor crudo. + + pypdf expone `creation_date`/`modification_date` (datetime) ademas del + string crudo `/CreationDate`/`/ModDate` en formato `D:YYYYMMDDHHmmSS`. + """ + try: + dt = getattr(reader.metadata, getter_name, None) + except Exception: + dt = None + if dt is not None: + try: + return dt.isoformat() + except Exception: + pass + return str(raw_value) if raw_value is not None else None + + +def extract_pdf_metadata(pdf_path: str) -> dict: + """Lee los metadatos del Document Info de un PDF. + + Abre el PDF con pypdf y extrae los campos estandar del diccionario de + informacion (titulo, autor, creador, productor, fechas) mas el numero de + paginas. Las fechas se devuelven en ISO 8601 cuando son parseables, en su + valor crudo en caso contrario. No falla si el PDF esta cifrado: captura la + excepcion, devuelve lo que pueda y rellena el campo `error`. + + Args: + pdf_path: ruta al archivo PDF en disco. + + Returns: + dict con las claves: title, author, creator, producer, creation_date, + mod_date, num_pages, raw (dict con todo el doc info) y error (None si + todo fue bien, mensaje de error en caso contrario). + """ + result = { + "title": None, + "author": None, + "creator": None, + "producer": None, + "creation_date": None, + "mod_date": None, + "num_pages": None, + "raw": {}, + "error": None, + } + + try: + reader = PdfReader(pdf_path) + + # PDF cifrado: intentar abrir con password vacio (caso comun). + if getattr(reader, "is_encrypted", False): + try: + reader.decrypt("") + except Exception as exc: + result["error"] = f"encrypted: {exc}" + + try: + result["num_pages"] = len(reader.pages) + except Exception as exc: + result["error"] = result["error"] or f"pages: {exc}" + + meta = reader.metadata + if meta is not None: + result["title"] = str(meta.title) if meta.title is not None else None + result["author"] = str(meta.author) if meta.author is not None else None + result["creator"] = str(meta.creator) if meta.creator is not None else None + result["producer"] = ( + str(meta.producer) if meta.producer is not None else None + ) + result["creation_date"] = _iso_or_raw( + reader, "creation_date", meta.get("/CreationDate") + ) + result["mod_date"] = _iso_or_raw( + reader, "modification_date", meta.get("/ModDate") + ) + result["raw"] = {str(k): str(v) for k, v in meta.items()} + except Exception as exc: + result["error"] = result["error"] or str(exc) + + return result diff --git a/python/functions/cybersecurity/extract_pdf_metadata_test.py b/python/functions/cybersecurity/extract_pdf_metadata_test.py new file mode 100644 index 00000000..559996dc --- /dev/null +++ b/python/functions/cybersecurity/extract_pdf_metadata_test.py @@ -0,0 +1,92 @@ +"""Tests para extract_pdf_metadata.""" + +import os +import sys + +from pypdf import PdfWriter + +sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..")) + +from cybersecurity.extract_pdf_metadata import extract_pdf_metadata + + +def _make_pdf_with_metadata(path: str) -> None: + """Crea un PDF de 2 paginas con doc info (titulo, autor, fechas).""" + writer = PdfWriter() + writer.add_blank_page(width=200, height=200) + writer.add_blank_page(width=200, height=200) + writer.add_metadata( + { + "/Title": "Documento OSINT", + "/Author": "Enmanuel G.", + "/Creator": "PyTestRig", + "/Producer": "pypdf", + "/CreationDate": "D:20240311102200+01'00'", + "/ModDate": "D:20240312113000+01'00'", + } + ) + with open(path, "wb") as fh: + writer.write(fh) + + +def _make_pdf_without_metadata(path: str) -> None: + """Crea un PDF de 1 pagina sin doc info.""" + writer = PdfWriter() + writer.add_blank_page(width=100, height=100) + with open(path, "wb") as fh: + writer.write(fh) + + +def test_pdf_con_metadatos_devuelve_titulo_autor_paginas(tmp_path): + """PDF con metadatos devuelve titulo, autor y num_pages.""" + p = str(tmp_path / "withmeta.pdf") + _make_pdf_with_metadata(p) + + meta = extract_pdf_metadata(p) + + assert meta["error"] is None + assert meta["title"] == "Documento OSINT" + assert meta["author"] == "Enmanuel G." + assert meta["creator"] == "PyTestRig" + assert meta["producer"] == "pypdf" + assert meta["num_pages"] == 2 + assert meta["raw"] # no vacio + + +def test_pdf_sin_doc_info_devuelve_none_sin_petar(tmp_path): + """PDF sin doc info devuelve campos None sin petar.""" + p = str(tmp_path / "nometa.pdf") + _make_pdf_without_metadata(p) + + meta = extract_pdf_metadata(p) + + assert meta["error"] is None + assert meta["num_pages"] == 1 + assert meta["title"] is None + assert meta["author"] is None + + +def test_fechas_parseables_en_iso_8601(tmp_path): + """fechas parseables se devuelven en ISO 8601.""" + p = str(tmp_path / "dates.pdf") + _make_pdf_with_metadata(p) + + meta = extract_pdf_metadata(p) + + # pypdf parsea D:YYYYMMDDHHmmSS a datetime; isoformat() lleva 'T'. + assert meta["creation_date"] is not None + assert "2024-03-11" in meta["creation_date"] + assert "T" in meta["creation_date"] + assert meta["mod_date"] is not None + assert "2024-03-12" in meta["mod_date"] + + +if __name__ == "__main__": + import tempfile + from pathlib import Path + + with tempfile.TemporaryDirectory() as d: + test_pdf_con_metadatos_devuelve_titulo_autor_paginas(Path(d)) + test_pdf_sin_doc_info_devuelve_none_sin_petar(Path(d)) + test_fechas_parseables_en_iso_8601(Path(d)) + print("Todos los tests pasaron.") diff --git a/python/functions/cybersecurity/guess_email_formats.md b/python/functions/cybersecurity/guess_email_formats.md new file mode 100644 index 00000000..7155a43e --- /dev/null +++ b/python/functions/cybersecurity/guess_email_formats.md @@ -0,0 +1,63 @@ +--- +name: guess_email_formats +kind: function +lang: py +domain: cybersecurity +version: "1.0.0" +purity: pure +signature: "def guess_email_formats(nombre: str, apellidos: str, dominio: str) -> list" +description: "Genera candidatos de email comunes (nombre.apellido, n.apellido, apellido.nombre, inicial+apellido, variantes con dos apellidos, etc.) a partir de nombre, apellidos y dominio. Normaliza acentos y ñ a ASCII en minusculas y deduplica preservando el orden. OSINT pasivo puro, sin red." +tags: [osint-passive, email, enumeration, recon, identity, cybersecurity, python] +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "" +imports: [unicodedata] +params: + - name: nombre + desc: "Nombre de pila. Si tiene varios tokens se usa el primero como nombre principal." + - name: apellidos + desc: "Uno o dos apellidos separados por espacio. Con dos apellidos se generan variantes que los unen." + - name: dominio + desc: "Dominio de correo sin arroba (ej. 'empresa.com'). Si viene con '@' delante se limpia." +output: "Lista de strings '@' con los candidatos de email en orden de generacion, sin duplicados." +tested: true +tests: + - "test_nombre_simple_un_apellido" + - "test_acentos_y_enie_normalizados" + - "test_dos_apellidos_genera_variantes_unidas" + - "test_dedup_preserva_orden" + - "test_dominio_con_arroba_se_limpia" +test_file_path: "python/functions/cybersecurity/guess_email_formats_test.py" +file_path: "python/functions/cybersecurity/guess_email_formats.py" +--- + +## Ejemplo + +```python +guess_email_formats("José", "García López", "empresa.com") +# ['jose@empresa.com', +# 'jose.garcia@empresa.com', +# 'josegarcia@empresa.com', +# 'j.garcia@empresa.com', +# 'jgarcia@empresa.com', +# 'jose_garcia@empresa.com', +# 'garcia.jose@empresa.com', +# 'joseg@empresa.com', +# 'jose.garcialopez@empresa.com', +# 'josegarcialopez@empresa.com', +# 'jose.lopez@empresa.com', +# 'jgarcialopez@empresa.com'] +``` + +## Cuando usarla + +Usala al arrancar una investigacion de identidad cuando conoces nombre + apellidos + dominio de una organizacion y quieres una lista de direcciones probables para verificar despues (MX, catch-all, validacion SMTP, breach lookup). Es el primer paso antes de cualquier comprobacion activa. + +## Gotchas + +- Funcion pura: NO valida que el email exista ni hace ninguna comprobacion de red. Solo genera candidatos sintacticos. +- La lista de patrones es heuristica (los formatos mas comunes), no exhaustiva: organizaciones con esquemas propios (ej. id numerico) no quedaran cubiertas. +- La normalizacion translitera acentos y ñ a ASCII y elimina cualquier caracter no alfanumerico del local part; nombres con guiones o apostrofes pierden esos separadores. +- Solo usa el primer token del nombre como nombre principal; nombres compuestos (ej. "Maria Jose") no generan variantes con el segundo nombre. diff --git a/python/functions/cybersecurity/guess_email_formats.py b/python/functions/cybersecurity/guess_email_formats.py new file mode 100644 index 00000000..0e0bbf65 --- /dev/null +++ b/python/functions/cybersecurity/guess_email_formats.py @@ -0,0 +1,84 @@ +"""Genera candidatos de email a partir de nombre, apellidos y dominio. + +Funcion pura de OSINT pasivo: produce los patrones de direccion de correo +mas habituales en organizaciones, sin tocar la red. Util como punto de +partida para verificacion posterior (MX, catch-all, validacion SMTP, etc.). +""" + +import unicodedata + + +def _ascii_lower(text: str) -> str: + """Normaliza un texto a ASCII en minusculas. + + Translitera acentos y caracteres latinos (a, e, n, ...) a su forma + ASCII, pasa a minusculas y elimina cualquier caracter que no sea + alfanumerico. No introduce separadores (a diferencia de un slug). + + Args: + text: texto de entrada (puede contener acentos, ñ, mayusculas). + + Returns: + cadena ASCII en minusculas formada solo por [a-z0-9]. + """ + # NFKD descompone los caracteres acentuados en base + diacritico. + decomposed = unicodedata.normalize("NFKD", text) + stripped = "".join(c for c in decomposed if not unicodedata.combining(c)) + lowered = stripped.lower() + return "".join(c for c in lowered if c.isalnum()) + + +def guess_email_formats(nombre: str, apellidos: str, dominio: str) -> list: + """Genera candidatos de email comunes a partir de identidad y dominio. + + Combina el nombre y los apellidos en los patrones de direccion mas + frecuentes (nombre.apellido, inicial+apellido, apellido.nombre, etc.), + normalizando acentos/ñ a ASCII y minusculas. Si hay dos apellidos + tambien genera variantes que los unen. Deduplica preservando el orden + de aparicion. + + Args: + nombre: nombre de pila (puede incluir varios tokens separados por + espacio; se usa el primero como nombre principal). + apellidos: uno o dos apellidos separados por espacio. + dominio: dominio de correo sin arroba (ej. "empresa.com"). + + Returns: + lista de strings "@" con los candidatos, en el + orden en que se generan los patrones y sin duplicados. + """ + n = _ascii_lower(nombre.split()[0]) if nombre.split() else "" + apellido_tokens = [_ascii_lower(a) for a in apellidos.split() if _ascii_lower(a)] + a1 = apellido_tokens[0] if apellido_tokens else "" + a2 = apellido_tokens[1] if len(apellido_tokens) > 1 else "" + dom = dominio.strip().lstrip("@").lower() + + ni = n[0] if n else "" + a1i = a1[0] if a1 else "" + apellido_full = "".join(apellido_tokens) # apellido1apellido2 unidos + + locals_raw = [ + n, # nombre + f"{n}.{a1}" if n and a1 else "", # nombre.apellido + f"{n}{a1}" if n and a1 else "", # nombreapellido + f"{ni}.{a1}" if ni and a1 else "", # n.apellido + f"{ni}{a1}" if ni and a1 else "", # napellido + f"{n}_{a1}" if n and a1 else "", # nombre_apellido + f"{a1}.{n}" if a1 and n else "", # apellido.nombre + f"{n}{a1i}" if n and a1i else "", # nombre+inicial_apellido + f"{n}.{apellido_full}" if n and a2 else "", # nombre.apellido1apellido2 + f"{n}{apellido_full}" if n and a2 else "", # nombreapellido1apellido2 + f"{n}.{a2}" if n and a2 else "", # nombre.apellido2 + f"{ni}{apellido_full}" if ni and a2 else "", # n+apellidos unidos + ] + + seen = set() + out = [] + for local in locals_raw: + if not local: + continue + email = f"{local}@{dom}" + if email not in seen: + seen.add(email) + out.append(email) + return out diff --git a/python/functions/cybersecurity/guess_email_formats_test.py b/python/functions/cybersecurity/guess_email_formats_test.py new file mode 100644 index 00000000..ed8c165c --- /dev/null +++ b/python/functions/cybersecurity/guess_email_formats_test.py @@ -0,0 +1,53 @@ +"""Tests para guess_email_formats.""" + +from guess_email_formats import guess_email_formats + + +def test_nombre_simple_un_apellido(): + """Nombre simple con un apellido produce los patrones base.""" + result = guess_email_formats("Juan", "Perez", "empresa.com") + assert "juan.perez@empresa.com" in result + assert "juanperez@empresa.com" in result + assert "j.perez@empresa.com" in result + assert "jperez@empresa.com" in result + assert "juan_perez@empresa.com" in result + assert "perez.juan@empresa.com" in result + assert "juan@empresa.com" in result + # Sin segundo apellido no hay variantes unidas. + assert all("@empresa.com" in e for e in result) + + +def test_acentos_y_enie_normalizados(): + """Acentos y ñ se transliteran a ASCII en minusculas.""" + result = guess_email_formats("José", "Muñoz", "acme.org") + assert "jose.munoz@acme.org" in result + assert "j.munoz@acme.org" in result + # No debe aparecer ningun caracter no ASCII. + for email in result: + assert email == email.encode("ascii", "ignore").decode("ascii") + + +def test_dos_apellidos_genera_variantes_unidas(): + """Dos apellidos producen variantes que los unen.""" + result = guess_email_formats("Maria", "Garcia Lopez", "uni.edu") + assert "maria.garcialopez@uni.edu" in result + assert "mariagarcialopez@uni.edu" in result + assert "maria.lopez@uni.edu" in result + assert "mgarcialopez@uni.edu" in result + # El patron de primer apellido sigue presente. + assert "maria.garcia@uni.edu" in result + + +def test_dedup_preserva_orden(): + """Los candidatos no se repiten y mantienen el orden de generacion.""" + result = guess_email_formats("Ana", "Ruiz", "x.com") + assert len(result) == len(set(result)) + # nombre.apellido aparece antes que apellido.nombre. + assert result.index("ana.ruiz@x.com") < result.index("ruiz.ana@x.com") + + +def test_dominio_con_arroba_se_limpia(): + """Un dominio prefijado con @ se normaliza sin duplicar la arroba.""" + result = guess_email_formats("Luis", "Soto", "@corp.io") + assert "luis.soto@corp.io" in result + assert all(e.count("@") == 1 for e in result) diff --git a/python/functions/cybersecurity/scan_ficha_attachments_metadata.md b/python/functions/cybersecurity/scan_ficha_attachments_metadata.md new file mode 100644 index 00000000..4b9d5468 --- /dev/null +++ b/python/functions/cybersecurity/scan_ficha_attachments_metadata.md @@ -0,0 +1,57 @@ +--- +name: scan_ficha_attachments_metadata +kind: function +lang: py +domain: cybersecurity +version: "1.0.0" +purity: impure +signature: "def scan_ficha_attachments_metadata(attachments_dir: str) -> dict" +description: "Orquestador OSINT pasivo: recorre un directorio de attachments de una ficha (imagenes y PDFs), extrae sus metadatos componiendo extract_exif_metadata (imagenes .jpg/.jpeg/.png/.heic) y extract_pdf_metadata (.pdf), y agrega los puntos GPS y las fechas encontradas. Devuelve files + gps_points + dates + summary." +tags: [osint-enrich, osint-passive, cybersecurity, metadata, exif, pdf] +uses_functions: [extract_exif_metadata_py_cybersecurity, extract_pdf_metadata_py_cybersecurity] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: [os] +params: + - name: attachments_dir + desc: "ruta a un directorio de attachments, p.ej. /home/enmanuel/Obsidian/osint/attachments/personas//. Se recorre recursivamente. Si no es un directorio existente lanza NotADirectoryError" +output: "dict con files (lista de {path, type, metadata} por archivo procesado: type es 'image' o 'pdf'), gps_points (lista de {file, lat, lon} agregando las coordenadas EXIF), dates (lista de fechas str de EXIF y PDF) y summary ({n_files, n_images, n_pdfs, n_gps_points, n_dates, errors}). Los archivos cuya extraccion falla quedan con metadata={'error': ...} y suman a summary.errors" +tested: true +tests: ["test_golden_agrega_gps_y_fechas_de_imagen_y_pdf", "test_directorio_inexistente_lanza", "test_ignora_extensiones_no_soportadas", "test_error_en_archivo_se_captura_en_summary"] +test_file_path: "python/functions/cybersecurity/scan_ficha_attachments_metadata_test.py" +file_path: "python/functions/cybersecurity/scan_ficha_attachments_metadata.py" +--- + +## Ejemplo + +```python +import sys, os +sys.path.insert(0, os.path.join("python", "functions")) +from cybersecurity import scan_ficha_attachments_metadata + +# Escanea los attachments de una persona en el vault OSINT. +res = scan_ficha_attachments_metadata( + "/home/enmanuel/Obsidian/osint/attachments/personas/juan-perez/" +) + +print(res["summary"]) # {'n_files': 7, 'n_images': 5, 'n_pdfs': 2, 'n_gps_points': 2, 'n_dates': 4, 'errors': 0} +for p in res["gps_points"]: + print(p["file"], p["lat"], p["lon"]) # coordenadas extraidas de las fotos +print(res["dates"]) # fechas EXIF + fechas de creacion/modificacion de los PDFs +``` + +## Cuando usarla + +- Cuando montas la ficha OSINT de una persona u organizacion y quieres saber de un vistazo que huella de metadatos dejan los documentos/fotos que ya tienes guardados (donde y cuando se hicieron). +- Antes de publicar/compartir attachments propios: para auditar que GPS y fechas se filtrarian. +- Como paso de enriquecimiento dentro de un pipeline de investigacion, justo despues de descargar los attachments al directorio de la ficha. + +## Gotchas + +- **Uso solo para investigacion autorizada.** Extraer metadatos de archivos ajenos sin permiso puede ser ilegal segun jurisdiccion. Limitate a tus propios documentos o a material que estes autorizado a analizar. +- Funcion IMPURA: hace I/O sobre el sistema de archivos (recorrido recursivo con `os.walk`). Si `attachments_dir` no existe lanza `NotADirectoryError`. +- La extraccion por archivo se aisla con try/except: un archivo corrupto no aborta el escaneo, queda con `metadata={"error": ...}` y suma a `summary.errors`. +- Solo procesa imagenes .jpg/.jpeg/.png/.heic y PDFs .pdf; el resto se ignora silenciosamente. El soporte real de HEIC/EXIF depende de lo que `extract_exif_metadata` (Pillow) pueda abrir en el sistema. +- Las fechas se devuelven tal cual las reportan EXIF/PDF (formatos heterogeneos, sin normalizar a ISO). diff --git a/python/functions/cybersecurity/scan_ficha_attachments_metadata.py b/python/functions/cybersecurity/scan_ficha_attachments_metadata.py new file mode 100644 index 00000000..18165c62 --- /dev/null +++ b/python/functions/cybersecurity/scan_ficha_attachments_metadata.py @@ -0,0 +1,107 @@ +"""Orquestador OSINT pasivo: escanea metadatos de los attachments de una ficha. + +Recorre un directorio de attachments (imagenes y PDFs) y extrae sus metadatos +componiendo las funciones atomicas del registro (`extract_exif_metadata`, +`extract_pdf_metadata`). Agrega los puntos GPS y las fechas encontradas para +dar una vista rapida de la huella de metadatos de una persona/organizacion. + +Funcion IMPURA: hace I/O sobre el sistema de archivos. +""" + +import os + +from cybersecurity import extract_exif_metadata, extract_pdf_metadata + +_IMAGE_EXTS = (".jpg", ".jpeg", ".png", ".heic") +_PDF_EXTS = (".pdf",) + + +def _iter_files(attachments_dir: str): + """Recorre recursivamente el directorio devolviendo rutas de archivo ordenadas.""" + for root, _dirs, files in os.walk(attachments_dir): + for name in sorted(files): + yield os.path.join(root, name) + + +def scan_ficha_attachments_metadata(attachments_dir: str) -> dict: + """Escanea un directorio de attachments y agrega los metadatos extraidos. + + Aplica `extract_exif_metadata` a las imagenes (.jpg/.jpeg/.png/.heic) y + `extract_pdf_metadata` a los PDFs (.pdf). Agrega los puntos GPS de las + imagenes y todas las fechas detectadas (EXIF + PDF). + + Args: + attachments_dir: ruta a un directorio de attachments, p.ej. + `/home/enmanuel/Obsidian/osint/attachments/personas//`. + Se recorre recursivamente. + + Returns: + dict con las claves: + - files: lista de {path, type, metadata} por archivo procesado. + - gps_points: lista de {file, lat, lon} con las coordenadas EXIF. + - dates: lista de fechas (str) encontradas en EXIF y PDF. + - summary: {n_files, n_images, n_pdfs, n_gps_points, n_dates, + errors} con conteos agregados. + + Raises: + NotADirectoryError: si `attachments_dir` no es un directorio existente. + """ + if not os.path.isdir(attachments_dir): + raise NotADirectoryError(f"no es un directorio: {attachments_dir}") + + files: list[dict] = [] + gps_points: list[dict] = [] + dates: list[str] = [] + n_images = 0 + n_pdfs = 0 + errors = 0 + + for path in _iter_files(attachments_dir): + ext = os.path.splitext(path)[1].lower() + + if ext in _IMAGE_EXTS: + ftype = "image" + elif ext in _PDF_EXTS: + ftype = "pdf" + else: + continue + + try: + if ftype == "image": + metadata = extract_exif_metadata(path) + n_images += 1 + lat = metadata.get("gps_lat") + lon = metadata.get("gps_lon") + if lat is not None and lon is not None: + gps_points.append({"file": path, "lat": lat, "lon": lon}) + dt = metadata.get("datetime") + if dt: + dates.append(str(dt)) + else: + metadata = extract_pdf_metadata(path) + n_pdfs += 1 + for key in ("creation_date", "modification_date", "creationDate", "modDate"): + val = metadata.get(key) + if val: + dates.append(str(val)) + except Exception as exc: # noqa: BLE001 - I/O sobre archivos heterogeneos + errors += 1 + metadata = {"error": f"{type(exc).__name__}: {exc}"} + + files.append({"path": path, "type": ftype, "metadata": metadata}) + + summary = { + "n_files": len(files), + "n_images": n_images, + "n_pdfs": n_pdfs, + "n_gps_points": len(gps_points), + "n_dates": len(dates), + "errors": errors, + } + + return { + "files": files, + "gps_points": gps_points, + "dates": dates, + "summary": summary, + } diff --git a/python/functions/cybersecurity/scan_ficha_attachments_metadata_test.py b/python/functions/cybersecurity/scan_ficha_attachments_metadata_test.py new file mode 100644 index 00000000..4757c3b7 --- /dev/null +++ b/python/functions/cybersecurity/scan_ficha_attachments_metadata_test.py @@ -0,0 +1,113 @@ +"""Tests para scan_ficha_attachments_metadata. + +Las funciones compuestas (extract_exif_metadata / extract_pdf_metadata) se +monkeypatchean para no depender ni de archivos reales ni de Pillow. Solo se +verifica la orquestacion y la agregacion (GPS, fechas, summary, manejo de +errores y filtrado de extensiones). +""" + +import importlib +import os +import sys + +import pytest + +sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..")) + +from cybersecurity import scan_ficha_attachments_metadata + +# El paquete re-exporta la funcion bajo el mismo nombre que el submodulo, asi +# que `cybersecurity.scan_ficha_attachments_metadata` resuelve a la funcion. +# Para parchear los globals del modulo orquestador lo tomamos via importlib. +mod = importlib.import_module("cybersecurity.scan_ficha_attachments_metadata") + + +def _make_tree(tmp_path, names): + """Crea archivos vacios en tmp_path; devuelve el directorio.""" + d = tmp_path / "ficha" + d.mkdir() + for name in names: + (d / name).write_bytes(b"") + return str(d) + + +def test_golden_agrega_gps_y_fechas_de_imagen_y_pdf(tmp_path, monkeypatch): + attachments = _make_tree(tmp_path, ["foto1.jpg", "foto2.png", "doc.pdf"]) + + exif_by_name = { + "foto1.jpg": {"datetime": "2024:01:02 10:11:12", "gps_lat": 40.4, "gps_lon": -3.7}, + "foto2.png": {"datetime": None, "gps_lat": None, "gps_lon": None}, + } + + def fake_exif(path): + return exif_by_name[os.path.basename(path)] + + def fake_pdf(path): + return {"creation_date": "D:20230101000000", "modification_date": "D:20230202000000"} + + monkeypatch.setattr(mod, "extract_exif_metadata", fake_exif) + monkeypatch.setattr(mod, "extract_pdf_metadata", fake_pdf) + + res = scan_ficha_attachments_metadata(attachments) + + # 3 archivos procesados (2 imagenes + 1 pdf). + assert res["summary"] == { + "n_files": 3, + "n_images": 2, + "n_pdfs": 1, + "n_gps_points": 1, + "n_dates": 3, # 1 de la imagen + 2 del pdf + "errors": 0, + } + + # GPS solo de foto1. + assert res["gps_points"] == [ + {"file": os.path.join(attachments, "foto1.jpg"), "lat": 40.4, "lon": -3.7} + ] + + # Fechas agregadas de EXIF + PDF. + assert "2024:01:02 10:11:12" in res["dates"] + assert "D:20230101000000" in res["dates"] + assert "D:20230202000000" in res["dates"] + + # files lleva path/type/metadata por cada uno. + types = {os.path.basename(f["path"]): f["type"] for f in res["files"]} + assert types == {"foto1.jpg": "image", "foto2.png": "image", "doc.pdf": "pdf"} + + +def test_directorio_inexistente_lanza(tmp_path): + with pytest.raises(NotADirectoryError): + scan_ficha_attachments_metadata(str(tmp_path / "no-existe")) + + +def test_ignora_extensiones_no_soportadas(tmp_path, monkeypatch): + attachments = _make_tree(tmp_path, ["nota.txt", "video.mp4", "foto.jpg"]) + + monkeypatch.setattr(mod, "extract_exif_metadata", lambda p: {"gps_lat": None, "gps_lon": None, "datetime": None}) + monkeypatch.setattr(mod, "extract_pdf_metadata", lambda p: {}) + + res = scan_ficha_attachments_metadata(attachments) + + # Solo la imagen cuenta; txt y mp4 se ignoran. + assert res["summary"]["n_files"] == 1 + assert res["summary"]["n_images"] == 1 + assert res["summary"]["n_pdfs"] == 0 + assert [os.path.basename(f["path"]) for f in res["files"]] == ["foto.jpg"] + + +def test_error_en_archivo_se_captura_en_summary(tmp_path, monkeypatch): + attachments = _make_tree(tmp_path, ["roto.jpg", "ok.pdf"]) + + def boom(path): + raise OSError("imagen corrupta") + + monkeypatch.setattr(mod, "extract_exif_metadata", boom) + monkeypatch.setattr(mod, "extract_pdf_metadata", lambda p: {"creation_date": "D:20200101"}) + + res = scan_ficha_attachments_metadata(attachments) + + assert res["summary"]["errors"] == 1 + assert res["summary"]["n_files"] == 2 # ambos archivos quedan registrados + roto = next(f for f in res["files"] if os.path.basename(f["path"]) == "roto.jpg") + assert "error" in roto["metadata"] + assert "imagen corrupta" in roto["metadata"]["error"] diff --git a/python/functions/cybersecurity/whois_lookup.md b/python/functions/cybersecurity/whois_lookup.md new file mode 100644 index 00000000..7b6bb950 --- /dev/null +++ b/python/functions/cybersecurity/whois_lookup.md @@ -0,0 +1,68 @@ +--- +name: whois_lookup +kind: function +lang: py +domain: cybersecurity +version: "1.0.0" +purity: impure +signature: "def whois_lookup(dominio: str, timeout_s: float = 15.0) -> dict" +description: "Recoleccion OSINT pasiva de datos de registro de dominio via RDAP (reemplazo moderno de WHOIS sobre HTTP/JSON). Consulta https://rdap.org/domain/ con http_get_json y normaliza registrar, fechas de creacion/expiracion/ultimo cambio, nameservers, estados y entidades. Devuelve {found: False} si el dominio no existe (404)." +tags: [osint-passive, whois, rdap, recon, cybersecurity] +params: + - name: dominio + desc: "Dominio a consultar, ej. organic-machine.com. Vacio lanza RuntimeError." + - name: timeout_s + desc: "Segundos maximo de espera de la peticion HTTP a rdap.org (default 15.0)." +output: "dict normalizado con found (bool), registrar, creation_date, expiration_date, last_changed, nameservers (lista), status (lista), entities (lista de {handle, roles}) y raw (RDAP completo). Si el dominio no existe (HTTP 404) devuelve {found: False}." +uses_functions: ["http_get_json_py_infra"] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: [] +tested: true +tests: ["test_normaliza_respuesta_rdap", "test_dominio_no_encontrado_404", "test_otro_error_http_se_propaga", "test_sin_registrar_ni_fechas", "test_dominio_vacio_lanza_error"] +test_file_path: "python/functions/cybersecurity/whois_lookup_test.py" +file_path: "python/functions/cybersecurity/whois_lookup.py" +--- + +## Ejemplo + +```python +import sys, os +sys.path.insert(0, os.path.join("python", "functions")) +from cybersecurity import whois_lookup + +info = whois_lookup("organic-machine.com") +if info["found"]: + print(info["registrar"]) # 'Example Registrar Inc.' + print(info["creation_date"]) # '2020-01-15T10:00:00Z' + print(info["expiration_date"]) # '2027-01-15T10:00:00Z' + print(info["nameservers"]) # ['ns1.example.net', 'ns2.example.net'] + print(info["status"]) # ['client transfer prohibited'] +else: + print("dominio no registrado") +``` + +## Cuando usarla + +Usala para obtener metadatos de registro de un dominio sin depender del CLI +`whois` (no instalado): edad del dominio, fecha de expiracion (dominios a +punto de caducar), registrar y nameservers autoritativos. Util en perfilado +pasivo, deteccion de dominios recien creados (typosquatting/phishing) y +validacion de propiedad. + +## Gotchas + +- RDAP no esta uniformemente desplegado en todos los TLD: algunos devuelven + campos vacios o ni siquiera responden. Por eso los campos opcionales pueden + quedar `None` y `nameservers`/`status`/`entities` listas vacias. +- rdap.org actua como bootstrap y redirige al servidor RDAP autoritativo del + TLD; depende de su disponibilidad. +- El registrante (`entities` con rol distinto de `registrar`) suele estar + redactado por privacy/GDPR: casi siempre solo veras `handle` y `roles`, sin + datos personales. +- Un dominio no registrado devuelve `{"found": False}` (HTTP 404); cualquier + otro error HTTP (rate limit 429, 5xx) se propaga como `RuntimeError`. +- Las fechas se devuelven tal cual las da RDAP (ISO 8601 UTC), sin parsear a + objetos `datetime`. diff --git a/python/functions/cybersecurity/whois_lookup.py b/python/functions/cybersecurity/whois_lookup.py new file mode 100644 index 00000000..c8957df3 --- /dev/null +++ b/python/functions/cybersecurity/whois_lookup.py @@ -0,0 +1,114 @@ +"""Recoleccion OSINT pasiva de datos de registro de dominio via RDAP. + +Funcion IMPURA: consulta el servicio RDAP publico (reemplazo moderno de +WHOIS, sobre HTTP/JSON) y normaliza la respuesta. Es OSINT pasivo: no toca +al dominio objetivo, solo el directorio RDAP publico. +""" + +import os +import sys + +sys.path.insert( + 0, os.path.join(os.path.dirname(__file__), "..", "..", "functions") +) + +from infra.http_get_json import http_get_json # noqa: E402 + + +def _events_by_action(raw: dict) -> dict: + """Indexa la lista RDAP ``events`` por ``eventAction`` -> ``eventDate``.""" + out: dict = {} + for event in raw.get("events", []) or []: + action = event.get("eventAction") + date = event.get("eventDate") + if action and date: + out[action] = date + return out + + +def _extract_registrar(raw: dict) -> str | None: + """Busca la entidad con rol ``registrar`` y devuelve su nombre vCard.""" + for entity in raw.get("entities", []) or []: + roles = entity.get("roles", []) or [] + if "registrar" not in roles: + continue + vcard = entity.get("vcardArray") + if isinstance(vcard, list) and len(vcard) == 2: + for field in vcard[1]: + if isinstance(field, list) and field and field[0] == "fn": + return field[3] + return entity.get("handle") + return None + + +def _extract_nameservers(raw: dict) -> list: + """Extrae los ldhName de los nameservers RDAP, ordenados.""" + servers = [] + for ns in raw.get("nameservers", []) or []: + name = ns.get("ldhName") + if name: + servers.append(name.lower()) + return sorted(set(servers)) + + +def whois_lookup(dominio: str, timeout_s: float = 15.0) -> dict: + """Consulta RDAP de un dominio y normaliza la informacion de registro. + + Usa ``http_get_json`` del registry contra ``https://rdap.org/domain/`` + (rdap.org redirige al servidor RDAP autoritativo del TLD). Normaliza + registrar, fechas (creacion / expiracion / ultimo cambio), nameservers, + estados y entidades, e incluye la respuesta cruda en ``raw``. + + Args: + dominio: Dominio a consultar (ej. ``"organic-machine.com"``). + timeout_s: Segundos maximo de espera de la peticion HTTP (default 15). + + Returns: + Dict normalizado con claves: ``found`` (bool), ``registrar``, + ``creation_date``, ``expiration_date``, ``last_changed``, + ``nameservers`` (lista), ``status`` (lista), ``entities`` (lista de + roles/handles) y ``raw`` (respuesta RDAP completa). Si el dominio no + existe (HTTP 404) devuelve ``{"found": False}``. + + Raises: + RuntimeError: Si el dominio esta vacio o la peticion falla por una + razon distinta de 404. + """ + if not dominio or not dominio.strip(): + raise RuntimeError("whois_lookup: dominio vacio") + + url = f"https://rdap.org/domain/{dominio.strip()}" + + try: + raw = http_get_json(url, timeout=timeout_s) + except RuntimeError as e: + # http_get_json envuelve los HTTPError como "HTTP ". + if "HTTP 404" in str(e): + return {"found": False} + raise + + if not isinstance(raw, dict): + raise RuntimeError( + f"whois_lookup: respuesta RDAP inesperada (tipo {type(raw).__name__})" + ) + + events = _events_by_action(raw) + entities = [ + { + "handle": ent.get("handle"), + "roles": ent.get("roles", []) or [], + } + for ent in raw.get("entities", []) or [] + ] + + return { + "found": True, + "registrar": _extract_registrar(raw), + "creation_date": events.get("registration"), + "expiration_date": events.get("expiration"), + "last_changed": events.get("last changed"), + "nameservers": _extract_nameservers(raw), + "status": raw.get("status", []) or [], + "entities": entities, + "raw": raw, + } diff --git a/python/functions/cybersecurity/whois_lookup_test.py b/python/functions/cybersecurity/whois_lookup_test.py new file mode 100644 index 00000000..d19af6ea --- /dev/null +++ b/python/functions/cybersecurity/whois_lookup_test.py @@ -0,0 +1,109 @@ +"""Tests para whois_lookup.""" + +import os +import sys + +sys.path.insert(0, os.path.dirname(__file__)) + +import whois_lookup as wl +from whois_lookup import whois_lookup + + +def _rdap_sample() -> dict: + return { + "ldhName": "organic-machine.com", + "status": ["client transfer prohibited"], + "events": [ + {"eventAction": "registration", "eventDate": "2020-01-15T10:00:00Z"}, + {"eventAction": "expiration", "eventDate": "2027-01-15T10:00:00Z"}, + {"eventAction": "last changed", "eventDate": "2026-01-10T08:30:00Z"}, + ], + "nameservers": [ + {"ldhName": "ns1.example.net"}, + {"ldhName": "NS2.EXAMPLE.NET"}, + ], + "entities": [ + { + "handle": "REG-123", + "roles": ["registrar"], + "vcardArray": [ + "vcard", + [ + ["version", {}, "text", "4.0"], + ["fn", {}, "text", "Example Registrar Inc."], + ], + ], + }, + {"handle": "REGISTRANT-9", "roles": ["registrant"]}, + ], + } + + +def test_normaliza_respuesta_rdap(monkeypatch): + """Extrae registrar, fechas, nameservers, status y entities.""" + monkeypatch.setattr(wl, "http_get_json", lambda url, timeout=15.0: _rdap_sample()) + + result = whois_lookup("organic-machine.com") + + assert result["found"] is True + assert result["registrar"] == "Example Registrar Inc." + assert result["creation_date"] == "2020-01-15T10:00:00Z" + assert result["expiration_date"] == "2027-01-15T10:00:00Z" + assert result["last_changed"] == "2026-01-10T08:30:00Z" + assert result["nameservers"] == ["ns1.example.net", "ns2.example.net"] + assert result["status"] == ["client transfer prohibited"] + assert {"handle": "REGISTRANT-9", "roles": ["registrant"]} in result["entities"] + assert result["raw"]["ldhName"] == "organic-machine.com" + + +def test_dominio_no_encontrado_404(monkeypatch): + """Un HTTP 404 de http_get_json devuelve {'found': False}.""" + + def fake(url, timeout=15.0): + raise RuntimeError("http_get_json: HTTP 404 at 'rdap.org' — not found") + + monkeypatch.setattr(wl, "http_get_json", fake) + + result = whois_lookup("nope-no-existe-xyz.invalid") + + assert result == {"found": False} + + +def test_otro_error_http_se_propaga(monkeypatch): + """Un error HTTP distinto de 404 se propaga como RuntimeError.""" + + def fake(url, timeout=15.0): + raise RuntimeError("http_get_json: HTTP 500 at 'rdap.org' — boom") + + monkeypatch.setattr(wl, "http_get_json", fake) + + try: + whois_lookup("organic-machine.com") + assert False, "deberia haberse propagado el error 500" + except RuntimeError as e: + assert "HTTP 500" in str(e) + + +def test_sin_registrar_ni_fechas(monkeypatch): + """RDAP minimo: campos opcionales quedan None / listas vacias.""" + monkeypatch.setattr( + wl, "http_get_json", lambda url, timeout=15.0: {"ldhName": "x.com"} + ) + + result = whois_lookup("x.com") + + assert result["found"] is True + assert result["registrar"] is None + assert result["creation_date"] is None + assert result["nameservers"] == [] + assert result["status"] == [] + assert result["entities"] == [] + + +def test_dominio_vacio_lanza_error(): + """Dominio vacio lanza RuntimeError.""" + try: + whois_lookup("") + assert False, "deberia haber lanzado RuntimeError" + except RuntimeError: + pass diff --git a/python/functions/infra/__init__.py b/python/functions/infra/__init__.py index 78664c91..790c94e7 100644 --- a/python/functions/infra/__init__.py +++ b/python/functions/infra/__init__.py @@ -1,10 +1,28 @@ from .setup_logger import setup_logger, get_logger from .generate_app_icon import generate_app_icon +from .generate_initials_avatar import generate_initials_avatar from .http_replay_sequence import http_replay_sequence +from .hoppscotch_login import hoppscotch_login +from .hoppscotch_create_request import hoppscotch_create_request +from .hoppscotch_update_request import hoppscotch_update_request +from .hoppscotch_delete_request import hoppscotch_delete_request +from .hoppscotch_list_requests import hoppscotch_list_requests +from .pass_get_secret import pass_get_secret +from .hoppscotch_set_environment import hoppscotch_set_environment +from .hoppscotch_run_request import hoppscotch_run_request __all__ = [ "setup_logger", "get_logger", "generate_app_icon", + "generate_initials_avatar", "http_replay_sequence", + "hoppscotch_login", + "hoppscotch_create_request", + "hoppscotch_update_request", + "hoppscotch_delete_request", + "hoppscotch_list_requests", + "pass_get_secret", + "hoppscotch_set_environment", + "hoppscotch_run_request", ] diff --git a/python/functions/infra/build_hoppscotch_collection.md b/python/functions/infra/build_hoppscotch_collection.md new file mode 100644 index 00000000..06574126 --- /dev/null +++ b/python/functions/infra/build_hoppscotch_collection.md @@ -0,0 +1,115 @@ +--- +name: build_hoppscotch_collection +kind: function +lang: py +domain: infra +version: "1.0.0" +purity: pure +signature: "def build_hoppscotch_collection(calls: list[dict], *, name: str = \"Collection\", request_names: list[str] | None = None) -> dict" +description: "Helper interno de serializacion del grupo hoppscotch: convierte call specs (method/url/headers/body/body_type) en el formato HoppRESTRequest/coleccion Hoppscotch (request v:2). Lo usan hoppscotch_create_request y hoppscotch_update_request para construir el campo request de las mutations GraphQL del self-host. NO uses el dict resultante para escribir un .json e importarlo a mano: el flujo canonico es operar el self-host por la API (ver docs/capabilities/hoppscotch.md). Pura: solo stdlib, sin red." +tags: [hoppscotch, flow-replay, http, infra, python] +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "" +imports: [] +params: + - name: calls + desc: "lista de call specs (tipicamente la salida de har_extract_calls). Cada elemento es un dict con claves opcionales: method (str), url (str), headers (dict name->value), cookies (dict name->value), body (str|None), body_type (json|form|raw|None). Otras claves como status o sets_cookies se ignoran." + - name: name + desc: "nombre de la coleccion Hoppscotch resultante. Default 'Collection'." + - name: request_names + desc: "nombres explicitos por request, alineados por indice con calls. Si se pasa y existe el indice, sobreescribe el nombre derivado. None = derivar todos como ' '." +output: "dict de coleccion Hoppscotch JSON-serializable: {\"v\": 1, \"name\", \"folders\": [], \"requests\": [...]}. Cada request lleva v:'2', endpoint, name, method (upper), headers (lista key/value/active con header Cookie inyectado si habia cookies), body (contentType+body segun body_type), auth none, params/requestVariables vacios." +tested: true +tests: + - "test_golden_get_simple" + - "test_edge_post_json_con_headers_y_cookies" + - "test_request_names_sobreescribe_nombre_derivado" + - "test_form_body_genera_contenttype_urlencoded" + - "test_raw_body_genera_contenttype_text_plain" + - "test_body_type_desconocido_da_body_null" + - "test_lista_vacia" + - "test_call_spec_sin_url_ni_method" + - "test_sin_cookies_no_anade_header_cookie" +test_file_path: "python/functions/infra/build_hoppscotch_collection_test.py" +file_path: "python/functions/infra/build_hoppscotch_collection.py" +--- + +## Ejemplo + +```python +import json +from build_hoppscotch_collection import build_hoppscotch_collection + +# Call specs tal cual salen de har_extract_calls. +calls = [ + { + "method": "GET", + "url": "https://api.example.com/api/search?q=foo", + "headers": {"Accept": "application/json"}, + }, + { + "method": "POST", + "url": "https://api.example.com/login", + "headers": {"Content-Type": "application/json"}, + "cookies": {"session": "abc", "csrf": "xyz"}, + "body": '{"user":"neo","pass":"<>"}', + "body_type": "json", + }, +] + +collection = build_hoppscotch_collection(calls, name="Example flow") +# { +# "v": 1, +# "name": "Example flow", +# "folders": [], +# "requests": [ +# { +# "v": "2", +# "endpoint": "https://api.example.com/api/search?q=foo", +# "name": "GET /api/search", +# "params": [], +# "headers": [{"key": "Accept", "value": "application/json", "active": True}], +# "method": "GET", +# "auth": {"authType": "none", "authActive": True}, +# "preRequestScript": "", +# "testScript": "", +# "body": {"contentType": None, "body": None}, +# "requestVariables": [], +# }, +# { +# "v": "2", +# "endpoint": "https://api.example.com/login", +# "name": "POST /login", +# "params": [], +# "headers": [ +# {"key": "Content-Type", "value": "application/json", "active": True}, +# {"key": "Cookie", "value": "session=abc; csrf=xyz", "active": True}, +# ], +# "method": "POST", +# "auth": {"authType": "none", "authActive": True}, +# "preRequestScript": "", +# "testScript": "", +# "body": {"contentType": "application/json", "body": '{"user":"neo","pass":"<>"}'}, +# "requestVariables": [], +# }, +# ], +# } + +# Listo para escribir a disco e importar en la app Desktop / hopp CLI. +with open("flow.collection.json", "w") as f: + json.dump(collection, f, indent=2) +``` + +## Cuando usarla + +Usala cuando quieras abrir en la GUI de Hoppscotch unas peticiones que ya grabaste y destilaste con el patron grabar->destilar->reproducir (HAR -> har_filter_flows -> har_extract_calls). Pasas las call specs por esta funcion, guardas el dict resultante como `.json` y lo importas en la app Desktop o con el CLI `hopp`. Es la salida amigable para humanos del flujo de replay: cuando prefieras inspeccionar/tocar las peticiones a mano en el GUI antes de promoverlas a una funcion-accion del registry con http_replay_sequence. La funcion inversa, parse_hoppscotch_collection, reimporta una coleccion editada en el GUI de vuelta a call specs. + +## Gotchas + +- **Genera el formato canonico estable v1/v2.** La coleccion sale como `v:1` y cada request como `v:"2"` — la forma de los fixtures oficiales de Hoppscotch, garantizada importable. Hoppscotch la migra automaticamente a su ultima version interna al importar; no intentes emitir la version "ultima" a mano. +- **Las cookies se inyectan como header Cookie.** Si un call spec trae `cookies` no vacio, se anade un unico header `Cookie` al final con formato `k1=v1; k2=v2`. Hoppscotch no tiene un slot de cookies separado en el request, asi que viajan en headers; al reimportar con parse_hoppscotch_collection se vuelven a separar. +- **Los secretos NO se sustituyen.** La funcion copia headers, cookies y body tal cual. Tokens de sesion, `Authorization` y contrasenas viajan en claro en el dict resultante. Si quieres parametrizar, es el caller quien debe marcar los valores con `<>` (referencia a variable de environment de Hoppscotch) antes de llamar a esta funcion. NO commitear el `.json` resultante sin redactar. +- **Claves extra del call spec se ignoran.** `status`, `sets_cookies` y cualquier otra clave que no sea method/url/headers/cookies/body/body_type no aparecen en la coleccion (son metadata de la captura, no del request a reproducir). diff --git a/python/functions/infra/build_hoppscotch_collection.py b/python/functions/infra/build_hoppscotch_collection.py new file mode 100644 index 00000000..a523ab85 --- /dev/null +++ b/python/functions/infra/build_hoppscotch_collection.py @@ -0,0 +1,135 @@ +"""Convierte call specs del registry en una coleccion Hoppscotch importable. + +Mitad "exportar al GUI" del puente entre el motor de replay del registry y +Hoppscotch. La funcion inversa es parse_hoppscotch_collection. +""" + +from urllib.parse import urlparse + + +def _request_name(call: dict, fallback_index: int) -> str: + """Deriva un nombre legible para la request a partir del metodo y el path. + + Args: + call: call spec con (opcional) method y url. + fallback_index: indice de la call dentro de la lista (no usado en el + nombre derivado, reservado para desambiguar si hiciera falta). + + Returns: + nombre del estilo "GET /api/search". + """ + method = str(call.get("method") or "GET").upper() + url = str(call.get("url") or "") + path = urlparse(url).path or "/" + return f"{method} {path}" + + +def _build_headers(call: dict) -> list[dict]: + """Construye la lista de headers Hoppscotch desde el dict del call spec. + + Convierte el dict headers (preservando orden de insercion) a la lista + [{"key", "value", "active": True}, ...] y, si el call spec trae cookies no + vacias, anade un header extra "Cookie" al final con formato "k1=v1; k2=v2". + + Args: + call: call spec con (opcional) headers y cookies. + + Returns: + lista de headers Hoppscotch. + """ + headers: list[dict] = [] + raw_headers = call.get("headers") or {} + for key, value in raw_headers.items(): + headers.append({"key": key, "value": value, "active": True}) + + cookies = call.get("cookies") or {} + if cookies: + cookie_value = "; ".join(f"{name}={val}" for name, val in cookies.items()) + headers.append({"key": "Cookie", "value": cookie_value, "active": True}) + + return headers + + +def _build_body(call: dict) -> dict: + """Construye el objeto body Hoppscotch segun body_type del call spec. + + Args: + call: call spec con (opcional) body y body_type. + + Returns: + dict con contentType y body. Si no hay body o el body_type es + desconocido/None, ambos campos son None. + """ + body = call.get("body") + body_type = call.get("body_type") + + content_types = { + "json": "application/json", + "form": "application/x-www-form-urlencoded", + "raw": "text/plain", + } + + if body is None or body_type not in content_types: + return {"contentType": None, "body": None} + + return {"contentType": content_types[body_type], "body": body} + + +def build_hoppscotch_collection( + calls: list[dict], + *, + name: str = "Collection", + request_names: list[str] | None = None, +) -> dict: + """Convierte una lista de call specs en una coleccion Hoppscotch importable. + + Genera el formato canonico estable (coleccion v:1, request v:"2") que + Hoppscotch migra a la ultima version al importar. Pura: sin I/O ni red, + solo stdlib, determinista. + + Args: + calls: lista de call specs (salida de har_extract_calls). Cada elemento + es un dict con claves opcionales: method, url, headers, cookies, + body, body_type. Otras claves (status, sets_cookies, ...) se ignoran. + name: nombre de la coleccion Hoppscotch. + request_names: nombres explicitos por request, alineados por indice. Si + se pasa y existe el indice, sobreescribe el nombre derivado. None = + derivar todos los nombres como " ". + + Returns: + dict con la coleccion Hoppscotch: {"v": 1, "name", "folders": [], + "requests": [...]}. JSON-serializable. + """ + requests: list[dict] = [] + + for index, call in enumerate(calls): + if request_names is not None and index < len(request_names): + req_name = request_names[index] + else: + req_name = _request_name(call, index) + + endpoint = str(call.get("url") or "") + method = str(call.get("method") or "GET").upper() + + requests.append( + { + "v": "2", + "endpoint": endpoint, + "name": req_name, + "params": [], + "headers": _build_headers(call), + "method": method, + "auth": {"authType": "none", "authActive": True}, + "preRequestScript": "", + "testScript": "", + "body": _build_body(call), + "requestVariables": [], + } + ) + + return { + "v": 1, + "name": name, + "folders": [], + "requests": requests, + } diff --git a/python/functions/infra/build_hoppscotch_collection_test.py b/python/functions/infra/build_hoppscotch_collection_test.py new file mode 100644 index 00000000..519c1311 --- /dev/null +++ b/python/functions/infra/build_hoppscotch_collection_test.py @@ -0,0 +1,172 @@ +"""Tests para build_hoppscotch_collection.""" + +import json + +from build_hoppscotch_collection import build_hoppscotch_collection + + +def test_golden_get_simple(): + calls = [ + { + "method": "GET", + "url": "https://api.example.com/api/search?q=foo", + "headers": {"Accept": "application/json"}, + } + ] + + result = build_hoppscotch_collection(calls, name="MyCol") + + assert result["v"] == 1 + assert result["name"] == "MyCol" + assert result["folders"] == [] + assert len(result["requests"]) == 1 + + req = result["requests"][0] + assert req["v"] == "2" + assert req["endpoint"] == "https://api.example.com/api/search?q=foo" + assert req["name"] == "GET /api/search" + assert req["method"] == "GET" + assert req["params"] == [] + assert req["headers"] == [ + {"key": "Accept", "value": "application/json", "active": True} + ] + assert req["auth"] == {"authType": "none", "authActive": True} + assert req["preRequestScript"] == "" + assert req["testScript"] == "" + assert req["requestVariables"] == [] + assert req["body"] == {"contentType": None, "body": None} + + # JSON-serializable + json.dumps(result) + + +def test_edge_post_json_con_headers_y_cookies(): + calls = [ + { + "method": "post", + "url": "https://api.example.com/login", + "headers": { + "Content-Type": "application/json", + "X-Csrf": "tok", + }, + "cookies": {"session": "abc", "csrf": "xyz"}, + "body": '{"user":"neo"}', + "body_type": "json", + } + ] + + result = build_hoppscotch_collection(calls) + + req = result["requests"][0] + assert req["method"] == "POST" + assert req["name"] == "POST /login" + + # Header Cookie generado al final con formato "; " join + assert req["headers"] == [ + {"key": "Content-Type", "value": "application/json", "active": True}, + {"key": "X-Csrf", "value": "tok", "active": True}, + {"key": "Cookie", "value": "session=abc; csrf=xyz", "active": True}, + ] + + assert req["body"] == { + "contentType": "application/json", + "body": '{"user":"neo"}', + } + + json.dumps(result) + + +def test_request_names_sobreescribe_nombre_derivado(): + calls = [ + {"method": "GET", "url": "https://api.example.com/a"}, + {"method": "GET", "url": "https://api.example.com/b"}, + ] + + result = build_hoppscotch_collection( + calls, request_names=["Custom A"] + ) + + # Indice 0 usa el nombre explicito; indice 1 cae al derivado. + assert result["requests"][0]["name"] == "Custom A" + assert result["requests"][1]["name"] == "GET /b" + + +def test_form_body_genera_contenttype_urlencoded(): + calls = [ + { + "method": "POST", + "url": "https://api.example.com/form", + "body": "a=1&b=2", + "body_type": "form", + } + ] + + req = build_hoppscotch_collection(calls)["requests"][0] + assert req["body"] == { + "contentType": "application/x-www-form-urlencoded", + "body": "a=1&b=2", + } + + +def test_raw_body_genera_contenttype_text_plain(): + calls = [ + { + "method": "POST", + "url": "https://api.example.com/raw", + "body": "hello", + "body_type": "raw", + } + ] + + req = build_hoppscotch_collection(calls)["requests"][0] + assert req["body"] == {"contentType": "text/plain", "body": "hello"} + + +def test_body_type_desconocido_da_body_null(): + calls = [ + { + "method": "POST", + "url": "https://api.example.com/x", + "body": "ignored", + "body_type": "binary", + } + ] + + req = build_hoppscotch_collection(calls)["requests"][0] + assert req["body"] == {"contentType": None, "body": None} + + +def test_lista_vacia(): + result = build_hoppscotch_collection([], name="Empty") + assert result == { + "v": 1, + "name": "Empty", + "folders": [], + "requests": [], + } + json.dumps(result) + + +def test_call_spec_sin_url_ni_method(): + calls = [{}] + + req = build_hoppscotch_collection(calls)["requests"][0] + assert req["endpoint"] == "" + assert req["method"] == "GET" + assert req["name"] == "GET /" + assert req["headers"] == [] + assert req["body"] == {"contentType": None, "body": None} + + +def test_sin_cookies_no_anade_header_cookie(): + calls = [ + { + "method": "GET", + "url": "https://api.example.com/x", + "headers": {"Accept": "*/*"}, + "cookies": {}, + } + ] + + req = build_hoppscotch_collection(calls)["requests"][0] + assert all(h["key"] != "Cookie" for h in req["headers"]) diff --git a/python/functions/infra/generate_initials_avatar.md b/python/functions/infra/generate_initials_avatar.md new file mode 100644 index 00000000..42745fc1 --- /dev/null +++ b/python/functions/infra/generate_initials_avatar.md @@ -0,0 +1,94 @@ +--- +name: generate_initials_avatar +kind: function +lang: py +domain: infra +version: "1.0.0" +purity: impure +signature: "def generate_initials_avatar(text: str, out_path: str, bg_hex: str = \"\", size: int = 256, fg_hex: str = \"#FFFFFF\") -> str" +description: "Genera un avatar circular de iniciales (foto de perfil) como PNG: circulo de color con 1-2 iniciales blancas centradas. Color de fondo derivado de forma determinista del texto si no se especifica." +tags: [avatar, icon, rofi, pillow, profile, initials] +params: + - name: text + desc: "Nombre del que derivar las iniciales (ej. 'John Doe', 'osint_01'). Se trocea por espacios, guiones y guiones bajos." + - name: out_path + desc: "Ruta de salida del PNG. Se crea el directorio padre si no existe. Rutas relativas se resuelven contra el cwd." + - name: bg_hex + desc: "Color de fondo del circulo en formato '#RRGGBB'. Si va vacio ('') se deriva de forma determinista de text via md5 sobre una paleta de 12 colores." + - name: size + desc: "Lado del PNG cuadrado en pixels. Default 256. El circulo deja ~4% de margen; fuera queda transparente." + - name: fg_hex + desc: "Color del texto de las iniciales en '#RRGGBB'. Default blanco '#FFFFFF'." +output: "La misma out_path recibida. Efecto: escribe un PNG RGBA cuadrado con el avatar circular en disco." +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: [hashlib, os, pathlib, PIL] +tested: false +tests: [] +test_file_path: "" +file_path: "python/functions/infra/generate_initials_avatar.py" +--- + +## Ejemplo + +```python +import sys, os +sys.path.insert(0, os.path.join("python", "functions")) +from infra.generate_initials_avatar import generate_initials_avatar + +# Color de fondo determinista derivado del nombre. +generate_initials_avatar("Aurgi", "/tmp/aurgi.png") # -> circulo con "A" +generate_initials_avatar("John Doe", "/tmp/john.png") # -> circulo con "JD" + +# Color de fondo explicito + tamano custom. +generate_initials_avatar("Personal", "/tmp/personal.png", bg_hex="#7c3aed", size=128) +``` + +Desde el dispatcher (genera con defaults, fondo derivado del texto): + +```bash +./fn run generate_initials_avatar_py_infra "Aurgi" /tmp/aurgi.png +``` + +## Cuando usarla + +Cuando necesites un icono reconocible de un perfil (navegador, usuario, cuenta) +y no tengas una foto real: genera un avatar de iniciales determinista por nombre. +Util para entradas de rofi, launchers, listas de perfiles o cualquier UI que +muestre un identificador visual estable. Mismo `text` -> mismo color siempre. + +## Gotchas + +- **Impura**: escribe un PNG a disco. Crea el directorio padre si falta y lanza + `OSError` con mensaje claro si la escritura falla. +- **Fondo transparente**: solo el circulo (con ~4% de margen) lleva color; las + esquinas del PNG quedan con alpha 0. Si lo pegas sobre un fondo claro, el + circulo se ve recortado correctamente, pero un visor que ignore el alpha + mostrara las esquinas negras. +- **Dependencia Pillow**: requiere `PIL` (Pillow) instalado en el venv del + registry (`python/.venv`). No usa cairosvg. +- **Fuente DejaVu hardcodeada**: usa `/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf`. + Si no existe (otro SO/distro), cae a `ImageFont.load_default()`, que es mas + pequena y pixelada — las iniciales se veran peor pero no falla. +- **Antialiasing 4x**: renderiza a `size*4` y reduce con LANCZOS. Para `size` + muy grande (>1024) el coste de memoria/tiempo crece cuadraticamente. + +## Notas + +Reglas de iniciales: trocea por espacios, `-` y `_`; toma la primera letra +alfabetica de los dos primeros tokens que empiecen por letra (max 2, en +mayusculas). Si solo un token tiene letra inicial -> 1 inicial. Si ninguno +empieza por letra -> primer caracter alfanumerico del texto. Ejemplos: +"Aurgi" -> "A", "Work" -> "W", "osint_01" -> "O", "John Doe" -> "JD", +"Personal" -> "P". + +Paleta determinista (12 colores tipo Tailwind 500): sky, emerald, violet, +amber, rose, indigo, teal, orange, fuchsia, lime, cyan, red. El indice se +elige con `int(md5(text), 16) % 12`, estable entre procesos. + +Las funciones auxiliares `derive_initials(text)` y `derive_bg_color(text)` son +publicas y reutilizables por separado si solo necesitas la logica de iniciales +o de color sin generar el PNG. diff --git a/python/functions/infra/generate_initials_avatar.py b/python/functions/infra/generate_initials_avatar.py new file mode 100644 index 00000000..0de79edb --- /dev/null +++ b/python/functions/infra/generate_initials_avatar.py @@ -0,0 +1,192 @@ +"""Genera un avatar circular de iniciales tipo foto de perfil. + +Dibuja un circulo relleno de color con 1-2 iniciales blancas centradas sobre +fondo transparente y lo exporta como PNG cuadrado. El color de fondo se puede +fijar explicitamente o derivar de forma DETERMINISTA del texto (mismo texto -> +mismo color siempre), lo que produce avatares reconocibles y distintos por +nombre sin necesidad de una imagen real. + +Funciones publicas reutilizables: + derive_initials — extrae 1-2 iniciales en mayusculas de un nombre + derive_bg_color — mapea un texto a un color de paleta de forma estable +""" +import hashlib +import os +from pathlib import Path + +from PIL import Image, ImageDraw, ImageFont + +# Fuente bold preinstalada en este Linux. Si no existe, se cae al default de PIL. +DEFAULT_FONT_PATH = "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf" + +# Paleta agradable tipo Tailwind 500-600 (12 colores). El indice se elige de +# forma determinista a partir del hash del texto -> mismo texto, mismo color. +PALETTE = [ + "#0ea5e9", # sky-500 + "#10b981", # emerald-500 + "#8b5cf6", # violet-500 + "#f59e0b", # amber-500 + "#f43f5e", # rose-500 + "#6366f1", # indigo-500 + "#14b8a6", # teal-500 + "#f97316", # orange-500 + "#d946ef", # fuchsia-500 + "#84cc16", # lime-500 + "#06b6d4", # cyan-500 + "#ef4444", # red-500 +] + +# Factor de supersampling para antialiasing: se renderiza a NxN veces el tamano +# final y se reduce con LANCZOS para obtener bordes suaves. +_SUPERSAMPLE = 4 + +# Margen del circulo respecto al canvas (~4% por lado). +_MARGIN_RATIO = 0.04 + +# Tamano de fuente como fraccion del lado del canvas. +_FONT_RATIO = 0.46 + + +def _hex_to_rgb(h: str) -> tuple[int, int, int]: + """Convierte un color "#RRGGBB" (o "RRGGBB") a una tupla RGB.""" + h = h.lstrip("#") + if len(h) != 6: + raise ValueError(f"color hex invalido, se espera #RRGGBB: {h!r}") + return tuple(int(h[i: i + 2], 16) for i in (0, 2, 4)) + + +def derive_initials(text: str) -> str: + """Extrae 1-2 iniciales en mayusculas a partir de un nombre. + + Trocea el texto por espacios, guiones y guiones bajos. Toma la primera + letra alfabetica de los dos primeros tokens que empiecen por letra. Si solo + un token tiene letra inicial, devuelve 1 inicial. Si ninguno empieza por + letra, usa el primer caracter alfanumerico del texto completo. + + Args: + text: Nombre del que derivar las iniciales (ej. "John Doe", "osint_01"). + + Returns: + 1 o 2 caracteres en mayusculas. Cadena vacia si no hay nada alfanumerico. + """ + # Normaliza separadores a espacios. + normalized = text.replace("-", " ").replace("_", " ") + tokens = [t for t in normalized.split() if t] + + initials = [] + for token in tokens: + # Primera letra alfabetica del token (el token debe empezar por letra). + if token[0].isalpha(): + initials.append(token[0].upper()) + if len(initials) == 2: + break + + if initials: + return "".join(initials) + + # Fallback: primer caracter alfanumerico del texto entero. + for ch in text: + if ch.isalnum(): + return ch.upper() + return "" + + +def derive_bg_color(text: str) -> str: + """Mapea un texto a un color de la paleta de forma estable y determinista. + + Usa md5 del texto para indexar la paleta, de modo que el mismo texto + produce siempre el mismo color entre ejecuciones y procesos. + + Args: + text: Texto del que derivar el color. + + Returns: + Color en formato "#RRGGBB" de la paleta interna. + """ + digest = hashlib.md5(text.encode("utf-8")).hexdigest() + idx = int(digest, 16) % len(PALETTE) + return PALETTE[idx] + + +def _load_font(font_size: int) -> ImageFont.FreeTypeFont | ImageFont.ImageFont: + """Carga la fuente DejaVu Bold al tamano dado, con fallback al default.""" + try: + return ImageFont.truetype(DEFAULT_FONT_PATH, font_size) + except OSError: + return ImageFont.load_default() + + +def generate_initials_avatar( + text: str, + out_path: str, + bg_hex: str = "", + size: int = 256, + fg_hex: str = "#FFFFFF", +) -> str: + """Genera un avatar circular de iniciales y lo guarda como PNG. + + Dibuja un circulo relleno con `bg_hex` (o un color derivado de `text` si va + vacio) y centra 1-2 iniciales en `fg_hex` sobre el. El fondo fuera del + circulo queda transparente. Renderiza a 4x y reduce con LANCZOS para bordes + suaves. + + Args: + text: Nombre del que derivar las iniciales (ej. "Aurgi", "John Doe"). + out_path: Ruta de salida del PNG. El directorio padre se crea si falta. + bg_hex: Color de fondo del circulo en "#RRGGBB". Si va vacio (""), se + deriva de forma determinista de `text`. + size: Lado del PNG cuadrado en pixels (default 256). + fg_hex: Color del texto en "#RRGGBB" (default blanco "#FFFFFF"). + + Returns: + La misma `out_path` recibida. + + Raises: + ValueError: Si algun color no tiene formato "#RRGGBB" o `size` <= 0. + OSError: Si falla la escritura del archivo a disco. + """ + if size <= 0: + raise ValueError(f"size debe ser positivo, recibido: {size!r}") + + background = bg_hex if bg_hex else derive_bg_color(text) + bg_rgb = _hex_to_rgb(background) + fg_rgb = _hex_to_rgb(fg_hex) + + initials = derive_initials(text) + + # Render a 4x para antialiasing, luego se reduce con LANCZOS. + big = size * _SUPERSAMPLE + canvas = Image.new("RGBA", (big, big), (0, 0, 0, 0)) + draw = ImageDraw.Draw(canvas) + + margin = int(big * _MARGIN_RATIO) + circle_box = [margin, margin, big - margin - 1, big - margin - 1] + draw.ellipse(circle_box, fill=bg_rgb + (255,)) + + if initials: + font_size = max(1, int(big * _FONT_RATIO)) + font = _load_font(font_size) + + # Bounding box real del glyph (no solo ascent) para centrado optico. + bbox = draw.textbbox((0, 0), initials, font=font) + text_w = bbox[2] - bbox[0] + text_h = bbox[3] - bbox[1] + # El origen del texto se desplaza por el offset del bbox para que el + # glyph quede centrado tanto horizontal como verticalmente. + text_x = (big - text_w) / 2 - bbox[0] + text_y = (big - text_h) / 2 - bbox[1] + draw.text((text_x, text_y), initials, font=font, fill=fg_rgb + (255,)) + + final = canvas.resize((size, size), Image.LANCZOS) + + out = Path(out_path) + if not out.is_absolute(): + out = Path.cwd() / out + out.parent.mkdir(parents=True, exist_ok=True) + + try: + final.save(out, format="PNG") + except OSError as exc: + raise OSError(f"no se pudo escribir el avatar en {out}: {exc}") from exc + + return out_path diff --git a/python/functions/infra/hoppscotch_create_request.md b/python/functions/infra/hoppscotch_create_request.md new file mode 100644 index 00000000..522153b7 --- /dev/null +++ b/python/functions/infra/hoppscotch_create_request.md @@ -0,0 +1,103 @@ +--- +name: hoppscotch_create_request +kind: function +lang: py +domain: infra +version: "1.0.0" +purity: impure +signature: "def hoppscotch_create_request(collection_id: str, method: str, url: str, *, title: str | None = None, headers: dict | None = None, body: str | None = None, body_type: str | None = None, team_id: str | None = None, access_token: str, backend_url: str = \"http://localhost:3170\") -> dict" +description: "Crea una request REST dentro de una team collection de Hoppscotch self-hosted via la mutation GraphQL createRequestInCollection. Construye el HoppRESTRequest canonico reusando build_hoppscotch_collection del registry y lo envia como json string en el campo request del input. La mutation esta protegida por GqlAuthGuard: el JWT de sesion (de hoppscotch_login) viaja en la cookie access_token. Algunas versiones del backend exigen team_id dentro del input." +tags: [hoppscotch, flow-replay, http, infra, crud] +uses_functions: [build_hoppscotch_collection_py_infra] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: [json, requests] +params: + - name: collection_id + desc: "ID de la team collection donde insertar la request." + - name: method + desc: "metodo HTTP de la request (GET, POST, PUT, ...). Se normaliza a mayusculas por build_hoppscotch_collection." + - name: url + desc: "endpoint completo de la request (con query string si aplica)." + - name: title + desc: "nombre visible de la request en la GUI de Hoppscotch. None = derivar de method + path (p.ej. 'GET /ping')." + - name: headers + desc: "dict name->value de cabeceras de la request. None = sin cabeceras." + - name: body + desc: "cuerpo de la request como texto YA serializado (no se re-serializa). None = sin cuerpo." + - name: body_type + desc: "tipo de cuerpo: 'json' | 'form' | 'raw' | None. Determina el contentType del HoppRESTRequest." + - name: team_id + desc: "ID de la team duena de la collection. Requerido por las versiones del backend cuyo CreateTeamRequestInput exige teamID (el self-host de referencia lo exige). Si el backend no lo pide, None." + - name: access_token + desc: "JWT de sesion (de hoppscotch_login). Viaja en la cookie access_token, NO en el header Authorization." + - name: backend_url + desc: "base del backend Hoppscotch sin barra final. El endpoint GraphQL es {backend_url}/graphql. Default http://localhost:3170." +output: "dict. En exito: {status: 'ok', id: str, title: str} con el ID de la request creada. En error (GraphQL errors, respuesta no JSON, sin id, o fallo de transporte): {status: 'error', error: str, data: }. Nunca lanza por errores de red esperables." +tested: true +tests: + - "test_golden_crea_request_y_devuelve_id" + - "test_body_json_se_serializa_en_el_request" + - "test_team_id_se_incluye_en_data" + - "test_team_id_omitido_no_aparece_en_data" + - "test_error_graphql_errors" +test_file_path: "python/functions/infra/hoppscotch_create_request_test.py" +file_path: "python/functions/infra/hoppscotch_create_request.py" +--- + +## Ejemplo + +```python +import sys +sys.path.insert(0, "python/functions") +from infra.hoppscotch_login import hoppscotch_login +from infra.hoppscotch_create_request import hoppscotch_create_request + +token = hoppscotch_login("admin@example.com")["access_token"] + +# Crear una request POST con body JSON en una team collection. +result = hoppscotch_create_request( + collection_id="cmq8lt8ta000t0xls4ddy6sdz", + method="POST", + url="https://api.example.com/login", + title="Login", + headers={"Content-Type": "application/json"}, + body='{"user":"neo","pass":"<>"}', + body_type="json", + team_id="cmq8kn0v500030xls1nvminjy", # requerido por este backend + access_token=token, +) +print(result) # {"status": "ok", "id": "...", "title": "Login"} +``` + +## Cuando usarla + +Cuando el agente quiera preparar una request REST en una team Hoppscotch +self-hosted via API para que el humano la vea aparecer en vivo en la GUI (las +subscriptions de Hoppscotch propagan la creacion en tiempo real). Util en el +patron grabar->destilar->reproducir: tras destilar un flujo a call specs, se +materializan como requests dentro de una collection que el humano inspecciona. +Primero obten el `access_token` con `hoppscotch_login`. + +## Gotchas + +- **El access_token va como cookie, no como header Authorization.** La mutation + esta protegida por GqlAuthGuard que lee el JWT de la cookie `access_token`. +- **El token expira (~24h).** Si la llamada devuelve un error de auth, re-loguea + con `hoppscotch_login`. +- **`request` debe ser un json string de un HoppRESTRequest v:"2".** No se pasa el + dict directo: el campo `request` del input es un string. Esta funcion serializa + con `json.dumps` el item que produce `build_hoppscotch_collection`. +- **`team_id` puede ser obligatorio.** El self-host de referencia exige `teamID` + dentro de `CreateTeamRequestInput`. Si lo omites contra ese backend, GraphQL + responde "Field teamID of required type ID! was not provided". Pasa `team_id`. +- **Secreto — nunca logear el token en crudo.** No imprimas `access_token` en + claro; trata el JWT como un secreto. + +## Capability growth log + +v1.0.0 — version inicial. CRUD validado contra el self-host vivo el 10/06/2026. +Se anadio `team_id` opcional porque el backend de referencia exige `teamID` en el +input. diff --git a/python/functions/infra/hoppscotch_create_request.py b/python/functions/infra/hoppscotch_create_request.py new file mode 100644 index 00000000..605ee590 --- /dev/null +++ b/python/functions/infra/hoppscotch_create_request.py @@ -0,0 +1,122 @@ +"""Crea una request REST dentro de una team collection de Hoppscotch. + +Construye el HoppRESTRequest canonico (reusando build_hoppscotch_collection del +registry) y lo inserta en una team collection via la mutation GraphQL +createRequestInCollection del backend self-hosted. La mutation esta protegida +por GqlAuthGuard: el JWT de sesion viaja en la cookie `access_token`. +""" + +import json + +import requests + +from infra.build_hoppscotch_collection import build_hoppscotch_collection + +_MUTATION = ( + "mutation($c:ID!,$d:CreateTeamRequestInput!){" + " createRequestInCollection(collectionID:$c, data:$d){ id title } }" +) + + +def hoppscotch_create_request( + collection_id: str, + method: str, + url: str, + *, + title: str | None = None, + headers: dict | None = None, + body: str | None = None, + body_type: str | None = None, + team_id: str | None = None, + access_token: str, + backend_url: str = "http://localhost:3170", +) -> dict: + """Crea una request en una team collection de Hoppscotch. + + Args: + collection_id: ID de la team collection donde insertar la request. + method: metodo HTTP de la request (GET, POST, ...). + url: endpoint de la request. + title: nombre visible de la request en la GUI. None = derivar de + method + path via build_hoppscotch_collection. + headers: dict name->value de cabeceras de la request. + body: cuerpo de la request como texto ya serializado. + body_type: tipo de cuerpo ("json"|"form"|"raw"|None). + team_id: ID de la team duena de la collection. Requerido por las + versiones del backend cuyo CreateTeamRequestInput exige `teamID` + (el self-host de referencia lo exige). Si el backend no lo pide, + dejar None. + access_token: JWT de sesion (de hoppscotch_login). Viaja en la cookie + `access_token`, NO en el header Authorization. + backend_url: base del backend Hoppscotch (sin barra final). + + Returns: + Dict. En exito: ``{"status": "ok", "id": str, "title": str}``. En error + (GraphQL errors, HTTP no 200, transporte): ``{"status": "error", + "error": str, "data": ...}`` con el cuerpo GraphQL si lo hubo. + """ + spec = { + "method": method, + "url": url, + "headers": headers or {}, + "body": body, + "body_type": body_type, + } + req_names = [title] if title else None + req_item = build_hoppscotch_collection([spec], request_names=req_names)[ + "requests" + ][0] + + data: dict = { + "title": req_item["name"], + "request": json.dumps(req_item), + } + if team_id is not None: + data["teamID"] = team_id + + payload = { + "query": _MUTATION, + "variables": { + "c": collection_id, + "d": data, + }, + } + + try: + resp = requests.post( + f"{backend_url}/graphql", + json=payload, + cookies={"access_token": access_token}, + timeout=30.0, + ) + except requests.RequestException as exc: + return {"status": "error", "error": f"transport error: {exc}"} + + try: + data = resp.json() + except ValueError: + return { + "status": "error", + "error": f"non-JSON response (HTTP {resp.status_code})", + } + + if data.get("errors"): + return { + "status": "error", + "error": "graphql errors", + "data": data, + } + + created = (data.get("data") or {}).get("createRequestInCollection") + if not created or not created.get("id"): + return { + "status": "error", + "error": "createRequestInCollection returned no id", + "data": data, + } + + return { + "status": "ok", + "id": created["id"], + "title": created.get("title"), + } diff --git a/python/functions/infra/hoppscotch_create_request_test.py b/python/functions/infra/hoppscotch_create_request_test.py new file mode 100644 index 00000000..f232859d --- /dev/null +++ b/python/functions/infra/hoppscotch_create_request_test.py @@ -0,0 +1,165 @@ +"""Tests para hoppscotch_create_request. + +Deterministas: monkeypatchean requests.post para no tocar la red. Verifican que +el POST GraphQL lleva la mutation createRequestInCollection, el access_token en +la cookie, y que `request` es el json string de un HoppRESTRequest v:"2". +""" + +import json +import sys + +import infra.hoppscotch_create_request # noqa: F401 + +# El __init__ rebinds el nombre a la funcion; recuperamos el submodulo real. +mod = sys.modules["infra.hoppscotch_create_request"] + + +class _FakeResponse: + def __init__(self, status_code=200, json_data=None): + self.status_code = status_code + self._json = json_data + + def json(self): + if self._json is None: + raise ValueError("no json") + return self._json + + +def test_golden_crea_request_y_devuelve_id(monkeypatch): + captured = {} + + def fake_post(url, **kwargs): + captured["url"] = url + captured["kwargs"] = kwargs + return _FakeResponse( + 200, + { + "data": { + "createRequestInCollection": { + "id": "req-99", + "title": "Ping", + } + } + }, + ) + + monkeypatch.setattr(mod.requests, "post", fake_post) + + result = mod.hoppscotch_create_request( + "col-1", + "GET", + "https://api.example.com/ping", + title="Ping", + headers={"Accept": "application/json"}, + access_token="ACCESS-JWT", + ) + + assert result["status"] == "ok" + assert result["id"] == "req-99" + assert result["title"] == "Ping" + + # El POST fue al endpoint GraphQL con la cookie access_token. + assert captured["url"].endswith("/graphql") + assert captured["kwargs"]["cookies"] == {"access_token": "ACCESS-JWT"} + + payload = captured["kwargs"]["json"] + assert "createRequestInCollection" in payload["query"] + variables = payload["variables"] + assert variables["c"] == "col-1" + assert variables["d"]["title"] == "Ping" + + # `request` es un json string de un HoppRESTRequest v:"2". + req = json.loads(variables["d"]["request"]) + assert req["v"] == "2" + assert req["method"] == "GET" + assert req["endpoint"] == "https://api.example.com/ping" + assert req["name"] == "Ping" + + +def test_body_json_se_serializa_en_el_request(monkeypatch): + captured = {} + + def fake_post(url, **kwargs): + captured["kwargs"] = kwargs + return _FakeResponse( + 200, + {"data": {"createRequestInCollection": {"id": "r", "title": "t"}}}, + ) + + monkeypatch.setattr(mod.requests, "post", fake_post) + + mod.hoppscotch_create_request( + "col-2", + "POST", + "https://api.example.com/login", + body='{"user":"neo"}', + body_type="json", + access_token="A", + ) + + req = json.loads(captured["kwargs"]["json"]["variables"]["d"]["request"]) + assert req["method"] == "POST" + assert req["body"] == { + "contentType": "application/json", + "body": '{"user":"neo"}', + } + + +def test_team_id_se_incluye_en_data(monkeypatch): + captured = {} + + def fake_post(url, **kwargs): + captured["kwargs"] = kwargs + return _FakeResponse( + 200, + {"data": {"createRequestInCollection": {"id": "r", "title": "t"}}}, + ) + + monkeypatch.setattr(mod.requests, "post", fake_post) + + mod.hoppscotch_create_request( + "col-3", + "GET", + "https://api.example.com/x", + team_id="team-abc", + access_token="A", + ) + + data = captured["kwargs"]["json"]["variables"]["d"] + assert data["teamID"] == "team-abc" + + +def test_team_id_omitido_no_aparece_en_data(monkeypatch): + captured = {} + + def fake_post(url, **kwargs): + captured["kwargs"] = kwargs + return _FakeResponse( + 200, + {"data": {"createRequestInCollection": {"id": "r", "title": "t"}}}, + ) + + monkeypatch.setattr(mod.requests, "post", fake_post) + + mod.hoppscotch_create_request( + "col-4", "GET", "https://api.example.com/x", access_token="A" + ) + + data = captured["kwargs"]["json"]["variables"]["d"] + assert "teamID" not in data + + +def test_error_graphql_errors(monkeypatch): + def fake_post(url, **kwargs): + return _FakeResponse( + 200, {"errors": [{"message": "team_req/not_found"}]} + ) + + monkeypatch.setattr(mod.requests, "post", fake_post) + + result = mod.hoppscotch_create_request( + "bad", "GET", "https://x", access_token="A" + ) + assert result["status"] == "error" + assert result["error"] == "graphql errors" + assert "errors" in result["data"] diff --git a/python/functions/infra/hoppscotch_delete_request.md b/python/functions/infra/hoppscotch_delete_request.md new file mode 100644 index 00000000..e54309f2 --- /dev/null +++ b/python/functions/infra/hoppscotch_delete_request.md @@ -0,0 +1,73 @@ +--- +name: hoppscotch_delete_request +kind: function +lang: py +domain: infra +version: "1.0.0" +purity: impure +signature: "def hoppscotch_delete_request(request_id: str, *, access_token: str, backend_url: str = \"http://localhost:3170\") -> dict" +description: "Borra una request REST de una team collection de Hoppscotch self-hosted via la mutation GraphQL deleteRequest. Protegida por GqlAuthGuard: el JWT de sesion (de hoppscotch_login) viaja en la cookie access_token. Confirma que la mutation devolvio true antes de reportar exito." +tags: [hoppscotch, flow-replay, http, infra, crud] +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: [requests] +params: + - name: request_id + desc: "ID de la request a borrar." + - name: access_token + desc: "JWT de sesion (de hoppscotch_login). Viaja en la cookie access_token, NO en el header Authorization." + - name: backend_url + desc: "base del backend Hoppscotch sin barra final. El endpoint GraphQL es {backend_url}/graphql. Default http://localhost:3170." +output: "dict. En exito (data.deleteRequest == true): {status: 'ok', deleted: str}. En error (GraphQL errors, deleteRequest != true, respuesta no JSON, o fallo de transporte): {status: 'error', error: str, data: }. Nunca lanza por errores de red esperables." +tested: true +tests: + - "test_golden_delete_true" + - "test_error_delete_false" +test_file_path: "python/functions/infra/hoppscotch_delete_request_test.py" +file_path: "python/functions/infra/hoppscotch_delete_request.py" +--- + +## Ejemplo + +```python +import sys +sys.path.insert(0, "python/functions") +from infra.hoppscotch_login import hoppscotch_login +from infra.hoppscotch_delete_request import hoppscotch_delete_request + +token = hoppscotch_login("admin@example.com")["access_token"] + +result = hoppscotch_delete_request( + request_id="cmq8lue8l000x0xlsd62bncpi", + access_token=token, +) +print(result) # {"status": "ok", "deleted": "cmq8lue8l000x0xlsd62bncpi"} +``` + +## Cuando usarla + +Cuando quieras eliminar una request que el agente creo (o que ya no hace falta) de +una team collection Hoppscotch self-hosted, y que el humano vea la baja en vivo en +la GUI por subscriptions. Util para limpiar requests temporales tras un flujo de +prueba. Necesitas el `request_id` (de `hoppscotch_list_requests`) y un +`access_token` fresco de `hoppscotch_login`. + +## Gotchas + +- **El access_token va como cookie, no como header Authorization.** La mutation + esta protegida por GqlAuthGuard que lee el JWT de la cookie `access_token`. +- **El token expira (~24h).** Si la llamada devuelve un error de auth, re-loguea + con `hoppscotch_login`. +- **Operacion destructiva.** Borra la request de verdad; no es reversible. Confirma + el `request_id` (p.ej. con `hoppscotch_list_requests`) antes de borrar. +- **Solo `data.deleteRequest == true` es exito.** Cualquier otro valor (false, null) + o un bloque `errors` se reporta como `status: 'error'`. +- **Secreto — nunca logear el token en crudo.** Trata el JWT como un secreto. + +## Capability growth log + +v1.0.0 — version inicial. Validado contra el self-host vivo el 10/06/2026 +(delete confirmo que la request desaparece de la lista posterior). diff --git a/python/functions/infra/hoppscotch_delete_request.py b/python/functions/infra/hoppscotch_delete_request.py new file mode 100644 index 00000000..526931d8 --- /dev/null +++ b/python/functions/infra/hoppscotch_delete_request.py @@ -0,0 +1,69 @@ +"""Borra una request REST de una team collection de Hoppscotch. + +Invoca la mutation GraphQL deleteRequest del backend self-hosted. Protegida por +GqlAuthGuard: el JWT de sesion viaja en la cookie `access_token`. +""" + +import requests + +_MUTATION = "mutation($r:ID!){ deleteRequest(requestID:$r) }" + + +def hoppscotch_delete_request( + request_id: str, + *, + access_token: str, + backend_url: str = "http://localhost:3170", +) -> dict: + """Borra una request de Hoppscotch por su ID. + + Args: + request_id: ID de la request a borrar. + access_token: JWT de sesion (de hoppscotch_login). Viaja en la cookie + `access_token`, NO en el header Authorization. + backend_url: base del backend Hoppscotch (sin barra final). + + Returns: + Dict. En exito: ``{"status": "ok", "deleted": str}``. En error (GraphQL + errors, deleteRequest != true, HTTP no 200, transporte): + ``{"status": "error", "error": str, "data": ...}``. + """ + payload = { + "query": _MUTATION, + "variables": {"r": request_id}, + } + + try: + resp = requests.post( + f"{backend_url}/graphql", + json=payload, + cookies={"access_token": access_token}, + timeout=30.0, + ) + except requests.RequestException as exc: + return {"status": "error", "error": f"transport error: {exc}"} + + try: + data = resp.json() + except ValueError: + return { + "status": "error", + "error": f"non-JSON response (HTTP {resp.status_code})", + } + + if data.get("errors"): + return { + "status": "error", + "error": "graphql errors", + "data": data, + } + + deleted = (data.get("data") or {}).get("deleteRequest") + if deleted is not True: + return { + "status": "error", + "error": "deleteRequest did not return true", + "data": data, + } + + return {"status": "ok", "deleted": request_id} diff --git a/python/functions/infra/hoppscotch_delete_request_test.py b/python/functions/infra/hoppscotch_delete_request_test.py new file mode 100644 index 00000000..43e8786a --- /dev/null +++ b/python/functions/infra/hoppscotch_delete_request_test.py @@ -0,0 +1,54 @@ +"""Tests para hoppscotch_delete_request. + +Deterministas: monkeypatchean requests.post. Verifican el camino ok +(deleteRequest=true) y el de error (deleteRequest=false). +""" + +import sys + +import infra.hoppscotch_delete_request # noqa: F401 + +# El __init__ rebinds el nombre a la funcion; recuperamos el submodulo real. +mod = sys.modules["infra.hoppscotch_delete_request"] + + +class _FakeResponse: + def __init__(self, status_code=200, json_data=None): + self.status_code = status_code + self._json = json_data + + def json(self): + if self._json is None: + raise ValueError("no json") + return self._json + + +def test_golden_delete_true(monkeypatch): + captured = {} + + def fake_post(url, **kwargs): + captured["url"] = url + captured["kwargs"] = kwargs + return _FakeResponse(200, {"data": {"deleteRequest": True}}) + + monkeypatch.setattr(mod.requests, "post", fake_post) + + result = mod.hoppscotch_delete_request("req-1", access_token="ACCESS-JWT") + + assert result["status"] == "ok" + assert result["deleted"] == "req-1" + assert captured["url"].endswith("/graphql") + assert captured["kwargs"]["cookies"] == {"access_token": "ACCESS-JWT"} + assert "deleteRequest" in captured["kwargs"]["json"]["query"] + assert captured["kwargs"]["json"]["variables"] == {"r": "req-1"} + + +def test_error_delete_false(monkeypatch): + def fake_post(url, **kwargs): + return _FakeResponse(200, {"data": {"deleteRequest": False}}) + + monkeypatch.setattr(mod.requests, "post", fake_post) + + result = mod.hoppscotch_delete_request("req-2", access_token="A") + assert result["status"] == "error" + assert "did not return true" in result["error"] diff --git a/python/functions/infra/hoppscotch_e2e_test.py b/python/functions/infra/hoppscotch_e2e_test.py new file mode 100644 index 00000000..a0f5c615 --- /dev/null +++ b/python/functions/infra/hoppscotch_e2e_test.py @@ -0,0 +1,79 @@ +"""Test e2e real del grupo hoppscotch contra un self-host VIVO. + +NO corre en la suite normal (skip). Para ejecutarlo a mano contra la instancia +viva, quita temporalmente el skip y asegura: + - backend Hoppscotch en http://localhost:3170 + - mailpit en http://localhost:8025 + - una team collection real cuyo ID pongas en COLLECTION_ID abajo. + +El flujo: login(admin@example.com) -> create_request -> list -> delete. + +Nota: el backend de referencia exige `teamID` dentro de CreateTeamRequestInput, +asi que la create pasa `team_id=TEAM_ID`. Rellena COLLECTION_ID y TEAM_ID con +una team collection real (consultables via myTeams / rootCollectionsOfTeam). +Este flujo se valido con exito contra la instancia viva el 10/06/2026. +""" + +import pytest + +from infra.hoppscotch_login import hoppscotch_login +from infra.hoppscotch_create_request import hoppscotch_create_request +from infra.hoppscotch_list_requests import hoppscotch_list_requests +from infra.hoppscotch_delete_request import hoppscotch_delete_request +from infra.hoppscotch_run_request import hoppscotch_run_request + +# Rellenar con IDs reales del self-host antes de correr. +TEAM_ID = "REPLACE_WITH_REAL_TEAM_ID" +COLLECTION_ID = "REPLACE_WITH_REAL_COLLECTION_ID" + + +@pytest.mark.skip(reason="e2e real contra self-host vivo, correr a mano") +def test_e2e_crud_request_real(): + login = hoppscotch_login("admin@example.com") + assert login["status"] == "ok", login + + token = login["access_token"] + + created = hoppscotch_create_request( + COLLECTION_ID, + "GET", + "https://api.example.com/e2e-ping", + title="e2e ping", + team_id=TEAM_ID, + access_token=token, + ) + assert created["status"] == "ok", created + req_id = created["id"] + + listed = hoppscotch_list_requests(COLLECTION_ID, access_token=token) + assert listed["status"] == "ok", listed + assert any(r["id"] == req_id for r in listed["requests"]) + + deleted = hoppscotch_delete_request(req_id, access_token=token) + assert deleted["status"] == "ok", deleted + assert deleted["deleted"] == req_id + + +@pytest.mark.skip(reason="e2e real self-host vivo") +def test_e2e_run_request_aparece_en_user_history(): + """Ejecuta una request real y verifica que entra en el UserHistory. + + login -> run_request GET <>/api/status -> status_code 200 + + recorded True. La entry debe verse en la pestana History de la GUI + (subscription userHistoryCreated). Validado contra la instancia viva. + """ + login = hoppscotch_login("admin@example.com") + assert login["status"] == "ok", login + token = login["access_token"] + + result = hoppscotch_run_request( + "GET", + "<>/api/status", + title="Status (e2e)", + variables={"baseURL": "https://registry.organic-machine.com"}, + access_token=token, + ) + assert result["status"] == "ok", result + assert result["status_code"] == 200, result + assert result["recorded"] is True, result + assert result["history_id"], result diff --git a/python/functions/infra/hoppscotch_list_requests.md b/python/functions/infra/hoppscotch_list_requests.md new file mode 100644 index 00000000..556d51e8 --- /dev/null +++ b/python/functions/infra/hoppscotch_list_requests.md @@ -0,0 +1,78 @@ +--- +name: hoppscotch_list_requests +kind: function +lang: py +domain: infra +version: "1.0.0" +purity: impure +signature: "def hoppscotch_list_requests(collection_id: str, *, access_token: str, backend_url: str = \"http://localhost:3170\", take: int = 50) -> dict" +description: "Lista las requests de una team collection de Hoppscotch self-hosted via la query GraphQL requestsInCollection. Devuelve cada request como {id, title}. Protegida por GqlAuthGuard: el JWT de sesion (de hoppscotch_login) viaja en la cookie access_token." +tags: [hoppscotch, flow-replay, http, infra, crud] +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: [requests] +params: + - name: collection_id + desc: "ID de la team collection cuyas requests se quieren listar." + - name: access_token + desc: "JWT de sesion (de hoppscotch_login). Viaja en la cookie access_token, NO en el header Authorization." + - name: backend_url + desc: "base del backend Hoppscotch sin barra final. El endpoint GraphQL es {backend_url}/graphql. Default http://localhost:3170." + - name: take + desc: "numero maximo de requests a devolver (argumento take de la query). Default 50." +output: "dict. En exito: {status: 'ok', requests: [{id: str, title: str}, ...]}. En error (GraphQL errors, requestsInCollection null, respuesta no JSON, o fallo de transporte): {status: 'error', error: str, data: }. Nunca lanza por errores de red esperables." +tested: true +tests: + - "test_golden_lista_dos_requests" + - "test_take_se_pasa_a_la_query" + - "test_error_graphql_errors" +test_file_path: "python/functions/infra/hoppscotch_list_requests_test.py" +file_path: "python/functions/infra/hoppscotch_list_requests.py" +--- + +## Ejemplo + +```python +import sys +sys.path.insert(0, "python/functions") +from infra.hoppscotch_login import hoppscotch_login +from infra.hoppscotch_list_requests import hoppscotch_list_requests + +token = hoppscotch_login("admin@example.com")["access_token"] + +result = hoppscotch_list_requests( + collection_id="cmq8lt8ta000t0xls4ddy6sdz", + access_token=token, +) +print(result) +# {"status": "ok", "requests": [{"id": "...", "title": "Login"}, ...]} +``` + +## Cuando usarla + +Cuando necesites enumerar las requests de una team collection Hoppscotch +self-hosted: para verificar que un `hoppscotch_create_request` aparecio, para +obtener el `request_id` que pasar a `hoppscotch_update_request` / +`hoppscotch_delete_request`, o para auditar el contenido de una collection antes +de modificarla. Necesitas un `access_token` fresco de `hoppscotch_login`. + +## Gotchas + +- **El access_token va como cookie, no como header Authorization.** La query esta + protegida por GqlAuthGuard que lee el JWT de la cookie `access_token`. +- **El token expira (~24h).** Si la llamada devuelve un error de auth, re-loguea + con `hoppscotch_login`. +- **Devuelve solo {id, title}, no el HoppRESTRequest completo.** La query pide + unicamente id y title; no incluye method/url/headers/body. Para el cuerpo + completo de una request, consulta su detalle aparte. +- **`take` limita el resultado.** Solo se devuelven hasta `take` requests (default + 50). Sube `take` si la collection tiene mas. +- **Secreto — nunca logear el token en crudo.** Trata el JWT como un secreto. + +## Capability growth log + +v1.0.0 — version inicial. Validado contra el self-host vivo el 10/06/2026 +(list reflejo la creacion y la baja de una request real). diff --git a/python/functions/infra/hoppscotch_list_requests.py b/python/functions/infra/hoppscotch_list_requests.py new file mode 100644 index 00000000..2f81dcf3 --- /dev/null +++ b/python/functions/infra/hoppscotch_list_requests.py @@ -0,0 +1,79 @@ +"""Lista las requests de una team collection de Hoppscotch. + +Invoca la query GraphQL requestsInCollection del backend self-hosted. Protegida +por GqlAuthGuard: el JWT de sesion viaja en la cookie `access_token`. +""" + +import requests + +_QUERY = ( + "query($c:ID!,$t:Int){" + " requestsInCollection(collectionID:$c, take:$t){ id title } }" +) + + +def hoppscotch_list_requests( + collection_id: str, + *, + access_token: str, + backend_url: str = "http://localhost:3170", + take: int = 50, +) -> dict: + """Lista las requests de una team collection de Hoppscotch. + + Args: + collection_id: ID de la team collection a listar. + access_token: JWT de sesion (de hoppscotch_login). Viaja en la cookie + `access_token`, NO en el header Authorization. + backend_url: base del backend Hoppscotch (sin barra final). + take: numero maximo de requests a devolver (default 50). + + Returns: + Dict. En exito: ``{"status": "ok", "requests": [{"id": str, + "title": str}, ...]}``. En error (GraphQL errors, HTTP no 200, + transporte): ``{"status": "error", "error": str, "data": ...}``. + """ + payload = { + "query": _QUERY, + "variables": {"c": collection_id, "t": take}, + } + + try: + resp = requests.post( + f"{backend_url}/graphql", + json=payload, + cookies={"access_token": access_token}, + timeout=30.0, + ) + except requests.RequestException as exc: + return {"status": "error", "error": f"transport error: {exc}"} + + try: + data = resp.json() + except ValueError: + return { + "status": "error", + "error": f"non-JSON response (HTTP {resp.status_code})", + } + + if data.get("errors"): + return { + "status": "error", + "error": "graphql errors", + "data": data, + } + + rows = (data.get("data") or {}).get("requestsInCollection") + if rows is None: + return { + "status": "error", + "error": "requestsInCollection returned null", + "data": data, + } + + return { + "status": "ok", + "requests": [ + {"id": r.get("id"), "title": r.get("title")} for r in rows + ], + } diff --git a/python/functions/infra/hoppscotch_list_requests_test.py b/python/functions/infra/hoppscotch_list_requests_test.py new file mode 100644 index 00000000..78f906ef --- /dev/null +++ b/python/functions/infra/hoppscotch_list_requests_test.py @@ -0,0 +1,85 @@ +"""Tests para hoppscotch_list_requests. + +Deterministas: monkeypatchean requests.post. Verifican el camino ok (devuelve la +lista normalizada) y el de error (GraphQL errors). +""" + +import sys + +import infra.hoppscotch_list_requests # noqa: F401 + +# El __init__ rebinds el nombre a la funcion; recuperamos el submodulo real. +mod = sys.modules["infra.hoppscotch_list_requests"] + + +class _FakeResponse: + def __init__(self, status_code=200, json_data=None): + self.status_code = status_code + self._json = json_data + + def json(self): + if self._json is None: + raise ValueError("no json") + return self._json + + +def test_golden_lista_dos_requests(monkeypatch): + captured = {} + + def fake_post(url, **kwargs): + captured["url"] = url + captured["kwargs"] = kwargs + return _FakeResponse( + 200, + { + "data": { + "requestsInCollection": [ + {"id": "r1", "title": "Ping"}, + {"id": "r2", "title": "Login"}, + ] + } + }, + ) + + monkeypatch.setattr(mod.requests, "post", fake_post) + + result = mod.hoppscotch_list_requests("col-1", access_token="ACCESS-JWT") + + assert result["status"] == "ok" + assert result["requests"] == [ + {"id": "r1", "title": "Ping"}, + {"id": "r2", "title": "Login"}, + ] + assert captured["url"].endswith("/graphql") + assert captured["kwargs"]["cookies"] == {"access_token": "ACCESS-JWT"} + assert "requestsInCollection" in captured["kwargs"]["json"]["query"] + assert captured["kwargs"]["json"]["variables"] == {"c": "col-1", "t": 50} + + +def test_take_se_pasa_a_la_query(monkeypatch): + captured = {} + + def fake_post(url, **kwargs): + captured["kwargs"] = kwargs + return _FakeResponse(200, {"data": {"requestsInCollection": []}}) + + monkeypatch.setattr(mod.requests, "post", fake_post) + + result = mod.hoppscotch_list_requests("col", access_token="A", take=10) + assert result["status"] == "ok" + assert result["requests"] == [] + assert captured["kwargs"]["json"]["variables"]["t"] == 10 + + +def test_error_graphql_errors(monkeypatch): + def fake_post(url, **kwargs): + return _FakeResponse( + 200, {"errors": [{"message": "team_coll/not_found"}]} + ) + + monkeypatch.setattr(mod.requests, "post", fake_post) + + result = mod.hoppscotch_list_requests("bad", access_token="A") + assert result["status"] == "error" + assert result["error"] == "graphql errors" + assert "errors" in result["data"] diff --git a/python/functions/infra/hoppscotch_login.md b/python/functions/infra/hoppscotch_login.md new file mode 100644 index 00000000..65a779eb --- /dev/null +++ b/python/functions/infra/hoppscotch_login.md @@ -0,0 +1,94 @@ +--- +name: hoppscotch_login +kind: function +lang: py +domain: infra +version: "1.0.0" +purity: impure +signature: "def hoppscotch_login(email: str, *, backend_url: str = \"http://localhost:3170\", mailpit_url: str = \"http://localhost:8025\", timeout_s: float = 15.0) -> dict" +description: "Login headless contra un Hoppscotch self-hosted via magic link, leyendo el correo de verificacion desde una instancia Mailpit de pruebas. Reproduce el flujo sin navegador: POST /v1/auth/signin (deviceIdentifier) -> lee el correo 'Sign in' del email en Mailpit -> extrae el token (?token=...) del cuerpo -> POST /v1/auth/verify (Set-Cookie access_token + refresh_token). Devuelve los JWT de sesion que las mutations GraphQL protegidas esperan en la cookie access_token." +tags: [hoppscotch, flow-replay, http, infra, auth] +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: [re, requests] +params: + - name: email + desc: "correo del usuario que inicia sesion. Debe poder recibir el correo de verificacion en la instancia Mailpit indicada (en el self-host de pruebas, admin@example.com)." + - name: backend_url + desc: "base del backend Hoppscotch sin barra final. Los endpoints REST de auth cuelgan de {backend_url}/v1/auth/signin y /v1/auth/verify. Default http://localhost:3170." + - name: mailpit_url + desc: "base de la API de Mailpit donde aterriza el correo de verificacion, sin barra final. Default http://localhost:8025." + - name: timeout_s + desc: "timeout por request HTTP en segundos. Default 15.0." +output: "dict. En exito: {status: 'ok', access_token: str, refresh_token: str, email: str}. En error (signin != 201, no llega correo 'Sign in', token no encontrado en el correo, verify != 200, o fallo de transporte): {status: 'error', error: str}. Nunca lanza por errores de red esperables." +tested: true +tests: + - "test_golden_login_devuelve_tokens" + - "test_verify_recibe_token_extraido_y_device_identifier" + - "test_error_signin_no_201" + - "test_error_correo_no_encontrado" + - "test_error_token_no_en_correo" +test_file_path: "python/functions/infra/hoppscotch_login_test.py" +file_path: "python/functions/infra/hoppscotch_login.py" +--- + +## Ejemplo + +```python +import sys +sys.path.insert(0, "python/functions") +from infra.hoppscotch_login import hoppscotch_login +from infra.hoppscotch_create_request import hoppscotch_create_request + +# 1) Obtener un JWT de sesion via magic link (headless, lee el correo de Mailpit). +login = hoppscotch_login("admin@example.com") +assert login["status"] == "ok", login["error"] +token = login["access_token"] + +# 2) Usar el token para crear una request en una team collection. +# El self-host de referencia exige team_id dentro del input. +created = hoppscotch_create_request( + collection_id="cmq8lt8ta000t0xls4ddy6sdz", + method="GET", + url="https://api.example.com/ping", + title="Ping", + team_id="cmq8kn0v500030xls1nvminjy", + access_token=token, +) +print(created) # {"status": "ok", "id": "...", "title": "Ping"} +``` + +## Cuando usarla + +Cuando necesites un JWT de sesion de un Hoppscotch self-hosted para operar su API +GraphQL protegida (crear/editar/borrar requests, gestionar collections) sin abrir +el navegador. Es el primer paso de cualquier flujo CRUD del grupo `hoppscotch`: +llama esto, captura `access_token`, y paselo a `hoppscotch_create_request` / +`hoppscotch_update_request` / `hoppscotch_delete_request` / `hoppscotch_list_requests`. +Requiere que el backend mande el correo de verificacion a una instancia Mailpit +accesible (entorno de pruebas). + +## Gotchas + +- **El access_token va como cookie, no como header Authorization.** Las mutations + GraphQL leen el JWT de la cookie `access_token`. Cada funcion del grupo lo manda + con `cookies={"access_token": ...}`. +- **El token expira (~24h).** Cuando una llamada GraphQL devuelva un error de auth, + re-loguea con `hoppscotch_login` para obtener un access_token fresco. +- **Depende de Mailpit.** El flujo lee el correo de verificacion de una instancia + Mailpit de pruebas. No funciona contra un backend que mande el correo a un buzon + real al que esta funcion no pueda consultar por API. +- **Secreto — nunca logear el token en crudo.** `access_token`/`refresh_token` son + credenciales de sesion. No los imprimas ni los persistas en claro; trataelos como + un secreto (vault/pass) si los guardas entre ejecuciones. +- **Coincidencia del correo por subject + destinatario.** Se elige el mensaje mas + reciente cuyo destinatario sea `email` y cuyo subject contenga "Sign in". Si hay + varios magic links pendientes para el mismo email, se usa el ultimo de la lista. + +## Capability growth log + +v1.0.0 — version inicial. Flujo magic link headless validado contra el self-host +vivo (login + CRUD completo) el 10/06/2026. diff --git a/python/functions/infra/hoppscotch_login.py b/python/functions/infra/hoppscotch_login.py new file mode 100644 index 00000000..73d3a73e --- /dev/null +++ b/python/functions/infra/hoppscotch_login.py @@ -0,0 +1,179 @@ +"""Login headless contra un Hoppscotch self-hosted via magic link. + +Reproduce el flujo de magic link de Hoppscotch sin navegador, leyendo el +correo de verificacion desde una instancia Mailpit de pruebas: + + 1. POST /v1/auth/signin -> deviceIdentifier + 2. GET mailpit messages -> ultimo correo "Sign in" para ese email + 3. GET mailpit message/{id} -> extrae el token (?token=...) del cuerpo + 4. POST /v1/auth/verify -> Set-Cookie access_token + refresh_token + +Devuelve los JWT de sesion (access_token / refresh_token). El access_token es +el que las mutations GraphQL protegidas por GqlAuthGuard esperan en la cookie +`access_token` (no en el header Authorization). +""" + +import re + +import requests + +# El correo de Hoppscotch incluye un enlace con ?token=. El token es un +# JWT (3 segmentos base64url separados por puntos), asi que aceptamos letras, +# digitos, guion, guion bajo y punto. +_TOKEN_RE = re.compile(r"token=([A-Za-z0-9_\-.]+)") + + +def hoppscotch_login( + email: str, + *, + backend_url: str = "http://localhost:3170", + mailpit_url: str = "http://localhost:8025", + timeout_s: float = 15.0, +) -> dict: + """Obtiene un JWT de sesion de Hoppscotch via magic link (headless). + + Args: + email: correo del usuario que inicia sesion. Debe poder recibir el + correo de verificacion en la instancia Mailpit indicada. + backend_url: base del backend Hoppscotch (sin barra final). El endpoint + REST de auth cuelga de ``{backend_url}/v1/auth/...``. + mailpit_url: base de la API de Mailpit donde aterriza el correo de + verificacion (sin barra final). + timeout_s: timeout por request HTTP en segundos. + + Returns: + Dict. En exito: + ``{"status": "ok", "access_token": str, "refresh_token": str, + "email": str}``. En error (signin no 201, no llega correo, token no + encontrado, verify no 200, o fallo de transporte): + ``{"status": "error", "error": str}``. + """ + session = requests.Session() + + try: + # 1) Signin: pide el magic link. Respuesta 201 con deviceIdentifier. + signin = session.post( + f"{backend_url}/v1/auth/signin", + json={"email": email}, + timeout=timeout_s, + ) + if signin.status_code != 201: + return { + "status": "error", + "error": ( + f"signin returned {signin.status_code} " + f"(expected 201): {signin.text[:200]}" + ), + } + try: + device_identifier = signin.json().get("deviceIdentifier") + except ValueError: + device_identifier = None + if not device_identifier: + return { + "status": "error", + "error": "signin response missing deviceIdentifier", + } + + # 2) Localiza el correo de verificacion mas reciente para este email. + messages = session.get( + f"{mailpit_url}/api/v1/messages", + params={"limit": 5}, + timeout=timeout_s, + ) + if messages.status_code != 200: + return { + "status": "error", + "error": ( + f"mailpit messages returned {messages.status_code} " + "(expected 200)" + ), + } + try: + inbox = messages.json().get("messages") or [] + except ValueError: + return { + "status": "error", + "error": "mailpit messages response is not valid JSON", + } + + message_id = None + for msg in inbox: + recipients = msg.get("To") or [] + to_match = any( + (addr.get("Address") or "").lower() == email.lower() + for addr in recipients + ) + subject = msg.get("Subject") or "" + if to_match and "Sign in" in subject: + message_id = msg.get("ID") + break + if not message_id: + return { + "status": "error", + "error": f"no 'Sign in' email found for {email} in mailpit", + } + + # 3) Descarga el cuerpo del correo y extrae el token. + message = session.get( + f"{mailpit_url}/api/v1/message/{message_id}", + timeout=timeout_s, + ) + if message.status_code != 200: + return { + "status": "error", + "error": ( + f"mailpit message returned {message.status_code} " + "(expected 200)" + ), + } + try: + body = message.json() + except ValueError: + return { + "status": "error", + "error": "mailpit message response is not valid JSON", + } + haystack = f"{body.get('Text') or ''}\n{body.get('HTML') or ''}" + token_match = _TOKEN_RE.search(haystack) + if not token_match: + return { + "status": "error", + "error": "magic-link token not found in verification email", + } + token = token_match.group(1) + + # 4) Verify: canjea el token + deviceIdentifier por las cookies de + # sesion (access_token / refresh_token). + verify = session.post( + f"{backend_url}/v1/auth/verify", + json={"token": token, "deviceIdentifier": device_identifier}, + timeout=timeout_s, + ) + if verify.status_code != 200: + return { + "status": "error", + "error": ( + f"verify returned {verify.status_code} " + f"(expected 200): {verify.text[:200]}" + ), + } + + access_token = session.cookies.get("access_token") + refresh_token = session.cookies.get("refresh_token") + if not access_token: + return { + "status": "error", + "error": "verify succeeded but no access_token cookie was set", + } + + return { + "status": "ok", + "access_token": access_token, + "refresh_token": refresh_token, + "email": email, + } + except requests.RequestException as exc: + return {"status": "error", "error": f"transport error: {exc}"} + finally: + session.close() diff --git a/python/functions/infra/hoppscotch_login_test.py b/python/functions/infra/hoppscotch_login_test.py new file mode 100644 index 00000000..1a60d7e0 --- /dev/null +++ b/python/functions/infra/hoppscotch_login_test.py @@ -0,0 +1,216 @@ +"""Tests para hoppscotch_login. + +Deterministas: monkeypatchean requests.Session para no tocar la red. Simulan el +flujo magic link completo (signin -> mailpit list -> mailpit message -> verify) +y verifican que se devuelven los JWT, asi como los caminos de error. +""" + +import sys + +import infra.hoppscotch_login # noqa: F401 (registra el submodulo en sys.modules) + +# El __init__ del paquete rebinds el nombre `hoppscotch_login` a la funcion, +# que sombrea el submodulo. Recuperamos el submodulo real desde sys.modules +# para monkeypatchear su simbolo `requests`. +mod = sys.modules["infra.hoppscotch_login"] + + +class _FakeResponse: + """Respuesta HTTP mockeada minima: status_code, json(), text.""" + + def __init__(self, status_code=200, json_data=None, text=""): + self.status_code = status_code + self._json = json_data + self.text = text + + def json(self): + if self._json is None: + raise ValueError("no json") + return self._json + + +class _FakeCookies: + def __init__(self, store): + self._store = store + + def get(self, name): + return self._store.get(name) + + +class _FakeSession: + """Session mockeada: despacha por (method, path) a respuestas predefinidas.""" + + def __init__(self, routes, cookie_store): + self._routes = routes + self.cookies = _FakeCookies(cookie_store) + self.calls = [] + + def _dispatch(self, method, url, **kwargs): + self.calls.append((method, url, kwargs)) + for (m, fragment), resp in self._routes.items(): + if m == method and fragment in url: + return resp + raise AssertionError(f"unexpected {method} {url}") + + def post(self, url, **kwargs): + return self._dispatch("POST", url, **kwargs) + + def get(self, url, **kwargs): + return self._dispatch("GET", url, **kwargs) + + def close(self): + pass + + +def _install_session(monkeypatch, routes, cookie_store): + session = _FakeSession(routes, cookie_store) + monkeypatch.setattr(mod.requests, "Session", lambda: session) + return session + + +def test_golden_login_devuelve_tokens(monkeypatch): + routes = { + ("POST", "/v1/auth/signin"): _FakeResponse( + 201, {"deviceIdentifier": "dev-123"} + ), + ("GET", "/api/v1/messages"): _FakeResponse( + 200, + { + "messages": [ + { + "ID": "msg-1", + "Subject": "Sign in to Hoppscotch", + "To": [{"Address": "admin@example.com"}], + } + ] + }, + ), + ("GET", "/api/v1/message/msg-1"): _FakeResponse( + 200, + { + "Text": "Click here", + "HTML": ( + "Sign in" + ), + }, + ), + ("POST", "/v1/auth/verify"): _FakeResponse(200, {"ok": True}), + } + _install_session( + monkeypatch, + routes, + {"access_token": "ACCESS-JWT", "refresh_token": "REFRESH-JWT"}, + ) + + result = mod.hoppscotch_login("admin@example.com") + + assert result["status"] == "ok" + assert result["access_token"] == "ACCESS-JWT" + assert result["refresh_token"] == "REFRESH-JWT" + assert result["email"] == "admin@example.com" + + +def test_verify_recibe_token_extraido_y_device_identifier(monkeypatch): + routes = { + ("POST", "/v1/auth/signin"): _FakeResponse( + 201, {"deviceIdentifier": "dev-xyz"} + ), + ("GET", "/api/v1/messages"): _FakeResponse( + 200, + { + "messages": [ + { + "ID": "m9", + "Subject": "Sign in", + "To": [{"Address": "admin@example.com"}], + } + ] + }, + ), + ("GET", "/api/v1/message/m9"): _FakeResponse( + 200, + {"Text": "verify at ?token=abc.DEF-123_456", "HTML": ""}, + ), + ("POST", "/v1/auth/verify"): _FakeResponse(200, {}), + } + session = _install_session( + monkeypatch, routes, {"access_token": "A", "refresh_token": "R"} + ) + + result = mod.hoppscotch_login("admin@example.com") + assert result["status"] == "ok" + + # El POST a verify llevo el token extraido del correo + el deviceIdentifier. + verify_call = next( + c for c in session.calls if c[0] == "POST" and "verify" in c[1] + ) + sent = verify_call[2]["json"] + assert sent["token"] == "abc.DEF-123_456" + assert sent["deviceIdentifier"] == "dev-xyz" + + +def test_error_signin_no_201(monkeypatch): + routes = { + ("POST", "/v1/auth/signin"): _FakeResponse( + 500, None, text="boom" + ), + } + _install_session(monkeypatch, routes, {}) + + result = mod.hoppscotch_login("admin@example.com") + assert result["status"] == "error" + assert "signin returned 500" in result["error"] + + +def test_error_correo_no_encontrado(monkeypatch): + routes = { + ("POST", "/v1/auth/signin"): _FakeResponse( + 201, {"deviceIdentifier": "d"} + ), + ("GET", "/api/v1/messages"): _FakeResponse( + 200, + { + "messages": [ + { + "ID": "x", + "Subject": "Newsletter", + "To": [{"Address": "other@example.com"}], + } + ] + }, + ), + } + _install_session(monkeypatch, routes, {}) + + result = mod.hoppscotch_login("admin@example.com") + assert result["status"] == "error" + assert "no 'Sign in' email" in result["error"] + + +def test_error_token_no_en_correo(monkeypatch): + routes = { + ("POST", "/v1/auth/signin"): _FakeResponse( + 201, {"deviceIdentifier": "d"} + ), + ("GET", "/api/v1/messages"): _FakeResponse( + 200, + { + "messages": [ + { + "ID": "m", + "Subject": "Sign in", + "To": [{"Address": "admin@example.com"}], + } + ] + }, + ), + ("GET", "/api/v1/message/m"): _FakeResponse( + 200, {"Text": "no token here", "HTML": "

nada

"} + ), + } + _install_session(monkeypatch, routes, {}) + + result = mod.hoppscotch_login("admin@example.com") + assert result["status"] == "error" + assert "token not found" in result["error"] diff --git a/python/functions/infra/hoppscotch_run_request.md b/python/functions/infra/hoppscotch_run_request.md new file mode 100644 index 00000000..b6bae370 --- /dev/null +++ b/python/functions/infra/hoppscotch_run_request.md @@ -0,0 +1,118 @@ +--- +name: hoppscotch_run_request +kind: function +lang: py +domain: infra +version: "1.0.0" +purity: impure +signature: "def hoppscotch_run_request(method: str, url: str, *, title: str | None = None, headers: dict | None = None, body: str | None = None, body_type: str | None = None, variables: dict | None = None, access_token: str, backend_url: str = \"http://localhost:3170\", record_history: bool = True, timeout_s: float = 30.0, verify_tls: bool = True) -> dict" +description: "Ejecuta una peticion HTTP real (resolviendo placeholders <>/{{var}} con un dict de variables) y la registra en el UserHistory de un Hoppscotch self-hosted via la mutation GraphQL createUserHistory, para que el humano la vea aparecer en vivo en la pestana History de su GUI (subscription userHistoryCreated). La request se ejecuta con las variables resueltas, pero en el History se guarda SIN resolver (con los literales <>) igual que en el editor. resMetadata minimo: statusCode + duration. El access_token va como cookie, no como header Authorization." +tags: [hoppscotch, flow-replay, http] +uses_functions: [build_hoppscotch_collection_py_infra] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: [json, re, requests] +params: + - name: method + desc: "metodo HTTP de la peticion (GET, POST, ...)." + - name: url + desc: "endpoint de la peticion. Puede contener placeholders <> o {{var}} que se resuelven con `variables` antes de ejecutar." + - name: title + desc: "nombre visible de la request en el History. None = derivar de method + path via build_hoppscotch_collection." + - name: headers + desc: "dict name->value de cabeceras. Sus values tambien admiten placeholders <>/{{var}}." + - name: body + desc: "cuerpo de la peticion como texto ya serializado. Admite placeholders. None = sin cuerpo." + - name: body_type + desc: "tipo de cuerpo para el HoppRESTRequest del History: 'json' | 'form' | 'raw' | None." + - name: variables + desc: "dict name->value para resolver los placeholders al EJECUTAR. Una variable que falte deja el literal intacto. None = no se resuelve nada." + - name: access_token + desc: "JWT de sesion (de hoppscotch_login). Viaja en la cookie access_token, NO en el header Authorization. Necesario para registrar en el History." + - name: backend_url + desc: "base del backend Hoppscotch self-host sin barra final. La mutation cuelga de {backend_url}/graphql. Default http://localhost:3170." + - name: record_history + desc: "si True y hay access_token, registra la request ejecutada en el UserHistory via createUserHistory. Default True." + - name: timeout_s + desc: "timeout en segundos de la peticion HTTP ejecutada (y del POST de History). Default 30.0." + - name: verify_tls + desc: "verificacion del certificado TLS de la peticion ejecutada. Default True." +output: "dict. En exito de la ejecucion HTTP: {status: 'ok', status_code: int, duration_ms: int, response_body: str (truncado a 5000 chars), response_headers: dict, recorded: bool, history_id: str|None}. Si la ejecucion fue ok pero el registro de History fallo, status sigue 'ok', recorded False y se anade history_error. Si la ejecucion HTTP falla (RequestException): {status: 'error', error: str, recorded: False}. Nunca lanza por errores de red esperables." +tested: true +tests: + - "test_ejecuta_resolviendo_variables_angle" + - "test_ejecuta_resolviendo_variables_brace" + - "test_record_history_registra_request_sin_resolver" + - "test_record_history_false_no_llama_create_user_history" + - "test_request_exception_status_error" + - "test_variable_faltante_conserva_literal" +test_file_path: "python/functions/infra/hoppscotch_run_request_test.py" +file_path: "python/functions/infra/hoppscotch_run_request.py" +--- + +## Ejemplo + +```python +import sys +sys.path.insert(0, "python/functions") +from infra.hoppscotch_login import hoppscotch_login +from infra.hoppscotch_run_request import hoppscotch_run_request + +# 1) Obtener un JWT de sesion (headless, lee el correo de Mailpit). +login = hoppscotch_login("admin@example.com") +assert login["status"] == "ok", login["error"] +token = login["access_token"] + +# 2) Ejecutar una request con una variable y dejar rastro en el History de la GUI. +result = hoppscotch_run_request( + "GET", + "<>/api/status", + title="Status", + variables={"baseURL": "https://registry.organic-machine.com"}, + access_token=token, +) +print(result["status_code"], result["recorded"], result["history_id"]) +# 200 True hist-... +# -> aparece en vivo en la pestana History del Hoppscotch self-host. +``` + +## Cuando usarla + +Cuando el agente ejecuta una consulta HTTP y quiere que el humano la vea en el +History de su GUI Hoppscotch self-hosted, en vivo. La entry aparece via la +subscription `userHistoryCreated` sin que el humano refresque. Util para hacer +auditable/observable lo que el agente prueba: cada `hoppscotch_run_request` deja +en la pestana History la request (con sus variables sin resolver) y su statusCode ++ duracion. Encadena con `hoppscotch_login` para obtener el `access_token`. + +## Gotchas + +- **El access_token va como cookie, no como header Authorization.** La mutation + `createUserHistory` lee el JWT de la cookie `access_token`. Se manda con + `cookies={"access_token": ...}`. Si expira (~24h), re-loguea con + `hoppscotch_login`. +- **reqData lleva la request SIN resolver.** Lo que se guarda en el History es el + HoppRESTRequest con los placeholders `<>`/`{{var}}` literales, igual que en + el editor de la GUI, para que el humano vea la plantilla con sus variables y no + los valores expandidos. La peticion SI se ejecuta con las variables resueltas. +- **Soporta `<<>>` y `{{}}`.** Hoppscotch usa `<>`; muchas plantillas traen + `{{var}}`. Ambas sintaxis se resuelven al ejecutar. Una variable que falte en + `variables` deja el literal intacto (no rompe). +- **resMetadata minimo: statusCode + duration.** Se envia + `{"statusCode": ..., "duration": ...}`. Si una version del backend exigiera mas + campos, el registro fallaria con `history_error` (la ejecucion HTTP sigue siendo + ok). Ajustar el shape si el self-host lo pide. +- **El body de respuesta se trunca a 5000 chars** en `response_body` del output, + para no devolver payloads enormes. Los `response_headers` van completos. +- **duration_ms viene de `resp.elapsed`,** no de `time.time()`: es la latencia que + midio `requests` para la peticion ejecutada. +- **Degradacion suave del History:** si la ejecucion HTTP fue ok pero el POST de la + mutation falla (transporte, no-JSON, errores GraphQL, sin id), `status` sigue + "ok", `recorded` es False y se anade `history_error` con el detalle. + +## Capability growth log + +v1.0.0 — version inicial. Ejecucion + registro en UserHistory del self-host; +resolucion de placeholders `<<>>`/`{{}}`. diff --git a/python/functions/infra/hoppscotch_run_request.py b/python/functions/infra/hoppscotch_run_request.py new file mode 100644 index 00000000..5d04eaa4 --- /dev/null +++ b/python/functions/infra/hoppscotch_run_request.py @@ -0,0 +1,212 @@ +"""Ejecuta una peticion HTTP y la registra en el History de Hoppscotch self-host. + +Doble proposito: (1) lanza la request real con `requests` resolviendo placeholders +de variables y (2) opcionalmente la persiste en el UserHistory del backend +Hoppscotch self-hosted via la mutation GraphQL createUserHistory, de modo que el +humano la vea aparecer en vivo en la pestana History de su GUI (la GUI escucha la +subscription `userHistoryCreated`). + +La request se ejecuta con las variables resueltas, pero lo que se guarda en el +History es la request SIN resolver (con `<>`/`{{var}}` literales), igual que +en la GUI: asi el humano ve la plantilla con sus variables, no los valores +expandidos. La mutation esta protegida por GqlAuthGuard: el JWT de sesion viaja en +la cookie `access_token`. +""" + +import json +import re + +import requests + +from infra.build_hoppscotch_collection import build_hoppscotch_collection + +# Hoppscotch usa la sintaxis <>; muchas plantillas tambien traen {{var}}. +# Aceptamos ambas: grupo 1 = delimitador de apertura, grupo 2 = nombre de la +# variable, grupo 3 = delimitador de cierre. +_VAR_RE = re.compile(r"(<<|\{\{)\s*([A-Za-z0-9_]+)\s*(>>|\}\})") + +# Limite del cuerpo de respuesta en el output, para no devolver payloads enormes. +_BODY_TRUNCATE = 5000 + +_HISTORY_MUTATION = ( + "mutation($d:String!,$m:String!,$t:ReqType!){" + " createUserHistory(reqData:$d, resMetadata:$m, reqType:$t){ id } }" +) + + +def _resolve_placeholders(text: str, variables: dict) -> str: + """Sustituye <>/{{var}} por su valor en `variables`. + + Si la variable no esta en `variables`, se conserva el literal tal cual + (incluidos los delimitadores). Determinista y sin I/O. + + Args: + text: cadena con (opcionales) placeholders. + variables: dict name->value con los valores de sustitucion. + + Returns: + la cadena con los placeholders conocidos resueltos. + """ + + def repl(match: re.Match) -> str: + name = match.group(2) + if name in variables: + return str(variables[name]) + return match.group(0) + + return _VAR_RE.sub(repl, text) + + +def hoppscotch_run_request( + method: str, + url: str, + *, + title: str | None = None, + headers: dict | None = None, + body: str | None = None, + body_type: str | None = None, + variables: dict | None = None, + access_token: str, + backend_url: str = "http://localhost:3170", + record_history: bool = True, + timeout_s: float = 30.0, + verify_tls: bool = True, +) -> dict: + """Ejecuta una request HTTP y la registra en el History de Hoppscotch. + + Resuelve los placeholders `<>`/`{{var}}` de la url, los headers y el + body usando `variables`, lanza la peticion real con `requests`, y (si + `record_history`) guarda en el UserHistory del backend self-host la request + SIN resolver (para que en la GUI History se vea con las variables, igual que + en el editor). + + Args: + method: metodo HTTP (GET, POST, ...). + url: endpoint, puede contener placeholders `<>`/`{{var}}`. + title: nombre visible de la request en el History. None = derivar de + method + path via build_hoppscotch_collection. + headers: dict name->value de cabeceras. Sus values admiten placeholders. + body: cuerpo de la request como texto ya serializado. Admite placeholders. + body_type: tipo de cuerpo ("json"|"form"|"raw"|None). + variables: dict name->value para resolver los placeholders al EJECUTAR. + None = no se resuelve nada (los literales viajan tal cual). + access_token: JWT de sesion (de hoppscotch_login). Viaja en la cookie + `access_token`, NO en el header Authorization. Necesario para grabar + en el History. + backend_url: base del backend Hoppscotch self-host (sin barra final). + record_history: si True y hay access_token, registra la request en el + UserHistory via createUserHistory. + timeout_s: timeout de la peticion HTTP en segundos. + verify_tls: verificacion del certificado TLS de la request ejecutada. + + Returns: + Dict. En exito de la ejecucion HTTP: + ``{"status": "ok", "status_code": int, "duration_ms": int, + "response_body": str (truncado a 5000 chars), "response_headers": dict, + "recorded": bool, "history_id": str|None}``. Si la ejecucion fue ok pero + el registro de History fallo, `status` sigue "ok", `recorded` False y se + anade `history_error`. Si la ejecucion HTTP falla (RequestException): + ``{"status": "error", "error": str, "recorded": False}``. + """ + variables = variables or {} + headers = headers or {} + + # 1) Resolver placeholders para EJECUTAR (copia; los originales se conservan + # para registrarlos sin resolver en el History). + resolved_url = _resolve_placeholders(url, variables) + resolved_headers = { + key: _resolve_placeholders(str(value), variables) + for key, value in headers.items() + } + resolved_body = ( + _resolve_placeholders(body, variables) if body is not None else None + ) + + # 2) Ejecutar la peticion real. + try: + resp = requests.request( + method, + resolved_url, + headers=resolved_headers, + data=resolved_body if resolved_body is not None else None, + timeout=timeout_s, + verify=verify_tls, + ) + except requests.RequestException as exc: + return { + "status": "error", + "error": f"transport error: {exc}", + "recorded": False, + } + + duration_ms = int(resp.elapsed.total_seconds() * 1000) + status_code = resp.status_code + response_body = resp.text[:_BODY_TRUNCATE] + response_headers = dict(resp.headers) + + result = { + "status": "ok", + "status_code": status_code, + "duration_ms": duration_ms, + "response_body": response_body, + "response_headers": response_headers, + "recorded": False, + "history_id": None, + } + + # 3) Registrar en el UserHistory (request SIN resolver, como en la GUI). + if not record_history or not access_token: + return result + + spec = { + "method": method, + "url": url, + "headers": headers, + "body": body, + "body_type": body_type, + } + req_names = [title] if title else None + req_item = build_hoppscotch_collection([spec], request_names=req_names)[ + "requests" + ][0] + req_data = json.dumps(req_item) + res_metadata = json.dumps( + {"statusCode": status_code, "duration": duration_ms} + ) + + payload = { + "query": _HISTORY_MUTATION, + "variables": {"d": req_data, "m": res_metadata, "t": "REST"}, + } + + try: + hist_resp = requests.post( + f"{backend_url}/graphql", + json=payload, + cookies={"access_token": access_token}, + timeout=timeout_s, + ) + except requests.RequestException as exc: + result["history_error"] = f"transport error: {exc}" + return result + + try: + hist_data = hist_resp.json() + except ValueError: + result["history_error"] = ( + f"non-JSON history response (HTTP {hist_resp.status_code})" + ) + return result + + if hist_data.get("errors"): + result["history_error"] = f"graphql errors: {hist_data['errors']}" + return result + + created = (hist_data.get("data") or {}).get("createUserHistory") + if not created or not created.get("id"): + result["history_error"] = "createUserHistory returned no id" + return result + + result["recorded"] = True + result["history_id"] = created["id"] + return result diff --git a/python/functions/infra/hoppscotch_run_request_test.py b/python/functions/infra/hoppscotch_run_request_test.py new file mode 100644 index 00000000..86739919 --- /dev/null +++ b/python/functions/infra/hoppscotch_run_request_test.py @@ -0,0 +1,206 @@ +"""Tests para hoppscotch_run_request. + +Deterministas: monkeypatchean requests.request (ejecucion HTTP) y requests.post +(mutation createUserHistory). Verifican la resolucion de placedores `<<>>`/`{{}}` +para EJECUTAR, que el History recibe la request SIN resolver, y los caminos de +record_history=False y de error de transporte. +""" + +import json +import sys +from datetime import timedelta + +import infra.hoppscotch_run_request # noqa: F401 + +# El __init__ rebinds el nombre a la funcion; recuperamos el submodulo real. +mod = sys.modules["infra.hoppscotch_run_request"] + + +class _FakeResponse: + """Respuesta minima para requests.request (ejecucion).""" + + def __init__(self, status_code=200, text="OK", headers=None, elapsed_ms=12): + self.status_code = status_code + self.text = text + self.headers = headers or {"Content-Type": "text/plain"} + self.elapsed = timedelta(milliseconds=elapsed_ms) + + +class _FakeGraphQLResponse: + """Respuesta minima para requests.post (createUserHistory).""" + + def __init__(self, status_code=200, json_data=None): + self.status_code = status_code + self._json = json_data + + def json(self): + if self._json is None: + raise ValueError("no json") + return self._json + + +def _patch_history_ok(monkeypatch, captured): + def fake_post(url, **kwargs): + captured["history_url"] = url + captured["history_kwargs"] = kwargs + return _FakeGraphQLResponse( + 200, {"data": {"createUserHistory": {"id": "hist-42"}}} + ) + + monkeypatch.setattr(mod.requests, "post", fake_post) + + +def test_ejecuta_resolviendo_variables_angle(monkeypatch): + captured = {} + + def fake_request(method, url, **kwargs): + captured["method"] = method + captured["url"] = url + captured["kwargs"] = kwargs + return _FakeResponse(200, text="pong") + + monkeypatch.setattr(mod.requests, "request", fake_request) + _patch_history_ok(monkeypatch, captured) + + result = mod.hoppscotch_run_request( + "GET", + "<>/x", + variables={"baseURL": "https://h"}, + access_token="A", + ) + + # La request ejecutada lleva la url resuelta. + assert captured["url"] == "https://h/x" + assert result["status"] == "ok" + assert result["status_code"] == 200 + assert result["response_body"] == "pong" + assert result["duration_ms"] == 12 + + +def test_ejecuta_resolviendo_variables_brace(monkeypatch): + captured = {} + + def fake_request(method, url, **kwargs): + captured["url"] = url + return _FakeResponse(200) + + monkeypatch.setattr(mod.requests, "request", fake_request) + _patch_history_ok(monkeypatch, captured) + + mod.hoppscotch_run_request( + "GET", + "{{baseURL}}/x", + variables={"baseURL": "https://h"}, + access_token="A", + ) + + # {{var}} resuelve igual que <>. + assert captured["url"] == "https://h/x" + + +def test_record_history_registra_request_sin_resolver(monkeypatch): + captured = {} + + def fake_request(method, url, **kwargs): + return _FakeResponse(200, text="body", headers={"X-Test": "1"}) + + monkeypatch.setattr(mod.requests, "request", fake_request) + _patch_history_ok(monkeypatch, captured) + + result = mod.hoppscotch_run_request( + "GET", + "<>/api/status", + title="Status", + variables={"baseURL": "https://h"}, + access_token="ACCESS-JWT", + record_history=True, + ) + + assert result["recorded"] is True + assert result["history_id"] == "hist-42" + + # El POST de History fue al endpoint GraphQL con la cookie access_token. + assert captured["history_url"].endswith("/graphql") + assert captured["history_kwargs"]["cookies"] == {"access_token": "ACCESS-JWT"} + + payload = captured["history_kwargs"]["json"] + assert "createUserHistory" in payload["query"] + variables = payload["variables"] + assert variables["t"] == "REST" + + # reqData es el json string de un HoppRESTRequest v:"2" con la url SIN resolver. + req = json.loads(variables["d"]) + assert req["v"] == "2" + assert req["method"] == "GET" + assert req["endpoint"] == "<>/api/status" + assert req["name"] == "Status" + + # resMetadata minimo: statusCode + duration. + res_meta = json.loads(variables["m"]) + assert res_meta == {"statusCode": 200, "duration": 12} + + +def test_record_history_false_no_llama_create_user_history(monkeypatch): + calls = {"post": 0} + + def fake_request(method, url, **kwargs): + return _FakeResponse(200) + + def fake_post(url, **kwargs): + calls["post"] += 1 + return _FakeGraphQLResponse(200, {"data": {"createUserHistory": {"id": "x"}}}) + + monkeypatch.setattr(mod.requests, "request", fake_request) + monkeypatch.setattr(mod.requests, "post", fake_post) + + result = mod.hoppscotch_run_request( + "GET", + "https://h/x", + access_token="A", + record_history=False, + ) + + assert result["recorded"] is False + assert result["history_id"] is None + assert calls["post"] == 0 + + +def test_request_exception_status_error(monkeypatch): + def fake_request(method, url, **kwargs): + raise mod.requests.RequestException("boom") + + # Si llegara a postear seria un fallo del test: no debe. + def fake_post(url, **kwargs): + raise AssertionError("no debe registrar history si la ejecucion fallo") + + monkeypatch.setattr(mod.requests, "request", fake_request) + monkeypatch.setattr(mod.requests, "post", fake_post) + + result = mod.hoppscotch_run_request( + "GET", "https://h/x", access_token="A" + ) + + assert result["status"] == "error" + assert result["recorded"] is False + assert "boom" in result["error"] + + +def test_variable_faltante_conserva_literal(monkeypatch): + captured = {} + + def fake_request(method, url, **kwargs): + captured["url"] = url + return _FakeResponse(200) + + monkeypatch.setattr(mod.requests, "request", fake_request) + _patch_history_ok(monkeypatch, captured) + + mod.hoppscotch_run_request( + "GET", + "<>/x", + variables={"otra": "y"}, + access_token="A", + ) + + # baseURL no esta en variables -> el literal se conserva. + assert captured["url"] == "<>/x" diff --git a/python/functions/infra/hoppscotch_set_environment.md b/python/functions/infra/hoppscotch_set_environment.md new file mode 100644 index 00000000..b1ab4ae5 --- /dev/null +++ b/python/functions/infra/hoppscotch_set_environment.md @@ -0,0 +1,99 @@ +--- +name: hoppscotch_set_environment +kind: function +lang: py +domain: infra +version: "1.0.0" +purity: impure +signature: "def hoppscotch_set_environment(team_id: str, name: str, variables: list[dict], *, access_token: str, backend_url: str = \"http://localhost:3170\") -> dict" +description: "Crea o actualiza (idempotente por nombre) un Team Environment de Hoppscotch self-hosted via GraphQL, resolviendo secretos desde pass. Lista los environments de la team y, si ya existe uno con ese name, llama updateTeamEnvironment; si no, createTeamEnvironment. Cualquier variable cuyo value empiece por 'pass:' se resuelve con pass_get_secret y se fuerza secret=True. Los valores secretos nunca se logean ni aparecen en el output: resolved_secrets lista solo los keys. Las mutations estan protegidas por GqlAuthGuard: el JWT de sesion (de hoppscotch_login) viaja en la cookie access_token." +tags: [hoppscotch, flow-replay, http, secret, infra] +uses_functions: [pass_get_secret_py_infra] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: [json, requests] +params: + - name: team_id + desc: "ID de la team duena del environment." + - name: name + desc: "nombre del environment. La idempotencia es por este nombre dentro de la team: si ya existe uno con este name se actualiza, si no se crea." + - name: variables + desc: "lista de dicts {key: str, value: str, secret: bool}. Si un value empieza por 'pass:' el resto se resuelve como ruta de pass con pass_get_secret y el secreto resuelto se usa como value real, forzando secret=True. Campos secret ausentes se tratan como False." + - name: access_token + desc: "JWT de sesion (de hoppscotch_login). Viaja en la cookie access_token, NO en el header Authorization." + - name: backend_url + desc: "base del backend Hoppscotch sin barra final. El endpoint GraphQL es {backend_url}/graphql. Default http://localhost:3170." +output: "dict. En exito: {status: 'ok', id: str, name: str, action: 'created'|'updated', resolved_secrets: list[str]} donde resolved_secrets son SOLO los keys resueltos desde pass (nunca valores). En error: {status: 'error', error: str} (resolucion pass fallida con el key afectado, GraphQL errors, HTTP no JSON, o fallo de transporte). Si una variable pass: no se resuelve, NO se crea/actualiza el environment." +tested: true +tests: + - "test_crea_cuando_no_existe" + - "test_actualiza_cuando_existe" + - "test_resuelve_secreto_desde_pass" + - "test_error_pass_no_llama_mutation" +test_file_path: "python/functions/infra/hoppscotch_set_environment_test.py" +file_path: "python/functions/infra/hoppscotch_set_environment.py" +--- + +## Ejemplo + +```python +import sys +sys.path.insert(0, "python/functions") +from infra.hoppscotch_login import hoppscotch_login +from infra.hoppscotch_set_environment import hoppscotch_set_environment + +token = hoppscotch_login("admin@example.com")["access_token"] + +# Una variable normal + una resuelta desde pass (se marca secret=True sola). +result = hoppscotch_set_environment( + team_id="cmq8kn0v500030xls1nvminjy", + name="registry", + variables=[ + {"key": "base_url", "value": "https://api.example.com", "secret": False}, + {"key": "api_key", "value": "pass:apis/licenseplatedata"}, + ], + access_token=token, +) +print(result) +# {"status": "ok", "id": "...", "name": "registry", +# "action": "updated", "resolved_secrets": ["api_key"]} +# El valor crudo de api_key NUNCA aparece en el output. +``` + +## Cuando usarla + +Cuando quieras definir o actualizar las variables de un workspace (team +environment) Hoppscotch self-hosted desde el registry, con los secretos +resueltos desde `pass` en vez de hardcodearlos. Util en el patron grabar-> +destilar->reproducir: tras destilar un flujo, dejas sus tokens/credenciales como +variables `pass:` de un environment que el humano ve en la GUI, sin que el +secreto pase por el codigo. Idempotente por nombre: vuelve a llamarla para +actualizar sin duplicar. Primero obten el `access_token` con `hoppscotch_login`. + +## Gotchas + +- **Idempotente por nombre.** Busca un environment con ese `name` en la team: si + existe lo actualiza, si no lo crea. Dos teams pueden tener environments con el + mismo nombre sin colisionar (la busqueda es por team). +- **`pass:` resuelve de pass y fuerza `secret=True`.** Si el `value` empieza por + `pass:`, el resto es la ruta de pass; el secreto resuelto reemplaza al value y + la variable queda marcada como secreta aunque pasaras `secret=False`. +- **Nunca logea secretos.** Ni en stdout ni en el output: `resolved_secrets` + contiene solo los KEYS resueltos desde pass, jamas los valores. El valor crudo + no aparece en el dict de retorno. +- **Falla en pass = no se toca el environment.** Si una variable `pass:` no se + puede resolver, la funcion aborta con `{"status": "error"}` y el key afectado + ANTES de cualquier mutation: no deja el environment a medias. +- **El access_token va como cookie, no como header Authorization.** Las mutations + estan protegidas por GqlAuthGuard que lee el JWT de la cookie `access_token`. +- **El secreto viaja en claro al backend self-host local por GraphQL.** Hoppscotch + recibe el valor resuelto en el campo `variables`. Es aceptable porque el backend + de referencia es local; no apuntes esta funcion a un Hoppscotch remoto sin TLS. + +## Capability growth log + +v1.0.0 — version inicial. Listado + create + update validados contra el self-host +vivo el 11/06/2026 (createTeamEnvironment / updateTeamEnvironment / listado via +team{ teamEnvironments }). Resolucion `pass:` via pass_get_secret_py_infra. diff --git a/python/functions/infra/hoppscotch_set_environment.py b/python/functions/infra/hoppscotch_set_environment.py new file mode 100644 index 00000000..fe9d0cfe --- /dev/null +++ b/python/functions/infra/hoppscotch_set_environment.py @@ -0,0 +1,175 @@ +"""Crea o actualiza (idempotente por nombre) un Team Environment de Hoppscotch. + +Define las variables de un workspace Hoppscotch self-hosted via GraphQL, +resolviendo secretos desde `pass`: cualquier variable cuyo `value` empiece por +``pass:`` se resuelve con pass_get_secret y se marca como `secret=True`. + +Idempotencia por nombre: lista los environments de la team y, si ya existe uno +con el `name` dado, lo actualiza; si no, lo crea. Las mutations estan protegidas +por GqlAuthGuard: el JWT de sesion (de hoppscotch_login) viaja en la cookie +`access_token`. + +Los valores secretos NUNCA se logean ni aparecen en el output: `resolved_secrets` +lista solo los KEYS resueltos desde pass, jamas sus valores. +""" + +import json + +import requests + +from infra.pass_get_secret import pass_get_secret + +_LIST_QUERY = "query($t:ID!){ team(teamID:$t){ teamEnvironments{ id name } } }" +_CREATE_MUTATION = ( + "mutation($n:String!,$t:ID!,$v:String!){" + " createTeamEnvironment(name:$n,teamID:$t,variables:$v){ id name } }" +) +_UPDATE_MUTATION = ( + "mutation($id:ID!,$n:String!,$v:String!){" + " updateTeamEnvironment(id:$id,name:$n,variables:$v){ id name } }" +) + +_PASS_PREFIX = "pass:" + + +def hoppscotch_set_environment( + team_id: str, + name: str, + variables: list[dict], + *, + access_token: str, + backend_url: str = "http://localhost:3170", +) -> dict: + """Crea o actualiza un Team Environment de Hoppscotch (idempotente por nombre). + + Args: + team_id: ID de la team duena del environment. + name: nombre del environment. La idempotencia es por este nombre dentro + de la team: si ya existe uno con este name se actualiza, si no se crea. + variables: lista de dicts ``{"key": str, "value": str, "secret": bool}``. + Si un `value` empieza por ``pass:`` el resto se resuelve como ruta de + pass con pass_get_secret y el secreto resuelto se usa como value real, + forzando `secret=True` en esa variable. Campos `secret` ausentes se + tratan como False. + access_token: JWT de sesion (de hoppscotch_login). Viaja en la cookie + `access_token`, NO en el header Authorization. + backend_url: base del backend Hoppscotch sin barra final. El endpoint + GraphQL es ``{backend_url}/graphql``. + + Returns: + Dict. En exito: ``{"status": "ok", "id": str, "name": str, + "action": "created"|"updated", "resolved_secrets": list[str]}`` donde + `resolved_secrets` son SOLO los keys resueltos desde pass (nunca valores). + En error: ``{"status": "error", "error": str}`` (resolucion pass fallida, + GraphQL errors, HTTP no 200, o fallo de transporte). Si una variable + `pass:` no se puede resolver, NO se crea/actualiza el environment. + """ + resolved: list[dict] = [] + resolved_secrets: list[str] = [] + + for var in variables: + key = var.get("key") + value = var.get("value", "") + secret = bool(var.get("secret", False)) + + if isinstance(value, str) and value.startswith(_PASS_PREFIX): + pass_path = value[len(_PASS_PREFIX):] + secret_res = pass_get_secret(pass_path) + if secret_res.get("status") != "ok": + # NO crear el env a medias: aborta con el key afectado. + return { + "status": "error", + "error": ( + f"pass resolution failed for key {key!r} " + f"(path {pass_path!r}): {secret_res.get('error')}" + ), + } + value = secret_res["value"] + secret = True + resolved_secrets.append(key) + + resolved.append({"key": key, "value": value, "secret": secret}) + + variables_json = json.dumps(resolved) + + # 1) Localiza un environment existente con este nombre (idempotencia). + try: + list_resp = requests.post( + f"{backend_url}/graphql", + json={"query": _LIST_QUERY, "variables": {"t": team_id}}, + cookies={"access_token": access_token}, + timeout=30.0, + ) + except requests.RequestException as exc: + return {"status": "error", "error": f"transport error: {exc}"} + + list_data = _parse_json(list_resp) + if list_data is None: + return { + "status": "error", + "error": f"non-JSON list response (HTTP {list_resp.status_code})", + } + if list_data.get("errors"): + return {"status": "error", "error": "graphql errors", "data": list_data} + + team = (list_data.get("data") or {}).get("team") or {} + existing_id = None + for env in team.get("teamEnvironments") or []: + if env.get("name") == name: + existing_id = env.get("id") + break + + # 2) Update si existe, create si no. + if existing_id: + query = _UPDATE_MUTATION + gql_vars = {"id": existing_id, "n": name, "v": variables_json} + result_field = "updateTeamEnvironment" + action = "updated" + else: + query = _CREATE_MUTATION + gql_vars = {"n": name, "t": team_id, "v": variables_json} + result_field = "createTeamEnvironment" + action = "created" + + try: + resp = requests.post( + f"{backend_url}/graphql", + json={"query": query, "variables": gql_vars}, + cookies={"access_token": access_token}, + timeout=30.0, + ) + except requests.RequestException as exc: + return {"status": "error", "error": f"transport error: {exc}"} + + data = _parse_json(resp) + if data is None: + return { + "status": "error", + "error": f"non-JSON response (HTTP {resp.status_code})", + } + if data.get("errors"): + return {"status": "error", "error": "graphql errors", "data": data} + + env = (data.get("data") or {}).get(result_field) + if not env or not env.get("id"): + return { + "status": "error", + "error": f"{result_field} returned no id", + "data": data, + } + + return { + "status": "ok", + "id": env["id"], + "name": env.get("name", name), + "action": action, + "resolved_secrets": resolved_secrets, + } + + +def _parse_json(resp): + """Devuelve el JSON de la respuesta o None si no es JSON valido.""" + try: + return resp.json() + except ValueError: + return None diff --git a/python/functions/infra/hoppscotch_set_environment_test.py b/python/functions/infra/hoppscotch_set_environment_test.py new file mode 100644 index 00000000..6fc4fc35 --- /dev/null +++ b/python/functions/infra/hoppscotch_set_environment_test.py @@ -0,0 +1,226 @@ +"""Tests para hoppscotch_set_environment. + +Deterministas: monkeypatchean requests.post (capa de red) y pass_get_secret. +Verifican crear vs actualizar (idempotencia por nombre), resolucion de secretos +`pass:` (fuerza secret=True, key en resolved_secrets, valor crudo fuera del +output), y abortar sin llamar la mutation si pass falla. + +Hay un test e2e real marcado skip por defecto (self-host vivo). +""" + +import json +import sys + +import pytest + +import infra.hoppscotch_set_environment # noqa: F401 + +# El __init__ rebinds el nombre a la funcion; recuperamos el submodulo real. +mod = sys.modules["infra.hoppscotch_set_environment"] + + +class _FakeResponse: + def __init__(self, status_code=200, json_data=None): + self.status_code = status_code + self._json = json_data + + def json(self): + if self._json is None: + raise ValueError("no json") + return self._json + + +def _make_post(call_log, list_envs, mutation_result): + """Construye un fake requests.post que distingue listado de mutation. + + El listado lleva 'teamEnvironments' en la query; cualquier otra es mutation. + Cada llamada se registra en call_log para inspeccion. + """ + + def fake_post(url, **kwargs): + payload = kwargs["json"] + query = payload["query"] + call_log.append({"url": url, "kwargs": kwargs, "query": query}) + if "teamEnvironments" in query: + return _FakeResponse( + 200, {"data": {"team": {"teamEnvironments": list_envs}}} + ) + # mutation (create o update) + field = ( + "updateTeamEnvironment" + if "updateTeamEnvironment" in query + else "createTeamEnvironment" + ) + return _FakeResponse(200, {"data": {field: mutation_result}}) + + return fake_post + + +def test_crea_cuando_no_existe(monkeypatch): + calls = [] + monkeypatch.setattr( + mod.requests, + "post", + _make_post(calls, list_envs=[], mutation_result={"id": "env-1", "name": "test_env"}), + ) + + result = mod.hoppscotch_set_environment( + "team-1", + "test_env", + [{"key": "foo", "value": "bar", "secret": False}], + access_token="ACCESS-JWT", + ) + + assert result["status"] == "ok" + assert result["id"] == "env-1" + assert result["action"] == "created" + assert result["resolved_secrets"] == [] + + # Segunda llamada = mutation createTeamEnvironment con las variables. + mutation = calls[1] + assert "createTeamEnvironment" in mutation["query"] + assert mutation["kwargs"]["cookies"] == {"access_token": "ACCESS-JWT"} + gql_vars = mutation["kwargs"]["json"]["variables"] + assert gql_vars["n"] == "test_env" + assert gql_vars["t"] == "team-1" + sent_vars = json.loads(gql_vars["v"]) + assert sent_vars == [{"key": "foo", "value": "bar", "secret": False}] + + +def test_actualiza_cuando_existe(monkeypatch): + calls = [] + monkeypatch.setattr( + mod.requests, + "post", + _make_post( + calls, + list_envs=[{"id": "env-existing", "name": "test_env"}], + mutation_result={"id": "env-existing", "name": "test_env"}, + ), + ) + + result = mod.hoppscotch_set_environment( + "team-1", + "test_env", + [{"key": "foo", "value": "bar"}], + access_token="A", + ) + + assert result["status"] == "ok" + assert result["id"] == "env-existing" + assert result["action"] == "updated" + + mutation = calls[1] + assert "updateTeamEnvironment" in mutation["query"] + gql_vars = mutation["kwargs"]["json"]["variables"] + assert gql_vars["id"] == "env-existing" + + +def test_resuelve_secreto_desde_pass(monkeypatch): + calls = [] + monkeypatch.setattr( + mod.requests, + "post", + _make_post(calls, list_envs=[], mutation_result={"id": "env-2", "name": "e"}), + ) + + def fake_pass(path, **kwargs): + assert path == "apis/lpd" + return {"status": "ok", "value": "TOP-SECRET-VALUE"} + + monkeypatch.setattr(mod, "pass_get_secret", fake_pass) + + result = mod.hoppscotch_set_environment( + "team-1", + "e", + [ + {"key": "plain", "value": "visible", "secret": False}, + {"key": "apikey", "value": "pass:apis/lpd", "secret": False}, + ], + access_token="A", + ) + + assert result["status"] == "ok" + # El key resuelto aparece, pero NUNCA el valor crudo. + assert result["resolved_secrets"] == ["apikey"] + assert "TOP-SECRET-VALUE" not in json.dumps(result) + + # La variable resuelta viaja con el valor real y secret=True forzado. + mutation = calls[1] + sent_vars = json.loads(mutation["kwargs"]["json"]["variables"]["v"]) + by_key = {v["key"]: v for v in sent_vars} + assert by_key["apikey"]["value"] == "TOP-SECRET-VALUE" + assert by_key["apikey"]["secret"] is True + assert by_key["plain"]["value"] == "visible" + assert by_key["plain"]["secret"] is False + + +def test_error_pass_no_llama_mutation(monkeypatch): + calls = [] + + def fake_post(url, **kwargs): + calls.append(kwargs["json"]["query"]) + return _FakeResponse(200, {"data": {"team": {"teamEnvironments": []}}}) + + monkeypatch.setattr(mod.requests, "post", fake_post) + + def fake_pass(path, **kwargs): + return {"status": "error", "error": "pass not installed"} + + monkeypatch.setattr(mod, "pass_get_secret", fake_pass) + + result = mod.hoppscotch_set_environment( + "team-1", + "e", + [{"key": "apikey", "value": "pass:apis/lpd"}], + access_token="A", + ) + + assert result["status"] == "error" + assert "apikey" in result["error"] + # No se hizo ninguna llamada de red (ni listado ni mutation): aborta antes. + assert calls == [] + + +@pytest.mark.skip(reason="e2e real contra self-host vivo") +def test_e2e_create_then_update_live(): + """End-to-end real contra el Hoppscotch self-host vivo. + + login -> set_environment("test_env") -> created -> set_environment de nuevo + -> updated. Limpia el env al final con deleteTeamEnvironment. + """ + sys.path.insert(0, "python/functions") + from infra.hoppscotch_login import hoppscotch_login + import requests + + team_id = "cmq8kn0v500030xls1nvminjy" + token = hoppscotch_login("admin@example.com")["access_token"] + + first = mod.hoppscotch_set_environment( + team_id, + "test_env", + [{"key": "foo", "value": "bar", "secret": False}], + access_token=token, + ) + assert first["status"] == "ok" + assert first["action"] == "created" + env_id = first["id"] + + second = mod.hoppscotch_set_environment( + team_id, + "test_env", + [{"key": "foo", "value": "baz", "secret": False}], + access_token=token, + ) + assert second["status"] == "ok" + assert second["action"] == "updated" + assert second["id"] == env_id + + # Cleanup: borra el env de prueba. + del_q = "mutation($id:ID!){ deleteTeamEnvironment(id:$id) }" + requests.post( + "http://localhost:3170/graphql", + json={"query": del_q, "variables": {"id": env_id}}, + cookies={"access_token": token}, + timeout=15.0, + ) diff --git a/python/functions/infra/hoppscotch_update_request.md b/python/functions/infra/hoppscotch_update_request.md new file mode 100644 index 00000000..b0fa6947 --- /dev/null +++ b/python/functions/infra/hoppscotch_update_request.md @@ -0,0 +1,92 @@ +--- +name: hoppscotch_update_request +kind: function +lang: py +domain: infra +version: "1.0.0" +purity: impure +signature: "def hoppscotch_update_request(request_id: str, method: str, url: str, *, title: str | None = None, headers: dict | None = None, body: str | None = None, body_type: str | None = None, access_token: str, backend_url: str = \"http://localhost:3170\") -> dict" +description: "Actualiza una request REST existente en Hoppscotch self-hosted via la mutation GraphQL updateRequest. Reconstruye el HoppRESTRequest canonico reusando build_hoppscotch_collection del registry y lo aplica sobre la request identificada por request_id. Protegida por GqlAuthGuard: el JWT de sesion (de hoppscotch_login) viaja en la cookie access_token." +tags: [hoppscotch, flow-replay, http, infra, crud] +uses_functions: [build_hoppscotch_collection_py_infra] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: [json, requests] +params: + - name: request_id + desc: "ID de la request existente a actualizar." + - name: method + desc: "metodo HTTP de la request (GET, POST, ...). Se normaliza a mayusculas." + - name: url + desc: "endpoint completo de la request (con query string si aplica)." + - name: title + desc: "nuevo nombre visible de la request. None = derivar de method + path." + - name: headers + desc: "dict name->value de cabeceras de la request. None = sin cabeceras." + - name: body + desc: "cuerpo de la request como texto YA serializado. None = sin cuerpo." + - name: body_type + desc: "tipo de cuerpo: 'json' | 'form' | 'raw' | None." + - name: access_token + desc: "JWT de sesion (de hoppscotch_login). Viaja en la cookie access_token, NO en el header Authorization." + - name: backend_url + desc: "base del backend Hoppscotch sin barra final. El endpoint GraphQL es {backend_url}/graphql. Default http://localhost:3170." +output: "dict. En exito: {status: 'ok', id: str, title: str}. En error (GraphQL errors, respuesta no JSON, sin id, o fallo de transporte): {status: 'error', error: str, data: }. Nunca lanza por errores de red esperables." +tested: true +tests: + - "test_golden_actualiza_request_y_devuelve_id" + - "test_error_graphql_errors" +test_file_path: "python/functions/infra/hoppscotch_update_request_test.py" +file_path: "python/functions/infra/hoppscotch_update_request.py" +--- + +## Ejemplo + +```python +import sys +sys.path.insert(0, "python/functions") +from infra.hoppscotch_login import hoppscotch_login +from infra.hoppscotch_update_request import hoppscotch_update_request + +token = hoppscotch_login("admin@example.com")["access_token"] + +# Actualizar una request existente: cambiar metodo, url, titulo y body. +result = hoppscotch_update_request( + request_id="cmq8lue8l000x0xlsd62bncpi", + method="POST", + url="https://api.example.com/login", + title="Login (actualizado)", + body='{"user":"neo"}', + body_type="json", + access_token=token, +) +print(result) # {"status": "ok", "id": "...", "title": "Login (actualizado)"} +``` + +## Cuando usarla + +Cuando una request ya existe en una team collection y quieres reescribir su +contenido (metodo, url, cabeceras, body o titulo) desde el agente, para que el +humano vea el cambio reflejado en vivo en la GUI por subscriptions. Necesitas el +`request_id` (de `hoppscotch_list_requests` o de un `hoppscotch_create_request` +previo) y un `access_token` fresco de `hoppscotch_login`. + +## Gotchas + +- **El access_token va como cookie, no como header Authorization.** La mutation + esta protegida por GqlAuthGuard que lee el JWT de la cookie `access_token`. +- **El token expira (~24h).** Si la llamada devuelve un error de auth, re-loguea + con `hoppscotch_login`. +- **`request` debe ser un json string de un HoppRESTRequest v:"2".** El campo + `request` del input es un string; esta funcion lo serializa con `json.dumps`. +- **Reescribe la request entera, no hace patch.** El HoppRESTRequest enviado + reemplaza el contenido: pasa todos los campos que quieras conservar, no solo los + que cambian. +- **Secreto — nunca logear el token en crudo.** Trata el JWT como un secreto. + +## Capability growth log + +v1.0.0 — version inicial. Validado contra el self-host vivo el 10/06/2026 +(create -> update -> list confirmo el titulo actualizado). diff --git a/python/functions/infra/hoppscotch_update_request.py b/python/functions/infra/hoppscotch_update_request.py new file mode 100644 index 00000000..c374c296 --- /dev/null +++ b/python/functions/infra/hoppscotch_update_request.py @@ -0,0 +1,113 @@ +"""Actualiza una request REST existente en Hoppscotch. + +Reconstruye el HoppRESTRequest canonico (reusando build_hoppscotch_collection +del registry) y lo aplica sobre una request existente via la mutation GraphQL +updateRequest del backend self-hosted. Protegida por GqlAuthGuard: el JWT de +sesion viaja en la cookie `access_token`. +""" + +import json + +import requests + +from infra.build_hoppscotch_collection import build_hoppscotch_collection + +_MUTATION = ( + "mutation($r:ID!,$d:UpdateTeamRequestInput!){" + " updateRequest(requestID:$r, data:$d){ id title } }" +) + + +def hoppscotch_update_request( + request_id: str, + method: str, + url: str, + *, + title: str | None = None, + headers: dict | None = None, + body: str | None = None, + body_type: str | None = None, + access_token: str, + backend_url: str = "http://localhost:3170", +) -> dict: + """Actualiza una request existente en Hoppscotch. + + Args: + request_id: ID de la request a actualizar. + method: metodo HTTP de la request (GET, POST, ...). + url: endpoint de la request. + title: nombre visible de la request en la GUI. None = derivar de + method + path via build_hoppscotch_collection. + headers: dict name->value de cabeceras de la request. + body: cuerpo de la request como texto ya serializado. + body_type: tipo de cuerpo ("json"|"form"|"raw"|None). + access_token: JWT de sesion (de hoppscotch_login). Viaja en la cookie + `access_token`, NO en el header Authorization. + backend_url: base del backend Hoppscotch (sin barra final). + + Returns: + Dict. En exito: ``{"status": "ok", "id": str, "title": str}``. En error + (GraphQL errors, HTTP no 200, transporte): ``{"status": "error", + "error": str, "data": ...}`` con el cuerpo GraphQL si lo hubo. + """ + spec = { + "method": method, + "url": url, + "headers": headers or {}, + "body": body, + "body_type": body_type, + } + req_names = [title] if title else None + req_item = build_hoppscotch_collection([spec], request_names=req_names)[ + "requests" + ][0] + + payload = { + "query": _MUTATION, + "variables": { + "r": request_id, + "d": { + "title": req_item["name"], + "request": json.dumps(req_item), + }, + }, + } + + try: + resp = requests.post( + f"{backend_url}/graphql", + json=payload, + cookies={"access_token": access_token}, + timeout=30.0, + ) + except requests.RequestException as exc: + return {"status": "error", "error": f"transport error: {exc}"} + + try: + data = resp.json() + except ValueError: + return { + "status": "error", + "error": f"non-JSON response (HTTP {resp.status_code})", + } + + if data.get("errors"): + return { + "status": "error", + "error": "graphql errors", + "data": data, + } + + updated = (data.get("data") or {}).get("updateRequest") + if not updated or not updated.get("id"): + return { + "status": "error", + "error": "updateRequest returned no id", + "data": data, + } + + return { + "status": "ok", + "id": updated["id"], + "title": updated.get("title"), + } diff --git a/python/functions/infra/hoppscotch_update_request_test.py b/python/functions/infra/hoppscotch_update_request_test.py new file mode 100644 index 00000000..a7c07124 --- /dev/null +++ b/python/functions/infra/hoppscotch_update_request_test.py @@ -0,0 +1,90 @@ +"""Tests para hoppscotch_update_request. + +Deterministas: monkeypatchean requests.post para no tocar la red. Verifican que +el POST GraphQL lleva la mutation updateRequest con requestID, el access_token +en la cookie, y que `request` es el json string de un HoppRESTRequest v:"2". +""" + +import json +import sys + +import infra.hoppscotch_update_request # noqa: F401 + +# El __init__ rebinds el nombre a la funcion; recuperamos el submodulo real. +mod = sys.modules["infra.hoppscotch_update_request"] + + +class _FakeResponse: + def __init__(self, status_code=200, json_data=None): + self.status_code = status_code + self._json = json_data + + def json(self): + if self._json is None: + raise ValueError("no json") + return self._json + + +def test_golden_actualiza_request_y_devuelve_id(monkeypatch): + captured = {} + + def fake_post(url, **kwargs): + captured["url"] = url + captured["kwargs"] = kwargs + return _FakeResponse( + 200, + { + "data": { + "updateRequest": {"id": "req-7", "title": "New title"} + } + }, + ) + + monkeypatch.setattr(mod.requests, "post", fake_post) + + result = mod.hoppscotch_update_request( + "req-7", + "POST", + "https://api.example.com/x", + title="New title", + body="a=1&b=2", + body_type="form", + access_token="ACCESS-JWT", + ) + + assert result["status"] == "ok" + assert result["id"] == "req-7" + assert result["title"] == "New title" + + assert captured["url"].endswith("/graphql") + assert captured["kwargs"]["cookies"] == {"access_token": "ACCESS-JWT"} + + payload = captured["kwargs"]["json"] + assert "updateRequest" in payload["query"] + variables = payload["variables"] + assert variables["r"] == "req-7" + assert variables["d"]["title"] == "New title" + + req = json.loads(variables["d"]["request"]) + assert req["v"] == "2" + assert req["method"] == "POST" + assert req["body"] == { + "contentType": "application/x-www-form-urlencoded", + "body": "a=1&b=2", + } + + +def test_error_graphql_errors(monkeypatch): + def fake_post(url, **kwargs): + return _FakeResponse( + 200, {"errors": [{"message": "team_req/not_found"}]} + ) + + monkeypatch.setattr(mod.requests, "post", fake_post) + + result = mod.hoppscotch_update_request( + "missing", "GET", "https://x", access_token="A" + ) + assert result["status"] == "error" + assert result["error"] == "graphql errors" + assert "errors" in result["data"] diff --git a/python/functions/infra/pass_get_secret.md b/python/functions/infra/pass_get_secret.md new file mode 100644 index 00000000..1f40eacb --- /dev/null +++ b/python/functions/infra/pass_get_secret.md @@ -0,0 +1,77 @@ +--- +name: pass_get_secret +kind: function +lang: py +domain: infra +version: "1.0.0" +purity: impure +signature: "def pass_get_secret(path: str, *, line: int = 1, timeout_s: float = 10.0) -> dict" +description: "Lee un secreto del gestor de contrasenas pass (passwordstore.org) ejecutando `pass show ` como subproceso (lista de args, nunca shell=True). Devuelve la linea solicitada (1-indexed): line=1 es la contrasena por convencion de pass, line=N es metadata multilinea (usuario, URL, notas). El valor es sensible y la funcion NUNCA lo logea. Maneja errores sin lanzar: pass no instalado, entry inexistente, linea fuera de rango. Solo usa stdlib (subprocess)." +tags: [pass, secret, credential, infra, flow-replay] +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: [subprocess] +params: + - name: path + desc: "ruta del secreto dentro del store (p.ej. 'gitea/dataforge-git-token'). Es el argumento que recibiria `pass show `." + - name: line + desc: "numero de linea a devolver, 1-indexed. line=1 (default) = primera linea = contrasena por convencion de pass. line=N = linea N para metadata multilinea." + - name: timeout_s + desc: "timeout del subproceso `pass show` en segundos. Default 10.0." +output: "dict. En exito: {status: 'ok', value: str} con la linea pedida sin el salto de linea final. En error (sin lanzar): {status: 'error', error: str} para pass no instalado ('pass not installed'), entry inexistente o fallo de pass (stderr stripeado), o linea fuera de rango ('line N out of range')." +tested: true +tests: + - "test_line_1_devuelve_la_password" + - "test_line_2_devuelve_metadata" + - "test_returncode_distinto_de_cero_es_error" + - "test_pass_no_instalado_es_error" + - "test_linea_fuera_de_rango_es_error" + - "test_timeout_es_error" +test_file_path: "python/functions/infra/pass_get_secret_test.py" +file_path: "python/functions/infra/pass_get_secret.py" +--- + +## Ejemplo + +```python +import sys +sys.path.insert(0, "python/functions") +from infra.pass_get_secret import pass_get_secret + +# Primera linea = la contrasena/token (convencion de pass). +res = pass_get_secret("gitea/dataforge-git-token") +print(res) # {"status": "ok", "value": "ghp_..."} -- NO logear el value en prod + +# Linea 2 = metadata (p.ej. el usuario), si el entry es multilinea. +user = pass_get_secret("apis/licenseplatedata", line=2) +print(user) # {"status": "ok", "value": "user: neo"} +``` + +## Cuando usarla + +Cuando necesites resolver un secreto de `pass` para inyectarlo en una config, +un header HTTP, una variable de entorno o un body de request sin hardcodearlo en +el codigo. Es el lector de secretos del registry en Python: el caller pide la +ruta del store y recibe el valor en `value`, listo para enchufar donde haga +falta. line=1 para la password; line=N para metadata (usuario, URL, notas). + +## Gotchas + +- **Requiere `pass` instalado y el GPG agent desbloqueado.** Si `pass` no esta en + el PATH devuelve `{"status": "error", "error": "pass not installed"}`. Si el + agente GPG esta bloqueado, `pass show` puede colgarse hasta el `timeout_s`. +- **El valor es un secreto: no lo logees.** La funcion nunca lo imprime ni lo + registra. Trata el campo `value` como sensible aguas arriba (no `print` en + produccion, no persistir en claro). +- **line=1 es la contrasena.** Por convencion de pass la primera linea es el + secreto principal; las lineas siguientes son metadata 1-indexed. +- **No usa shell.** Ejecuta `["pass", "show", path]` como lista de args, nunca + `shell=True`, asi que `path` no puede inyectar comandos. + +## Capability growth log + +v1.0.0 — version inicial. Lector de secretos `pass` para Python, base de la +resolucion `pass:` en hoppscotch_set_environment. diff --git a/python/functions/infra/pass_get_secret.py b/python/functions/infra/pass_get_secret.py new file mode 100644 index 00000000..abcd01b6 --- /dev/null +++ b/python/functions/infra/pass_get_secret.py @@ -0,0 +1,52 @@ +"""Lee un secreto del gestor de contrasenas `pass` (passwordstore.org). + +Ejecuta `pass show ` como subproceso (lista de args, nunca shell=True) y +devuelve la linea solicitada del secreto. Por convencion de pass, la primera +linea es la contrasena y las lineas siguientes son metadata (usuario, URL, +notas, etc.). + +El valor devuelto es sensible: esta funcion NUNCA lo logea. El caller es +responsable de tratarlo como secreto (no imprimirlo, no persistirlo en claro). +""" + +import subprocess + + +def pass_get_secret(path: str, *, line: int = 1, timeout_s: float = 10.0) -> dict: + """Lee una linea de un secreto del password store (pass). + + Args: + path: ruta del secreto dentro del store (p.ej. "gitea/dataforge-git-token"). + Es el argumento que recibiria `pass show `. + line: numero de linea a devolver, 1-indexed. line=1 (default) es la + primera linea = la contrasena por convencion de pass. line=N + devuelve la linea N para metadata multilinea. + timeout_s: timeout del subproceso en segundos. + + Returns: + Dict. En exito: ``{"status": "ok", "value": str}`` con la linea pedida + sin el salto de linea final. En error (sin lanzar): + ``{"status": "error", "error": str}`` para: pass no instalado, entry + inexistente / fallo de pass (returncode != 0), o linea fuera de rango. + """ + try: + proc = subprocess.run( + ["pass", "show", path], + capture_output=True, + text=True, + timeout=timeout_s, + ) + except FileNotFoundError: + return {"status": "error", "error": "pass not installed"} + except subprocess.TimeoutExpired: + return {"status": "error", "error": f"pass timed out after {timeout_s}s"} + + if proc.returncode != 0: + return {"status": "error", "error": (proc.stderr or "").strip()} + + # `pass show` termina con un salto de linea; splitlines lo absorbe. + lines = proc.stdout.splitlines() + if line < 1 or line > len(lines): + return {"status": "error", "error": f"line {line} out of range"} + + return {"status": "ok", "value": lines[line - 1]} diff --git a/python/functions/infra/pass_get_secret_test.py b/python/functions/infra/pass_get_secret_test.py new file mode 100644 index 00000000..ca5a0a44 --- /dev/null +++ b/python/functions/infra/pass_get_secret_test.py @@ -0,0 +1,85 @@ +"""Tests para pass_get_secret. + +Deterministas: monkeypatchean subprocess.run para no ejecutar `pass` real. +Verifican seleccion de linea (1-indexed), errores de pass (returncode != 0), +pass no instalado (FileNotFoundError) y linea fuera de rango. +""" + +import subprocess +import sys + +import infra.pass_get_secret # noqa: F401 + +# El __init__ rebinds el nombre a la funcion; recuperamos el submodulo real. +mod = sys.modules["infra.pass_get_secret"] + + +class _FakeCompleted: + def __init__(self, returncode=0, stdout="", stderr=""): + self.returncode = returncode + self.stdout = stdout + self.stderr = stderr + + +def test_line_1_devuelve_la_password(monkeypatch): + def fake_run(args, **kwargs): + assert args == ["pass", "show", "apis/lpd"] + assert kwargs.get("shell") is None # nunca shell=True + return _FakeCompleted(0, stdout="s3cr3t-pass\nuser: neo\nurl: https://x\n") + + monkeypatch.setattr(mod.subprocess, "run", fake_run) + + result = mod.pass_get_secret("apis/lpd") + assert result == {"status": "ok", "value": "s3cr3t-pass"} + + +def test_line_2_devuelve_metadata(monkeypatch): + def fake_run(args, **kwargs): + return _FakeCompleted(0, stdout="s3cr3t-pass\nuser: neo\nurl: https://x\n") + + monkeypatch.setattr(mod.subprocess, "run", fake_run) + + result = mod.pass_get_secret("apis/lpd", line=2) + assert result == {"status": "ok", "value": "user: neo"} + + +def test_returncode_distinto_de_cero_es_error(monkeypatch): + def fake_run(args, **kwargs): + return _FakeCompleted(1, stdout="", stderr="Error: apis/nope is not in the password store.\n") + + monkeypatch.setattr(mod.subprocess, "run", fake_run) + + result = mod.pass_get_secret("apis/nope") + assert result["status"] == "error" + assert result["error"] == "Error: apis/nope is not in the password store." + + +def test_pass_no_instalado_es_error(monkeypatch): + def fake_run(args, **kwargs): + raise FileNotFoundError("no such file: pass") + + monkeypatch.setattr(mod.subprocess, "run", fake_run) + + result = mod.pass_get_secret("apis/lpd") + assert result == {"status": "error", "error": "pass not installed"} + + +def test_linea_fuera_de_rango_es_error(monkeypatch): + def fake_run(args, **kwargs): + return _FakeCompleted(0, stdout="solo-una-linea\n") + + monkeypatch.setattr(mod.subprocess, "run", fake_run) + + result = mod.pass_get_secret("apis/lpd", line=5) + assert result == {"status": "error", "error": "line 5 out of range"} + + +def test_timeout_es_error(monkeypatch): + def fake_run(args, **kwargs): + raise subprocess.TimeoutExpired(cmd=args, timeout=10.0) + + monkeypatch.setattr(mod.subprocess, "run", fake_run) + + result = mod.pass_get_secret("apis/lpd") + assert result["status"] == "error" + assert "timed out" in result["error"] diff --git a/python/functions/infra/sync_chromium_profiles_to_rofi.md b/python/functions/infra/sync_chromium_profiles_to_rofi.md new file mode 100644 index 00000000..57b2f62c --- /dev/null +++ b/python/functions/infra/sync_chromium_profiles_to_rofi.md @@ -0,0 +1,88 @@ +--- +name: sync_chromium_profiles_to_rofi +kind: function +lang: py +domain: infra +version: "1.0.0" +purity: impure +signature: "sync_chromium_profiles_to_rofi(local_state_path: str = '', apps_dir: str = '', icons_dir: str = '', chromium_cmd: str = 'chromium') -> dict" +description: "Sincroniza los perfiles de Chromium con el lanzador (rofi / menus .desktop). Lee profile.info_cache del Local State y por cada perfil de usuario valido genera un avatar PNG con las iniciales (o reutiliza la foto Gaia) y un archivo .desktop que lanza Chromium en ese perfil con su icono. Limpia los .desktop obsoletos generados por esta funcion (marcador X-RofiChromiumProfile) y refresca la base de datos de aplicaciones con update-desktop-database (best-effort). Excluye System Profile y perfiles con nombre vacio. Idempotente." +tags: ["rofi", "chromium", "desktop", "launcher", "xdg", "profiles", "icons"] +params: + - name: local_state_path + desc: "Ruta al archivo 'Local State' de Chromium (JSON con profile.info_cache). Si viene vacio usa ~/.config/chromium-cdp/Local State. El user-data-dir se deriva como su dirname." + - name: apps_dir + desc: "Directorio XDG de salida de los .desktop. Si viene vacio usa ~/.local/share/applications. rofi escanea este arbol." + - name: icons_dir + desc: "Directorio de salida de los iconos PNG por perfil. Si viene vacio usa ~/.local/share/icons/chromium-profiles." + - name: chromium_cmd + desc: "Comando base para el Exec del .desktop. Default 'chromium'. NO se pasa --user-data-dir: el wrapper del sistema (/etc/chromium.d/cdp) lo inyecta. El --profile-directory es relativo a ese user-data-dir." +output: "dict con user_data_dir (str absoluto), created (lista de .desktop escritos), removed (lista de .desktop obsoletos borrados), profiles (lista de {dir, name, desktop, icon}), warnings (perfiles saltados por datos raros) y update_desktop_database ({attempted, ok, detail})." +uses_functions: + - generate_initials_avatar_py_infra +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: + - Pillow +file_path: "python/functions/infra/sync_chromium_profiles_to_rofi.py" +tested: false +tests: [] +test_file_path: "" +--- + +## Ejemplo + +```bash +# Ejecucion directa con defaults (lee ~/.config/chromium-cdp/Local State, +# escribe .desktop en ~/.local/share/applications y PNGs en +# ~/.local/share/icons/chromium-profiles) +cd $HOME/fn_registry +./fn run sync_chromium_profiles_to_rofi_py_infra +``` + +```python +# Variante Python importando la funcion (PYTHONPATH=python/functions via fn run, +# o sys.path.insert al ejecutar suelto). +import sys +sys.path.insert(0, "python/functions") +from infra.sync_chromium_profiles_to_rofi import sync_chromium_profiles_to_rofi + +# Apuntando a un Local State y directorios de salida de prueba en /tmp +res = sync_chromium_profiles_to_rofi( + local_state_path="/tmp/chromium-test/Local State", + apps_dir="/tmp/chromium-test/apps", + icons_dir="/tmp/chromium-test/icons", +) +print(res["created"], res["removed"]) +``` + +## Cuando usarla + +Tras crear, renombrar o eliminar un perfil de Chromium, o a diario via dag_engine, +para que los perfiles aparezcan en rofi (y en cualquier menu XDG) con su propio +icono y un Exec que abre Chromium directamente en ese perfil. Util tambien al +provisionar una maquina nueva donde se han clonado varios perfiles. + +## Gotchas + +- El `Exec` del `.desktop` depende del wrapper del sistema que inyecta + `--user-data-dir=$HOME/.config/chromium-cdp` (via `/etc/chromium.d/cdp`). Por eso + NO se pasa `--user-data-dir` aqui; solo `chromium --profile-directory=""`. En + una maquina sin ese wrapper el `.desktop` abriria el perfil del user-data-dir por + defecto de Chromium, no el del directorio `chromium-cdp`. +- El marcador `X-RofiChromiumProfile=true` gobierna la limpieza: la funcion solo + borra `.desktop` que ella misma genero. NUNCA toca `.desktop` ajenos aunque + coincidan con el patron `chromium-*.desktop`. +- `update-desktop-database` es best-effort: si el binario no esta en el PATH, la + funcion NO falla; lo reporta en `update_desktop_database.detail`. rofi suele + funcionar igualmente sin el refresh, pero algunos menus cachean. +- Excluye siempre `"System Profile"` (no es un perfil de usuario) y cualquier + entrada con `name` vacio. +- Si un perfil tiene `gaia_picture_file_name` y el archivo existe en el dir del + perfil, se usa esa imagen tal cual como icono (sin recorte circular). Si no, se + genera el avatar de iniciales con `generate_initials_avatar`. +- El `slug` se deriva de la CLAVE del `info_cache` (el nombre del subdirectorio, + ej. `"Profile 1"` -> `profile-1`), no del nombre legible. Asi dos perfiles con el + mismo nombre visible pero distinto directorio no colisionan. diff --git a/python/functions/infra/sync_chromium_profiles_to_rofi.py b/python/functions/infra/sync_chromium_profiles_to_rofi.py new file mode 100644 index 00000000..b7f3721e --- /dev/null +++ b/python/functions/infra/sync_chromium_profiles_to_rofi.py @@ -0,0 +1,264 @@ +"""sync_chromium_profiles_to_rofi — sincroniza perfiles de Chromium con el lanzador (rofi / menus .desktop). + +Lee los perfiles de Chromium desde el `Local State` de un user-data-dir y, por +cada perfil de usuario valido, genera: + +1. un avatar PNG con las iniciales del perfil (icono distinto por perfil), o + reutiliza la foto Gaia del perfil si esta disponible, +2. un archivo `.desktop` que lanza Chromium en ese perfil con ese icono. + +Ademas limpia los `.desktop` de perfiles que ya no existen (identificados por el +marcador `X-RofiChromiumProfile=true`) y refresca la base de datos de aplicaciones +con `update-desktop-database` (best-effort). + +El `Exec` NO pasa `--user-data-dir`: el wrapper del sistema (`/etc/chromium.d/cdp`) +inyecta `--user-data-dir=$HOME/.config/chromium-cdp` en cada invocacion de chromium. +Por eso basta `chromium --profile-directory=""`. +""" + +from __future__ import annotations + +import json +import os +import re +import shutil +import subprocess +import sys +from pathlib import Path + +# Resolver el paquete `infra` del registry tanto al ejecutar via `fn run` +# (PYTHONPATH=python/functions) como al ejecutar el archivo directo como script. +sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..")) +from infra.generate_initials_avatar import generate_initials_avatar # noqa: E402 + +# Marcador que identifica los .desktop generados por ESTA funcion. Gobierna la +# limpieza de obsoletos sin tocar .desktop ajenos. +MARKER = "X-RofiChromiumProfile=true" + + +def _slugify(key: str) -> str: + """Convierte la clave del dir del perfil en un slug seguro para nombres de archivo. + + "Profile 1" -> "profile-1", "Default" -> "default", "osint_01" -> "osint-01". + """ + s = key.strip().lower() + s = re.sub(r"[\s_]+", "-", s) + s = re.sub(r"[^a-z0-9-]", "", s) + s = re.sub(r"-+", "-", s).strip("-") + return s + + +def _desktop_body(name: str, dir_key: str, icon_path: str, chromium_cmd: str) -> str: + """Construye el cuerpo del archivo .desktop para un perfil. + + El em dash en `Name` es intencional. `dir_key` se encierra entre comillas + dobles en el Exec porque puede contener espacios ("Profile 1"). + """ + return ( + "[Desktop Entry]\n" + "Version=1.0\n" + "Type=Application\n" + f"Name=Chromium — {name}\n" + "GenericName=Web Browser\n" + f"Comment=Chromium en el perfil {name}\n" + f'Exec={chromium_cmd} --profile-directory="{dir_key}" %U\n' + f"Icon={icon_path}\n" + "Terminal=false\n" + "Categories=Network;WebBrowser;\n" + "StartupWMClass=chromium\n" + f"{MARKER}\n" + ) + + +def sync_chromium_profiles_to_rofi( + local_state_path: str = "", + apps_dir: str = "", + icons_dir: str = "", + chromium_cmd: str = "chromium", +) -> dict: + """Sincroniza los perfiles de Chromium con entradas .desktop + iconos para rofi. + + Lee `profile.info_cache` del `Local State` y, por cada perfil de usuario valido + (excluye "System Profile" y perfiles con nombre vacio), genera un avatar PNG y + un archivo `.desktop` que lanza Chromium en ese perfil. Limpia los `.desktop` + obsoletos generados previamente por esta funcion y refresca la base de datos de + aplicaciones. Es idempotente: ejecutarla N veces deja el mismo estado. + + Args: + local_state_path: Ruta al archivo `Local State` de Chromium. Si viene vacio + usa `~/.config/chromium-cdp/Local State`. + apps_dir: Directorio de salida de los `.desktop`. Si viene vacio usa + `~/.local/share/applications`. + icons_dir: Directorio de salida de los iconos PNG. Si viene vacio usa + `~/.local/share/icons/chromium-profiles`. + chromium_cmd: Comando base para lanzar Chromium en el Exec del `.desktop`. + Default "chromium" (el wrapper del sistema inyecta `--user-data-dir`). + + Returns: + dict con: + user_data_dir: ruta absoluta del user-data-dir derivado del Local State. + created: lista de paths de los .desktop escritos/actualizados este run. + removed: lista de paths de los .desktop obsoletos borrados. + profiles: lista de {dir, name, desktop, icon} por perfil procesado. + warnings: lista de mensajes de perfiles saltados por datos raros. + update_desktop_database: dict {attempted, ok, detail} con el resultado + best-effort de `update-desktop-database`. + + Raises: + FileNotFoundError: si el `Local State` no existe. + ValueError: si el JSON no tiene `profile.info_cache`. + """ + if not local_state_path: + local_state_path = os.path.expanduser("~/.config/chromium-cdp/Local State") + if not apps_dir: + apps_dir = os.path.expanduser("~/.local/share/applications") + if not icons_dir: + icons_dir = os.path.expanduser("~/.local/share/icons/chromium-profiles") + + ls_path = Path(local_state_path) + if not ls_path.exists(): + raise FileNotFoundError( + f"Local State no encontrado en {ls_path}. " + "Verifica la ruta del user-data-dir de Chromium." + ) + + user_data_dir = ls_path.parent + + try: + state = json.loads(ls_path.read_text(encoding="utf-8")) + except Exception as exc: + raise ValueError(f"No se pudo parsear el JSON de {ls_path}: {exc}") from exc + + info_cache = state.get("profile", {}).get("info_cache") + if not isinstance(info_cache, dict): + raise ValueError( + f"{ls_path} no contiene profile.info_cache (dict). " + "El archivo no parece un Local State de Chromium valido." + ) + + apps_path = Path(apps_dir) + icons_path = Path(icons_dir) + icons_path.mkdir(parents=True, exist_ok=True) + apps_path.mkdir(parents=True, exist_ok=True) + + created: list[str] = [] + profiles: list[dict] = [] + warnings: list[str] = [] + # slugs vigentes -> sirve para la limpieza de obsoletos + valid_slugs: set[str] = set() + + for dir_key, meta in info_cache.items(): + try: + if dir_key == "System Profile": + continue + if not isinstance(meta, dict): + warnings.append(f"perfil {dir_key!r}: metadata no es dict, saltado") + continue + + name = (meta.get("name") or "").strip() + if not name: + # name vacio -> no es un perfil de usuario util + continue + + slug = _slugify(dir_key) + if not slug: + warnings.append(f"perfil {dir_key!r}: slug vacio tras sanitizar, saltado") + continue + valid_slugs.add(slug) + + icon_path = icons_path / f"{slug}.png" + + # Preferir la foto Gaia del perfil si existe; si no, avatar de iniciales. + gaia = (meta.get("gaia_picture_file_name") or "").strip() + gaia_src = user_data_dir / dir_key / gaia if gaia else None + if gaia_src is not None and gaia_src.is_file(): + try: + shutil.copyfile(str(gaia_src), str(icon_path)) + except Exception as exc: + warnings.append( + f"perfil {dir_key!r}: no se pudo copiar foto Gaia ({exc}), " + "usando avatar de iniciales" + ) + generate_initials_avatar(name, str(icon_path)) + else: + generate_initials_avatar(name, str(icon_path)) + + desktop_path = apps_path / f"chromium-{slug}.desktop" + desktop_path.write_text( + _desktop_body(name, dir_key, str(icon_path), chromium_cmd), + encoding="utf-8", + ) + + created.append(str(desktop_path)) + profiles.append( + { + "dir": dir_key, + "name": name, + "desktop": str(desktop_path), + "icon": str(icon_path), + } + ) + except Exception as exc: + warnings.append(f"perfil {dir_key!r}: error inesperado, saltado ({exc})") + continue + + # --- Limpieza de obsoletos: .desktop generados por esta funcion cuyo slug ya + # no corresponde a ningun perfil vigente. --- + removed: list[str] = [] + for desktop_file in apps_path.glob("chromium-*.desktop"): + try: + content = desktop_file.read_text(encoding="utf-8") + except Exception: + continue + if MARKER not in content: + # No es nuestro -> no tocar. + continue + slug = desktop_file.stem[len("chromium-"):] + if slug in valid_slugs: + continue + # Obsoleto: borrar .desktop + su icono asociado. + try: + desktop_file.unlink() + removed.append(str(desktop_file)) + except Exception as exc: + warnings.append(f"no se pudo borrar obsoleto {desktop_file}: {exc}") + continue + old_icon = icons_path / f"{slug}.png" + if old_icon.exists(): + try: + old_icon.unlink() + except Exception as exc: + warnings.append(f"no se pudo borrar icono obsoleto {old_icon}: {exc}") + + # --- Refrescar base de datos de aplicaciones (best-effort). --- + udb = {"attempted": False, "ok": False, "detail": ""} + udb_bin = shutil.which("update-desktop-database") + if udb_bin: + udb["attempted"] = True + try: + proc = subprocess.run( + [udb_bin, str(apps_path)], + capture_output=True, + text=True, + timeout=30, + ) + udb["ok"] = proc.returncode == 0 + udb["detail"] = (proc.stderr or proc.stdout or "").strip() + except Exception as exc: + udb["detail"] = f"error ejecutando update-desktop-database: {exc}" + else: + udb["detail"] = "update-desktop-database no encontrado en PATH" + + return { + "user_data_dir": str(user_data_dir), + "created": created, + "removed": removed, + "profiles": profiles, + "warnings": warnings, + "update_desktop_database": udb, + } + + +if __name__ == "__main__": + result = sync_chromium_profiles_to_rofi() + print(json.dumps(result, indent=2, default=str, ensure_ascii=False)) diff --git a/python/functions/obsidian/__init__.py b/python/functions/obsidian/__init__.py new file mode 100644 index 00000000..7e80e37b --- /dev/null +++ b/python/functions/obsidian/__init__.py @@ -0,0 +1,37 @@ +from .parse_obsidian_frontmatter import parse_obsidian_frontmatter +from .extract_obsidian_wikilinks import extract_obsidian_wikilinks +from .format_obsidian_note import format_obsidian_note + +# CRUD impuro de notas en disco (grupo obsidian) +from .read_obsidian_note import read_obsidian_note +from .create_obsidian_note import create_obsidian_note +from .update_obsidian_note import update_obsidian_note +from .delete_obsidian_note import delete_obsidian_note + +# Listado/busqueda de notas y CRUD de vaults (grupo obsidian) +from .list_obsidian_notes import list_obsidian_notes +from .search_obsidian_notes import search_obsidian_notes +from .list_obsidian_vaults import list_obsidian_vaults +from .create_obsidian_vault import create_obsidian_vault + +# Utilidades de migracion / extraccion de subgrafos (grupo obsidian) +from .slugify_obsidian_name import slugify_obsidian_name +from .extract_obsidian_embeds import extract_obsidian_embeds +from .resolve_obsidian_embed import resolve_obsidian_embed + +__all__ = [ + "parse_obsidian_frontmatter", + "extract_obsidian_wikilinks", + "format_obsidian_note", + "read_obsidian_note", + "create_obsidian_note", + "update_obsidian_note", + "delete_obsidian_note", + "list_obsidian_notes", + "search_obsidian_notes", + "list_obsidian_vaults", + "create_obsidian_vault", + "slugify_obsidian_name", + "extract_obsidian_embeds", + "resolve_obsidian_embed", +] diff --git a/python/functions/obsidian/create_obsidian_note.md b/python/functions/obsidian/create_obsidian_note.md new file mode 100644 index 00000000..a6ca8842 --- /dev/null +++ b/python/functions/obsidian/create_obsidian_note.md @@ -0,0 +1,67 @@ +--- +name: create_obsidian_note +kind: function +lang: py +domain: obsidian +version: "1.0.0" +purity: impure +signature: "def create_obsidian_note(vault_dir: str, rel_path: str, body: str = '', frontmatter: dict = None, overwrite: bool = False) -> str" +description: "Crea una nota Markdown nueva en un vault de Obsidian. Anade extension .md si falta, crea directorios padre, serializa frontmatter YAML + body con la funcion pura format_obsidian_note. Falla si la nota existe salvo overwrite=True. No depende de la app GUI de Obsidian: solo escribe un archivo .md plano en disco." +tags: [obsidian, markdown, frontmatter, create, write, notes] +uses_functions: ["format_obsidian_note_py_obsidian"] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: ["os"] +params: + - name: vault_dir + desc: "directorio raiz del vault de Obsidian donde se crea la nota" + - name: rel_path + desc: "ruta relativa de la nota dentro del vault; se le anade .md si no lo trae" + - name: body + desc: "cuerpo Markdown de la nota sin frontmatter (default cadena vacia)" + - name: frontmatter + desc: "dict con el frontmatter YAML a escribir; None se trata como {}" + - name: overwrite + desc: "si False (default) y la nota existe lanza FileExistsError; True sobreescribe" +output: "ruta absoluta (str) del archivo .md escrito" +tested: true +tests: + - "crea nota con frontmatter y body" + - "anade extension md si falta" + - "crea directorios padre" + - "existente sin overwrite lanza fileexistserror" + - "overwrite true sobreescribe" + - "destino directorio lanza isadirectoryerror" +test_file_path: "python/functions/obsidian/create_obsidian_note_test.py" +file_path: "python/functions/obsidian/create_obsidian_note.py" +--- + +## Ejemplo + +```python +import sys, os +sys.path.insert(0, os.path.join("python", "functions")) +from obsidian import create_obsidian_note + +path = create_obsidian_note( + vault_dir="/home/me/vault", + rel_path="Inbox/Idea rapida", # se convierte en Inbox/Idea rapida.md + body="Primer apunte. Ver [[Proyecto X]].", + frontmatter={"title": "Idea rapida", "tags": ["inbox", "wip"]}, +) +print(path) # /home/me/vault/Inbox/Idea rapida.md +``` + +## Cuando usarla + +Cuando quieras crear una nota nueva en un vault de Obsidian desde codigo o un agente: capturar una idea en el Inbox, generar notas a partir de datos, o materializar plantillas. Crea automaticamente los directorios padre, asi que sirve para sembrar estructuras de carpetas nuevas. + +## Gotchas + +- **Escribe en disco** (I/O impuro): crea el archivo y los directorios padre que falten (`os.makedirs(..., exist_ok=True)`). +- **No respeta locks de la app GUI**: si Obsidian esta abierto, el archivo nuevo aparecera en el vault, pero crear una nota cuyo nombre choque con una abierta y sin guardar puede provocar conflictos de version en el editor. +- Por defecto **no sobreescribe**: lanza `FileExistsError` si la nota ya existe. Pasa `overwrite=True` para reemplazar. +- Lanza `IsADirectoryError` si el destino resuelto es un directorio existente. +- El nombre de archivo se respeta tal cual (incluidos espacios); Obsidian admite espacios en nombres de nota. diff --git a/python/functions/obsidian/create_obsidian_note.py b/python/functions/obsidian/create_obsidian_note.py new file mode 100644 index 00000000..a9ae8631 --- /dev/null +++ b/python/functions/obsidian/create_obsidian_note.py @@ -0,0 +1,82 @@ +"""Crea una nota nueva de Obsidian (.md) en un vault, en disco. + +Compone la funcion pura format_obsidian_note del grupo obsidian para serializar +frontmatter + body. Funcion impura: escribe un archivo nuevo en disco y crea +directorios padre. +""" + +import os + +from obsidian import format_obsidian_note + + +def create_obsidian_note( + vault_dir: str, + rel_path: str, + body: str = "", + frontmatter: dict = None, + overwrite: bool = False, +) -> str: + """Crea una nota Markdown nueva dentro de un vault de Obsidian. + + Args: + vault_dir: directorio raiz del vault donde se crea la nota. + rel_path: ruta relativa de la nota dentro del vault. Si no termina en + ".md" se le anade la extension automaticamente. + body: cuerpo Markdown de la nota (sin frontmatter). Por defecto vacio. + frontmatter: dict con el frontmatter YAML a escribir. None -> {}. + overwrite: si False (default) y la nota ya existe, lanza FileExistsError. + Si True, sobreescribe el archivo existente. + + Returns: + La ruta absoluta del archivo .md escrito. + + Raises: + FileExistsError: si la nota existe y overwrite=False. + IsADirectoryError: si la ruta destino es un directorio existente. + OSError: si la escritura falla por otro motivo de I/O. + """ + if not rel_path.endswith(".md"): + rel_path = rel_path + ".md" + + abs_path = os.path.abspath(os.path.join(vault_dir, rel_path)) + + if os.path.isdir(abs_path): + raise IsADirectoryError(f"destination is a directory: {abs_path}") + if os.path.exists(abs_path) and not overwrite: + raise FileExistsError( + f"obsidian note already exists (use overwrite=True): {abs_path}" + ) + + parent = os.path.dirname(abs_path) + if parent: + os.makedirs(parent, exist_ok=True) + + content = format_obsidian_note(frontmatter or {}, body or "") + + with open(abs_path, "w", encoding="utf-8") as f: + f.write(content) + + return abs_path + + +if __name__ == "__main__": + import tempfile + + vault = tempfile.mkdtemp() + p = create_obsidian_note( + vault, "subdir/Nota Nueva", body="Cuerpo.", frontmatter={"title": "X"} + ) + assert os.path.isfile(p), p + assert p.endswith("Nota Nueva.md"), p + try: + create_obsidian_note(vault, "subdir/Nota Nueva", body="otra") + raise AssertionError("debio lanzar FileExistsError") + except FileExistsError: + pass + p2 = create_obsidian_note(vault, "subdir/Nota Nueva", body="z", overwrite=True) + assert p2 == p, (p2, p) + os.remove(p) + os.rmdir(os.path.dirname(p)) + os.rmdir(vault) + print("create_obsidian_note smoke OK") diff --git a/python/functions/obsidian/create_obsidian_note_test.py b/python/functions/obsidian/create_obsidian_note_test.py new file mode 100644 index 00000000..fc21ccdd --- /dev/null +++ b/python/functions/obsidian/create_obsidian_note_test.py @@ -0,0 +1,67 @@ +"""Tests para create_obsidian_note.""" + +import os + +import pytest + +from create_obsidian_note import create_obsidian_note +from read_obsidian_note import read_obsidian_note + + +def test_crea_nota_con_frontmatter_y_body(tmp_path): + # Golden path: crea nota con frontmatter + body y crea el subdir padre. + vault = str(tmp_path) + path = create_obsidian_note( + vault, + "Proyectos/Idea.md", + body="Primer apunte. [[Proyecto X]].", + frontmatter={"title": "Idea", "tags": ["inbox"]}, + ) + assert os.path.isfile(path) + assert path.endswith("Proyectos/Idea.md") + + note = read_obsidian_note(path) + assert note["frontmatter"]["title"] == "Idea" + assert note["tags"] == ["inbox"] + assert "Primer apunte" in note["body"] + assert note["wikilinks"] == ["Proyecto X"] + + +def test_anade_extension_md_si_falta(tmp_path): + # Edge: rel_path sin extension -> se le anade .md. + path = create_obsidian_note(str(tmp_path), "Inbox/Nota rapida", body="x") + assert path.endswith("Nota rapida.md") + assert os.path.isfile(path) + + +def test_crea_directorios_padre(tmp_path): + # Edge: crea toda la jerarquia de carpetas que no existe. + path = create_obsidian_note(str(tmp_path), "a/b/c/Honda.md", body="y") + assert os.path.isfile(path) + assert os.path.isdir(os.path.join(str(tmp_path), "a", "b", "c")) + + +def test_existente_sin_overwrite_lanza_fileexistserror(tmp_path): + # Error path: la nota ya existe y overwrite=False (default). + create_obsidian_note(str(tmp_path), "Dup.md", body="original") + with pytest.raises(FileExistsError): + create_obsidian_note(str(tmp_path), "Dup.md", body="nuevo") + + +def test_overwrite_true_sobreescribe(tmp_path): + # Edge: overwrite=True reemplaza el contenido y devuelve la misma ruta. + p1 = create_obsidian_note(str(tmp_path), "Dup.md", body="original") + p2 = create_obsidian_note( + str(tmp_path), "Dup.md", body="reemplazado", overwrite=True + ) + assert p1 == p2 + note = read_obsidian_note(p2) + assert note["body"].strip() == "reemplazado" + + +def test_destino_directorio_lanza_isadirectoryerror(tmp_path): + # Error path: el destino resuelto ya es un directorio. + target = tmp_path / "EsCarpeta.md" + target.mkdir() + with pytest.raises(IsADirectoryError): + create_obsidian_note(str(tmp_path), "EsCarpeta.md", body="x") diff --git a/python/functions/obsidian/create_obsidian_vault.md b/python/functions/obsidian/create_obsidian_vault.md new file mode 100644 index 00000000..c5e9bf10 --- /dev/null +++ b/python/functions/obsidian/create_obsidian_vault.md @@ -0,0 +1,49 @@ +--- +name: create_obsidian_vault +kind: function +lang: py +domain: obsidian +version: "1.0.0" +purity: impure +signature: "create_obsidian_vault(parent_dir: str, name: str) -> str" +description: "Crea un vault de Obsidian nuevo: parent_dir/name/ + parent_dir/name/.obsidian/app.json con {} (config minima valida). Lanza error si el vault ya existe (ya tiene .obsidian/). Devuelve el path absoluto del vault." +tags: [obsidian, vault, create, crud, filesystem] +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: ["json", "os"] +params: + - name: parent_dir + desc: "directorio bajo el cual se crea la carpeta del vault; se crea si no existe" + - name: name + desc: "nombre de la carpeta del nuevo vault (un solo segmento de path, sin separadores)" +output: "path absoluto del directorio del vault creado" +tested: false +tests: [] +test_file_path: "" +file_path: "python/functions/obsidian/create_obsidian_vault.py" +--- + +## Ejemplo + +```python +from obsidian import create_obsidian_vault + +path = create_obsidian_vault("/home/enmanuel/Obsidian", "Proyectos2026") +print(path) # /home/enmanuel/Obsidian/Proyectos2026 +# Crea ademas /home/enmanuel/Obsidian/Proyectos2026/.obsidian/app.json -> {} +``` + +## Cuando usarla + +Cuando necesites crear un vault de Obsidian listo para abrir desde cero (scaffolding de un workspace nuevo, automatizar la creacion de vaults por proyecto) sin pasar por la GUI de Obsidian. + +## Gotchas + +- **Impura**: escribe en el filesystem. Crea `parent_dir/name/.obsidian/` y un `app.json` con `{}` (config minima que Obsidian reconoce como vault valido). +- **No sobrescribe**: si el destino ya parece un vault (ya tiene `.obsidian/`) lanza `FileExistsError`; nunca pisa un vault existente. +- **Nombre validado**: lanza `ValueError` si `name` es vacio o contiene un separador de path (`/`), para evitar crear estructuras anidadas accidentales. +- Lo que hace vault a una carpeta es la presencia de `.obsidian/`; este es el mismo criterio que usa `list_obsidian_vaults` para descubrir vaults, asi que un vault recien creado aparece de inmediato en ese listado. +- `parent_dir` se crea si no existe (`makedirs`), de modo que se puede crear un vault en una ruta nueva en una sola llamada. diff --git a/python/functions/obsidian/create_obsidian_vault.py b/python/functions/obsidian/create_obsidian_vault.py new file mode 100644 index 00000000..b4550d45 --- /dev/null +++ b/python/functions/obsidian/create_obsidian_vault.py @@ -0,0 +1,71 @@ +"""Create a new, valid Obsidian vault on disk.""" + +import json +import os + + +def create_obsidian_vault(parent_dir: str, name: str) -> str: + """Create a new Obsidian vault under ``parent_dir`` and return its path. + + Creates ``parent_dir/name/`` together with a minimal but valid Obsidian + configuration: ``parent_dir/name/.obsidian/app.json`` containing ``{}``. + The presence of an ``.obsidian/`` directory is what Obsidian uses to + recognise a folder as a vault, so the result opens cleanly in Obsidian. + + Impure: it writes to the filesystem. If the target already looks like a + vault (it already has an ``.obsidian/`` directory) a ``FileExistsError`` is + raised so an existing vault is never silently overwritten. A + ``ValueError`` is raised for an empty ``name`` or one containing a path + separator. + + Args: + parent_dir: Directory under which the new vault folder is created. It is + created if it does not exist yet. + name: Name of the new vault folder (a single path segment, no + separators). + + Returns: + The absolute path of the created vault directory. + """ + if not name or os.sep in name or (os.altsep and os.altsep in name): + raise ValueError(f"invalid vault name: {name!r}") + + vault_path = os.path.abspath(os.path.join(parent_dir, name)) + obsidian_dir = os.path.join(vault_path, ".obsidian") + + if os.path.isdir(obsidian_dir): + raise FileExistsError(f"vault already exists: {vault_path}") + + os.makedirs(obsidian_dir, exist_ok=True) + app_json = os.path.join(obsidian_dir, "app.json") + with open(app_json, "w", encoding="utf-8") as handle: + json.dump({}, handle) + + return vault_path + + +if __name__ == "__main__": + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + path = create_obsidian_vault(tmp, "MyVault") + assert os.path.isdir(path), path + assert os.path.isfile(os.path.join(path, ".obsidian", "app.json")) + with open(os.path.join(path, ".obsidian", "app.json")) as f: + assert json.load(f) == {} + + # Re-creating the same vault must fail. + try: + create_obsidian_vault(tmp, "MyVault") + raise AssertionError("expected FileExistsError") + except FileExistsError: + pass + + # Invalid name must fail. + try: + create_obsidian_vault(tmp, "bad/name") + raise AssertionError("expected ValueError") + except ValueError: + pass + + print("OK") diff --git a/python/functions/obsidian/delete_obsidian_note.md b/python/functions/obsidian/delete_obsidian_note.md new file mode 100644 index 00000000..067d2775 --- /dev/null +++ b/python/functions/obsidian/delete_obsidian_note.md @@ -0,0 +1,52 @@ +--- +name: delete_obsidian_note +kind: function +lang: py +domain: obsidian +version: "1.0.0" +purity: impure +signature: "def delete_obsidian_note(path: str) -> bool" +description: "Borra un archivo de nota Markdown de Obsidian del disco. Por seguridad solo borra un archivo concreto, nunca un directorio. No depende de la app GUI de Obsidian: opera directamente sobre el archivo .md plano." +tags: [obsidian, markdown, delete, write, notes] +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: ["os"] +params: + - name: path + desc: "ruta al archivo .md de la nota a borrar" +output: "True (bool) si el archivo fue borrado correctamente" +tested: true +tests: + - "borra archivo existente y devuelve true" + - "archivo inexistente lanza filenotfounderror" + - "directorio lanza isadirectoryerror" + - "no borra otros archivos" +test_file_path: "python/functions/obsidian/delete_obsidian_note_test.py" +file_path: "python/functions/obsidian/delete_obsidian_note.py" +--- + +## Ejemplo + +```python +import sys, os +sys.path.insert(0, os.path.join("python", "functions")) +from obsidian import delete_obsidian_note + +ok = delete_obsidian_note("/home/me/vault/Inbox/Idea descartada.md") +print(ok) # True +``` + +## Cuando usarla + +Cuando quieras eliminar una nota concreta de un vault de Obsidian desde codigo o un agente: limpiar el Inbox, borrar notas generadas temporalmente, o eliminar una nota tras consolidar su contenido en otra. Para varias notas, llama una vez por archivo (no acepta directorios). + +## Gotchas + +- **Borra del disco** (I/O impuro) y de forma **irreversible**: no manda a papelera, hace `os.remove`. El archivo no se puede recuperar salvo backup del vault. +- **Solo archivos, nunca directorios**: lanza `IsADirectoryError` si el path apunta a una carpeta, para evitar borrados masivos accidentales. +- **No respeta locks de la app GUI**: si Obsidian tiene la nota abierta, borrarla en disco dejara la pestana huerfana en el editor; al guardar desde Obsidian podria recrearse el archivo. +- Lanza `FileNotFoundError` si el archivo no existe. +- No borra archivos asociados (adjuntos, attachments referenciados): solo el `.md` indicado. diff --git a/python/functions/obsidian/delete_obsidian_note.py b/python/functions/obsidian/delete_obsidian_note.py new file mode 100644 index 00000000..09b77cd5 --- /dev/null +++ b/python/functions/obsidian/delete_obsidian_note.py @@ -0,0 +1,48 @@ +"""Borra una nota de Obsidian (.md) del disco. + +Funcion impura: elimina un archivo del sistema de archivos. Por seguridad solo +borra archivos, nunca directorios. +""" + +import os + + +def delete_obsidian_note(path: str) -> bool: + """Borra un archivo de nota Markdown de Obsidian. + + Args: + path: ruta al archivo .md a borrar. + + Returns: + True si el archivo fue borrado correctamente. + + Raises: + FileNotFoundError: si el archivo no existe. + IsADirectoryError: si la ruta apunta a un directorio (nunca se borra un + directorio, solo un archivo concreto). + OSError: si el borrado falla por otro motivo de I/O. + """ + if not os.path.exists(path): + raise FileNotFoundError(f"obsidian note not found: {path}") + if os.path.isdir(path): + raise IsADirectoryError( + f"refusing to delete a directory, only single files: {path}" + ) + + os.remove(path) + return True + + +if __name__ == "__main__": + import tempfile + + fd, tmp = tempfile.mkstemp(suffix=".md") + os.close(fd) + assert delete_obsidian_note(tmp) is True + assert not os.path.exists(tmp) + try: + delete_obsidian_note(tmp) + raise AssertionError("debio lanzar FileNotFoundError") + except FileNotFoundError: + pass + print("delete_obsidian_note smoke OK") diff --git a/python/functions/obsidian/delete_obsidian_note_test.py b/python/functions/obsidian/delete_obsidian_note_test.py new file mode 100644 index 00000000..db1a5294 --- /dev/null +++ b/python/functions/obsidian/delete_obsidian_note_test.py @@ -0,0 +1,46 @@ +"""Tests para delete_obsidian_note.""" + +import os + +import pytest + +from delete_obsidian_note import delete_obsidian_note + + +def test_borra_archivo_existente_y_devuelve_true(tmp_path): + # Golden path: borra un .md existente y confirma que desaparece. + note = tmp_path / "Borrame.md" + note.write_text("contenido", encoding="utf-8") + + result = delete_obsidian_note(str(note)) + assert result is True + assert not note.exists() + + +def test_archivo_inexistente_lanza_filenotfounderror(tmp_path): + # Error path: borrar algo que no existe. + with pytest.raises(FileNotFoundError): + delete_obsidian_note(str(tmp_path / "fantasma.md")) + + +def test_directorio_lanza_isadirectoryerror(tmp_path): + # Error path: se niega a borrar un directorio. + sub = tmp_path / "carpeta" + sub.mkdir() + with pytest.raises(IsADirectoryError): + delete_obsidian_note(str(sub)) + # El directorio sigue intacto tras el error. + assert sub.is_dir() + + +def test_no_borra_otros_archivos(tmp_path): + # Edge: borrar una nota no afecta a las demas del vault. + a = tmp_path / "A.md" + b = tmp_path / "B.md" + a.write_text("a", encoding="utf-8") + b.write_text("b", encoding="utf-8") + + assert delete_obsidian_note(str(a)) is True + assert not a.exists() + assert b.exists() + assert os.path.isfile(str(b)) diff --git a/python/functions/obsidian/extract_obsidian_embeds.md b/python/functions/obsidian/extract_obsidian_embeds.md new file mode 100644 index 00000000..df2a6991 --- /dev/null +++ b/python/functions/obsidian/extract_obsidian_embeds.md @@ -0,0 +1,65 @@ +--- +name: extract_obsidian_embeds +kind: function +lang: py +domain: obsidian +version: "1.0.0" +purity: pure +signature: "def extract_obsidian_embeds(body: str) -> list" +description: "Extrae SOLO los embeds ![[...]] (attachments incrustados: imagenes, pdf, otras notas) del cuerpo de una nota de Obsidian, ignorando los wikilinks normales [[...]]. Para cada embed devuelve el target tal cual (nombre de archivo), quitando alias (|...) y anclas (#...). Deduplica preservando orden de aparicion. Pura, sin I/O. Util para detectar que attachments arrastra una nota al migrar un subgrafo." +tags: [obsidian, embed, attachment, image, markdown, extract, migrate] +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "" +imports: ["re"] +params: + - name: body + desc: "Cuerpo Markdown de una nota de Obsidian (idealmente sin frontmatter). Puede mezclar wikilinks [[...]] y embeds ![[...]] con alias (|) o ancla (#)." +output: "Lista de strings con los nombres de los attachments embebidos (el target de cada ![[...]]), unicos y en orden de aparicion. Solo embeds: los wikilinks normales [[...]] se ignoran. Lista vacia si no hay embeds." +tested: true +tests: + - "solo embeds ignora wikilinks" + - "varios embeds orden y dedup" + - "quita alias y ancla" + - "nombre con espacios y parentesis" + - "sin embeds solo wikilinks" + - "body vacio" +test_file_path: "python/functions/obsidian/extract_obsidian_embeds_test.py" +file_path: "python/functions/obsidian/extract_obsidian_embeds.py" +--- + +## Ejemplo + +```python +body = ( + "Texto con [[Nota normal]] y un embed ![[imagen.jpg]]. " + "Luego ![[doc.pdf]] y otra vez ![[imagen.jpg]]." +) +extract_obsidian_embeds(body) +# ["imagen.jpg", "doc.pdf"] + +extract_obsidian_embeds("![[dni enmanuel (2).jpg]]") +# ["dni enmanuel (2).jpg"] +``` + +## Cuando usarla + +Usala cuando migres o extraigas un subgrafo de notas y necesites saber QUE +attachments hay que copiar junto a cada nota. A diferencia de +`extract_obsidian_wikilinks` (que devuelve todos los enlaces, incluidos los +embeds), esta funcion aisla solo los `![[...]]`, que son los archivos fisicos +incrustados. Combinala con `resolve_obsidian_embed` para localizar el path real +de cada attachment dentro del vault. + +## Gotchas + +- Devuelve el nombre del attachment tal cual aparece en el embed (p.ej. + `dni enmanuel (2).jpg`), NO un path. Obsidian resuelve embeds por nombre de + archivo unico; para obtener la ruta real usa `resolve_obsidian_embed`. +- Quita deliberadamente el alias (`|300`, util para dimensionar imagenes) y el + ancla (`#Seccion`, util para embeber un trozo de otra nota). Si necesitas esos + modificadores, parsea el body tu mismo. +- Solo reconoce embeds con doble corchete `![[...]]`. Los embeds Markdown + estandar de imagen `![alt](ruta)` NO se detectan. diff --git a/python/functions/obsidian/extract_obsidian_embeds.py b/python/functions/obsidian/extract_obsidian_embeds.py new file mode 100644 index 00000000..26211668 --- /dev/null +++ b/python/functions/obsidian/extract_obsidian_embeds.py @@ -0,0 +1,70 @@ +"""Extrae los embeds ![[...]] (attachments incrustados) de una nota de Obsidian. + +Funcion pura: solo procesa texto. A diferencia de extract_obsidian_wikilinks, +ignora los wikilinks normales [[...]] y devuelve unicamente los embeds ![[...]]. +""" + +import re + +# Matchea SOLO embeds: el '!' inicial es obligatorio (? list: + """Extrae SOLO los embeds ``![[...]]`` del cuerpo de una nota de Obsidian. + + Un embed `![[archivo.jpg]]` incrusta un attachment (imagen, pdf, otra nota) + dentro de la nota. Esta funcion devuelve el target de cada embed, mientras + que los wikilinks normales `[[...]]` (que NO empiezan por `!`) se ignoran. + + Para cada embed se normaliza el target: + + ![[imagen.jpg]] -> "imagen.jpg" + ![[imagen.jpg|300]] -> "imagen.jpg" (se quita el alias |...) + ![[nota#Seccion]] -> "nota" (se quita el ancla #...) + ![[dni enmanuel (2).jpg]] -> "dni enmanuel (2).jpg" + + Los targets se deduplican preservando el orden de primera aparicion. Pura y + deterministica: no hace I/O ni muta nada. + + Args: + body: Cuerpo Markdown de una nota de Obsidian (idealmente sin + frontmatter). + + Returns: + Lista de strings con los nombres de los attachments embebidos, unicos y + en orden de aparicion. Lista vacia si no hay embeds. + """ + if not body: + return [] + + seen = set() + targets = [] + for match in _EMBED_RE.finditer(body): + inner = match.group(1) + # Quitar alias tras el primer '|'. + target = inner.split("|", 1)[0] + # Quitar ancla/heading tras el primer '#'. + target = target.split("#", 1)[0] + target = target.strip() + if not target: + continue + if target in seen: + continue + seen.add(target) + targets.append(target) + return targets + + +if __name__ == "__main__": + body = ( + "Texto con [[Nota normal]] y un embed ![[imagen.jpg]]. " + "Otra cosa [[Otra Nota|alias]] y ![[doc.pdf]] y ![[imagen.jpg]]." + ) + assert extract_obsidian_embeds(body) == ["imagen.jpg", "doc.pdf"], body + assert extract_obsidian_embeds("") == [] + assert extract_obsidian_embeds("solo [[wikilink]] aqui") == [] + assert extract_obsidian_embeds("![[dni enmanuel (2).jpg]]") == ["dni enmanuel (2).jpg"] + print("extract_obsidian_embeds smoke OK") diff --git a/python/functions/obsidian/extract_obsidian_embeds_test.py b/python/functions/obsidian/extract_obsidian_embeds_test.py new file mode 100644 index 00000000..009872a8 --- /dev/null +++ b/python/functions/obsidian/extract_obsidian_embeds_test.py @@ -0,0 +1,35 @@ +"""Tests para extract_obsidian_embeds.""" + +from extract_obsidian_embeds import extract_obsidian_embeds + + +def test_solo_embeds_ignora_wikilinks(): + # Golden path: mezcla de [[Nota normal]] y ![[imagen.jpg]] -> solo el embed. + body = "Texto con [[Nota normal]] y un embed ![[imagen.jpg]]." + assert extract_obsidian_embeds(body) == ["imagen.jpg"] + + +def test_varios_embeds_orden_y_dedup(): + # Edge: varios embeds preservan orden y deduplican. + body = "![[a.jpg]] luego ![[b.pdf]] luego ![[a.jpg]] y ![[c.png]]" + assert extract_obsidian_embeds(body) == ["a.jpg", "b.pdf", "c.png"] + + +def test_quita_alias_y_ancla(): + # Edge: alias (|) y heading/ancla (#) se descartan del target. + body = "![[imagen.jpg|300]] y ![[nota#Seccion]]" + assert extract_obsidian_embeds(body) == ["imagen.jpg", "nota"] + + +def test_nombre_con_espacios_y_parentesis(): + # Edge: nombre de archivo real con espacios y parentesis se preserva. + body = "Mira ![[dni enmanuel (2).jpg]] adjunto." + assert extract_obsidian_embeds(body) == ["dni enmanuel (2).jpg"] + + +def test_sin_embeds_solo_wikilinks(): + assert extract_obsidian_embeds("solo [[wikilink]] y [[otro|alias]]") == [] + + +def test_body_vacio(): + assert extract_obsidian_embeds("") == [] diff --git a/python/functions/obsidian/extract_obsidian_wikilinks.md b/python/functions/obsidian/extract_obsidian_wikilinks.md new file mode 100644 index 00000000..0d921c2c --- /dev/null +++ b/python/functions/obsidian/extract_obsidian_wikilinks.md @@ -0,0 +1,62 @@ +--- +name: extract_obsidian_wikilinks +kind: function +lang: py +domain: obsidian +version: "1.0.0" +purity: pure +signature: "def extract_obsidian_wikilinks(body: str) -> list" +description: "Extrae los targets de los wikilinks [[...]] del cuerpo de una nota de Obsidian. Normaliza alias ([[nota|alias]] -> nota), heading ([[nota#h]] -> nota) y block id ([[nota#^id]] -> nota). Incluye tambien los embeds ![[...]] como links (Obsidian los trata como tales). Deduplica preservando orden de aparicion. Pura, sin I/O." +tags: [obsidian, wikilink, links, markdown, extract, note, graph] +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "" +imports: ["re"] +params: + - name: body + desc: "Cuerpo Markdown de una nota de Obsidian (idealmente sin frontmatter). Puede contener wikilinks [[...]] y embeds ![[...]] con alias (|), heading (#) o block id (#^)." +output: "Lista de strings con los nombres de nota target unicos, en orden de primera aparicion. Cada target esta normalizado (sin alias, sin heading/block anchor, sin espacios al borde). Los embeds de imagen/nota se incluyen igual que los links normales. Lista vacia si no hay wikilinks." +tested: true +tests: + - "links basicos y normalizacion" + - "incluye embeds" + - "dedup preserva orden" + - "alias y heading combinados" + - "whitespace se strippa" + - "sin links" + - "body vacio" +test_file_path: "python/functions/obsidian/extract_obsidian_wikilinks_test.py" +file_path: "python/functions/obsidian/extract_obsidian_wikilinks.py" +--- + +## Ejemplo + +```python +body = ( + "See [[Note A]] and [[Note B|the second]] plus [[Note A#Section]] " + "and [[Note C#^block123]]. Embed: ![[diagram.png]]. Repeat [[Note A]]." +) +extract_obsidian_wikilinks(body) +# ["Note A", "Note B", "Note C", "diagram.png"] +``` + +## Cuando usarla + +Usala para construir el grafo de enlaces de un vault (backlinks/forward-links), +detectar notas huerfanas o referenciadas, o validar enlaces rotos antes de un +refactor. Aplicala al `body` que devuelve `parse_obsidian_frontmatter` para +ignorar wikilinks que pudieran aparecer dentro de valores YAML del frontmatter. + +## Gotchas + +- Los embeds `![[...]]` se incluyen como links (decision intencional: Obsidian + los cuenta en el grafo). Si necesitas separar links de embeds, filtra por la + extension del target o por el `!` aparte — esta funcion no distingue. +- Solo normaliza al nombre de nota: pierde deliberadamente el alias, el heading + y el block id. Si necesitas el anchor completo, parsea el body tu mismo. +- No resuelve rutas relativas ni desambigua notas con el mismo nombre en + carpetas distintas: devuelve el texto del link tal cual (sin la carpeta si el + link no la incluye). +- No procesa Markdown links estandar `[texto](url)` — solo wikilinks `[[...]]`. diff --git a/python/functions/obsidian/extract_obsidian_wikilinks.py b/python/functions/obsidian/extract_obsidian_wikilinks.py new file mode 100644 index 00000000..3af20636 --- /dev/null +++ b/python/functions/obsidian/extract_obsidian_wikilinks.py @@ -0,0 +1,66 @@ +"""Extract wikilink targets from the body of an Obsidian note.""" + +import re + +# Matches both plain wikilinks [[...]] and embeds ![[...]]. +# The captured group is everything between the double brackets. +_WIKILINK_RE = re.compile(r"!?\[\[([^\[\]]+?)\]\]") + + +def extract_obsidian_wikilinks(body: str) -> list: + """Extract the note targets from the wikilinks in a note body. + + Recognizes both plain links `[[...]]` and embeds `![[...]]` (Obsidian + treats embeds as links too). Each target is normalized to the bare note + name: + + [[note|alias]] -> "note" + [[note#heading]] -> "note" + [[note#^blockid]] -> "note" + [[note]] -> "note" + ![[image.png]] -> "image.png" + + The alias (after `|`), the heading/block anchor (after `#`) and surrounding + whitespace are stripped. Targets are deduplicated while preserving the + order of first appearance. Pure and deterministic: no I/O, no mutation. + + Args: + body: The Markdown body of an Obsidian note (without frontmatter). + + Returns: + A list of unique target note names (strings), in order of appearance. + """ + if not body: + return [] + + seen = set() + targets = [] + for match in _WIKILINK_RE.finditer(body): + inner = match.group(1) + # Drop the alias part after the first pipe. + target = inner.split("|", 1)[0] + # Drop the heading / block anchor after the first hash. + target = target.split("#", 1)[0] + target = target.strip() + if not target: + continue + if target in seen: + continue + seen.add(target) + targets.append(target) + return targets + + +if __name__ == "__main__": + body = ( + "See [[Note A]] and [[Note B|the second]] plus [[Note A#Section]] " + "and [[Note C#^block123]]. Embed: ![[diagram.png]]. Repeat [[Note A]]." + ) + links = extract_obsidian_wikilinks(body) + assert links == ["Note A", "Note B", "Note C", "diagram.png"], links + + assert extract_obsidian_wikilinks("") == [] + assert extract_obsidian_wikilinks("no links here") == [] + assert extract_obsidian_wikilinks("[[ spaced |alias]]") == ["spaced"] + + print("OK") diff --git a/python/functions/obsidian/extract_obsidian_wikilinks_test.py b/python/functions/obsidian/extract_obsidian_wikilinks_test.py new file mode 100644 index 00000000..2ee5f7d8 --- /dev/null +++ b/python/functions/obsidian/extract_obsidian_wikilinks_test.py @@ -0,0 +1,44 @@ +"""Tests para extract_obsidian_wikilinks.""" + +from extract_obsidian_wikilinks import extract_obsidian_wikilinks + + +def test_links_basicos_y_normalizacion(): + body = ( + "See [[Note A]] and [[Note B|the second]] plus [[Note A#Section]] " + "and [[Note C#^block123]]." + ) + links = extract_obsidian_wikilinks(body) + assert links == ["Note A", "Note B", "Note C"] + + +def test_incluye_embeds(): + body = "Text [[Note A]] and embed ![[diagram.png]] and ![[Note D]]." + links = extract_obsidian_wikilinks(body) + assert links == ["Note A", "diagram.png", "Note D"] + + +def test_dedup_preserva_orden(): + body = "[[Z]] [[A]] [[Z]] [[A|alias]] [[B]]" + links = extract_obsidian_wikilinks(body) + assert links == ["Z", "A", "B"] + + +def test_alias_y_heading_combinados(): + body = "[[Note E#Heading|Custom Alias]]" + links = extract_obsidian_wikilinks(body) + assert links == ["Note E"] + + +def test_whitespace_se_strippa(): + body = "[[ spaced note |alias]] and [[ tight ]]" + links = extract_obsidian_wikilinks(body) + assert links == ["spaced note", "tight"] + + +def test_sin_links(): + assert extract_obsidian_wikilinks("no links here") == [] + + +def test_body_vacio(): + assert extract_obsidian_wikilinks("") == [] diff --git a/python/functions/obsidian/format_obsidian_note.md b/python/functions/obsidian/format_obsidian_note.md new file mode 100644 index 00000000..a232031e --- /dev/null +++ b/python/functions/obsidian/format_obsidian_note.md @@ -0,0 +1,65 @@ +--- +name: format_obsidian_note +kind: function +lang: py +domain: obsidian +version: "1.0.0" +purity: pure +signature: "def format_obsidian_note(frontmatter: dict, body: str) -> str" +description: "Serializa una nota completa de Obsidian a partir de un dict de frontmatter y un body. Si frontmatter no esta vacio, emite '---\\n---\\n\\n' usando yaml.safe_dump(frontmatter, sort_keys=False, allow_unicode=True). Si frontmatter es vacio o None, devuelve solo el body. Es la inversa de parse_obsidian_frontmatter para un round-trip razonable. Pura, sin I/O." +tags: [obsidian, frontmatter, yaml, markdown, format, serialize, note] +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "" +imports: ["yaml"] +params: + - name: frontmatter + desc: "Dict con los metadatos YAML de la nota. Vacio o None significa que no se emite bloque frontmatter (solo el body). El orden de las claves se preserva (sort_keys=False)." + - name: body + desc: "Cuerpo Markdown de la nota. None se trata como cadena vacia." +output: "String con el texto completo de la nota. Con frontmatter: '---\\n---\\n\\n' (unicode literal, orden de claves preservado). Sin frontmatter: solo el body." +tested: true +tests: + - "con frontmatter" + - "frontmatter vacio devuelve body" + - "frontmatter none devuelve body" + - "preserva orden de claves" + - "unicode literal" + - "round trip con parse" +test_file_path: "python/functions/obsidian/format_obsidian_note_test.py" +file_path: "python/functions/obsidian/format_obsidian_note.py" +--- + +## Ejemplo + +```python +out = format_obsidian_note({"title": "My Note", "tags": ["a", "b"]}, "Hello.") +# "---\ntitle: My Note\ntags:\n- a\n- b\n---\n\nHello." + +format_obsidian_note({}, "just a body") +# "just a body" +``` + +## Cuando usarla + +Usala como ultimo paso del round-trip parse -> modificar -> format: tras leer +una nota con `parse_obsidian_frontmatter`, mutar el dict de frontmatter (anadir +un tag, cambiar status, actualizar una fecha) y volver a serializar la nota +lista para escribir a disco. Tambien para generar notas nuevas desde cero con +metadatos. + +## Gotchas + +- Inserta una linea en blanco entre el bloque frontmatter y el body (`---\n\n`). + En el round-trip con `parse_obsidian_frontmatter`, el body recuperado lleva + un salto de linea inicial extra; comparar con `.strip()` o asumir ese + separador. La inversa es "razonable", no byte-a-byte. +- `yaml.safe_dump` reformatea el YAML a su estilo canonico: las listas salen en + estilo bloque sin indentar (`tags:\n- a`), las claves no se reordenan + (`sort_keys=False`) y el unicode queda literal (`allow_unicode=True`). El + texto exacto del frontmatter original puede no preservarse aunque el mapping + si. +- Un dict vacio o `None` produce solo el body (sin `---`), coherente con que + `parse_obsidian_frontmatter` trate un frontmatter vacio como ausente. diff --git a/python/functions/obsidian/format_obsidian_note.py b/python/functions/obsidian/format_obsidian_note.py new file mode 100644 index 00000000..e6862ba9 --- /dev/null +++ b/python/functions/obsidian/format_obsidian_note.py @@ -0,0 +1,59 @@ +"""Serialize an Obsidian note from a frontmatter mapping and a body.""" + +import yaml + + +def format_obsidian_note(frontmatter: dict, body: str) -> str: + """Serialize a complete Obsidian note from frontmatter and body. + + When `frontmatter` is a non-empty mapping, the result is: + + ---\n---\n\n + + where `` is produced by + `yaml.safe_dump(frontmatter, sort_keys=False, allow_unicode=True)` (which + already ends in a newline). When `frontmatter` is empty or None, only the + body is returned. This is the inverse of `parse_obsidian_frontmatter` for a + reasonable round-trip (key order preserved, unicode kept literal). + + Pure and deterministic: no I/O, no mutation of the inputs. + + Args: + frontmatter: Mapping of YAML metadata for the note. Empty or None means + no frontmatter block is emitted. + body: The Markdown body of the note. + + Returns: + The full note text as a string. + """ + safe_body = body if body is not None else "" + + if not frontmatter: + return safe_body + + yaml_block = yaml.safe_dump(frontmatter, sort_keys=False, allow_unicode=True) + # yaml.safe_dump already terminates with a trailing newline. + return f"---\n{yaml_block}---\n\n{safe_body}" + + +if __name__ == "__main__": + out = format_obsidian_note({"title": "My Note", "tags": ["a", "b"]}, "Hello.") + assert out == "---\ntitle: My Note\ntags:\n- a\n- b\n---\n\nHello.", repr(out) + + # Empty frontmatter -> body only. + assert format_obsidian_note({}, "just a body") == "just a body" + assert format_obsidian_note(None, "just a body") == "just a body" + + # Round-trip with parse_obsidian_frontmatter: the frontmatter mapping is + # recovered exactly; the body is recovered modulo the blank separator line + # that the format inserts between the frontmatter block and the body. + from parse_obsidian_frontmatter import parse_obsidian_frontmatter + + fm = {"title": "Round Trip", "status": "open"} + body = "Body with a [[link]]." + note = format_obsidian_note(fm, body) + parsed = parse_obsidian_frontmatter(note) + assert parsed["frontmatter"] == fm, parsed + assert parsed["body"].strip() == body, repr(parsed["body"]) + + print("OK") diff --git a/python/functions/obsidian/format_obsidian_note_test.py b/python/functions/obsidian/format_obsidian_note_test.py new file mode 100644 index 00000000..310a7091 --- /dev/null +++ b/python/functions/obsidian/format_obsidian_note_test.py @@ -0,0 +1,40 @@ +"""Tests para format_obsidian_note.""" + +from format_obsidian_note import format_obsidian_note +from parse_obsidian_frontmatter import parse_obsidian_frontmatter + + +def test_con_frontmatter(): + out = format_obsidian_note({"title": "My Note", "tags": ["a", "b"]}, "Hello.") + assert out == "---\ntitle: My Note\ntags:\n- a\n- b\n---\n\nHello." + + +def test_frontmatter_vacio_devuelve_body(): + assert format_obsidian_note({}, "just a body") == "just a body" + + +def test_frontmatter_none_devuelve_body(): + assert format_obsidian_note(None, "just a body") == "just a body" + + +def test_preserva_orden_de_claves(): + fm = {"zeta": 1, "alpha": 2, "mid": 3} + out = format_obsidian_note(fm, "body") + # sort_keys=False -> insertion order preserved. + assert out.index("zeta") < out.index("alpha") < out.index("mid") + + +def test_unicode_literal(): + out = format_obsidian_note({"title": "Año Nuevo"}, "Cuerpo con ñ.") + assert "Año Nuevo" in out + assert "Cuerpo con ñ." in out + + +def test_round_trip_con_parse(): + fm = {"title": "Round Trip", "status": "open", "count": 3} + body = "Body with a [[link]] and #tag." + note = format_obsidian_note(fm, body) + parsed = parse_obsidian_frontmatter(note) + assert parsed["frontmatter"] == fm + # The format inserts a blank separator line before the body. + assert parsed["body"].strip() == body diff --git a/python/functions/obsidian/list_obsidian_notes.md b/python/functions/obsidian/list_obsidian_notes.md new file mode 100644 index 00000000..8e220da6 --- /dev/null +++ b/python/functions/obsidian/list_obsidian_notes.md @@ -0,0 +1,57 @@ +--- +name: list_obsidian_notes +kind: function +lang: py +domain: obsidian +version: "1.0.0" +purity: impure +signature: "list_obsidian_notes(vault_dir: str, subfolder: str = \"\", tag: str = \"\") -> list" +description: "Recorre recursivamente un vault de Obsidian (o un subfolder) y devuelve los paths absolutos de todas las notas .md, ordenados. Excluye siempre .obsidian/ y .trash/. Si se da tag, filtra a las notas cuyo frontmatter tags lo contenga (usa parse_obsidian_frontmatter)." +tags: [obsidian, notes, list, vault, frontmatter, filesystem] +uses_functions: ["parse_obsidian_frontmatter_py_obsidian"] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: ["os"] +params: + - name: vault_dir + desc: "path (absoluto o relativo) a la raiz del vault de Obsidian" + - name: subfolder + desc: "subcarpeta relativa dentro del vault a la que restringir el recorrido; vacio recorre todo el vault" + - name: tag + desc: "tag opcional; si no es vacio, solo devuelve notas cuyo frontmatter tags lo contenga (lista o escalar)" +output: "lista ordenada de paths absolutos a las notas .md que cumplen el filtro" +tested: false +tests: [] +test_file_path: "" +file_path: "python/functions/obsidian/list_obsidian_notes.py" +--- + +## Ejemplo + +```python +from obsidian import list_obsidian_notes + +# Todas las notas de un vault real +notas = list_obsidian_notes("/home/enmanuel/Obsidian/Finanzas") +print(len(notas), notas[:3]) + +# Solo las notas etiquetadas con #inversion +inversion = list_obsidian_notes("/home/enmanuel/Obsidian/Finanzas", tag="inversion") + +# Restringir a una subcarpeta del vault +plantillas = list_obsidian_notes("/home/enmanuel/Obsidian/Finanzas", subfolder="Plantillas") +``` + +## Cuando usarla + +Cuando necesites enumerar las notas de un vault de Obsidian (para indexar, exportar, contar o alimentar otra funcion) o filtrar por tag sin abrir Obsidian. Es el punto de entrada antes de leer/buscar contenido nota a nota. + +## Gotchas + +- **Impura**: lee el filesystem. Lanza `FileNotFoundError` si la ruta no existe y `NotADirectoryError` si no es un directorio. +- **Exclusion obligatoria**: `.obsidian/` y `.trash/` se podan del `os.walk` y nunca aparecen en el resultado; los `.md` internos de la config de Obsidian no se listan. +- **Coste en vaults grandes**: recorre todo el arbol. En vaults pesados como `NotasDeObsidian` (~554M) el `os.walk` completo es costoso; usa `subfolder` para acotar cuando puedas. +- **Filtro por tag**: cuando `tag` esta dado, ABRE cada nota para parsear su frontmatter — multiplica el coste de I/O. El campo `tags` se acepta como lista (`[a, b]`) o escalar (`a`); notas sin frontmatter o sin el tag se excluyen. +- Las notas con encoding invalido se leen con `errors="replace"`; el frontmatter ilegible se trata como ausente (la nota se excluye del filtro por tag). diff --git a/python/functions/obsidian/list_obsidian_notes.py b/python/functions/obsidian/list_obsidian_notes.py new file mode 100644 index 00000000..2c6b7729 --- /dev/null +++ b/python/functions/obsidian/list_obsidian_notes.py @@ -0,0 +1,111 @@ +"""List the Markdown notes inside an Obsidian vault, optionally filtered by tag.""" + +import os + +from obsidian import parse_obsidian_frontmatter + +# Directories that are part of Obsidian's machinery, never user notes. +_EXCLUDED_DIRS = {".obsidian", ".trash"} + + +def list_obsidian_notes(vault_dir: str, subfolder: str = "", tag: str = "") -> list: + """Return the absolute paths of every Markdown note under an Obsidian vault. + + Walks ``vault_dir`` (or ``vault_dir/subfolder`` when ``subfolder`` is given) + recursively and collects every ``.md`` file. The ``.obsidian/`` and + ``.trash/`` directories are always pruned from the walk so their internal + files never appear in the result. + + When ``tag`` is provided, only notes whose frontmatter ``tags`` field + contains that tag are kept. The frontmatter is read with + ``parse_obsidian_frontmatter`` (the registry's pure parser). The ``tags`` + field may be a list (``[a, b]``) or a single scalar (``a``); both forms are + handled. Notes without frontmatter or without the tag are excluded. + + Impure: it reads the filesystem. Raises ``FileNotFoundError`` if the root + directory does not exist and ``NotADirectoryError`` if it is not a directory. + + Args: + vault_dir: Absolute or relative path to the vault root. + subfolder: Optional relative subfolder inside the vault to restrict the + walk to. Empty string walks the whole vault. + tag: Optional tag. When non-empty, only notes whose frontmatter ``tags`` + contains it are returned. + + Returns: + A sorted list of absolute paths to the matching ``.md`` notes. + """ + root = os.path.join(vault_dir, subfolder) if subfolder else vault_dir + root = os.path.abspath(root) + + if not os.path.exists(root): + raise FileNotFoundError(f"vault path does not exist: {root}") + if not os.path.isdir(root): + raise NotADirectoryError(f"vault path is not a directory: {root}") + + notes: list[str] = [] + for dirpath, dirnames, filenames in os.walk(root): + # Prune Obsidian machinery in-place so os.walk never descends into them. + dirnames[:] = [d for d in dirnames if d not in _EXCLUDED_DIRS] + for filename in filenames: + if not filename.lower().endswith(".md"): + continue + full = os.path.abspath(os.path.join(dirpath, filename)) + if not tag: + notes.append(full) + continue + if _note_has_tag(full, tag): + notes.append(full) + + return sorted(notes) + + +def _note_has_tag(note_path: str, tag: str) -> bool: + """Return True if the note's frontmatter ``tags`` contains ``tag``.""" + try: + with open(note_path, "r", encoding="utf-8", errors="replace") as handle: + content = handle.read() + except OSError: + return False + + frontmatter = parse_obsidian_frontmatter(content).get("frontmatter", {}) + tags = frontmatter.get("tags") + if tags is None: + return False + if isinstance(tags, str): + return tags == tag + if isinstance(tags, (list, tuple, set)): + return tag in tags + return False + + +if __name__ == "__main__": + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + os.makedirs(os.path.join(tmp, ".obsidian")) + os.makedirs(os.path.join(tmp, "sub")) + # A note in .obsidian must never be listed. + with open(os.path.join(tmp, ".obsidian", "ignored.md"), "w") as f: + f.write("should be excluded") + with open(os.path.join(tmp, "a.md"), "w") as f: + f.write("---\ntags:\n - work\n - todo\n---\nbody A") + with open(os.path.join(tmp, "sub", "b.md"), "w") as f: + f.write("---\ntags: personal\n---\nbody B") + with open(os.path.join(tmp, "c.md"), "w") as f: + f.write("no frontmatter") + + all_notes = list_obsidian_notes(tmp) + assert len(all_notes) == 3, all_notes + assert all(".obsidian" not in p for p in all_notes), all_notes + + work = list_obsidian_notes(tmp, tag="work") + assert len(work) == 1 and work[0].endswith("a.md"), work + + personal = list_obsidian_notes(tmp, tag="personal") + assert len(personal) == 1 and personal[0].endswith("b.md"), personal + + only_sub = list_obsidian_notes(tmp, subfolder="sub") + assert len(only_sub) == 1 and only_sub[0].endswith("b.md"), only_sub + + print("OK") diff --git a/python/functions/obsidian/list_obsidian_vaults.md b/python/functions/obsidian/list_obsidian_vaults.md new file mode 100644 index 00000000..a6c80b7c --- /dev/null +++ b/python/functions/obsidian/list_obsidian_vaults.md @@ -0,0 +1,47 @@ +--- +name: list_obsidian_vaults +kind: function +lang: py +domain: obsidian +version: "1.0.0" +purity: impure +signature: "list_obsidian_vaults(base_dir: str) -> list" +description: "Devuelve los vaults de Obsidian que cuelgan directamente (1 nivel) de base_dir: subdirectorios que contienen un .obsidian/. Devuelve lista de {name, path} ordenada por name. Util para enumerar /home/enmanuel/Obsidian/." +tags: [obsidian, vault, list, discover, filesystem] +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: ["os"] +params: + - name: base_dir + desc: "directorio que contiene vaults de Obsidian como subcarpetas (p.ej. /home/enmanuel/Obsidian)" +output: "lista de dicts {name, path} (uno por vault), ordenada por name; path es absoluto" +tested: false +tests: [] +test_file_path: "" +file_path: "python/functions/obsidian/list_obsidian_vaults.py" +--- + +## Ejemplo + +```python +from obsidian import list_obsidian_vaults + +vaults = list_obsidian_vaults("/home/enmanuel/Obsidian") +for v in vaults: + print(v["name"], "->", v["path"]) +# NotasDeObsidian, AurgiObsidian, DataScientist, Finanzas, LLM_agentes +``` + +## Cuando usarla + +Cuando necesites descubrir que vaults de Obsidian existen bajo una carpeta raiz (por ejemplo para construir un selector, iterar sobre todos los vaults, o validar que un nombre de vault existe) sin abrir Obsidian. + +## Gotchas + +- **Impura**: lee el filesystem. Lanza `FileNotFoundError` si `base_dir` no existe y `NotADirectoryError` si no es un directorio. +- **Solo 1 nivel**: inspecciona unicamente los hijos inmediatos de `base_dir`; no es recursivo, asi que un vault anidado dentro de otro vault no se detecta. Esto es intencional para evitar recorrer arboles pesados. +- **Criterio de vault**: una carpeta cuenta como vault solo si contiene un subdirectorio `.obsidian/` (la carpeta de config que crea Obsidian). Carpetas con solo notas `.md` pero sin `.obsidian/` no se consideran vaults. +- No abre las notas ni recorre su contenido, asi que es barato incluso cuando algun vault es enorme (`NotasDeObsidian` ~554M): solo mira la presencia de `.obsidian/`. diff --git a/python/functions/obsidian/list_obsidian_vaults.py b/python/functions/obsidian/list_obsidian_vaults.py new file mode 100644 index 00000000..f0408349 --- /dev/null +++ b/python/functions/obsidian/list_obsidian_vaults.py @@ -0,0 +1,60 @@ +"""Discover the Obsidian vaults that live directly under a base directory.""" + +import os + + +def list_obsidian_vaults(base_dir: str) -> list: + """Return the Obsidian vaults found one level below ``base_dir``. + + A directory is considered an Obsidian vault when it contains an + ``.obsidian/`` subdirectory (the folder Obsidian creates to hold its + per-vault configuration). Only the immediate children of ``base_dir`` are + inspected; the search is not recursive, so nested vaults inside a vault are + not reported. + + Impure: it reads the filesystem. Raises ``FileNotFoundError`` if + ``base_dir`` does not exist and ``NotADirectoryError`` if it is not a + directory. + + Args: + base_dir: Directory that holds Obsidian vaults as subfolders, e.g. + ``/home/enmanuel/Obsidian``. + + Returns: + A list of dicts ``{"name": str, "path": str}`` (one per vault), sorted + by name. ``path`` is the absolute path of the vault directory. + """ + base = os.path.abspath(base_dir) + if not os.path.exists(base): + raise FileNotFoundError(f"base directory does not exist: {base}") + if not os.path.isdir(base): + raise NotADirectoryError(f"base path is not a directory: {base}") + + vaults: list[dict] = [] + for entry in os.scandir(base): + if not entry.is_dir(): + continue + if os.path.isdir(os.path.join(entry.path, ".obsidian")): + vaults.append({"name": entry.name, "path": os.path.abspath(entry.path)}) + + vaults.sort(key=lambda v: v["name"]) + return vaults + + +if __name__ == "__main__": + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + # Two real vaults, one plain dir, one file. + os.makedirs(os.path.join(tmp, "VaultA", ".obsidian")) + os.makedirs(os.path.join(tmp, "VaultB", ".obsidian")) + os.makedirs(os.path.join(tmp, "NotAVault")) + with open(os.path.join(tmp, "loose.md"), "w") as f: + f.write("not a dir") + + vaults = list_obsidian_vaults(tmp) + names = [v["name"] for v in vaults] + assert names == ["VaultA", "VaultB"], names + assert all(os.path.isabs(v["path"]) for v in vaults), vaults + + print("OK") diff --git a/python/functions/obsidian/parse_obsidian_frontmatter.md b/python/functions/obsidian/parse_obsidian_frontmatter.md new file mode 100644 index 00000000..af89b3f0 --- /dev/null +++ b/python/functions/obsidian/parse_obsidian_frontmatter.md @@ -0,0 +1,65 @@ +--- +name: parse_obsidian_frontmatter +kind: function +lang: py +domain: obsidian +version: "1.0.0" +purity: pure +signature: "def parse_obsidian_frontmatter(content: str) -> dict" +description: "Separa una nota de Obsidian (Markdown plano) en su frontmatter YAML y su cuerpo. Parsea el bloque YAML delimitado por --- al inicio del archivo con yaml.safe_load. Si no hay frontmatter valido al inicio, devuelve frontmatter vacio y el contenido completo como body. Soporta finales de linea \\n y \\r\\n. Pura, sin I/O." +tags: [obsidian, frontmatter, yaml, markdown, parse, note] +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "" +imports: ["yaml"] +params: + - name: content + desc: "Texto completo de una nota de Obsidian/Markdown. El frontmatter, si existe, debe ser un bloque YAML delimitado por lineas '---' que empieza en la primera linea del archivo." +output: "Dict con dos claves: 'frontmatter' (dict con el mapping YAML parseado, o {} si no hay frontmatter valido) y 'body' (str con el cuerpo de la nota tras el bloque frontmatter, o el contenido completo cuando no hay frontmatter valido)." +tested: true +tests: + - "frontmatter basico" + - "crlf line endings" + - "sin frontmatter devuelve content completo" + - "frontmatter sin cierre es body" + - "frontmatter vacio" + - "yaml invalido es body" + - "content vacio" +test_file_path: "python/functions/obsidian/parse_obsidian_frontmatter_test.py" +file_path: "python/functions/obsidian/parse_obsidian_frontmatter.py" +--- + +## Ejemplo + +```python +note = "---\ntitle: My Note\ntags:\n - a\n - b\n---\n\nHello [[other]]." +result = parse_obsidian_frontmatter(note) +# { +# "frontmatter": {"title": "My Note", "tags": ["a", "b"]}, +# "body": "\nHello [[other]].", +# } + +plain = "just a body, no frontmatter" +parse_obsidian_frontmatter(plain) +# {"frontmatter": {}, "body": "just a body, no frontmatter"} +``` + +## Cuando usarla + +Usala al leer una nota de Obsidian desde disco cuando necesites acceder a sus +metadatos YAML (tags, aliases, status, fechas) por separado del texto, o antes +de modificar el frontmatter y volver a serializar con `format_obsidian_note`. +Es el primer paso del round-trip parse -> modificar -> format. + +## Gotchas + +- Un bloque frontmatter vacio (`---\n---`) parsea a `None` en YAML, que no es + un dict, por lo que se trata como "sin frontmatter" y el contenido completo + vuelve como body. Esto es intencional para mantener la inversa con + `format_obsidian_note` (que omite frontmatter vacio). +- El `---` de apertura debe estar en la primera linea exacta del contenido. Un + `---` precedido de lineas en blanco o texto NO se considera frontmatter. +- YAML invalido se trata como "sin frontmatter": devuelve el contenido como + body en lugar de lanzar excepcion (funcion pura, sin error_type). diff --git a/python/functions/obsidian/parse_obsidian_frontmatter.py b/python/functions/obsidian/parse_obsidian_frontmatter.py new file mode 100644 index 00000000..9c20b2dc --- /dev/null +++ b/python/functions/obsidian/parse_obsidian_frontmatter.py @@ -0,0 +1,80 @@ +"""Parse the YAML frontmatter of an Obsidian note treated as plain Markdown.""" + +import yaml + + +def parse_obsidian_frontmatter(content: str) -> dict: + """Split an Obsidian note into its YAML frontmatter and body. + + The frontmatter is the YAML block delimited by `---` lines at the very + start of the file. It is parsed with `yaml.safe_load`. If there is no + valid frontmatter block at the start of the content (no leading `---`, + no closing `---`, or the YAML does not parse into a mapping), the whole + content is returned as the body and the frontmatter is an empty dict. + + Supports both `\\n` and `\\r\\n` line endings. Pure and deterministic: + no I/O, no mutation of the input. + + Args: + content: Full text of an Obsidian/Markdown note. + + Returns: + A dict with two keys: + - "frontmatter": the parsed YAML mapping (dict), or {} if absent. + - "body": the note body after the frontmatter block, or the full + content when there is no valid frontmatter. + """ + if not content: + return {"frontmatter": {}, "body": content} + + # Normalize line endings for splitting without mutating the original body. + normalized = content.replace("\r\n", "\n").replace("\r", "\n") + lines = normalized.split("\n") + + # Frontmatter must start on the very first line with an exact `---`. + if not lines or lines[0].strip() != "---": + return {"frontmatter": {}, "body": content} + + # Find the closing `---` delimiter. + closing_index = None + for i in range(1, len(lines)): + if lines[i].strip() == "---": + closing_index = i + break + + if closing_index is None: + return {"frontmatter": {}, "body": content} + + yaml_block = "\n".join(lines[1:closing_index]) + body = "\n".join(lines[closing_index + 1:]) + + try: + parsed = yaml.safe_load(yaml_block) + except yaml.YAMLError: + return {"frontmatter": {}, "body": content} + + if not isinstance(parsed, dict): + return {"frontmatter": {}, "body": content} + + return {"frontmatter": parsed, "body": body} + + +if __name__ == "__main__": + note = "---\ntitle: My Note\ntags:\n - a\n - b\n---\n\nHello [[other]]." + result = parse_obsidian_frontmatter(note) + assert result["frontmatter"] == {"title": "My Note", "tags": ["a", "b"]} + assert result["body"] == "\nHello [[other]]." + + # CRLF line endings. + crlf = "---\r\ntitle: X\r\n---\r\nbody line" + assert parse_obsidian_frontmatter(crlf)["frontmatter"] == {"title": "X"} + + # No frontmatter -> body is the full content. + plain = "just a body, no frontmatter" + assert parse_obsidian_frontmatter(plain) == {"frontmatter": {}, "body": plain} + + # Unterminated frontmatter -> treated as plain body. + broken = "---\ntitle: X\nno closing delimiter" + assert parse_obsidian_frontmatter(broken) == {"frontmatter": {}, "body": broken} + + print("OK") diff --git a/python/functions/obsidian/parse_obsidian_frontmatter_test.py b/python/functions/obsidian/parse_obsidian_frontmatter_test.py new file mode 100644 index 00000000..fcd91ad8 --- /dev/null +++ b/python/functions/obsidian/parse_obsidian_frontmatter_test.py @@ -0,0 +1,47 @@ +"""Tests para parse_obsidian_frontmatter.""" + +from parse_obsidian_frontmatter import parse_obsidian_frontmatter + + +def test_frontmatter_basico(): + note = "---\ntitle: My Note\ntags:\n - a\n - b\n---\n\nHello [[other]]." + result = parse_obsidian_frontmatter(note) + assert result["frontmatter"] == {"title": "My Note", "tags": ["a", "b"]} + assert result["body"] == "\nHello [[other]]." + + +def test_crlf_line_endings(): + crlf = "---\r\ntitle: X\r\nstatus: done\r\n---\r\nbody line\r\nsecond line" + result = parse_obsidian_frontmatter(crlf) + assert result["frontmatter"] == {"title": "X", "status": "done"} + assert "body line" in result["body"] + + +def test_sin_frontmatter_devuelve_content_completo(): + plain = "just a body, no frontmatter\nwith two lines" + result = parse_obsidian_frontmatter(plain) + assert result == {"frontmatter": {}, "body": plain} + + +def test_frontmatter_sin_cierre_es_body(): + broken = "---\ntitle: X\nno closing delimiter\nmore text" + result = parse_obsidian_frontmatter(broken) + assert result == {"frontmatter": {}, "body": broken} + + +def test_frontmatter_vacio(): + empty = "---\n---\nbody after empty frontmatter" + result = parse_obsidian_frontmatter(empty) + # An empty YAML block parses to None (not a dict) -> treated as no frontmatter. + assert result == {"frontmatter": {}, "body": empty} + + +def test_yaml_invalido_es_body(): + bad = "---\nthis: is: invalid: yaml: ::\n---\nbody" + result = parse_obsidian_frontmatter(bad) + assert result == {"frontmatter": {}, "body": bad} + + +def test_content_vacio(): + result = parse_obsidian_frontmatter("") + assert result == {"frontmatter": {}, "body": ""} diff --git a/python/functions/obsidian/read_obsidian_note.md b/python/functions/obsidian/read_obsidian_note.md new file mode 100644 index 00000000..a1877ecf --- /dev/null +++ b/python/functions/obsidian/read_obsidian_note.md @@ -0,0 +1,55 @@ +--- +name: read_obsidian_note +kind: function +lang: py +domain: obsidian +version: "1.0.0" +purity: impure +signature: "def read_obsidian_note(path: str) -> dict" +description: "Lee una nota Markdown de Obsidian desde disco y la descompone en frontmatter YAML, body, wikilinks [[...]] y tags normalizados. Compone las funciones puras parse_obsidian_frontmatter y extract_obsidian_wikilinks. No depende de la app GUI de Obsidian: solo lee el archivo .md plano." +tags: [obsidian, markdown, frontmatter, wikilinks, read, notes] +uses_functions: ["parse_obsidian_frontmatter_py_obsidian", "extract_obsidian_wikilinks_py_obsidian"] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: ["os"] +params: + - name: path + desc: "ruta al archivo .md de la nota a leer" +output: "dict con path (str), frontmatter (dict), body (str), wikilinks (list de destinos [[...]]) y tags (list normalizada desde frontmatter['tags'], acepta CSV o lista)" +tested: true +tests: + - "lee nota con frontmatter y wikilinks" + - "normaliza tags csv a lista" + - "nota sin frontmatter" + - "archivo inexistente lanza filenotfounderror" + - "directorio lanza isadirectoryerror" +test_file_path: "python/functions/obsidian/read_obsidian_note_test.py" +file_path: "python/functions/obsidian/read_obsidian_note.py" +--- + +## Ejemplo + +```python +import sys, os +sys.path.insert(0, os.path.join("python", "functions")) +from obsidian import read_obsidian_note + +note = read_obsidian_note("/home/me/vault/Proyectos/Idea.md") +print(note["frontmatter"]) # {'title': 'Idea', 'tags': ['proyecto', 'wip']} +print(note["tags"]) # ['proyecto', 'wip'] +print(note["wikilinks"]) # ['Nota Relacionada', 'Otra Idea'] +print(note["body"][:80]) # primeras lineas del cuerpo Markdown +``` + +## Cuando usarla + +Cuando necesites cargar el contenido de una nota de Obsidian de forma estructurada: leer su frontmatter, su cuerpo, los wikilinks que apunta o sus tags. Es el primer paso natural antes de actualizar una nota (`update_obsidian_note`) o de construir un grafo de enlaces a partir de los `wikilinks`. + +## Gotchas + +- **Lee de disco** (I/O impuro): el resultado refleja el estado del archivo en ese instante. +- **No respeta locks de la app GUI**: si Obsidian esta abierto y tiene la nota con cambios sin guardar, leeras la version persistida en disco, no la del editor en memoria. +- Lanza `FileNotFoundError` si el path no existe e `IsADirectoryError` si apunta a un directorio. +- `tags` se normaliza siempre a lista: acepta tanto `tags: proyecto, wip` (CSV) como `tags: [proyecto, wip]` (lista YAML). Otros tipos se convierten a string en un unico tag. diff --git a/python/functions/obsidian/read_obsidian_note.py b/python/functions/obsidian/read_obsidian_note.py new file mode 100644 index 00000000..885fc9ca --- /dev/null +++ b/python/functions/obsidian/read_obsidian_note.py @@ -0,0 +1,84 @@ +"""Lee una nota de Obsidian (.md) desde disco y la descompone en sus partes. + +Compone funciones puras del grupo obsidian: parse_obsidian_frontmatter y +extract_obsidian_wikilinks. Funcion impura: hace I/O de lectura de archivo. +""" + +import os + +from obsidian import extract_obsidian_wikilinks, parse_obsidian_frontmatter + + +def _normalize_tags(raw) -> list: + """Normaliza el campo tags del frontmatter a una lista de strings. + + Acepta None, un string CSV ("a, b, c") o una lista. Devuelve siempre + una lista de strings sin espacios sobrantes y sin entradas vacias. + """ + if raw is None: + return [] + if isinstance(raw, str): + return [t.strip() for t in raw.split(",") if t.strip()] + if isinstance(raw, (list, tuple)): + return [str(t).strip() for t in raw if str(t).strip()] + # Cualquier otro tipo (int, etc.) -> representacion como unico tag. + return [str(raw).strip()] if str(raw).strip() else [] + + +def read_obsidian_note(path: str) -> dict: + """Lee una nota Markdown de Obsidian y devuelve sus partes estructuradas. + + Args: + path: ruta al archivo .md a leer. + + Returns: + dict con las claves: + - path: la ruta leida (tal cual fue pasada). + - frontmatter: dict con el frontmatter YAML parseado. + - body: str con el cuerpo Markdown sin el frontmatter. + - wikilinks: list con los destinos de los wikilinks [[...]] del body. + - tags: list normalizada a partir de frontmatter["tags"]. + + Raises: + FileNotFoundError: si el archivo no existe. + IsADirectoryError: si la ruta apunta a un directorio. + OSError: si la lectura falla por otro motivo de I/O. + """ + if not os.path.exists(path): + raise FileNotFoundError(f"obsidian note not found: {path}") + if os.path.isdir(path): + raise IsADirectoryError(f"expected a file, got a directory: {path}") + + with open(path, "r", encoding="utf-8") as f: + content = f.read() + + parsed = parse_obsidian_frontmatter(content) + frontmatter = parsed.get("frontmatter", {}) or {} + body = parsed.get("body", "") or "" + + wikilinks = extract_obsidian_wikilinks(body) + tags = _normalize_tags(frontmatter.get("tags")) + + return { + "path": path, + "frontmatter": frontmatter, + "body": body, + "wikilinks": wikilinks, + "tags": tags, + } + + +if __name__ == "__main__": + import tempfile + + sample = "---\ntitle: Demo\ntags: [a, b]\n---\n\nHola [[Otra Nota]] y [[Tercera]].\n" + fd, tmp = tempfile.mkstemp(suffix=".md") + os.close(fd) + with open(tmp, "w", encoding="utf-8") as f: + f.write(sample) + note = read_obsidian_note(tmp) + assert note["frontmatter"].get("title") == "Demo", note["frontmatter"] + assert note["tags"] == ["a", "b"], note["tags"] + assert "Otra Nota" in note["wikilinks"], note["wikilinks"] + os.remove(tmp) + print("read_obsidian_note smoke OK") diff --git a/python/functions/obsidian/read_obsidian_note_test.py b/python/functions/obsidian/read_obsidian_note_test.py new file mode 100644 index 00000000..57d30bfa --- /dev/null +++ b/python/functions/obsidian/read_obsidian_note_test.py @@ -0,0 +1,61 @@ +"""Tests para read_obsidian_note.""" + +import pytest + +from read_obsidian_note import read_obsidian_note + + +def _write(path, content): + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(content, encoding="utf-8") + return str(path) + + +def test_lee_nota_con_frontmatter_y_wikilinks(tmp_path): + # Golden path: nota con frontmatter YAML + body con wikilinks. + note = _write( + tmp_path / "Idea.md", + "---\ntitle: Idea\ntags: [proyecto, wip]\n---\n\n" + "Cuerpo con [[Otra Nota]] y [[Tercera|alias]].", + ) + result = read_obsidian_note(note) + + assert result["path"] == note + assert result["frontmatter"]["title"] == "Idea" + assert result["tags"] == ["proyecto", "wip"] + assert result["wikilinks"] == ["Otra Nota", "Tercera"] + assert "Cuerpo con" in result["body"] + + +def test_normaliza_tags_csv_a_lista(tmp_path): + # Edge: tags como CSV en vez de lista YAML. + note = _write( + tmp_path / "CSV.md", + "---\ntitle: CSV\ntags: proyecto, wip , done\n---\n\nTexto.", + ) + result = read_obsidian_note(note) + assert result["tags"] == ["proyecto", "wip", "done"] + + +def test_nota_sin_frontmatter(tmp_path): + # Edge: nota plana sin frontmatter -> frontmatter vacio, tags vacios. + note = _write(tmp_path / "Plana.md", "Solo cuerpo, [[Enlace]] suelto.") + result = read_obsidian_note(note) + assert result["frontmatter"] == {} + assert result["tags"] == [] + assert result["wikilinks"] == ["Enlace"] + assert result["body"] == "Solo cuerpo, [[Enlace]] suelto." + + +def test_archivo_inexistente_lanza_filenotfounderror(tmp_path): + # Error path: ruta inexistente. + with pytest.raises(FileNotFoundError): + read_obsidian_note(str(tmp_path / "no_existe.md")) + + +def test_directorio_lanza_isadirectoryerror(tmp_path): + # Error path: ruta a directorio, no archivo. + sub = tmp_path / "carpeta" + sub.mkdir() + with pytest.raises(IsADirectoryError): + read_obsidian_note(str(sub)) diff --git a/python/functions/obsidian/resolve_obsidian_embed.md b/python/functions/obsidian/resolve_obsidian_embed.md new file mode 100644 index 00000000..112f9c01 --- /dev/null +++ b/python/functions/obsidian/resolve_obsidian_embed.md @@ -0,0 +1,71 @@ +--- +name: resolve_obsidian_embed +kind: function +lang: py +domain: obsidian +version: "1.0.0" +purity: impure +signature: "def resolve_obsidian_embed(vault_dir: str, embed_name: str) -> str" +description: "Resuelve el path absoluto real de un attachment embebido buscandolo por nombre dentro de un vault de Obsidian. Obsidian resuelve los embeds ![[...]] por nombre de archivo unico (no por path), asi que esta funcion recorre el vault recursivamente (una pasada con os.walk) y devuelve el primer archivo cuyo basename coincida (case-insensitive), excluyendo .obsidian/ y .trash/. Si el embed no trae extension, acepta cualquier match de ese basename. Devuelve cadena vacia si no existe (NO lanza). Lanza si vault_dir no existe. No depende de la app GUI." +tags: [obsidian, embed, attachment, resolve, filesystem, migrate] +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: ["os"] +params: + - name: vault_dir + desc: "ruta a la raiz del vault Obsidian donde buscar el attachment" + - name: embed_name + desc: "nombre del attachment embebido (el target de un ![[...]], lo que devuelve extract_obsidian_embeds), con o sin extension" +output: "string con el path absoluto del primer archivo del vault cuyo basename coincide (case-insensitive) con embed_name, o cadena vacia '' si ningun archivo coincide. Excluye .obsidian/ y .trash/." +tested: true +tests: + - "match exacto en subcarpeta" + - "match case insensitive" + - "sin extension acepta cualquier match" + - "no existe devuelve vacio" + - "excluye obsidian y trash" + - "vault inexistente lanza" +test_file_path: "python/functions/obsidian/resolve_obsidian_embed_test.py" +file_path: "python/functions/obsidian/resolve_obsidian_embed.py" +--- + +## Ejemplo + +```python +import sys, os +sys.path.insert(0, os.path.join("python", "functions")) +from obsidian import extract_obsidian_embeds, resolve_obsidian_embed + +body = "Mi DNI: ![[dni enmanuel (2).jpg]]" +for embed in extract_obsidian_embeds(body): + path = resolve_obsidian_embed("/home/me/MiVault", embed) + print(embed, "->", path or "(no encontrado)") +# dni enmanuel (2).jpg -> /home/me/MiVault/attachments/dni enmanuel (2).jpg +``` + +## Cuando usarla + +Usala junto a `extract_obsidian_embeds` cuando migres o extraigas un subgrafo de +notas y necesites el path fisico real de cada attachment para copiarlo al nuevo +destino. Replica la resolucion por-nombre de Obsidian sin abrir la app GUI: +basta con el directorio del vault en disco. + +## Gotchas + +- **Resuelve por NOMBRE de archivo, no por path.** Igual que Obsidian: busca el + basename en TODO el vault. Si hay dos archivos con el mismo nombre en carpetas + distintas (`fotos/logo.png` y `assets/logo.png`), devuelve el PRIMERO que + encuentra `os.walk` — el orden de `os.walk` no esta garantizado entre sistemas, + asi que con nombres duplicados el resultado puede no ser el embed que Obsidian + mostraria. Para vaults con nombres ambiguos, deduplica los nombres antes de + migrar. +- Si el embed no existe en el vault devuelve `""` (cadena vacia), NO lanza + excepcion. Comprueba el valor antes de usarlo como ruta. +- SI lanza `FileNotFoundError` / `NotADirectoryError` si `vault_dir` no existe o + no es un directorio. +- Es impura: recorre el filesystem en cada llamada. Si vas a resolver muchos + embeds del mismo vault, considera construir tu propio indice `basename -> path` + con un unico `os.walk` en lugar de llamar a esta funcion en bucle. diff --git a/python/functions/obsidian/resolve_obsidian_embed.py b/python/functions/obsidian/resolve_obsidian_embed.py new file mode 100644 index 00000000..481edb3d --- /dev/null +++ b/python/functions/obsidian/resolve_obsidian_embed.py @@ -0,0 +1,97 @@ +"""Resuelve el path absoluto real de un attachment embebido en un vault Obsidian. + +Funcion impura: recorre el filesystem del vault. Obsidian resuelve los embeds +![[...]] por nombre de archivo unico (no por path), asi que esta funcion busca +recursivamente un archivo cuyo basename coincida con el nombre del embed. +""" + +import os + +# Directorios de maquinaria de Obsidian que nunca contienen attachments de usuario. +_EXCLUDED_DIRS = {".obsidian", ".trash"} + + +def resolve_obsidian_embed(vault_dir: str, embed_name: str) -> str: + """Resuelve el path absoluto de un attachment embebido buscandolo por nombre. + + Obsidian resuelve los embeds `![[archivo.jpg]]` por nombre de archivo unico + dentro del vault, no por ruta. Esta funcion replica ese comportamiento: + recorre ``vault_dir`` recursivamente (una sola pasada con ``os.walk``) y + devuelve el primer archivo cuyo basename coincida, de forma + case-insensitive, con ``embed_name``. + + Si ``embed_name`` no trae extension (p.ej. ``"foto"``), se acepta cualquier + archivo cuyo basename sin extension coincida (p.ej. ``foto.jpg``). + + Los directorios ``.obsidian/`` y ``.trash/`` se excluyen del recorrido. + + Impura: lee el filesystem. NO lanza si el embed no se encuentra (devuelve + cadena vacia). SI lanza si ``vault_dir`` no existe. + + Args: + vault_dir: Ruta a la raiz del vault Obsidian. + embed_name: Nombre del attachment embebido (lo que devuelve + ``extract_obsidian_embeds``), con o sin extension. + + Returns: + El path absoluto del primer archivo que coincide, o cadena vacia ``""`` + si ningun archivo del vault coincide. + + Raises: + FileNotFoundError: si ``vault_dir`` no existe. + NotADirectoryError: si ``vault_dir`` no es un directorio. + """ + if not os.path.exists(vault_dir): + raise FileNotFoundError(f"vault path does not exist: {vault_dir}") + if not os.path.isdir(vault_dir): + raise NotADirectoryError(f"vault path is not a directory: {vault_dir}") + + target = embed_name.strip() + if not target: + return "" + + target_lower = target.lower() + has_extension = os.path.splitext(target)[1] != "" + target_stem_lower = os.path.splitext(target_lower)[0] + + for dirpath, dirnames, filenames in os.walk(vault_dir): + # Podar maquinaria de Obsidian in-place para no descender en ella. + dirnames[:] = [d for d in dirnames if d not in _EXCLUDED_DIRS] + for filename in filenames: + filename_lower = filename.lower() + if has_extension: + # Comparar basename completo, case-insensitive. + if filename_lower == target_lower: + return os.path.abspath(os.path.join(dirpath, filename)) + else: + # Sin extension en el embed: comparar solo el stem del archivo. + stem_lower = os.path.splitext(filename_lower)[0] + if stem_lower == target_stem_lower: + return os.path.abspath(os.path.join(dirpath, filename)) + + return "" + + +if __name__ == "__main__": + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + os.makedirs(os.path.join(tmp, "attachments")) + os.makedirs(os.path.join(tmp, ".obsidian")) + with open(os.path.join(tmp, "attachments", "Foto.JPG"), "w") as f: + f.write("x") + with open(os.path.join(tmp, "doc.pdf"), "w") as f: + f.write("y") + + # Match case-insensitive con extension. + hit = resolve_obsidian_embed(tmp, "foto.jpg") + assert hit.endswith(os.path.join("attachments", "Foto.JPG")), hit + + # Match sin extension en el embed. + hit2 = resolve_obsidian_embed(tmp, "doc") + assert hit2.endswith("doc.pdf"), hit2 + + # No existe -> "". + assert resolve_obsidian_embed(tmp, "no_existe.png") == "" + + print("resolve_obsidian_embed smoke OK") diff --git a/python/functions/obsidian/resolve_obsidian_embed_test.py b/python/functions/obsidian/resolve_obsidian_embed_test.py new file mode 100644 index 00000000..b2be6ba4 --- /dev/null +++ b/python/functions/obsidian/resolve_obsidian_embed_test.py @@ -0,0 +1,54 @@ +"""Tests para resolve_obsidian_embed.""" + +import os + +import pytest + +from resolve_obsidian_embed import resolve_obsidian_embed + + +def _write(path, content="x"): + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(content, encoding="utf-8") + return str(path) + + +def test_match_exacto_en_subcarpeta(tmp_path): + # Golden path: archivo en subcarpeta resuelto por nombre exacto. + target = _write(tmp_path / "attachments" / "imagen.jpg") + result = resolve_obsidian_embed(str(tmp_path), "imagen.jpg") + assert result == os.path.abspath(target) + + +def test_match_case_insensitive(tmp_path): + # Edge: el nombre en disco difiere en mayusculas/minusculas. + target = _write(tmp_path / "media" / "Foto.JPG") + result = resolve_obsidian_embed(str(tmp_path), "foto.jpg") + assert result == os.path.abspath(target) + + +def test_sin_extension_acepta_cualquier_match(tmp_path): + # Edge: embed sin extension -> coincide cualquier archivo con ese stem. + target = _write(tmp_path / "doc.pdf") + result = resolve_obsidian_embed(str(tmp_path), "doc") + assert result == os.path.abspath(target) + + +def test_no_existe_devuelve_vacio(tmp_path): + # Error de dominio (no excepcion): nombre inexistente -> "". + _write(tmp_path / "otra.png") + assert resolve_obsidian_embed(str(tmp_path), "no_existe.png") == "" + + +def test_excluye_obsidian_y_trash(tmp_path): + # Edge: archivos en .obsidian/ y .trash/ no se resuelven. + _write(tmp_path / ".obsidian" / "config.jpg") + _write(tmp_path / ".trash" / "borrada.jpg") + assert resolve_obsidian_embed(str(tmp_path), "config.jpg") == "" + assert resolve_obsidian_embed(str(tmp_path), "borrada.jpg") == "" + + +def test_vault_inexistente_lanza(tmp_path): + # Error path: vault_dir que no existe -> FileNotFoundError. + with pytest.raises(FileNotFoundError): + resolve_obsidian_embed(str(tmp_path / "no_vault"), "imagen.jpg") diff --git a/python/functions/obsidian/search_obsidian_notes.md b/python/functions/obsidian/search_obsidian_notes.md new file mode 100644 index 00000000..767a3de9 --- /dev/null +++ b/python/functions/obsidian/search_obsidian_notes.md @@ -0,0 +1,62 @@ +--- +name: search_obsidian_notes +kind: function +lang: py +domain: obsidian +version: "1.0.0" +purity: impure +signature: "search_obsidian_notes(vault_dir: str, query: str, in_body: bool = True, in_frontmatter: bool = True) -> list" +description: "Busca un substring (case-insensitive) en todas las notas .md de un vault de Obsidian, excluyendo .obsidian/ y .trash/. Devuelve por nota las lineas que contienen el query con su numero de linea. Los flags in_body/in_frontmatter acotan donde buscar." +tags: [obsidian, notes, search, grep, vault, frontmatter, filesystem] +uses_functions: ["parse_obsidian_frontmatter_py_obsidian"] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: ["os"] +params: + - name: vault_dir + desc: "path a la raiz del vault de Obsidian a buscar" + - name: query + desc: "substring a buscar (matcheado de forma case-insensitive); no puede ser vacio" + - name: in_body + desc: "buscar en el cuerpo de la nota cuando es True (defecto True)" + - name: in_frontmatter + desc: "buscar en el bloque de frontmatter cuando es True (defecto True)" +output: "lista de dicts {path, matches} (uno por nota con coincidencias), ordenada por path; cada match es {line, text} con numero de linea 1-based relativo al archivo completo" +tested: false +tests: [] +test_file_path: "" +file_path: "python/functions/obsidian/search_obsidian_notes.py" +--- + +## Ejemplo + +```python +from obsidian import search_obsidian_notes + +# Buscar "presupuesto" en todo el vault (frontmatter + cuerpo) +hits = search_obsidian_notes("/home/enmanuel/Obsidian/Finanzas", "presupuesto") +for h in hits: + print(h["path"]) + for m in h["matches"]: + print(f" L{m['line']}: {m['text']}") + +# Solo en el cuerpo, ignorando el frontmatter +solo_cuerpo = search_obsidian_notes( + "/home/enmanuel/Obsidian/Finanzas", "TODO", in_frontmatter=False +) +``` + +## Cuando usarla + +Cuando necesites un grep de un solo paso sobre un vault de Obsidian: encontrar en que notas aparece un termino y en que lineas, antes de abrir/editar. Util para auditar tags, localizar referencias o construir un indice de busqueda. + +## Gotchas + +- **Impura**: lee el filesystem. Lanza `ValueError` si `query` es vacio, `FileNotFoundError` si el vault no existe y `NotADirectoryError` si no es un directorio. +- **Exclusion obligatoria**: `.obsidian/` y `.trash/` se podan del recorrido; su contenido nunca se busca ni aparece en resultados. +- **Coste en vaults grandes**: abre y lee CADA nota `.md` linea a linea. En vaults pesados como `NotasDeObsidian` (~554M) esto recorre todo el contenido en memoria por archivo; puede tardar. Acota el vault o pre-filtra con `list_obsidian_notes` si necesitas rendimiento. +- **Numeros de linea**: son 1-based y relativos al archivo completo (incluyen las lineas del frontmatter `---`), de modo que mapean directamente sobre el archivo en disco aunque se busque solo en cuerpo o solo en frontmatter. +- La delimitacion frontmatter/cuerpo se calcula con `parse_obsidian_frontmatter`; si la nota no tiene frontmatter valido, todo se considera cuerpo. +- Archivos con encoding invalido se leen con `errors="replace"`. diff --git a/python/functions/obsidian/search_obsidian_notes.py b/python/functions/obsidian/search_obsidian_notes.py new file mode 100644 index 00000000..2d546620 --- /dev/null +++ b/python/functions/obsidian/search_obsidian_notes.py @@ -0,0 +1,138 @@ +"""Full-text substring search across the notes of an Obsidian vault.""" + +import os + +from obsidian import parse_obsidian_frontmatter + +# Directories that are part of Obsidian's machinery, never user notes. +_EXCLUDED_DIRS = {".obsidian", ".trash"} + + +def search_obsidian_notes( + vault_dir: str, + query: str, + in_body: bool = True, + in_frontmatter: bool = True, +) -> list: + """Search a case-insensitive substring across every note of a vault. + + Walks ``vault_dir`` recursively (pruning ``.obsidian/`` and ``.trash/``), + reads every ``.md`` note and looks for ``query`` as a case-insensitive + substring. Each line that contains the query is reported together with its + 1-based line number. + + The ``in_body`` and ``in_frontmatter`` flags control which part of a note is + searched. The frontmatter is delimited with ``parse_obsidian_frontmatter``: + its raw lines (between the opening and closing ``---``) are searched when + ``in_frontmatter`` is True, and the body lines when ``in_body`` is True. Line + numbers are always relative to the full file so they map directly onto the + note on disk. + + Impure: it reads the filesystem. Raises ``ValueError`` if ``query`` is empty, + ``FileNotFoundError`` if the vault does not exist and ``NotADirectoryError`` + if it is not a directory. + + Args: + vault_dir: Path to the vault root. + query: Substring to look for (matched case-insensitively). + in_body: Search the note body when True. + in_frontmatter: Search the note frontmatter block when True. + + Returns: + A list of dicts ``{"path": str, "matches": list}`` (one per matching + note), sorted by path. Each match is + ``{"line": int, "text": str}``. + """ + if not query: + raise ValueError("query must be a non-empty string") + + root = os.path.abspath(vault_dir) + if not os.path.exists(root): + raise FileNotFoundError(f"vault path does not exist: {root}") + if not os.path.isdir(root): + raise NotADirectoryError(f"vault path is not a directory: {root}") + + needle = query.lower() + results: list[dict] = [] + + for dirpath, dirnames, filenames in os.walk(root): + dirnames[:] = [d for d in dirnames if d not in _EXCLUDED_DIRS] + for filename in filenames: + if not filename.lower().endswith(".md"): + continue + full = os.path.abspath(os.path.join(dirpath, filename)) + matches = _search_note(full, needle, in_body, in_frontmatter) + if matches: + results.append({"path": full, "matches": matches}) + + results.sort(key=lambda r: r["path"]) + return results + + +def _frontmatter_line_count(content: str) -> int: + """Number of full-file lines occupied by the frontmatter block (0 if none). + + Counts the opening ``---``, the YAML lines and the closing ``---``. Returns + 0 when the note has no valid frontmatter (per ``parse_obsidian_frontmatter``). + """ + if parse_obsidian_frontmatter(content).get("frontmatter"): + normalized = content.replace("\r\n", "\n").replace("\r", "\n") + lines = normalized.split("\n") + if lines and lines[0].strip() == "---": + for i in range(1, len(lines)): + if lines[i].strip() == "---": + return i + 1 # inclusive of both delimiters + return 0 + + +def _search_note( + note_path: str, needle: str, in_body: bool, in_frontmatter: bool +) -> list: + """Return the matching lines (with 1-based line numbers) inside one note.""" + try: + with open(note_path, "r", encoding="utf-8", errors="replace") as handle: + content = handle.read() + except OSError: + return [] + + normalized = content.replace("\r\n", "\n").replace("\r", "\n") + lines = normalized.split("\n") + fm_lines = _frontmatter_line_count(content) + + matches: list[dict] = [] + for idx, text in enumerate(lines): + is_frontmatter = idx < fm_lines + if is_frontmatter and not in_frontmatter: + continue + if not is_frontmatter and not in_body: + continue + if needle in text.lower(): + matches.append({"line": idx + 1, "text": text}) + return matches + + +if __name__ == "__main__": + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + os.makedirs(os.path.join(tmp, ".obsidian")) + with open(os.path.join(tmp, ".obsidian", "noise.md"), "w") as f: + f.write("ALPHA hidden in obsidian config") + with open(os.path.join(tmp, "note.md"), "w") as f: + f.write("---\ntitle: Alpha note\n---\nfirst line\nsecond ALPHA line\n") + + hits = search_obsidian_notes(tmp, "alpha") + assert len(hits) == 1, hits # .obsidian note excluded + assert hits[0]["path"].endswith("note.md") + lines = [m["line"] for m in hits[0]["matches"]] + assert 2 in lines and 5 in lines, hits # frontmatter + body + + body_only = search_obsidian_notes(tmp, "alpha", in_frontmatter=False) + body_lines = [m["line"] for m in body_only[0]["matches"]] + assert body_lines == [5], body_only + + fm_only = search_obsidian_notes(tmp, "alpha", in_body=False) + fm_lines = [m["line"] for m in fm_only[0]["matches"]] + assert fm_lines == [2], fm_only + + print("OK") diff --git a/python/functions/obsidian/slugify_obsidian_name.md b/python/functions/obsidian/slugify_obsidian_name.md new file mode 100644 index 00000000..a7dfbd89 --- /dev/null +++ b/python/functions/obsidian/slugify_obsidian_name.md @@ -0,0 +1,61 @@ +--- +name: slugify_obsidian_name +kind: function +lang: py +domain: obsidian +version: "1.0.0" +purity: pure +signature: "def slugify_obsidian_name(name: str) -> str" +description: "Convierte un nombre o titulo a un slug kebab-case estable: transliteracion Unicode (NFKD + descarte de combining marks, mapeo explicito de ñ/Ñ -> n), minusculas, colapsa cualquier secuencia de caracteres no [a-z0-9] a un solo guion, y strip de guiones en los bordes. Sin guiones dobles. Deterministica, pura, sin I/O. Util para migrar notas de Obsidian a nombres de archivo/identificadores estables." +tags: [obsidian, slug, kebab-case, transliterate, unicode, normalize, migrate] +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "" +imports: ["re", "unicodedata"] +params: + - name: name + desc: "Nombre o titulo arbitrario (puede llevar acentos, mayusculas, espacios y simbolos). P.ej. el titulo de una nota de Obsidian que se quiere convertir en slug estable." +output: "String con el slug kebab-case: solo caracteres [a-z0-9-], sin guiones al inicio/fin ni guiones dobles. Cadena vacia si name no contiene ningun caracter slugificable." +tested: true +tests: + - "acentos y espacios" + - "enye se mapea a n" + - "mezcla mayusculas y acentos" + - "simbolos y dobles separadores" + - "string vacio" + - "solo simbolos devuelve vacio" +test_file_path: "python/functions/obsidian/slugify_obsidian_name_test.py" +file_path: "python/functions/obsidian/slugify_obsidian_name.py" +--- + +## Ejemplo + +```python +slugify_obsidian_name("Enmanuel Gutiérrez Pérez") # "enmanuel-gutierrez-perez" +slugify_obsidian_name("Jose manuel camaño castro") # "jose-manuel-camano-castro" +slugify_obsidian_name("DNI de María del Mar") # "dni-de-maria-del-mar" +slugify_obsidian_name(" raro__nombre!! ") # "raro-nombre" +``` + +## Cuando usarla + +Usala al migrar o extraer subgrafos de notas de Obsidian cuando necesites un +identificador estable a partir de un titulo: renombrar archivos `.md`, generar +claves de un mapa de equivalencias `titulo -> slug`, o crear nombres de carpeta +deterministas. Es pura, asi que sirve igual de bien para indexar, ordenar o +comparar nombres normalizados sin tocar disco. + +## Gotchas + +- Mapea `ñ`/`Ñ` -> `n` explicitamente porque `NFKD` NO descompone la enye en + `n` + tilde (la cedilla queda como combining mark sobre la `n` base ya + formada). Otros idiomas con letras especiales (ß, ø, đ) NO se transliteran: + caen bajo el colapso de no-`[a-z0-9]` y desaparecen. Si necesitas soportarlas, + amplia `_TRANSLIT_MAP`. +- Dos titulos distintos pueden colisionar en el mismo slug (`"Mi Nota!"` y + `"Mi Nota"` -> `"mi-nota"`). Si el slug debe ser unico en un vault, anade un + desambiguador (sufijo numerico) por fuera de esta funcion. +- No preserva ningun caracter no ASCII: emojis, ideogramas CJK, cirilico, etc. + se descartan. Un titulo formado solo por esos caracteres devuelve `""`. diff --git a/python/functions/obsidian/slugify_obsidian_name.py b/python/functions/obsidian/slugify_obsidian_name.py new file mode 100644 index 00000000..c4c915a9 --- /dev/null +++ b/python/functions/obsidian/slugify_obsidian_name.py @@ -0,0 +1,70 @@ +"""Convierte un nombre/titulo de Obsidian a un slug kebab-case estable. + +Funcion pura: transliteracion Unicode + normalizacion a [a-z0-9-]. No hace I/O. +""" + +import re +import unicodedata + +# Cualquier secuencia de caracteres que NO sea [a-z0-9] colapsa a un solo '-'. +_NON_SLUG_RE = re.compile(r"[^a-z0-9]+") + +# Mapeo explicito de caracteres que NFKD no descompone como queremos. +_TRANSLIT_MAP = { + "ñ": "n", + "Ñ": "n", +} + + +def slugify_obsidian_name(name: str) -> str: + """Convierte un nombre o titulo a un slug kebab-case estable. + + Pasos, en orden: + 1. Mapea caracteres especiales que NFKD no descompone (ñ/Ñ -> n). + 2. Normaliza con ``unicodedata.normalize('NFKD', ...)`` y descarta los + combining marks (acentos, diacriticos), transliterando a ASCII. + 3. Pasa todo a minusculas. + 4. Reemplaza cualquier secuencia de caracteres no ``[a-z0-9]`` por un + unico ``-``. + 5. Hace strip de ``-`` al inicio y al final. Nunca quedan guiones dobles. + + Es deterministica y pura: misma entrada -> mismo slug, sin efectos + secundarios ni I/O. + + Args: + name: Nombre o titulo arbitrario (puede llevar acentos, mayusculas, + espacios, simbolos). + + Returns: + El slug kebab-case correspondiente. Cadena vacia si ``name`` no + contiene ningun caracter slugificable. + """ + if not name: + return "" + + # 1. Mapeo explicito antes de NFKD (la cedilla de la enye se trataria mal). + for src, dst in _TRANSLIT_MAP.items(): + name = name.replace(src, dst) + + # 2. Transliteracion Unicode: descompone y descarta combining marks. + decomposed = unicodedata.normalize("NFKD", name) + ascii_only = "".join(ch for ch in decomposed if not unicodedata.combining(ch)) + + # 3. Minusculas. + lowered = ascii_only.lower() + + # 4. Colapsar todo lo no [a-z0-9] a un unico '-'. + slug = _NON_SLUG_RE.sub("-", lowered) + + # 5. Strip de guiones en los bordes. + return slug.strip("-") + + +if __name__ == "__main__": + assert slugify_obsidian_name("Enmanuel Gutiérrez Pérez") == "enmanuel-gutierrez-perez" + assert slugify_obsidian_name("Jose manuel camaño castro") == "jose-manuel-camano-castro" + assert slugify_obsidian_name("DNI de María del Mar") == "dni-de-maria-del-mar" + assert slugify_obsidian_name(" raro__nombre!! ") == "raro-nombre" + assert slugify_obsidian_name("") == "" + assert slugify_obsidian_name("!!!") == "" + print("slugify_obsidian_name smoke OK") diff --git a/python/functions/obsidian/slugify_obsidian_name_test.py b/python/functions/obsidian/slugify_obsidian_name_test.py new file mode 100644 index 00000000..c80ead6c --- /dev/null +++ b/python/functions/obsidian/slugify_obsidian_name_test.py @@ -0,0 +1,31 @@ +"""Tests para slugify_obsidian_name.""" + +from slugify_obsidian_name import slugify_obsidian_name + + +def test_acentos_y_espacios(): + # Golden path: transliteracion de acentos + espacios a kebab-case. + assert slugify_obsidian_name("Enmanuel Gutiérrez Pérez") == "enmanuel-gutierrez-perez" + + +def test_enye_se_mapea_a_n(): + # Edge: la enye no la descompone NFKD, la mapeamos explicitamente. + assert slugify_obsidian_name("Jose manuel camaño castro") == "jose-manuel-camano-castro" + + +def test_mezcla_mayusculas_y_acentos(): + assert slugify_obsidian_name("DNI de María del Mar") == "dni-de-maria-del-mar" + + +def test_simbolos_y_dobles_separadores(): + # Edge: secuencias de no-alfanumericos colapsan a un solo '-', strip en bordes. + assert slugify_obsidian_name(" raro__nombre!! ") == "raro-nombre" + + +def test_string_vacio(): + assert slugify_obsidian_name("") == "" + + +def test_solo_simbolos_devuelve_vacio(): + # Edge: nada slugificable -> cadena vacia, sin guiones colgando. + assert slugify_obsidian_name("!!!---???") == "" diff --git a/python/functions/obsidian/update_obsidian_note.md b/python/functions/obsidian/update_obsidian_note.md new file mode 100644 index 00000000..2fec9fa8 --- /dev/null +++ b/python/functions/obsidian/update_obsidian_note.md @@ -0,0 +1,64 @@ +--- +name: update_obsidian_note +kind: function +lang: py +domain: obsidian +version: "1.0.0" +purity: impure +signature: "def update_obsidian_note(path: str, body: str = None, set_frontmatter: dict = None, append: str = None) -> str" +description: "Actualiza una nota Markdown de Obsidian existente. Lee el estado actual con parse_obsidian_frontmatter, hace merge de claves del frontmatter (set_frontmatter), reemplaza el body (body) o concatena texto al final (append), y reescribe con la funcion pura format_obsidian_note. No depende de la app GUI de Obsidian: solo lee y reescribe el archivo .md plano." +tags: [obsidian, markdown, frontmatter, update, write, notes] +uses_functions: ["parse_obsidian_frontmatter_py_obsidian", "format_obsidian_note_py_obsidian"] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: ["os"] +params: + - name: path + desc: "ruta al archivo .md de la nota a actualizar" + - name: body + desc: "si no es None, reemplaza por completo el cuerpo de la nota" + - name: set_frontmatter + desc: "dict que se mergea (update de claves) sobre el frontmatter actual; las no mencionadas se conservan" + - name: append + desc: "texto que se concatena al final del cuerpo (separado por salto de linea); se aplica despues de body" +output: "la ruta (str) del archivo actualizado" +tested: true +tests: + - "merge frontmatter conserva claves previas" + - "reemplazo de body" + - "append concatena al final" + - "body y append combinados" + - "nota inexistente lanza filenotfounderror" + - "directorio lanza isadirectoryerror" +test_file_path: "python/functions/obsidian/update_obsidian_note_test.py" +file_path: "python/functions/obsidian/update_obsidian_note.py" +--- + +## Ejemplo + +```python +import sys, os +sys.path.insert(0, os.path.join("python", "functions")) +from obsidian import update_obsidian_note + +# Marcar como hecha y anadir una linea de log al final +update_obsidian_note( + "/home/me/vault/Tareas/Revisar PR.md", + set_frontmatter={"status": "done", "closed": "2026-06-09"}, + append="- Cerrada tras revisar [[PR 42]].", +) +``` + +## Cuando usarla + +Cuando necesites modificar una nota existente sin reescribirla entera: cambiar campos del frontmatter (status, fechas, tags), reemplazar el cuerpo, o ir anadiendo entradas a un log/diario al final. El merge de `set_frontmatter` permite tocar solo las claves que cambian sin perder el resto. + +## Gotchas + +- **Lee y reescribe en disco** (I/O impuro): sobreescribe el archivo completo con el contenido reserializado por `format_obsidian_note`. El formato/orden del frontmatter puede normalizarse respecto al original escrito a mano. +- **No respeta locks de la app GUI**: si Obsidian tiene la nota abierta con cambios sin guardar, esos cambios en memoria se perderan cuando esta funcion reescriba el archivo (la app puede recargarlo o sobreescribirlo de vuelta). Cierra/guarda en Obsidian antes de editar desde codigo. +- `set_frontmatter` hace **merge superficial** (`dict.update`): claves nuevas se anaden, existentes se reemplazan, las demas se conservan. No borra claves. +- `append` se aplica **despues** de un eventual reemplazo de `body`, garantizando un salto de linea de separacion. +- Lanza `FileNotFoundError` si la nota no existe (no la crea — usa `create_obsidian_note` para eso). diff --git a/python/functions/obsidian/update_obsidian_note.py b/python/functions/obsidian/update_obsidian_note.py new file mode 100644 index 00000000..012582fc --- /dev/null +++ b/python/functions/obsidian/update_obsidian_note.py @@ -0,0 +1,86 @@ +"""Actualiza una nota existente de Obsidian (.md) en disco. + +Compone funciones puras del grupo obsidian: parse_obsidian_frontmatter para +leer el estado actual y format_obsidian_note para reescribir. Funcion impura: +lee y reescribe un archivo en disco. +""" + +import os + +from obsidian import format_obsidian_note, parse_obsidian_frontmatter + + +def update_obsidian_note( + path: str, + body: str = None, + set_frontmatter: dict = None, + append: str = None, +) -> str: + """Actualiza una nota Markdown de Obsidian existente. + + Lee la nota actual, aplica las modificaciones pedidas y la reescribe. + + Args: + path: ruta al archivo .md a actualizar. + body: si se da (no None), reemplaza por completo el cuerpo de la nota. + set_frontmatter: si se da, hace merge (update de claves) sobre el + frontmatter actual. Las claves nuevas se anaden, las existentes se + sobreescriben. Las no mencionadas se conservan. + append: si se da, concatena este texto al final del cuerpo (separado + por un salto de linea). Se aplica DESPUES de un eventual reemplazo + de body. + + Returns: + La ruta del archivo actualizado. + + Raises: + FileNotFoundError: si la nota no existe. + IsADirectoryError: si la ruta apunta a un directorio. + OSError: si la lectura/escritura falla por otro motivo de I/O. + """ + if not os.path.exists(path): + raise FileNotFoundError(f"obsidian note not found: {path}") + if os.path.isdir(path): + raise IsADirectoryError(f"expected a file, got a directory: {path}") + + with open(path, "r", encoding="utf-8") as f: + content = f.read() + + parsed = parse_obsidian_frontmatter(content) + frontmatter = dict(parsed.get("frontmatter", {}) or {}) + current_body = parsed.get("body", "") or "" + + if set_frontmatter: + frontmatter.update(set_frontmatter) + + new_body = current_body if body is None else body + + if append is not None: + if new_body and not new_body.endswith("\n"): + new_body = new_body + "\n" + append + else: + new_body = new_body + append + + new_content = format_obsidian_note(frontmatter, new_body) + + with open(path, "w", encoding="utf-8") as f: + f.write(new_content) + + return path + + +if __name__ == "__main__": + import tempfile + + fd, tmp = tempfile.mkstemp(suffix=".md") + os.close(fd) + with open(tmp, "w", encoding="utf-8") as f: + f.write("---\ntitle: A\n---\n\nLinea original.") + update_obsidian_note(tmp, set_frontmatter={"status": "wip"}, append="Linea nueva.") + with open(tmp, "r", encoding="utf-8") as f: + out = f.read() + assert "status" in out, out + assert "Linea nueva." in out, out + assert "Linea original." in out, out + os.remove(tmp) + print("update_obsidian_note smoke OK") diff --git a/python/functions/obsidian/update_obsidian_note_test.py b/python/functions/obsidian/update_obsidian_note_test.py new file mode 100644 index 00000000..8336fc92 --- /dev/null +++ b/python/functions/obsidian/update_obsidian_note_test.py @@ -0,0 +1,72 @@ +"""Tests para update_obsidian_note.""" + +import pytest + +from read_obsidian_note import read_obsidian_note +from update_obsidian_note import update_obsidian_note + + +def _seed(tmp_path, name="Nota.md", content="---\ntitle: A\nstatus: open\n---\n\nLinea original."): + path = tmp_path / name + path.write_text(content, encoding="utf-8") + return str(path) + + +def test_merge_frontmatter_conserva_claves_previas(tmp_path): + # Golden path: set_frontmatter mergea sin perder claves no mencionadas. + note = _seed(tmp_path) + ret = update_obsidian_note( + note, set_frontmatter={"status": "done", "closed": "2026-06-09"} + ) + assert ret == note + + fm = read_obsidian_note(note)["frontmatter"] + assert fm["title"] == "A" # clave previa conservada + assert fm["status"] == "done" # clave existente sobreescrita + assert fm["closed"] == "2026-06-09" # clave nueva anadida + + +def test_reemplazo_de_body(tmp_path): + # Edge: body no None reemplaza por completo el cuerpo. + note = _seed(tmp_path) + update_obsidian_note(note, body="Cuerpo nuevo entero.") + parsed = read_obsidian_note(note) + assert parsed["body"].strip() == "Cuerpo nuevo entero." + assert "Linea original" not in parsed["body"] + # El frontmatter se conserva intacto. + assert parsed["frontmatter"]["title"] == "A" + + +def test_append_concatena_al_final(tmp_path): + # Edge: append concatena tras el body existente con salto de linea. + note = _seed(tmp_path) + update_obsidian_note(note, append="Linea anadida.") + body = read_obsidian_note(note)["body"] + assert "Linea original." in body + assert "Linea anadida." in body + assert body.index("Linea original.") < body.index("Linea anadida.") + + +def test_body_y_append_combinados(tmp_path): + # Edge: append se aplica DESPUES del reemplazo de body. + note = _seed(tmp_path) + update_obsidian_note(note, body="Base.", append="Extra.") + body = read_obsidian_note(note)["body"] + assert "Base." in body + assert "Extra." in body + assert "Linea original" not in body + assert body.index("Base.") < body.index("Extra.") + + +def test_nota_inexistente_lanza_filenotfounderror(tmp_path): + # Error path: actualizar una nota que no existe no la crea. + with pytest.raises(FileNotFoundError): + update_obsidian_note(str(tmp_path / "no_existe.md"), body="x") + + +def test_directorio_lanza_isadirectoryerror(tmp_path): + # Error path: ruta a directorio. + sub = tmp_path / "carpeta" + sub.mkdir() + with pytest.raises(IsADirectoryError): + update_obsidian_note(str(sub), body="x") diff --git a/python/pyproject.toml b/python/pyproject.toml index 36de2d1d..48e0feea 100644 --- a/python/pyproject.toml +++ b/python/pyproject.toml @@ -45,3 +45,11 @@ jupyter = [ dev = [ "pytest>=9.0.2", ] + +[tool.pytest.ini_options] +# Las funciones del registry importan paquetes por su nombre raiz +# (p.ej. `from obsidian import format_obsidian_note`), por lo que el +# directorio `functions/` debe estar en sys.path al recolectar tests. +# `functions/obsidian` permite a los tests importar los modulos hoja por +# su nombre directo (p.ej. `from format_obsidian_note import ...`). +pythonpath = ["functions", "functions/obsidian"]