bps-kit 1.0.1 → 1.0.2

package/templates/vault/context-agent/scripts/session_summary.py

@@ -0,0 +1,319 @@
+"""
+Gerador de resumos estruturados de sessão.
+Analisa mensagens e gera session-NNN.md.
+"""
+
+import re
+from datetime import datetime
+from pathlib import Path
+
+from config import (
+    SESSIONS_DIR,
+    DECISION_MARKERS,
+    PENDING_MARKERS,
+)
+from models import SessionSummary, PendingTask, SessionEntry
+
+
+def get_next_session_number() -> int:
+    """Retorna o próximo número de sessão disponível."""
+    SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
+    existing = list(SESSIONS_DIR.glob("session-*.md"))
+    if not existing:
+        return 1
+    numbers = []
+    for f in existing:
+        try:
+            num = int(f.stem.split("-")[1])
+            numbers.append(num)
+        except (IndexError, ValueError):
+            continue
+    return max(numbers) + 1 if numbers else 1
+
+
+def generate_summary(
+    entries: list[SessionEntry],
+    session_number: int,
+    metadata: dict,
+) -> SessionSummary:
+    """Gera um resumo estruturado a partir das entradas da sessão."""
+    user_messages = [e.content for e in entries if e.role == "user" and e.content.strip()]
+    assistant_messages = [e.content for e in entries if e.role == "assistant" and e.content.strip()]
+    all_messages = user_messages + assistant_messages
+    all_tool_calls = []
+    all_files_modified = []
+
+    for e in entries:
+        all_tool_calls.extend(e.tool_calls)
+        all_files_modified.extend(e.files_modified)
+
+    # Deduplicate files
+    seen_files = set()
+    unique_files = []
+    for f in all_files_modified:
+        if f["path"] not in seen_files:
+            seen_files.add(f["path"])
+            unique_files.append(f)
+
+    # Extrair data
+    date_str = ""
+    start_time = metadata.get("start_time", "")
+    if start_time:
+        try:
+            dt = datetime.fromisoformat(start_time.replace("Z", "+00:00"))
+            date_str = dt.strftime("%Y-%m-%d")
+        except ValueError:
+            date_str = datetime.now().strftime("%Y-%m-%d")
+    else:
+        date_str = datetime.now().strftime("%Y-%m-%d")
+
+    summary = SessionSummary(
+        session_number=session_number,
+        session_id=metadata.get("session_id", ""),
+        slug=metadata.get("slug", ""),
+        date=date_str,
+        start_time=start_time,
+        end_time=metadata.get("end_time", ""),
+        duration_minutes=metadata.get("duration_minutes", 0),
+        model=metadata.get("model", ""),
+        total_input_tokens=metadata.get("total_input_tokens", 0),
+        total_output_tokens=metadata.get("total_output_tokens", 0),
+        total_cache_tokens=metadata.get("total_cache_tokens", 0),
+        message_count=metadata.get("message_count", 0),
+        tool_call_count=metadata.get("tool_call_count", 0),
+        files_modified=unique_files,
+    )
+
+    # Extrair tópicos das mensagens do usuário
+    summary.topics = _extract_topics(user_messages)
+
+    # Extrair decisões
+    summary.decisions = _extract_decisions(all_messages)
+
+    # Extrair tarefas
+    summary.tasks_completed = _extract_completed_tasks(all_messages)
+    summary.tasks_pending = _extract_pending_tasks(all_messages, session_number, date_str)
+
+    # Extrair erros
+    summary.errors_resolved = _extract_errors(assistant_messages)
+
+    # Extrair findings
+    summary.key_findings = _extract_findings(assistant_messages)
+
+    return summary
+
+
+def _extract_topics(user_messages: list[str]) -> list[str]:
+    """Identifica tópicos principais das mensagens do usuário."""
+    topics = []
+    for msg in user_messages:
+        # Limpar mensagens muito longas
+        msg_clean = msg[:500] if len(msg) > 500 else msg
+        # Pegar a primeira frase significativa como tópico
+        sentences = re.split(r'[.!?\n]', msg_clean)
+        for s in sentences:
+            s = s.strip()
+            if len(s) > 10 and len(s) < 200:
+                topics.append(s)
+                break
+
+    # Deduplicate e limitar
+    seen = set()
+    unique = []
+    for t in topics:
+        t_lower = t.lower()
+        if t_lower not in seen:
+            seen.add(t_lower)
+            unique.append(t)
+
+    return unique[:10]
+
+
+def _extract_decisions(messages: list[str]) -> list[str]:
+    """Encontra decisões nas mensagens."""
+    decisions = []
+    for msg in messages:
+        for line in msg.split("\n"):
+            line_lower = line.lower().strip()
+            for marker in DECISION_MARKERS:
+                if marker in line_lower:
+                    clean = line.strip()
+                    if 15 < len(clean) < 300:
+                        decisions.append(clean)
+                    break
+    return list(dict.fromkeys(decisions))[:10]  # Deduplicate, max 10
+
+
+def _extract_completed_tasks(messages: list[str]) -> list[str]:
+    """Encontra tarefas concluídas."""
+    completed = []
+    patterns = [
+        r"- \[x\]\s+(.+)",
+        r"✅\s+(.+)",
+        r"(?:concluí|completei|terminei|finalizei|done|completed|finished)\s+(.+)",
+    ]
+    for msg in messages:
+        for line in msg.split("\n"):
+            for pattern in patterns:
+                m = re.search(pattern, line, re.IGNORECASE)
+                if m:
+                    task = m.group(1).strip()
+                    if len(task) > 5:
+                        completed.append(task)
+    return list(dict.fromkeys(completed))[:15]
+
+
+def _extract_pending_tasks(
+    messages: list[str],
+    session_number: int,
+    date: str,
+) -> list[PendingTask]:
+    """Encontra tarefas pendentes. Foca em checkboxes não marcados nas mensagens do user."""
+    tasks = []
+    for msg in messages:
+        # Ignorar mensagens muito longas (provavelmente tool results, não conversação)
+        if len(msg) > 5000:
+            continue
+
+        for line in msg.split("\n"):
+            stripped = line.strip()
+
+            # Checkbox não marcado — sinal claro de tarefa
+            m = re.match(r"- \[ \]\s+(.+)", stripped)
+            if m:
+                desc = m.group(1).strip()
+                # Filtrar descrições que parecem código/documentação
+                if 10 < len(desc) < 200 and not desc.startswith("`") and not desc.startswith("-"):
+                    tasks.append(PendingTask(
+                        description=desc,
+                        source_session=session_number,
+                        created_date=date,
+                    ))
+
+    # Deduplicate
+    seen = set()
+    unique = []
+    for t in tasks:
+        if t.description not in seen:
+            seen.add(t.description)
+            unique.append(t)
+
+    return unique[:10]
+
+
+def _extract_errors(assistant_messages: list[str]) -> list[dict]:
+    """Encontra erros e suas soluções."""
+    errors = []
+    error_patterns = [
+        r"(?:error|erro|falha|failed|exception)[\s:]+(.+)",
+    ]
+    for msg in assistant_messages:
+        for pattern in error_patterns:
+            matches = re.findall(pattern, msg, re.IGNORECASE)
+            for match in matches:
+                if len(match) > 10:
+                    errors.append({"error": match[:200], "solution": ""})
+    return errors[:5]
+
+
+def _extract_findings(assistant_messages: list[str]) -> list[str]:
+    """Extrai descobertas/findings importantes."""
+    findings = []
+    markers = [
+        "descobri que", "encontrei", "notei que", "importante:",
+        "found that", "noticed that", "important:", "key finding",
+    ]
+    for msg in assistant_messages:
+        for line in msg.split("\n"):
+            line_lower = line.lower().strip()
+            for marker in markers:
+                if marker in line_lower and len(line.strip()) > 20:
+                    findings.append(line.strip()[:200])
+                    break
+    return list(dict.fromkeys(findings))[:5]
+
+
+def save_session_summary(summary: SessionSummary):
+    """Salva resumo como arquivo markdown."""
+    SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
+    path = SESSIONS_DIR / f"session-{summary.session_number:03d}.md"
+
+    lines = [
+        f"# Sessão {summary.session_number:03d} — {summary.date}",
+        f"**Slug:** {summary.slug} | **Duração:** ~{summary.duration_minutes}min | **Modelo:** {summary.model}",
+        "",
+    ]
+
+    if summary.topics:
+        lines.append("## Tópicos")
+        for t in summary.topics:
+            lines.append(f"- {t}")
+        lines.append("")
+
+    if summary.decisions:
+        lines.append("## Decisões")
+        for d in summary.decisions:
+            lines.append(f"- {d}")
+        lines.append("")
+
+    if summary.tasks_completed:
+        lines.append("## Tarefas Concluídas")
+        for t in summary.tasks_completed:
+            lines.append(f"- [x] {t}")
+        lines.append("")
+
+    if summary.tasks_pending:
+        lines.append("## Tarefas Pendentes")
+        for t in summary.tasks_pending:
+            if isinstance(t, PendingTask):
+                lines.append(f"- [ ] {t.description} (prioridade: {t.priority})")
+            else:
+                lines.append(f"- [ ] {t}")
+        lines.append("")
+
+    if summary.files_modified:
+        lines.append("## Arquivos Modificados")
+        for f in summary.files_modified:
+            lines.append(f"- `{f['path']}` — {f['action']}")
+        lines.append("")
+
+    if summary.key_findings:
+        lines.append("## Descobertas")
+        for f in summary.key_findings:
+            lines.append(f"- {f}")
+        lines.append("")
+
+    if summary.errors_resolved:
+        lines.append("## Erros Resolvidos")
+        for e in summary.errors_resolved:
+            lines.append(f"- {e['error']}")
+        lines.append("")
+
+    if summary.open_questions:
+        lines.append("## Questões em Aberto")
+        for q in summary.open_questions:
+            lines.append(f"- {q}")
+        lines.append("")
+
+    if summary.technical_debt:
+        lines.append("## Dívida Técnica")
+        for d in summary.technical_debt:
+            lines.append(f"- {d}")
+        lines.append("")
+
+    lines.append("## Métricas")
+    lines.append(f"- Input tokens: {summary.total_input_tokens:,}")
+    lines.append(f"- Output tokens: {summary.total_output_tokens:,}")
+    lines.append(f"- Cache tokens: {summary.total_cache_tokens:,}")
+    lines.append(f"- Mensagens: {summary.message_count}")
+    lines.append(f"- Tool calls: {summary.tool_call_count}")
+    lines.append("")
+
+    # Link para sessão anterior
+    if summary.session_number > 1:
+        prev = summary.session_number - 1
+        lines.append("---")
+        lines.append(f"*Sessão anterior: [session-{prev:03d}](session-{prev:03d}.md)*")
+
+    path.write_text("\n".join(lines), encoding="utf-8")
+    return path

package/templates/vault/context-guardian/scripts/context_snapshot.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""
+Context Guardian — Snapshot Manager.
+
+Cria, lista e le snapshots de contexto para preservacao
+pre-compactacao. Os snapshots sao arquivos .md estruturados
+com todas as informacoes criticas de uma sessao.
+
+Uso:
+    python context_snapshot.py save --project "nome" --phase "fase" --summary "resumo"
+    python context_snapshot.py list
+    python context_snapshot.py latest
+    python context_snapshot.py read <snapshot-file>
+    python context_snapshot.py prune --keep 10
+"""
+
+import json
+import sys
+import os
+from datetime import datetime
+from pathlib import Path
+
+# ── Paths ──────────────────────────────────────────────────────────────────
+SCRIPT_DIR = Path(__file__).resolve().parent
+SKILL_DIR = SCRIPT_DIR.parent
+DATA_DIR = SKILL_DIR / "data"
+
+# ── Functions ──────────────────────────────────────────────────────────────
+
+def ensure_data_dir():
+    """Create data directory if it doesn't exist."""
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def save_snapshot(project: str = "", phase: str = "", summary: str = "") -> str:
+    """
+    Create a new snapshot file with metadata header.
+    Returns the path to the created file.
+
+    The Claude agent is expected to APPEND the actual content
+    (extracted from the conversation) after this header is created.
+    """
+    ensure_data_dir()
+
+    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    filename = f"snapshot-{timestamp}.md"
+    filepath = DATA_DIR / filename
+
+    header = f"""# Context Guardian Snapshot — {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
+**Projeto**: {project or 'nao especificado'}
+**Fase**: {phase or 'nao especificada'}
+**Resumo**: {summary or 'snapshot pre-compactacao'}
+**Modelo**: claude-opus-4-6
+
+---
+
+<!-- O Claude deve preencher as secoes abaixo seguindo references/extraction-protocol.md -->
+
+## Arquivos Tocados
+| Arquivo | Acao | Detalhes |
+|---------|------|----------|
+| | | |
+
+## Decisoes
+- (preencher)
+
+## Correcoes
+- (preencher)
+
+## Progresso
+- Total de tarefas:
+- Concluidas:
+- Pendentes:
+
+## Trechos Criticos
+- (preencher)
+
+## Padroes Observados
+- (preencher)
+
+## Dependencias
+- (preencher)
+
+## Contexto do Usuario
+- Objetivo:
+- Proxima acao esperada:
+
+---
+*Snapshot gerado por context-guardian v1.0.0*
+*Para restaurar: leia este arquivo + MEMORY.md + context_manager.py load*
+"""
+
+    filepath.write_text(header, encoding="utf-8")
+    return str(filepath)
+
+
+def list_snapshots() -> list[dict]:
+    """List all snapshots with metadata."""
+    ensure_data_dir()
+    snapshots = []
+
+    for f in sorted(DATA_DIR.glob("snapshot-*.md"), reverse=True):
+        stat = f.stat()
+        snapshots.append({
+            "file": f.name,
+            "path": str(f),
+            "size_kb": round(stat.st_size / 1024, 1),
+            "modified": datetime.fromtimestamp(stat.st_mtime).strftime("%Y-%m-%d %H:%M:%S"),
+        })
+
+    return snapshots
+
+
+def read_latest() -> dict:
+    """Read the most recent snapshot."""
+    snapshots = list_snapshots()
+    if not snapshots:
+        return {"error": "Nenhum snapshot encontrado."}
+
+    latest = snapshots[0]
+    path = Path(latest["path"])
+    content = path.read_text(encoding="utf-8")
+
+    return {
+        "file": latest["file"],
+        "path": latest["path"],
+        "size_kb": latest["size_kb"],
+        "content": content,
+    }
+
+
+def read_snapshot(filename: str) -> dict:
+    """Read a specific snapshot by filename."""
+    filepath = DATA_DIR / filename
+    if not filepath.exists():
+        return {"error": f"Arquivo nao encontrado: {filename}"}
+
+    content = filepath.read_text(encoding="utf-8")
+    return {
+        "file": filename,
+        "path": str(filepath),
+        "content": content,
+    }
+
+
+def prune_snapshots(keep: int = 10) -> dict:
+    """Remove old snapshots, keeping the N most recent."""
+    snapshots = list_snapshots()
+    if len(snapshots) <= keep:
+        return {"pruned": 0, "remaining": len(snapshots)}
+
+    to_remove = snapshots[keep:]
+    for s in to_remove:
+        Path(s["path"]).unlink()
+
+    return {"pruned": len(to_remove), "remaining": keep}
+
+
+# ── CLI ────────────────────────────────────────────────────────────────────
+
+def main():
+    args = sys.argv[1:]
+
+    if not args:
+        print(json.dumps({
+            "error": "Comando necessario: save, list, latest, read, prune",
+            "usage": "python context_snapshot.py <command> [options]",
+        }, indent=2, ensure_ascii=False))
+        sys.exit(1)
+
+    cmd = args[0]
+
+    if cmd == "save":
+        project = ""
+        phase = ""
+        summary = ""
+        i = 1
+        while i < len(args):
+            if args[i] == "--project" and i + 1 < len(args):
+                project = args[i + 1]
+                i += 2
+            elif args[i] == "--phase" and i + 1 < len(args):
+                phase = args[i + 1]
+                i += 2
+            elif args[i] == "--summary" and i + 1 < len(args):
+                summary = args[i + 1]
+                i += 2
+            else:
+                i += 1
+
+        path = save_snapshot(project, phase, summary)
+        print(json.dumps({
+            "status": "ok",
+            "action": "snapshot_created",
+            "path": path,
+            "next_step": "Preencher o snapshot com dados extraidos da conversa",
+        }, indent=2, ensure_ascii=False))
+
+    elif cmd == "list":
+        snapshots = list_snapshots()
+        print(json.dumps({
+            "total": len(snapshots),
+            "snapshots": snapshots,
+        }, indent=2, ensure_ascii=False))
+
+    elif cmd == "latest":
+        result = read_latest()
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+
+    elif cmd == "read" and len(args) > 1:
+        result = read_snapshot(args[1])
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+
+    elif cmd == "prune":
+        keep = 10
+        if "--keep" in args:
+            idx = args.index("--keep")
+            if idx + 1 < len(args):
+                keep = int(args[idx + 1])
+        result = prune_snapshots(keep)
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+
+    else:
+        print(json.dumps({"error": f"Comando desconhecido: {cmd}"}, indent=2))
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/templates/vault/docx/ooxml/scripts/pack.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""
+Tool to pack a directory into a .docx, .pptx, or .xlsx file with XML formatting undone.
+
+Example usage:
+    python pack.py <input_directory> <office_file> [--force]
+"""
+
+import argparse
+import shutil
+import subprocess
+import sys
+import tempfile
+import defusedxml.minidom
+import zipfile
+from pathlib import Path
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Pack a directory into an Office file")
+    parser.add_argument("input_directory", help="Unpacked Office document directory")
+    parser.add_argument("output_file", help="Output Office file (.docx/.pptx/.xlsx)")
+    parser.add_argument("--force", action="store_true", help="Skip validation")
+    args = parser.parse_args()
+
+    try:
+        success = pack_document(
+            args.input_directory, args.output_file, validate=not args.force
+        )
+
+        # Show warning if validation was skipped
+        if args.force:
+            print("Warning: Skipped validation, file may be corrupt", file=sys.stderr)
+        # Exit with error if validation failed
+        elif not success:
+            print("Contents would produce a corrupt file.", file=sys.stderr)
+            print("Please validate XML before repacking.", file=sys.stderr)
+            print("Use --force to skip validation and pack anyway.", file=sys.stderr)
+            sys.exit(1)
+
+    except ValueError as e:
+        sys.exit(f"Error: {e}")
+
+
+def pack_document(input_dir, output_file, validate=False):
+    """Pack a directory into an Office file (.docx/.pptx/.xlsx).
+
+    Args:
+        input_dir: Path to unpacked Office document directory
+        output_file: Path to output Office file
+        validate: If True, validates with soffice (default: False)
+
+    Returns:
+        bool: True if successful, False if validation failed
+    """
+    input_dir = Path(input_dir)
+    output_file = Path(output_file)
+
+    if not input_dir.is_dir():
+        raise ValueError(f"{input_dir} is not a directory")
+    if output_file.suffix.lower() not in {".docx", ".pptx", ".xlsx"}:
+        raise ValueError(f"{output_file} must be a .docx, .pptx, or .xlsx file")
+
+    # Work in temporary directory to avoid modifying original
+    with tempfile.TemporaryDirectory() as temp_dir:
+        temp_content_dir = Path(temp_dir) / "content"
+        shutil.copytree(input_dir, temp_content_dir)
+
+        # Process XML files to remove pretty-printing whitespace
+        for pattern in ["*.xml", "*.rels"]:
+            for xml_file in temp_content_dir.rglob(pattern):
+                condense_xml(xml_file)
+
+        # Create final Office file as zip archive
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+        with zipfile.ZipFile(output_file, "w", zipfile.ZIP_DEFLATED) as zf:
+            for f in temp_content_dir.rglob("*"):
+                if f.is_file():
+                    zf.write(f, f.relative_to(temp_content_dir))
+
+        # Validate if requested
+        if validate:
+            if not validate_document(output_file):
+                output_file.unlink()  # Delete the corrupt file
+                return False
+
+    return True
+
+
+def validate_document(doc_path):
+    """Validate document by converting to HTML with soffice."""
+    # Determine the correct filter based on file extension
+    match doc_path.suffix.lower():
+        case ".docx":
+            filter_name = "html:HTML"
+        case ".pptx":
+            filter_name = "html:impress_html_Export"
+        case ".xlsx":
+            filter_name = "html:HTML (StarCalc)"
+
+    with tempfile.TemporaryDirectory() as temp_dir:
+        try:
+            result = subprocess.run(
+                [
+                    "soffice",
+                    "--headless",
+                    "--convert-to",
+                    filter_name,
+                    "--outdir",
+                    temp_dir,
+                    str(doc_path),
+                ],
+                capture_output=True,
+                timeout=10,
+                text=True,
+            )
+            if not (Path(temp_dir) / f"{doc_path.stem}.html").exists():
+                error_msg = result.stderr.strip() or "Document validation failed"
+                print(f"Validation error: {error_msg}", file=sys.stderr)
+                return False
+            return True
+        except FileNotFoundError:
+            print("Warning: soffice not found. Skipping validation.", file=sys.stderr)
+            return True
+        except subprocess.TimeoutExpired:
+            print("Validation error: Timeout during conversion", file=sys.stderr)
+            return False
+        except Exception as e:
+            print(f"Validation error: {e}", file=sys.stderr)
+            return False
+
+
+def condense_xml(xml_file):
+    """Strip unnecessary whitespace and remove comments."""
+    with open(xml_file, "r", encoding="utf-8") as f:
+        dom = defusedxml.minidom.parse(f)
+
+    # Process each element to remove whitespace and comments
+    for element in dom.getElementsByTagName("*"):
+        # Skip w:t elements and their processing
+        if element.tagName.endswith(":t"):
+            continue
+
+        # Remove whitespace-only text nodes and comment nodes
+        for child in list(element.childNodes):
+            if (
+                child.nodeType == child.TEXT_NODE
+                and child.nodeValue
+                and child.nodeValue.strip() == ""
+            ) or child.nodeType == child.COMMENT_NODE:
+                element.removeChild(child)
+
+    # Write back the condensed XML
+    with open(xml_file, "wb") as f:
+        f.write(dom.toxml(encoding="UTF-8"))
+
+
+if __name__ == "__main__":
+    main()