kcreate-scaffolding-gcp-script 0.0.0-stage → 0.2.1

package/vendor/github-proyect-tracking/references/architecture.md

@@ -0,0 +1,171 @@
+# Arquitectura — github-proyect-tracking
+
+## Visión general
+
+El skill instrumenta procesos (no los ejecuta): convierte cada transición en
+un evento persistido en un Issue de GitHub y mantiene una memoria local para
+saber si hay un proceso inconcluso y en qué Issue vive.
+
+```
+┌──────────────┐   instrucción    ┌─────────────────────────────────────┐
+│ Agente (tú)  │ ───────────────▶ │ scripts/tracking.py (CLI, stdlib)   │
+│              │ ◀─────────────── │  · 1 JSON por comando + exit code   │
+└──────────────┘   JSON + exit    └───────────────┬─────────────────────┘
+     │ trabajo real del proceso                   │
+     ▼                                            ▼
+┌──────────────────┐   comentarios [STATUS:…]  ┌──────────────────────────┐
+│ Memoria interna  │ ◀──────────────────────── │ GitHub REST API v3       │
+│ ~/.github-       │   Issue #N (fuente de     │ /repos/{o}/{r}/issues/…  │
+│ proyect-tracking/│   verdad al reanudar)     │ Bearer token             │
+│ {owner}__{repo}. │                           └──────────────────────────┘
+│ json             │
+└──────────────────┘
+```
+
+Doble libro:
+
+1. **Remoto (autoritativo):** un Issue con título
+   `[Process Tracking] Execution ID: {id}`; cada transición es un comentario
+   con contrato visible exacto y el último evento decide la reanudación.
+2. **Local (rápido):** `~/.github-proyect-tracking/{owner}__{repo}.json` con
+   esquema v2, `active_process_id`, `github_token` opcional, plan y metadatos.
+   La carga migra v1 a v2 en memoria y el siguiente guardado la persiste.
+   Escritura atómica (tmp único + fsync + rename), permisos 0600.
+
+## Contrato de eventos y reconciliación
+
+Formatos visibles:
+
+```text
+[STATUS: INICIANDO] - Paso: {nombre}
+[STATUS: ERROR] - Paso: {nombre} - Detalles: {detalles}
+[STATUS: COMPLETADO] - Paso: {nombre}
+[STATUS: FINALIZADO] - El proceso concluyó exitosamente.
+[STATUS: CANCELADO] - El proceso fue cerrado anticipadamente (--force).
+```
+
+Los eventos nuevos añaden una línea HTML invisible:
+
+```text
+<!-- github-proyect-tracking: {"execution_id":"...","sequence":1,"transition_id":"..."} -->
+```
+
+`transition_id` es un UUID por intento y se conserva en el reintento del mismo
+comando. Ante respuesta de red perdida o HTTP 500/502/503/504, el cliente lee
+los comentarios y solo reconcilia si encuentra ese UUID fuera de la línea base.
+Un texto idéntico antiguo o nuevo de otro emisor no basta. Si no lo encuentra,
+reintenta una vez y vuelve a reconciliar. `init` recupera una creación ambigua
+buscando el título exacto con paginación; si no lo encuentra, el error incluye
+Execution ID, título y comando `adopt` sugerido.
+
+El parser elimina los metadatos antes de aplicar `COMMENT_RE`, por lo que los
+formatos visibles y los comentarios antiguos siguen siendo compatibles.
+`Detalles` admite stacktraces multilínea. `events_from_comments()` ordena por
+`(created_at, comment_id)`, sin confiar en el orden de llegada.
+
+## Máquina de estados del proceso
+
+```
+                 init (URL válida + token issues:write)
+  (sin proceso) ───────────────────────────────────────▶ RUNNING
+                                                            │
+        ┌─────────── step-start / step-done ───────────────┤
+        ▼                                                  │
+     RUNNING ── step-error ──▶ ERROR ──(resume: RERUN_STEP)─┘
+        │
+        ├──── finalize: FINALIZADO + Issue cerrado ────────▶ FINALIZED
+        └──── finalize --force: CANCELADO + Issue cerrado ─▶ CANCELADO
+              (active_process_id := null)
+```
+
+| Estado en memoria | Significado | `active_process_id` |
+|---|---|---|
+| `RUNNING` | Issue abierto, último evento INICIANDO/COMPLETADO | número |
+| `ERROR` | Último evento ERROR; proceso detenido | número |
+| `FINALIZED` | Issue cerrado con FINALIZADO | `null` |
+| `CANCELADO` | Issue cerrado anticipadamente con CANCELADO | `null` |
+| `ABORTED` | Issue cerrado sin FINALIZADO/CANCELADO | `null` |
+| `CLEARED` | Memoria descartada localmente | `null` |
+
+`is_unfinished()` exige ID activo y estado RUNNING o ERROR. `init` sobre un
+proceso inconcluso falla con exit 7 (`RESUME_REQUIRED`). El esquema valida
+tipos y estas invariantes cruzadas; un estado terminal no puede conservar ID
+activo.
+
+Después de ERROR, `resume` registra `last_resume` con Issue y comentario de
+error. `step-start` solo acepta esa autorización para reintentar el mismo paso;
+`step-done` y `step-error` también se detienen mientras el último evento remoto
+sea ERROR. `adopt` reconstruye ERROR, nunca lo sustituye por RUNNING.
+
+## Ciclo de vida de una ejecución
+
+1. **init** — valida URL y permisos, genera `exec-{timestamp}-{12 hex}`, crea
+   el Issue y guarda memoria. Un plan duplicado nuevo se rechaza.
+2. **resume** — lee Issue y todos los comentarios, deriva el veredicto y
+   sincroniza el estado. Los planes legados duplicados producen
+   `PLAN_AMBIGUOUS` con instrucciones de reparación; no se deduplican.
+3. **step-start / step-error / step-done** — una transición por comentario,
+   validada contra la misma instantánea remota.
+4. **finalize** — publica el evento terminal, cierra y verifica el Issue,
+   limpia memoria y conserva las últimas 20 entradas de historial.
+
+Con plan, el éxito exige todos los pasos completados. Sin plan, el último
+evento COMPLETADO permite FINALIZADO; sin trabajo, `finalize` se bloquea y
+`--force` registra CANCELADO. El `outcome` siempre procede del evento remoto:
+un reintento sin `--force` no convierte CANCELADO en FINALIZADO.
+
+## Veredictos de `resume`
+
+| Último evento / situación | `verdict.action` | `outcome` | Acción |
+|---|---|---|---|
+| FINALIZADO + Issue abierto | `FINISH_CLEANUP` | `FINALIZADO` | Ejecutar `finalize` |
+| CANCELADO + Issue abierto | `FINISH_CLEANUP` | `CANCELADO` | Ejecutar `finalize` |
+| FINALIZADO + Issue cerrado | `NONE` | `FINALIZADO` | Nada; memoria auto-limpia |
+| CANCELADO + Issue cerrado | `NONE` | `CANCELADO` | Nada; conservar cancelación |
+| ERROR | `RERUN_STEP` | — | Re-ejecutar ese paso tras esta autorización |
+| INICIANDO | `RERUN_STEP` | — | Re-ejecutar el paso en vuelo |
+| COMPLETADO + plan pendiente | `NEXT_STEP` | — | Ejecutar `resume_from_step` |
+| COMPLETADO + plan agotado | `ALL_STEPS_DONE` | — | Ejecutar `finalize` |
+| Sin comentarios | `START_FIRST` | — | Empezar por el paso 1 |
+| Issue cerrado sin evento terminal | `ABORTED_EXTERNALLY` | — | Preguntar al usuario |
+| Sin plan explícito | `NEXT_STEP_AGENT_DEFINED` | — | Elegir paso o finalizar tras COMPLETADO |
+
+## Módulos
+
+| Archivo | Responsabilidad |
+|---|---|
+| `scripts/tracking.py` | Parser CLI, punto de entrada y exportaciones compatibles |
+| `tracking_core/common.py` | Versión, constantes, errores y validación/redacción |
+| `tracking_core/events.py` | Contrato visible, metadatos, parser y planner |
+| `tracking_core/state.py` | Esquema v2, migración, persistencia, selección y locks |
+| `tracking_core/github.py` | Token, preflight, transporte, paginación y reconciliación |
+| `tracking_core/commands.py` | Comandos y guardas sobre instantáneas remotas |
+
+## Locks y robustez
+
+`StateLock` usa un directorio por repositorio, propietario con token y un hilo
+daemon que refresca heartbeat durante toda la operación, incluidas las llamadas
+HTTP. `ensure_owner()` se exige antes de efectos remotos y antes de guardar o
+borrar. Perder el lock produce `STATE_LOCK_LOST` y exige `resume`.
+
+- Escritura atómica, estado 0600, tokens enmascarados y persistencia opt-in.
+- Reintentos de GET/PATCH y rate limit con espera acotada.
+- Paginación completa por `Link`; más de 10 000 comentarios →
+  `COMMENTS_TOO_MANY`.
+- `adopt` usa el token almacenado antes de buscar el Issue.
+- `clear` sin URL exige contexto único también cuando solo hay estados
+  inactivos; varios candidatos → `CONTEXT_AMBIGUOUS`.
+- Preflight: un rol demostrado de solo lectura falla; `triage`, `push`,
+  `maintain` o `admin` habilitan la gestión de Issues.
+- Redacción de todo userinfo, query y fragment en URLs reflejadas.
+
+## Límites y garantías
+
+- Un proceso activo por repositorio (la memoria es por `{owner}/{repo}`).
+- Los eventos son append-only; una persona con acceso puede imitar el contrato
+  visible. Usa repositorios controlados y revisa la cronología ante anomalías.
+- No hay transacciones distribuidas: el lock protege el estado local y el
+  heartbeat evita su expiración durante una operación viva, pero dos agentes
+  independientes pueden intervenir manualmente en el mismo Issue.
+- La integración real es opt-in y requiere autorización y un repositorio
+  desechable; no se ejecuta en la suite offline por defecto.

package/vendor/github-proyect-tracking/scripts/tracking.py

@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""CLI de github-proyect-tracking; un JSON por comando, stdlib únicamente."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+
+from tracking_core import github as _github
+from tracking_core.common import *  # noqa: F401,F403
+from tracking_core.events import *  # noqa: F401,F403
+from tracking_core.state import *  # noqa: F401,F403
+from tracking_core.commands import *  # noqa: F401,F403
+
+_raw_api = _github._raw_api
+
+
+def _sync_runtime():
+    _github._raw_api = _raw_api
+    _github.shutil = shutil
+    _github.MAX_COMMENT_PAGES = MAX_COMMENT_PAGES
+    StateLock.STALE_SECONDS = LOCK_STALE_SECONDS
+    StateLock.WAIT_SECONDS = LOCK_WAIT_SECONDS
+
+
+def api(method, path, token, body=None, retries=3):
+    _sync_runtime()
+    return _github.api(method, path, token, body, retries)
+
+
+def check_issues_write(owner, repo, token):
+    _sync_runtime()
+    return _github.check_issues_write(owner, repo, token)
+
+
+def resolve_token(cli_token=None, state=None):
+    _sync_runtime()
+    return _github.resolve_token(cli_token, state)
+
+
+def post_comment(owner, repo, number, body, token,
+                 baseline_ids=None, execution_id=None, sequence=None):
+    _sync_runtime()
+    return _github.post_comment(owner, repo, number, body, token,
+                                baseline_ids, execution_id, sequence)
+
+
+def fetch_issue(owner, repo, number, token):
+    _sync_runtime()
+    return _github.fetch_issue(owner, repo, number, token)
+
+
+def fetch_all_comments(owner, repo, number, token):
+    _sync_runtime()
+    return _github.fetch_all_comments(owner, repo, number, token)
+
+
+def close_issue(owner, repo, number, token):
+    _sync_runtime()
+    return _github.close_issue(owner, repo, number, token)
+
+
+def find_issue_by_title(owner, repo, title, token):
+    _sync_runtime()
+    return _github.find_issue_by_title(owner, repo, title, token)
+
+
+class JsonArgumentParser(argparse.ArgumentParser):
+    def error(self, message):
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         f"argumentos inválidos: {message}")
+
+
+def build_parser():
+    parser = JsonArgumentParser(
+        prog="tracking.py",
+        description="github-proyect-tracking: persiste y reanuda el estado de un "
+                    "proceso en GitHub Issues. Cada comando imprime un único JSON.")
+    parser.add_argument("--version", action="version", version=USER_AGENT)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    def common(subparser, with_url=True, url_required=False):
+        if with_url:
+            subparser.add_argument(
+                "--url", required=url_required, metavar="URL",
+                help="github_project_url (https://github.com/{owner}/{repo}); "
+                     "obligatorio si hay varios procesos activos")
+        subparser.add_argument("--token", default=None, metavar="T",
+                               help="GitHub PAT con issues:write (si se omite: "
+                                    "env/gh/estado)")
+
+    subparser = subparsers.add_parser(
+        "init", help="nueva ejecución: valida, crea el Issue y guarda memoria")
+    common(subparser, url_required=True)
+    subparser.add_argument("--plan", default=None, metavar="JSON",
+                           help='plan de pasos con nombres ÚNICOS, ej. \'["Paso 1", "Paso 2"]\'')
+    subparser.add_argument("--plan-file", default=None, metavar="F",
+                           help="archivo JSON con la lista de pasos")
+    subparser.add_argument("--process-name", default=None, metavar="N",
+                           help="nombre del proceso/skill padre que se rastrea "
+                                "(aparece en el título y cuerpo del Issue)")
+    subparser.add_argument("--process-inputs", default=None, metavar="JSON",
+                           help='parámetros de entrada del proceso (objeto '
+                                "clave→valor, se publican en el Issue; los "
+                                "secretos se redactan), ej. \'{\"archivo\": "
+                                '\"datos.csv\"}\'')
+    subparser.add_argument("--prompt-token", action="store_true",
+                           help="pedir el token interactivamente (TTY)")
+    subparser.add_argument("--store-token", action="store_true",
+                           help="persistir el token provisto (opt-in; por defecto NO se guarda)")
+    subparser.add_argument("--no-store-token", action="store_true",
+                           help="obsoleto (compatibilidad): ahora NO guardar es el default")
+    subparser.set_defaults(func=cmd_init)
+
+    subparser = subparsers.add_parser(
+        "resume", help="lee el último comentario del Issue y planea la reanudación")
+    common(subparser)
+    subparser.set_defaults(func=cmd_resume)
+
+    subparser = subparsers.add_parser(
+        "step-start", help="comenta [STATUS: INICIANDO] - Paso: N")
+    common(subparser)
+    subparser.add_argument("--name", required=True, metavar="N", help="nombre del paso")
+    subparser.set_defaults(func=cmd_step_start)
+
+    subparser = subparsers.add_parser(
+        "step-done", help="comenta [STATUS: COMPLETADO] - Paso: N")
+    common(subparser)
+    subparser.add_argument("--name", required=True, metavar="N", help="nombre del paso")
+    subparser.set_defaults(func=cmd_step_done)
+
+    subparser = subparsers.add_parser(
+        "step-error", help="comenta [STATUS: ERROR] y detiene el proceso")
+    common(subparser)
+    subparser.add_argument("--name", required=True, metavar="N", help="nombre del paso")
+    subparser.add_argument("--details", default=None, metavar="D",
+                           help="mensaje de error o stacktrace (se sanitiza antes de publicar)")
+    subparser.add_argument("--details-file", default=None, metavar="F",
+                           help="archivo con el error/stacktrace")
+    subparser.set_defaults(func=cmd_step_error)
+
+    subparser = subparsers.add_parser(
+        "finalize", help="cierra el Issue con resultado FINALIZADO o CANCELADO")
+    common(subparser)
+    subparser.add_argument("--force", action="store_true",
+                           help="cancelar aunque queden pasos pendientes o no haya trabajo "
+                                "(no aplica si el Issue fue cerrado externamente)")
+    subparser.add_argument("--summary", default=None, metavar="TEXT",
+                           help="resumen final del proceso (se publica como comentario "
+                                "aparte, después del de FINALIZADO y antes de cerrar el "
+                                "Issue; se sanitiza igual que --details). Solo aplica en "
+                                "la ruta de éxito (no con --force)")
+    subparser.add_argument("--summary-file", default=None, metavar="F",
+                           help="archivo con el resumen final (alternativa a --summary)")
+    subparser.set_defaults(func=cmd_finalize)
+
+    subparser = subparsers.add_parser(
+        "status", help="muestra el estado local (y remoto con --remote)")
+    common(subparser)
+    subparser.add_argument("--remote", action="store_true",
+                           help="consultar también el Issue en GitHub")
+    subparser.set_defaults(func=cmd_status)
+
+    subparser = subparsers.add_parser(
+        "adopt", help="recupera el estado local desde un Issue remoto")
+    common(subparser, url_required=True)
+    subparser.add_argument("--execution-id", required=True, metavar="ID",
+                           help="Execution ID EXACTO del título del Issue")
+    subparser.add_argument("--process-name", default=None, metavar="N",
+                           help="nombre del proceso a adoptar (filtro adicional "
+                                "opcional si hay ambigüedad)")
+    subparser.add_argument("--force", action="store_true",
+                           help="reemplazar un proceso activo existente (conserva token "
+                                "e historial)")
+    subparser.set_defaults(func=cmd_adopt)
+
+    subparser = subparsers.add_parser(
+        "clear", help="limpia la memoria interna (soft por defecto)")
+    common(subparser)
+    subparser.add_argument("--hard", action="store_true",
+                           help="eliminar el archivo de estado por completo")
+    subparser.set_defaults(func=cmd_clear)
+
+    subparser = subparsers.add_parser(
+        "doctor", help="diagnóstico del entorno (siempre exit 0)")
+    common(subparser)
+    subparser.set_defaults(func=cmd_doctor)
+    return parser
+
+
+def main(argv=None):
+    try:
+        args = build_parser().parse_args(argv)
+        _sync_runtime()
+        return args.func(args)
+    except SkillError as error:
+        emit(error.to_json())
+        return error.exit_code
+    except KeyboardInterrupt:
+        return 130
+    except SystemExit:
+        raise
+    except Exception as error:
+        emit({"ok": False, "error": {
+            "code": "UNEXPECTED",
+            "message": f"{type(error).__name__}: {error}",
+            "hint": "error no previsto; reporta el comando exacto y este JSON"}})
+        return EXIT_RUNTIME
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/vendor/github-proyect-tracking/scripts/tracking_core/__init__.py

@@ -0,0 +1 @@
+"""Componentes internos de github-proyect-tracking."""