dctracker 1.0.0__py3-none-any.whl

dct/skills/track-update/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: track-update
+description: |
+  Update an existing tracked item in dct.
+  Use when: "update issue", "edit item", "change priority", "zmień issue",
+  "track-update", "set status", "reassign priority",
+  "w toku", "zacznij", "rozpocznij", "start working on", "in progress",
+  "wip", "mark as wip", "assign priority", "flag as sprint", "add to sprint",
+  "remove from sprint", "wstrzymaj", "pause".
+---
+
+# /track-update — Update Tracked Item
+
+## Step 1: Identify item(s)
+
+**ID normalization** — accept all of these forms from user:
+- `#42`, `42`, `ITEM-42`, `item-42`, `0042`
+
+Parse by: strip leading `#`, strip `ITEM-`/`item-`/`ITEM_`/`item_` prefix
+(case-insensitive), strip leading zeros, cast to integer.
+Regex: `^(#|ITEM-|item-|ITEM_|item_)?0*(\d+)$` — capture group 2 is the numeric id.
+
+**Batch form** — user may give multiple ids for the SAME change, e.g.
+"set #42 #45 to P1" or "w toku: 7, 12, 19". Parse each id separately
+(whitespace or comma separated) and apply the same update to all. Ask
+confirmation ONCE for the batch, not per-item.
+
+Invalid inputs (non-digit body, empty, negative) — reject with clear message.
+
+For each id, call `mcp__dct__get_item(item_id)` to fetch current state.
+
+## Step 2: Determine changes
+
+From user request, identify which fields to change:
+- `title`, `status`, `priority`, `component`, `description`, `resolution`
+
+`update_item` does NOT change sprint membership — `in_current_sprint` is a
+derived, read-only field. Sprint changes go through dedicated tools
+(see "Sprint membership" below).
+
+Status transitions:
+- "start" / "zacznij" / "rozpocznij" / "w toku" / "wip" / "in progress" → `status="in_progress"`
+- "pause" / "wstrzymaj" / "block" / "zablokuj" → keep status, add note explaining pause
+- "open" / "reopen" / "wznów" → `status="open"` (also clears `resolved_at` automatically — see CLAUDE.md terminal invariant)
+
+Sprint membership (NOT via update_item):
+- "add to sprint" / "flag for sprint" / "na sprint" / "dodaj do sprintu" →
+  `mcp__dct__add_item_to_current_sprint(item_id, project)` — auto-creates the
+  current sprint; additive, keeps existing members.
+- "remove from sprint" / "out of sprint" / "zdejmij ze sprintu" →
+  `mcp__dct__remove_item_from_current_sprint(item_id, project)`.
+- To replace the WHOLE current sprint at once: `mcp__dct__set_sprint(project, item_ids)`.
+
+## Step 3: Confirm
+
+Show before/after (batch shows list):
+```
+#42 — Parser crashes on empty files
+  Priority: P2 → P1
+  Status:   open → in_progress
+  + Note:   "Reproducible on 0-byte input, blocking v0.3"
+```
+
+Wait for confirmation.
+
+## Step 4: Execute
+
+### When add_note is MANDATORY
+
+Call `mcp__dct__add_note(item_id, note)` BEFORE the `update_item` call when the
+transition is one of:
+- **status** change (especially to `in_progress` or any terminal) — note the reason / link to commit
+- **priority** change — note what prompted the bump or demotion
+- **resolution** set — note the commit hash or decision rationale
+
+This is the audit trail — future /pickup will read these notes via `get_item`.
+
+### When add_note is OPTIONAL
+
+Title, component, description, tags edits — notes welcome but not required.
+
+Then call `mcp__dct__update_item(item_id, ...)` with changed fields.
+For batch updates, loop per-id with the same kwargs.
+
+For sprint membership changes, call `add_item_to_current_sprint` /
+`remove_item_from_current_sprint` (or `set_sprint` for a full replace) — NOT
+`update_item`.
+
+## Step 5: Report
+
+Single:
+```
+✓ #42 updated — priority P1, status in_progress
+```
+
+Batch:
+```
+✓ 3 items updated — priority P1, status in_progress
+  #7, #12, #19
+```
+
+## Rules
+
+- **Every status/priority change gets a note** — no "I'll explain later" allowed.
+- **Batch confirmations are one-shot** — do NOT ask per-item if user clearly grouped them.
+- **ID normalization is uniform** — use the same regex as /track-resolve and /track-list.
+- **Terminal transitions auto-remove the item from the current sprint** (resolve
+  soft-removes its item_sprints links); sprint membership is never set via
+  `update_item` — `in_current_sprint` is derived and read-only.

dct/web/__init__.py

@@ -0,0 +1 @@
+"""dct web viewer — v1 read-only Flask adapter over dct.core."""

dct/web/app.py

@@ -0,0 +1,83 @@
+"""Flask application factory for the dct web viewer (v1, read-only).
+
+Third adapter over ``dct.core`` — symmetric to the CLI and MCP server. Read-only
+means the web layer NEVER calls ``create_tables()``: when it has to open its own
+engine it uses ``bootstrap_engine(create=False)``. Schema ownership stays with
+the CLI / MCP writers.
+"""
+
+import flask
+
+from dct.core.engine import bootstrap_engine
+from dct.web.serializers import parse_tags, render_markdown, to_iso
+
+_BLUEPRINT_MODULES = (
+    "home",
+    "projects",
+    "items",
+    "sprints",
+    "plans",
+    "changelog",
+    "decisions",
+    "handoffs",
+    "analytics",
+    "events",
+)
+
+
+def create_app(engine=None, *, read_only: bool = True) -> flask.Flask:
+    """Build the Flask app.
+
+    When `engine` is None, open a fresh read-only engine via
+    ``bootstrap_engine(create=False)`` — never creating tables. The engine is
+    stashed on ``app.config["DCT_ENGINE"]`` for blueprints to read via
+    :func:`current_engine`.
+    """
+    if engine is None:
+        engine = bootstrap_engine(create=False)
+
+    app = flask.Flask(__name__)
+    app.config["DCT_ENGINE"] = engine
+    app.config["DCT_READ_ONLY"] = read_only
+
+    # Jinja filters — registered HERE only. Templates across all tasks rely on
+    # these; no other task registers filters or adds a conditional fallback.
+    app.jinja_env.filters["render_markdown"] = render_markdown
+    app.jinja_env.filters["to_iso"] = to_iso
+    app.jinja_env.filters["parse_tags"] = parse_tags
+
+    from importlib import import_module
+
+    for name in _BLUEPRINT_MODULES:
+        module = import_module(f"dct.web.blueprints.{name}")
+        app.register_blueprint(module.bp)
+
+    @app.context_processor
+    def _inject_nav():
+        """Expose the project list + current location to every template, so the
+        sidebar can render the project switcher, highlight the active project,
+        and show a per-project section sub-nav."""
+        from dct.core.projects import list_projects
+
+        view_args = (flask.request.view_args or {}) if flask.request else {}
+        endpoint = (flask.request.endpoint or "") if flask.request else ""
+        try:
+            projects = list_projects(engine)
+        except Exception:
+            projects = []
+        # Detail routes (/sprints/<id>, /plans/<id>) have no slug in the URL but
+        # set flask.g.current_slug/section so the sidebar + breadcrumb still scope
+        # to the owning project. g wins; URL/endpoint are the fallback.
+        return {
+            "projects": projects,
+            "current_slug": getattr(flask.g, "current_slug", None) or view_args.get("slug"),
+            "current_section": getattr(flask.g, "current_section", None)
+            or (endpoint.split(".")[0] if endpoint else ""),
+        }
+
+    return app
+
+
+def current_engine():
+    """Return the shared engine bound to the active Flask app."""
+    return flask.current_app.config["DCT_ENGINE"]

dct/web/blueprints/__init__.py

@@ -0,0 +1,5 @@
+"""Route blueprints for the dct web viewer.
+
+Each module exposes a module-level ``bp`` Flask Blueprint. v1 stubs are filled
+in by later tasks; ``events`` already owns ``/healthz``.
+"""

dct/web/blueprints/analytics.py

@@ -0,0 +1,34 @@
+"""Analytics dashboard blueprint: Backlog Health + Velocity (read-only)."""
+from __future__ import annotations
+
+from flask import Blueprint, abort, render_template
+
+from dct.core.analytics import backlog_health, velocity
+from dct.core.projects import get_project
+from dct.web.app import current_engine
+
+bp = Blueprint("analytics", __name__)
+
+
+@bp.route("/p/<slug>/analytics")
+def dashboard(slug: str):
+    """Render the two-tab BI dashboard for a single project.
+
+    Tab 1 (Backlog Health) uses CSS/SVG bars over ``backlog_health`` dicts.
+    Tab 2 (Velocity) emits the ``velocity`` dict as an embedded JSON payload
+    that the vendored uPlot chart-init (static/app.js) reads on load.
+    """
+    engine = current_engine()
+    project = get_project(engine, slug)
+    if project is None:
+        abort(404)
+
+    health = backlog_health(engine, slug)
+    vel = velocity(engine, slug)
+    return render_template(
+        "analytics.html",
+        project=project,
+        slug=slug,
+        health=health,
+        velocity=vel,
+    )

dct/web/blueprints/changelog.py

@@ -0,0 +1,40 @@
+"""Changelog view — grouped by version, unreleased bucket first."""
+
+from __future__ import annotations
+
+from flask import Blueprint, render_template
+
+from dct.web.app import current_engine
+from dct.core import changelog as changelog_core
+
+bp = Blueprint("changelog", __name__)
+
+
+@bp.route("/p/<slug>/changelog")
+def list(slug):  # noqa: A001 — endpoint name changelog.list is part of the contract
+    engine = current_engine()
+    entries = changelog_core.list_entries(engine, slug)
+    unreleased_count = changelog_core.count_unreleased(engine, slug)
+
+    # Group by version, preserving created_at-desc order. version=None => unreleased.
+    groups: dict = {}
+    order: list = []
+    for entry in entries:
+        key = entry.get("version")  # None for unreleased
+        if key not in groups:
+            groups[key] = []
+            order.append(key)
+        groups[key].append(entry)
+
+    # Unreleased bucket (None) always rendered first, then versions in encounter order.
+    version_groups = []
+    if None in groups:
+        version_groups.append((None, groups[None]))
+    version_groups.extend((k, groups[k]) for k in order if k is not None)
+
+    return render_template(
+        "changelog/list.html",
+        slug=slug,
+        version_groups=version_groups,
+        unreleased_count=unreleased_count,
+    )

dct/web/blueprints/decisions.py

@@ -0,0 +1,23 @@
+"""Decision views — ADR list with supersede chains + status."""
+
+from __future__ import annotations
+
+from flask import Blueprint, render_template
+
+from dct.web.app import current_engine
+from dct.core import decisions as decisions_core
+
+bp = Blueprint("decisions", __name__)
+
+
+@bp.route("/p/<slug>/decisions")
+def list(slug):  # noqa: A001 — endpoint name decisions.list is part of the contract
+    engine = current_engine()
+    decisions = decisions_core.list_decisions(engine, project_slug=slug)
+    by_id = {d["id"]: d for d in decisions}
+    return render_template(
+        "decisions/list.html",
+        slug=slug,
+        decisions=decisions,
+        by_id=by_id,
+    )

dct/web/blueprints/events.py

@@ -0,0 +1,69 @@
+"""SSE live-refresh stream and liveness probe (read-only)."""
+
+import time
+
+from flask import Blueprint, Response
+
+bp = Blueprint("events", __name__)
+
+
+def _sse_events(token_source, *, poll_interval, sleep=time.sleep, should_continue=None):
+    """Yield SSE frames; emit an `event: stale` frame whenever the token changes.
+
+    token_source:   zero-arg callable returning the current change token (str).
+    poll_interval:  seconds to sleep between polls.
+    sleep:          injectable sleep (tests pass a no-op).
+    should_continue: zero-arg predicate gating the loop. Defaults to an infinite
+                     stream (real request); tests pass a bounded predicate.
+
+    Pure: no Flask / DB imports, so it is unit-testable with a fake token source.
+    """
+    if should_continue is None:
+        should_continue = lambda: True  # noqa: E731 — infinite stream for a live request
+    last = token_source()
+    # Opening comment defeats proxy buffering and confirms the stream is live.
+    yield ": connected\n\n"
+    while should_continue():
+        sleep(poll_interval)
+        current = token_source()
+        if current != last:
+            last = current
+            yield f"event: stale\ndata: {current}\n\n"
+        else:
+            yield ": keep-alive\n\n"
+
+
+@bp.route("/events")
+def stream():
+    """text/event-stream: poll change_token, push a 'stale' event on change."""
+    from dct.config import load_config
+    from dct.web.app import current_engine
+    from dct.web.changes import change_token
+
+    engine = current_engine()  # capture in request context, before the generator runs
+    web_cfg = getattr(load_config(), "web", None)
+    poll_ms = getattr(web_cfg, "refresh_poll_ms", 2000)
+    poll = max(int(poll_ms), 250) / 1000.0  # floor avoids hammering the DB
+
+    # NOTE: this is an unbounded generator — with Flask threaded=True each open
+    # tab pins one worker thread polling change_token() every `poll` seconds for
+    # the life of the connection. Acceptable for the localhost single-user v1;
+    # revisit (max lifetime / backoff) before any multi-client exposure.
+    def gen():
+        yield from _sse_events(lambda: change_token(engine), poll_interval=poll)
+
+    return Response(
+        gen(),
+        mimetype="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "X-Accel-Buffering": "no",  # disable nginx buffering if proxied
+            "Connection": "keep-alive",
+        },
+    )
+
+
+@bp.route("/healthz")
+def healthz():
+    """Liveness probe."""
+    return {"status": "ok"}

dct/web/blueprints/handoffs.py

@@ -0,0 +1,26 @@
+"""Handoff views — ledger split into unconsumed inbox + consumed history."""
+
+from __future__ import annotations
+
+from flask import Blueprint, render_template
+
+from dct.web.app import current_engine
+from dct.core import handoff as handoff_core
+
+bp = Blueprint("handoffs", __name__)
+
+
+@bp.route("/p/<slug>/handoffs")
+def list(slug):  # noqa: A001 — endpoint name handoffs.list is part of the contract
+    engine = current_engine()
+    all_handoffs = handoff_core.list_handoffs(
+        engine, project_slug=slug, unconsumed_only=False
+    )
+    unconsumed = [h for h in all_handoffs if h.get("consumed_at") is None]
+    consumed = [h for h in all_handoffs if h.get("consumed_at") is not None]
+    return render_template(
+        "handoffs/list.html",
+        slug=slug,
+        unconsumed=unconsumed,
+        consumed=consumed,
+    )

dct/web/blueprints/home.py

@@ -0,0 +1,15 @@
+"""Home view — cross-project Radar rollup cards (GET /)."""
+
+from flask import Blueprint, render_template
+
+from dct.core.analytics import radar as compute_radar
+from dct.web.app import current_engine
+
+bp = Blueprint("home", __name__)
+
+
+@bp.route("/")
+def radar():
+    """Cross-project operational rollup: open/priority/in-progress/stale/handoffs."""
+    data = compute_radar(current_engine())
+    return render_template("home.html", radar=data)

dct/web/blueprints/items.py

@@ -0,0 +1,128 @@
+"""Items views — filterable list table + detail page (read-only).
+
+GET /p/<slug>/items            filter form + htmx-swappable table
+GET /p/<slug>/items/<int:id>   detail: markdown description, notes, checkpoints
+"""
+
+from flask import Blueprint, abort, render_template, request
+
+from dct.web.app import current_engine
+from dct.core.items import list_items, get_item
+
+bp = Blueprint("items", __name__)
+
+# Checkpoint kinds that are NOT gates. Anything else is a gate (conservative
+# default — mirrors dct.core.checkpoints gate semantics).
+GATE_NONKINDS = {"task", "cc-task"}
+
+
+def is_gate(kind: str | None) -> bool:
+    return (kind or "task") not in GATE_NONKINDS
+
+
+# Filter values offered in the list form. Kept here (not in templates) so the
+# allowed set is one source of truth.
+TYPE_OPTIONS = ["issue", "todo", "feature", "idea", "improvement"]
+PRIORITY_OPTIONS = ["P1", "P2", "P3", "future"]
+STATUS_OPTIONS = ["open", "in_progress", "resolved", "wont_fix"]
+SORT_OPTIONS = [
+    ("status", "status"),
+    ("priority", "priority"),
+    ("recent", "recently updated"),
+    ("created", "newest"),
+    ("title", "title"),
+]
+_PRI_RANK = {"P1": 1, "P2": 2, "P3": 3, "future": 4}
+# Active work first, terminal states sink to the bottom: in_progress, open,
+# then wont_fix, resolved. Priority is the secondary key within each status.
+_STATUS_RANK = {"in_progress": 0, "open": 1, "wont_fix": 2, "resolved": 3}
+
+
+def _clean(value: str | None) -> str | None:
+    """Empty querystring value -> None so it is not passed as a filter."""
+    if value is None:
+        return None
+    value = value.strip()
+    return value or None
+
+
+@bp.route("/p/<slug>/items")
+def list(slug):
+    engine = current_engine()
+    filters = {
+        "item_type": _clean(request.args.get("type")),
+        "priority": _clean(request.args.get("priority")),
+        "status": _clean(request.args.get("status")),
+        "component": _clean(request.args.get("component")),
+        "search": _clean(request.args.get("q")),
+    }
+    rows = list_items(
+        engine,
+        project_slug=slug,
+        item_type=filters["item_type"],
+        priority=filters["priority"],
+        status=filters["status"],
+        component=filters["component"],
+        search=filters["search"],
+        limit=500,
+    )
+
+    # Optional tag filter — applied in Python because list_items has no tag
+    # parameter; tags are already parsed to list[str] in the returned dicts.
+    tag = _clean(request.args.get("tag"))
+    if tag:
+        rows = [r for r in rows if tag in (r.get("tags") or [])]
+
+    # Sorting — list_items returns priority-then-newest; re-sort in Python for
+    # the other modes (no extra query). "priority" keeps the core order.
+    sort = _clean(request.args.get("sort")) or "status"
+    if sort == "status":
+        rows.sort(key=lambda r: (_STATUS_RANK.get(r["status"], 9), _PRI_RANK.get(r["priority"], 9), -r["id"]))
+    elif sort == "recent":
+        rows.sort(key=lambda r: (r.get("updated_at") or r.get("created_at")), reverse=True)
+    elif sort == "created":
+        rows.sort(key=lambda r: r.get("created_at"), reverse=True)
+    elif sort == "title":
+        rows.sort(key=lambda r: (r.get("title") or "").lower())
+
+    ctx = {
+        "slug": slug,
+        "items": rows,
+        "filters": filters,
+        "tag": tag or "",
+        "sort": sort,
+        "type_options": TYPE_OPTIONS,
+        "priority_options": PRIORITY_OPTIONS,
+        "status_options": STATUS_OPTIONS,
+        "sort_options": SORT_OPTIONS,
+    }
+
+    # Return ONLY the table fragment when the filter form swaps it
+    # (hx-target="#items-table" → HX-Target: items-table). Other htmx requests
+    # — notably the SSE live-refresh which re-fetches #main (HX-Target: main) —
+    # must receive the full page so `select:"#main"` finds the chrome.
+    if request.headers.get("HX-Target") == "items-table":
+        return render_template("partials/_items_table.html", **ctx)
+    return render_template("items_list.html", **ctx)
+
+
+@bp.route("/p/<slug>/items/<int:id>")
+def detail(slug, id):
+    engine = current_engine()
+    item = get_item(engine, id)
+    if item is None:
+        abort(404)
+    # Prev/next within the project, in the default list order (priority, newest).
+    siblings = list_items(engine, project_slug=slug, limit=1000)
+    ids = [r["id"] for r in siblings]
+    prev_item = next_item = None
+    if id in ids:
+        i = ids.index(id)
+        if i > 0:
+            prev_item = siblings[i - 1]
+        if i < len(ids) - 1:
+            next_item = siblings[i + 1]
+    return render_template(
+        "item_detail.html", slug=slug, item=item, is_gate=is_gate,
+        prev_item=prev_item, next_item=next_item,
+    )

dct/web/blueprints/plans.py

@@ -0,0 +1,53 @@
+"""Plan views — list + detail rendering the nested section tree recursively."""
+
+from __future__ import annotations
+
+from flask import Blueprint, abort, g, render_template
+
+from dct.web.app import current_engine
+from dct.core.plans import crud as plans_core
+from dct.core import projects as projects_core
+
+bp = Blueprint("plans", __name__)
+
+
+@bp.route("/p/<slug>/plans")
+def list(slug):  # noqa: A001 — endpoint name plans.list is part of the contract
+    engine = current_engine()
+    plans = plans_core.list_plans(engine, project_slug=slug)
+    return render_template("plans/list.html", slug=slug, plans=plans)
+
+
+@bp.route("/plans/<int:plan_id>")
+def detail(plan_id):
+    engine = current_engine()
+    plan = plans_core.get_plan(engine, plan_id)
+    if plan is None:
+        abort(404)
+    # /plans/<id> carries no slug; resolve the owning project so the sidebar +
+    # breadcrumb scope to it (projects core has no get-by-id → map from list).
+    slug = next(
+        (p["slug"] for p in projects_core.list_projects(engine)
+         if p["id"] == plan.get("project_id")),
+        None,
+    )
+    g.current_slug = slug
+    g.current_section = "plans"
+    # get_plan returns a FLAT `sections` list (each with parent_section_id +
+    # embedded `checkpoints`). Rebuild parent->children adjacency for the
+    # recursive template; sections are already sort_order-ordered.
+    children_map: dict[int, list] = {}
+    roots = []
+    for section in plan["sections"]:
+        parent_id = section.get("parent_section_id")
+        if parent_id is None:
+            roots.append(section)
+        else:
+            children_map.setdefault(parent_id, []).append(section)
+    return render_template(
+        "plans/detail.html",
+        plan=plan,
+        roots=roots,
+        children_map=children_map,
+        progress=plan["progress"],
+    )

dct/web/blueprints/projects.py

@@ -0,0 +1,23 @@
+"""Project home view — ready-made sprint-review dashboard (GET /p/<slug>)."""
+
+from flask import Blueprint, abort, render_template
+
+from dct.core.projects import get_project
+from dct.core.sprint import get_sprint_review
+from dct.web.app import current_engine
+
+bp = Blueprint("projects", __name__)
+
+
+@bp.route("/p/<slug>")
+def home(slug):
+    """Per-project dashboard backed by sprint.get_sprint_review.
+
+    A missing/soft-deleted slug yields 404 (distinct from an empty project).
+    """
+    engine = current_engine()
+    project = get_project(engine, slug)
+    if project is None:
+        abort(404)
+    review = get_sprint_review(engine, slug)
+    return render_template("project_home.html", project=project, review=review)