dctracker 1.0.0__py3-none-any.whl

dct/web/blueprints/sprints.py

@@ -0,0 +1,71 @@
+"""Sprint views — list (both models, labeled) + detail (members + steps)."""
+
+from __future__ import annotations
+
+from flask import Blueprint, abort, g, render_template
+
+from dct.web.app import current_engine
+from dct.core import sprints as sprints_core
+from dct.core import checkpoints as checkpoints_core
+from dct.core import projects as projects_core
+
+bp = Blueprint("sprints", __name__)
+
+
+@bp.route("/p/<slug>/sprints")
+def list(slug):  # noqa: A001 — Flask endpoint name is intentional (sprints.list)
+    engine = current_engine()
+    first_class = sprints_core.list_sprints(engine, project_slug=slug)
+    # Current sprint = the project's single active sprint; its members come from
+    # item_sprints (one source of truth, #216). No more legacy-boolean section.
+    current = sprints_core.get_current_sprint(engine, slug)
+    current_items = (
+        sprints_core.list_items_in_sprint(engine, current["id"]) if current else []
+    )
+    return render_template(
+        "sprints/list.html",
+        slug=slug,
+        sprints=first_class,
+        current=current,
+        current_items=current_items,
+    )
+
+
+@bp.route("/sprints/<int:sprint_id>")
+def detail(sprint_id):
+    engine = current_engine()
+    sprint = sprints_core.get_sprint(engine, sprint_id)
+    if sprint is None:
+        abort(404)
+    # get_sprint returns project_id (int) but NO slug; resolve it so member
+    # links can build url_for('items.detail', slug=..., id=...). projects core
+    # has no get-by-id, so map id->slug from list_projects.
+    slug = next(
+        (p["slug"] for p in projects_core.list_projects(engine)
+         if p["id"] == sprint["project_id"]),
+        None,
+    )
+    # Scope the sidebar + breadcrumb to the owning project (no slug in the URL).
+    g.current_slug = slug
+    g.current_section = "sprints"
+    members = sprints_core.list_items_in_sprint(engine, sprint_id)
+    rows = []
+    done = total = 0
+    for it in members:
+        cps = checkpoints_core.list_checkpoints(
+            engine, it["id"], include_rejected=True
+        )
+        rows.append({"item": it, "checkpoints": cps})
+        for cp in cps:
+            if cp["status"] != "rejected":
+                total += 1
+                if cp["status"] == "done":
+                    done += 1
+    return render_template(
+        "sprints/detail.html",
+        sprint=sprint,
+        slug=slug,
+        rows=rows,
+        cp_done=done,
+        cp_total=total,
+    )

dct/web/changes.py

@@ -0,0 +1,77 @@
+"""Cheap composite change-token for SSE live refresh.
+
+The token is two halves joined by ':':
+  1. max(updated_at) across every table that carries an updated_at column
+     — advances on any UPDATE (core stamps updated_at with microsecond precision).
+  2. per-table live row counts (deleted_at IS NULL; item_sprints uses removed_at
+     IS NULL) — advances on any INSERT or SOFT-DELETE, including child rows
+     (notes, checkpoints, links) that never touch a parent's updated_at.
+
+Stable when the DB is unchanged. Read-only: SELECTs only, never DDL.
+"""
+
+import sqlalchemy as sa
+
+from dct.db import (
+    projects,
+    items,
+    item_notes,
+    item_checkpoints,
+    changelog_entries,
+    session_handoffs,
+    sprints,
+    plans,
+    plan_sections,
+    plan_checkpoints,
+    item_sprints,
+    decisions,
+)
+
+# Tables carrying an updated_at column — feed the freshness half of the token.
+_UPDATED_AT_TABLES = (
+    projects,
+    items,
+    item_checkpoints,
+    changelog_entries,
+    sprints,
+    plans,
+    plan_sections,
+    plan_checkpoints,
+    decisions,
+)
+
+# (table, live_predicate) — count of non-deleted rows feeds the count half.
+# item_notes / session_handoffs / item_sprints have no updated_at, so their
+# mutations are visible only through this row-count half.
+_COUNT_TABLES = (
+    (projects, projects.c.deleted_at.is_(None)),
+    (items, items.c.deleted_at.is_(None)),
+    (item_notes, item_notes.c.deleted_at.is_(None)),
+    (item_checkpoints, item_checkpoints.c.deleted_at.is_(None)),
+    (changelog_entries, changelog_entries.c.deleted_at.is_(None)),
+    (session_handoffs, session_handoffs.c.deleted_at.is_(None)),
+    (sprints, sprints.c.deleted_at.is_(None)),
+    (plans, plans.c.deleted_at.is_(None)),
+    (plan_sections, plan_sections.c.deleted_at.is_(None)),
+    (plan_checkpoints, plan_checkpoints.c.deleted_at.is_(None)),
+    (item_sprints, item_sprints.c.removed_at.is_(None)),
+    (decisions, decisions.c.deleted_at.is_(None)),
+)
+
+
+def change_token(engine: sa.Engine) -> str:
+    """Return a cheap composite token that changes on any tracked mutation."""
+    parts: list[str] = []
+    with engine.connect() as conn:
+        newest = None
+        for table in _UPDATED_AT_TABLES:
+            value = conn.execute(sa.select(sa.func.max(table.c.updated_at))).scalar()
+            if value is not None and (newest is None or value > newest):
+                newest = value
+        parts.append(str(newest) if newest is not None else "-")
+        for table, predicate in _COUNT_TABLES:
+            count = conn.execute(
+                sa.select(sa.func.count()).select_from(table).where(predicate)
+            ).scalar()
+            parts.append(str(count or 0))
+    return ":".join(parts)

dct/web/serializers.py

@@ -0,0 +1,109 @@
+"""Serialization helpers for the dct web viewer.
+
+JSON-native conversions shared by every blueprint:
+- datetimes -> ISO 8601 strings,
+- the JSON-in-TEXT `tags` column -> a real list,
+- markdown prose -> sanitized HTML (raw HTML escaped, never executed).
+"""
+
+import json
+import re
+from datetime import datetime
+
+import markdown as _markdown
+import markupsafe
+
+
+def to_iso(dt) -> str | None:
+    """datetime -> ISO 8601 string; None passes through; other types stringified."""
+    if dt is None:
+        return None
+    if isinstance(dt, datetime):
+        return dt.isoformat()
+    return str(dt)
+
+
+def parse_tags(raw) -> list[str]:
+    """Tolerant parse of the `tags` field.
+
+    Accepts JSON-encoded TEXT (``'["a","b"]'``), ``None``, an already-decoded
+    list, or a bare string. Always returns ``list[str]`` and never raises.
+    """
+    if raw is None:
+        return []
+    if isinstance(raw, list):
+        return [str(t) for t in raw]
+    if isinstance(raw, str):
+        s = raw.strip()
+        if not s:
+            return []
+        try:
+            parsed = json.loads(s)
+        except (ValueError, TypeError):
+            return [s]
+        if isinstance(parsed, list):
+            return [str(t) for t in parsed]
+        return [str(parsed)]
+    return []
+
+
+# Markdown link syntax can emit dangerous-scheme URIs (e.g. `[x](javascript:alert(1))`)
+# even though raw HTML is escaped upstream. Rewrite such href/src values to "#" so a
+# malicious description/note can't smuggle a javascript:/data: link into the page.
+_UNSAFE_URI = re.compile(
+    r"""(href|src)\s*=\s*(["'])\s*(?:javascript|vbscript|data|file)\s*:[^"']*\2""",
+    re.IGNORECASE,
+)
+
+
+def _neutralize_unsafe_links(html: str) -> str:
+    return _UNSAFE_URI.sub(lambda m: f"{m.group(1)}={m.group(2)}#{m.group(2)}", html)
+
+
+# --- readability: paragraph-split long unstructured prose ------------------
+# Many dct descriptions/notes are stored as ONE continuous block (zero newlines)
+# and render as an unreadable wall. When a block has no paragraph breaks and no
+# markdown block syntax, we split it on sentence boundaries and regroup so the
+# renderer emits real <p> breaks. Conservative: structured/short text is left alone.
+_ABBREV = ("e.g.", "i.e.", "etc.", "vs.", "cf.", "al.", "inc.", "approx.", "no.", "fig.")
+_SENTENCE_SPLIT = re.compile(r"(?<=[.!?])\s+(?=[A-Z(`])")
+_BLOCK_MD = re.compile(r"(?m)^\s*(?:#{1,6}\s|[-*+]\s|\d+\.\s|>\s|```)")
+
+
+def _paragraphize(text: str, group: int = 2) -> str:
+    if "\n\n" in text or _BLOCK_MD.search(text) or len(text) <= 300:
+        return text
+    parts = _SENTENCE_SPLIT.split(text.strip())
+    sentences: list[str] = []
+    for part in parts:
+        if sentences and sentences[-1].rstrip().lower().endswith(_ABBREV):
+            sentences[-1] = f"{sentences[-1]} {part}"
+        else:
+            sentences.append(part)
+    if len(sentences) < 3:
+        return text
+    return "\n\n".join(
+        " ".join(sentences[i:i + group]) for i in range(0, len(sentences), group)
+    )
+
+
+def render_markdown(text: str | None) -> markupsafe.Markup:
+    """Render markdown to HTML with raw HTML escaped (defense-in-depth).
+
+    We escape the source *before* handing it to python-markdown, so any raw
+    ``<script>`` / ``<img onerror=...>`` becomes inert text while ordinary
+    markdown syntax (emphasis, lists, code fences, tables) still renders.
+    Long unstructured blocks are paragraph-split first for readability.
+    Returns a ``Markup`` so Jinja2 treats it as safe to emit verbatim.
+    """
+    if not text:
+        return markupsafe.Markup("")
+    text = _paragraphize(text)
+    escaped = str(markupsafe.escape(text))
+    html = _markdown.markdown(
+        escaped,
+        extensions=["fenced_code", "tables"],
+        output_format="html",
+    )
+    html = _neutralize_unsafe_links(html)
+    return markupsafe.Markup(html)