dctracker 1.0.0__py3-none-any.whl

dct/config.py

@@ -0,0 +1,150 @@
+"""Configuration loading for dct.
+
+Priority: DCT_DATABASE_URL env var > ~/.claude/dct.toml > defaults.
+"""
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+DEFAULT_CONFIG_PATH = Path.home() / ".claude" / "dct.toml"
+DEFAULT_DB_PATH = Path.home() / ".claude" / "dct.db"
+
+
+@dataclass
+class PlansConfig:
+    """[plans] section — v0.2.0 parser/classifier/hook behaviour."""
+    auto_resolve_uncertain: bool = True
+    classify_model: str = "claude-haiku-4-5-20251001"
+    classify_timeout_seconds: int = 30
+    surface_on_session_start: bool = False
+    discovery_include: list[str] = field(default_factory=list)
+    discovery_exclude: list[str] = field(default_factory=list)
+
+
+@dataclass
+class MirrorConfig:
+    """[mirror] section — v0.4.0 TaskCreate ↔ dct integration.
+
+    task_to_dct: 'auto' mirrors every TaskCreate/TodoWrite into a session-scoped
+                 item as kind='cc-task' checkpoints (non-blocking).
+                 'ask'  skips mirror — Claude keeps TaskCreate and dct separate.
+                 'off'  disables the hook entirely.
+    """
+    task_to_dct: str = "auto"
+
+
+@dataclass
+class WebConfig:
+    """[web] section — v0.4.1 read-only browser viewer.
+
+    The viewer is reached at ``http://localhost:<port>`` — plain localhost
+    binding, no privileged port.
+
+    host           bind address (localhost-only by design)
+    port           preferred port; auto_fallback scans upward if busy
+    auto_fallback  pick the next free port when `port` is occupied
+    open_browser   open the browser on `dct web start`
+    refresh_poll_ms SSE change-token poll interval (milliseconds)
+    """
+    host: str = "127.0.0.1"
+    port: int = 8787
+    auto_fallback: bool = True
+    open_browser: bool = False
+    refresh_poll_ms: int = 2000
+
+
+@dataclass
+class Config:
+    database_url: str = ""
+    dct_root: str = ""  # absolute path to the dct repo (for MCP server references)
+    plans: PlansConfig = field(default_factory=PlansConfig)
+    mirror: MirrorConfig = field(default_factory=MirrorConfig)
+    web: WebConfig = field(default_factory=WebConfig)
+
+    def __post_init__(self):
+        if not self.database_url:
+            self.database_url = f"sqlite:///{DEFAULT_DB_PATH}"
+        if not self.dct_root:
+            self.dct_root = str(Path(__file__).resolve().parent.parent)
+
+
+def load_config(config_path: Path | None = None) -> Config:
+    path = config_path or Path(os.environ.get("DCT_CONFIG_PATH", str(DEFAULT_CONFIG_PATH)))
+    data: dict = {}
+
+    if path.exists():
+        with open(path, "rb") as f:
+            data = tomllib.load(f)
+
+    db_section = data.get("database", {})
+    database_url = db_section.get("url", "")
+    dct_root = data.get("dct_root", "")
+
+    plans_section = data.get("plans", {})
+    plans = PlansConfig(
+        auto_resolve_uncertain=bool(plans_section.get("auto_resolve_uncertain", True)),
+        classify_model=str(plans_section.get("classify_model", "claude-haiku-4-5-20251001")),
+        classify_timeout_seconds=int(plans_section.get("classify_timeout_seconds", 30)),
+        surface_on_session_start=bool(plans_section.get("surface_on_session_start", False)),
+        discovery_include=list(plans_section.get("discovery_include", [])),
+        discovery_exclude=list(plans_section.get("discovery_exclude", [])),
+    )
+
+    mirror_section = data.get("mirror", {})
+    mirror_mode = str(mirror_section.get("task_to_dct", "auto"))
+    if mirror_mode not in ("auto", "ask", "off"):
+        mirror_mode = "auto"
+    mirror = MirrorConfig(task_to_dct=mirror_mode)
+
+    web_section = data.get("web", {})
+    web = WebConfig(
+        host=str(web_section.get("host", "127.0.0.1")),
+        port=int(web_section.get("port", 8787)),
+        auto_fallback=bool(web_section.get("auto_fallback", True)),
+        open_browser=bool(web_section.get("open_browser", False)),
+        refresh_poll_ms=int(web_section.get("refresh_poll_ms", 2000)),
+    )
+
+    # Env var overrides config file
+    env_url = os.environ.get("DCT_DATABASE_URL")
+    if env_url:
+        database_url = env_url
+
+    return Config(database_url=database_url, dct_root=dct_root, plans=plans, mirror=mirror, web=web)
+
+
+def save_config(config: Config, config_path: Path | None = None) -> Path:
+    path = config_path or DEFAULT_CONFIG_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    lines = []
+    if config.dct_root:
+        lines.append(f'dct_root = "{config.dct_root}"\n\n')
+    lines.append('[database]\n')
+    lines.append(f'url = "{config.database_url}"\n\n')
+    lines.append('[plans]\n')
+    lines.append(f'auto_resolve_uncertain = {str(config.plans.auto_resolve_uncertain).lower()}\n')
+    lines.append(f'classify_model = "{config.plans.classify_model}"\n')
+    lines.append(f'classify_timeout_seconds = {config.plans.classify_timeout_seconds}\n')
+    lines.append(f'surface_on_session_start = {str(config.plans.surface_on_session_start).lower()}\n')
+    if config.plans.discovery_include:
+        inc = ", ".join(f'"{p}"' for p in config.plans.discovery_include)
+        lines.append(f'discovery_include = [{inc}]\n')
+    if config.plans.discovery_exclude:
+        exc = ", ".join(f'"{p}"' for p in config.plans.discovery_exclude)
+        lines.append(f'discovery_exclude = [{exc}]\n')
+
+    lines.append('\n[mirror]\n')
+    lines.append(f'task_to_dct = "{config.mirror.task_to_dct}"\n')
+
+    lines.append('\n[web]\n')
+    lines.append(f'host = "{config.web.host}"\n')
+    lines.append(f'port = {config.web.port}\n')
+    lines.append(f'auto_fallback = {str(config.web.auto_fallback).lower()}\n')
+    lines.append(f'open_browser = {str(config.web.open_browser).lower()}\n')
+    lines.append(f'refresh_poll_ms = {config.web.refresh_poll_ms}\n')
+
+    path.write_text("".join(lines))
+    return path

dct/core/analytics.py

@@ -0,0 +1,382 @@
+"""Pure aggregation helpers over dct.core data.
+
+Engine-first, JSON-native return dicts, no ORM. Every query is a single
+GROUP BY (or a constant number of grouped queries merged in Python) — never a
+per-project loop (no N+1). All aggregates exclude soft-deleted rows
+(`deleted_at IS NULL`; `item_sprints` uses `removed_at IS NULL`).
+
+Read-only: this module issues SELECTs only. Used by the web viewer
+(dct/web) and exposable later via MCP/CLI.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone, time
+
+import sqlalchemy as sa
+
+from dct.db import (
+    projects, items, item_checkpoints, changelog_entries,
+    session_handoffs, sprints, item_sprints,
+)
+
+OPEN_STATUSES = ("open", "in_progress")
+TERMINAL_STATUSES = ("resolved", "wont_fix")
+NON_GATE_KINDS = ("task", "cc-task")  # everything else is a gate (see resolve_item)
+
+
+def _iso(dt) -> str | None:
+    """datetime -> ISO 8601 string; None passthrough."""
+    return dt.isoformat() if dt is not None else None
+
+
+def _safe_tags(raw) -> list[str]:
+    """Tolerant tag parse: JSON-TEXT | None | garbage -> list[str].
+
+    Reuses items._parse_tags (returns [] on malformed JSON) and additionally
+    guards against non-list / non-str payloads so an adversarial `tags` value
+    can never crash an aggregate.
+    """
+    from dct.core.items import _parse_tags
+
+    parsed = _parse_tags(raw)
+    if not isinstance(parsed, list):
+        return []
+    return [t for t in parsed if isinstance(t, str) and t]
+
+
+def radar(engine: sa.Engine) -> dict:
+    """Cross-project operational rollup — one grouped query per table, merged.
+
+    open_total counts status='open'; by_priority breaks down those open items;
+    in_progress counts status='in_progress'; stale_Nd counts items with status
+    in (open,in_progress) whose updated_at is older than N days.
+    """
+    now = datetime.now(timezone.utc)
+    anchor7 = now - timedelta(days=7)
+    anchor30 = now - timedelta(days=30)
+
+    def _open_pri(pri):
+        return sa.func.sum(
+            sa.case((sa.and_(items.c.status == "open", items.c.priority == pri), 1), else_=0)
+        )
+
+    items_q = (
+        sa.select(
+            items.c.project_id.label("project_id"),
+            sa.func.sum(sa.case((items.c.status == "open", 1), else_=0)).label("open_total"),
+            _open_pri("P1").label("p1"),
+            _open_pri("P2").label("p2"),
+            _open_pri("P3").label("p3"),
+            _open_pri("future").label("pfuture"),
+            sa.func.sum(sa.case((items.c.status == "in_progress", 1), else_=0)).label("in_progress"),
+            sa.func.sum(sa.case(
+                (sa.and_(items.c.status.in_(OPEN_STATUSES), items.c.updated_at < anchor7), 1), else_=0
+            )).label("stale_7d"),
+            sa.func.sum(sa.case(
+                (sa.and_(items.c.status.in_(OPEN_STATUSES), items.c.updated_at < anchor30), 1), else_=0
+            )).label("stale_30d"),
+        )
+        .where(items.c.deleted_at.is_(None))
+        .group_by(items.c.project_id)
+    )
+    handoffs_q = (
+        sa.select(session_handoffs.c.project_id.label("project_id"), sa.func.count().label("cnt"))
+        .where(session_handoffs.c.consumed_at.is_(None), session_handoffs.c.deleted_at.is_(None))
+        .group_by(session_handoffs.c.project_id)
+    )
+    clog_q = (
+        sa.select(changelog_entries.c.project_id.label("project_id"), sa.func.count().label("cnt"))
+        .where(changelog_entries.c.version.is_(None), changelog_entries.c.deleted_at.is_(None))
+        .group_by(changelog_entries.c.project_id)
+    )
+
+    with engine.connect() as conn:
+        proj_rows = conn.execute(
+            sa.select(projects.c.id, projects.c.slug, projects.c.name)
+            .where(projects.c.deleted_at.is_(None))
+            .order_by(projects.c.slug)
+        ).fetchall()
+        items_by = {r.project_id: r for r in conn.execute(items_q)}
+        handoffs_by = {r.project_id: int(r.cnt) for r in conn.execute(handoffs_q)}
+        clog_by = {r.project_id: int(r.cnt) for r in conn.execute(clog_q)}
+
+    out_projects = []
+    tot_open = tot_ip = tot_stale7 = tot_handoff = 0
+    for p in proj_rows:
+        it = items_by.get(p.id)
+        open_total = int(it.open_total) if it else 0
+        in_progress = int(it.in_progress) if it else 0
+        stale_7d = int(it.stale_7d) if it else 0
+        stale_30d = int(it.stale_30d) if it else 0
+        by_priority = {
+            "P1": int(it.p1) if it else 0,
+            "P2": int(it.p2) if it else 0,
+            "P3": int(it.p3) if it else 0,
+            "future": int(it.pfuture) if it else 0,
+        }
+        unconsumed = handoffs_by.get(p.id, 0)
+        unreleased = clog_by.get(p.id, 0)
+        out_projects.append({
+            "slug": p.slug,
+            "name": p.name,
+            "open_total": open_total,
+            "by_priority": by_priority,
+            "in_progress": in_progress,
+            "stale_7d": stale_7d,
+            "stale_30d": stale_30d,
+            "unconsumed_handoffs": unconsumed,
+            "unreleased_changelog": unreleased,
+        })
+        tot_open += open_total
+        tot_ip += in_progress
+        tot_stale7 += stale_7d
+        tot_handoff += unconsumed
+
+    return {
+        "projects": out_projects,
+        "totals": {
+            "open_total": tot_open,
+            "in_progress": tot_ip,
+            "stale_7d": tot_stale7,
+            "unconsumed_handoffs": tot_handoff,
+        },
+    }
+
+
+def backlog_health(engine: sa.Engine, project_slug: str) -> dict:
+    """Single-project distributions, aging, hotspots, tags, checkpoint stats.
+
+    "open backlog" (aging / hotspots / tags) = OPEN_STATUSES (open + in_progress).
+    Distributions (by_type/priority/status/component) span all non-deleted items.
+    """
+    from dct.core.projects import resolve_project_id
+
+    now = datetime.now(timezone.utc)
+    a1w = now - timedelta(days=7)
+    a4w = now - timedelta(days=28)
+    a3m = now - timedelta(days=90)
+
+    with engine.connect() as conn:
+        pid = resolve_project_id(conn, project_slug)
+        base = sa.and_(items.c.project_id == pid, items.c.deleted_at.is_(None))
+        open_base = sa.and_(base, items.c.status.in_(OPEN_STATUSES))
+
+        def _group(col):
+            return conn.execute(
+                sa.select(col, sa.func.count().label("cnt")).where(base).group_by(col)
+            ).fetchall()
+
+        by_type = {r[0]: int(r.cnt) for r in _group(items.c.item_type)}
+        by_priority = {r[0]: int(r.cnt) for r in _group(items.c.priority)}
+        by_status = {r[0]: int(r.cnt) for r in _group(items.c.status)}
+
+        comp_rows = conn.execute(
+            sa.select(items.c.component, sa.func.count().label("cnt"))
+            .where(base, items.c.component.isnot(None))
+            .group_by(items.c.component)
+            .order_by(sa.func.count().desc(), items.c.component)
+        ).fetchall()
+        by_component = [{"component": r.component, "count": int(r.cnt)} for r in comp_rows]
+
+        aging_row = conn.execute(
+            sa.select(
+                sa.func.sum(sa.case((items.c.created_at > a1w, 1), else_=0)).label("lt_1w"),
+                sa.func.sum(sa.case(
+                    (sa.and_(items.c.created_at <= a1w, items.c.created_at > a4w), 1), else_=0
+                )).label("w1_4"),
+                sa.func.sum(sa.case(
+                    (sa.and_(items.c.created_at <= a4w, items.c.created_at > a3m), 1), else_=0
+                )).label("m1_3"),
+                sa.func.sum(sa.case((items.c.created_at <= a3m, 1), else_=0)).label("gt_3m"),
+            ).where(open_base)
+        ).first()
+        aging = {
+            "lt_1w": int(aging_row.lt_1w or 0),
+            "w1_4": int(aging_row.w1_4 or 0),
+            "m1_3": int(aging_row.m1_3 or 0),
+            "gt_3m": int(aging_row.gt_3m or 0),
+        }
+
+        def _hotspot(col):
+            rows = conn.execute(
+                sa.select(col, sa.func.count().label("cnt"))
+                .where(open_base, col.isnot(None))
+                .group_by(col)
+                .having(sa.func.count() >= 2)
+                .order_by(sa.func.count().desc(), col)
+            ).fetchall()
+            return [{"name": r[0], "count": int(r.cnt)} for r in rows]
+
+        hotspots = {"components": _hotspot(items.c.component), "files": _hotspot(items.c.source_file)}
+
+        tag_rows = conn.execute(sa.select(items.c.tags).where(open_base)).fetchall()
+
+        cp_join = item_checkpoints.join(items, items.c.id == item_checkpoints.c.item_id)
+        cp_filter = sa.and_(
+            items.c.project_id == pid,
+            items.c.deleted_at.is_(None),
+            item_checkpoints.c.deleted_at.is_(None),
+        )
+        cp_status_rows = conn.execute(
+            sa.select(item_checkpoints.c.status, sa.func.count().label("cnt"))
+            .select_from(cp_join).where(cp_filter)
+            .group_by(item_checkpoints.c.status)
+        ).fetchall()
+        cp_by = {r.status: int(r.cnt) for r in cp_status_rows}
+
+        gate_rows = conn.execute(
+            sa.select(item_checkpoints.c.kind, sa.func.count().label("cnt"))
+            .select_from(cp_join)
+            .where(cp_filter, item_checkpoints.c.kind.notin_(NON_GATE_KINDS))
+            .group_by(item_checkpoints.c.kind)
+        ).fetchall()
+        gates_by_kind = {r.kind: int(r.cnt) for r in gate_rows}
+
+    # tag frequency (parsed defensively outside the connection)
+    tag_counts: dict[str, int] = {}
+    for r in tag_rows:
+        for t in _safe_tags(r[0]):
+            tag_counts[t] = tag_counts.get(t, 0) + 1
+    tags = [
+        {"tag": t, "count": c}
+        for t, c in sorted(tag_counts.items(), key=lambda kv: (-kv[1], kv[0]))
+    ]
+
+    done = cp_by.get("done", 0)
+    pending = cp_by.get("pending", 0)
+    rejected = cp_by.get("rejected", 0)
+    denom = done + pending
+    completion_rate = round(done / denom, 4) if denom else 0.0
+
+    return {
+        "by_type": by_type,
+        "by_priority": by_priority,
+        "by_status": by_status,
+        "by_component": by_component,
+        "aging": aging,
+        "hotspots": hotspots,
+        "tags": tags,
+        "checkpoints": {
+            "pending": pending,
+            "done": done,
+            "rejected": rejected,
+            "gates_by_kind": gates_by_kind,
+            "completion_rate": completion_rate,
+        },
+    }
+
+
+def velocity(engine: sa.Engine, project_slug: str, weeks: int = 26) -> dict:
+    """Single-project time-series. Weeks are bucketed by their Monday (ISO date
+    string). Bucketing is done in Python (portable across SQLite/Postgres) after
+    a constant number of windowed SELECTs — never a per-week query loop.
+    """
+    from dct.core.projects import resolve_project_id
+
+    now = datetime.now(timezone.utc)
+    today = now.date()
+    this_monday = today - timedelta(days=today.weekday())
+    start_monday = this_monday - timedelta(days=7 * (weeks - 1))
+    week_keys = [(start_monday + timedelta(days=7 * i)).isoformat() for i in range(weeks)]
+    window_start = datetime.combine(start_monday, time(0, 0, 0))
+
+    def _monday_key(dt) -> str:
+        d = dt.date() if isinstance(dt, datetime) else dt
+        return (d - timedelta(days=d.weekday())).isoformat()
+
+    with engine.connect() as conn:
+        pid = resolve_project_id(conn, project_slug)
+
+        resolved_rows = conn.execute(
+            sa.select(items.c.resolved_at).where(
+                items.c.project_id == pid,
+                items.c.deleted_at.is_(None),
+                items.c.status.in_(TERMINAL_STATUSES),
+                items.c.resolved_at.isnot(None),
+                items.c.resolved_at >= window_start,
+            )
+        ).fetchall()
+        created_rows = conn.execute(
+            sa.select(items.c.created_at).where(
+                items.c.project_id == pid,
+                items.c.deleted_at.is_(None),
+                items.c.created_at >= window_start,
+            )
+        ).fetchall()
+        clog_rows = conn.execute(
+            sa.select(changelog_entries.c.category, changelog_entries.c.created_at).where(
+                changelog_entries.c.project_id == pid,
+                changelog_entries.c.deleted_at.is_(None),
+                changelog_entries.c.created_at >= window_start,
+            )
+        ).fetchall()
+        release_rows = conn.execute(
+            sa.select(
+                changelog_entries.c.version,
+                sa.func.min(changelog_entries.c.released_at).label("released_at"),
+            )
+            .where(
+                changelog_entries.c.project_id == pid,
+                changelog_entries.c.deleted_at.is_(None),
+                changelog_entries.c.version.isnot(None),
+                changelog_entries.c.released_at.isnot(None),
+            )
+            .group_by(changelog_entries.c.version)
+            .order_by(sa.func.min(changelog_entries.c.released_at))
+        ).fetchall()
+
+        isp = item_sprints.alias("isp")
+        live_link = sa.and_(isp.c.removed_at.is_(None), items.c.id.isnot(None))
+        sprint_rows = conn.execute(
+            sa.select(
+                sprints.c.name,
+                sprints.c.code,
+                sa.func.sum(sa.case((live_link, 1), else_=0)).label("size"),
+                sa.func.sum(sa.case(
+                    (sa.and_(live_link, items.c.status.in_(TERMINAL_STATUSES)), 1), else_=0
+                )).label("done"),
+            )
+            .select_from(
+                sprints
+                .outerjoin(isp, isp.c.sprint_id == sprints.c.id)
+                .outerjoin(items, sa.and_(items.c.id == isp.c.item_id, items.c.deleted_at.is_(None)))
+            )
+            .where(sprints.c.project_id == pid, sprints.c.deleted_at.is_(None))
+            .group_by(sprints.c.id, sprints.c.name, sprints.c.code, sprints.c.created_at)
+            .order_by(sprints.c.created_at)
+        ).fetchall()
+
+    resolved_per = {k: 0 for k in week_keys}
+    for r in resolved_rows:
+        k = _monday_key(r[0])
+        if k in resolved_per:
+            resolved_per[k] += 1
+    created_per = {k: 0 for k in week_keys}
+    for r in created_rows:
+        k = _monday_key(r[0])
+        if k in created_per:
+            created_per[k] += 1
+    clog_per = {k: {"added": 0, "changed": 0, "fixed": 0, "removed": 0} for k in week_keys}
+    for r in clog_rows:
+        k = _monday_key(r.created_at)
+        if k in clog_per and r.category in clog_per[k]:
+            clog_per[k][r.category] += 1
+
+    return {
+        "resolved_per_week": [{"week": k, "count": resolved_per[k]} for k in week_keys],
+        "created_per_week": [{"week": k, "count": created_per[k]} for k in week_keys],
+        "backlog_growth": [
+            {"week": k, "created": created_per[k], "resolved": resolved_per[k],
+             "net": created_per[k] - resolved_per[k]}
+            for k in week_keys
+        ],
+        "changelog_per_week": [{"week": k, **clog_per[k]} for k in week_keys],
+        "release_cadence": [
+            {"version": r.version, "released_at": _iso(r.released_at)} for r in release_rows
+        ],
+        "sprint_completion": [
+            {"name": r.name, "code": r.code, "done": int(r.done or 0), "size": int(r.size or 0)}
+            for r in sprint_rows
+        ],
+    }

dct/core/changelog.py

@@ -0,0 +1,112 @@
+"""Changelog CRUD operations with soft deletes."""
+
+from datetime import datetime, timezone
+
+import sqlalchemy as sa
+
+from dct.db import changelog_entries, projects, row_to_dict
+from dct.core.projects import resolve_project_id
+
+VALID_CATEGORIES = {"added", "changed", "fixed", "removed"}
+
+
+def add_entry(
+    engine: sa.Engine,
+    project_slug: str,
+    category: str,
+    entry: str,
+    version: str | None = None,
+    component: str | None = None,
+    source_file: str | None = None,
+    source_lines: str | None = None,
+    related_item_id: int | None = None,
+) -> dict:
+    if not entry or not entry.strip():
+        raise ValueError("Changelog entry cannot be empty")
+    if category not in VALID_CATEGORIES:
+        raise ValueError(f"Invalid category: '{category}'. Valid: {', '.join(sorted(VALID_CATEGORIES))}")
+
+    with engine.begin() as conn:
+        project_id = resolve_project_id(conn, project_slug)
+        result = conn.execute(
+            changelog_entries.insert()
+            .values(
+                project_id=project_id,
+                version=version,
+                category=category,
+                entry=entry,
+                component=component,
+                source_file=source_file,
+                source_lines=source_lines,
+                related_item_id=related_item_id,
+            )
+            .returning(changelog_entries)
+        )
+        return row_to_dict(result.first())
+
+
+def list_entries(
+    engine: sa.Engine,
+    project_slug: str,
+    version: str | None = None,
+    unreleased_only: bool = False,
+) -> list[dict]:
+    with engine.begin() as conn:
+        pid = resolve_project_id(conn, project_slug)
+        q = (
+            sa.select(changelog_entries)
+            .where(changelog_entries.c.project_id == pid, changelog_entries.c.deleted_at.is_(None))
+            .order_by(changelog_entries.c.created_at.desc())
+        )
+        if unreleased_only:
+            q = q.where(changelog_entries.c.version.is_(None))
+        elif version:
+            q = q.where(changelog_entries.c.version == version)
+        return [row_to_dict(r) for r in conn.execute(q)]
+
+
+def count_unreleased(engine: sa.Engine, project_slug: str) -> int:
+    with engine.begin() as conn:
+        pid = resolve_project_id(conn, project_slug)
+        result = conn.execute(
+            sa.select(sa.func.count())
+            .select_from(changelog_entries)
+            .where(
+                changelog_entries.c.project_id == pid,
+                changelog_entries.c.version.is_(None),
+                changelog_entries.c.deleted_at.is_(None),
+            )
+        )
+        return result.scalar() or 0
+
+
+def release_entries(engine: sa.Engine, project_slug: str, version: str) -> int:
+    """Stamp all unreleased entries with a version and update project's current_version."""
+    now = datetime.now(timezone.utc)
+    with engine.begin() as conn:
+        pid = resolve_project_id(conn, project_slug)
+        result = conn.execute(
+            changelog_entries.update()
+            .where(
+                changelog_entries.c.project_id == pid,
+                changelog_entries.c.version.is_(None),
+                changelog_entries.c.deleted_at.is_(None),
+            )
+            .values(version=version, released_at=now, updated_at=now)
+        )
+        conn.execute(
+            projects.update()
+            .where(projects.c.id == pid)
+            .values(current_version=version, updated_at=now)
+        )
+        return result.rowcount
+
+
+def delete_entry(engine: sa.Engine, entry_id: int) -> bool:
+    with engine.begin() as conn:
+        result = conn.execute(
+            changelog_entries.update()
+            .where(changelog_entries.c.id == entry_id, changelog_entries.c.deleted_at.is_(None))
+            .values(deleted_at=datetime.now(timezone.utc))
+        )
+        return result.rowcount > 0