dctracker 1.0.0__py3-none-any.whl

dct/export.py

@@ -0,0 +1,107 @@
+"""Export changelog entries to Keep a Changelog markdown format."""
+
+from collections import defaultdict
+from datetime import date
+
+import sqlalchemy as sa
+
+from dct.db import changelog_entries, projects, row_to_dict
+
+
+def export_changelog_md(
+    engine: sa.Engine,
+    project_slug: str,
+    include_unreleased: bool = True,
+    version: str | None = None,
+) -> str:
+    """Generate Keep a Changelog format markdown from DB entries.
+
+    When `version` is given, render ONLY that version's `## [version] - DATE`
+    block — WITHOUT the top-level `# Changelog` header and WITHOUT the
+    [Unreleased] section. This single-version unit is what the append-only
+    /release flow prepends into an existing changelog.md (see item #214); an
+    unknown version renders to an empty string. When `version` is None
+    (default) the full file is rendered: header + [Unreleased] + every version.
+    """
+    with engine.begin() as conn:
+        row = conn.execute(
+            sa.select(projects.c.id).where(projects.c.slug == project_slug, projects.c.deleted_at.is_(None))
+        ).first()
+        if not row:
+            raise ValueError(f"Project '{project_slug}' not found")
+        pid = row._mapping["id"]
+        q = (
+            sa.select(changelog_entries)
+            .where(changelog_entries.c.project_id == pid, changelog_entries.c.deleted_at.is_(None))
+        )
+        if version is not None:
+            q = q.where(changelog_entries.c.version == version)
+        q = q.order_by(changelog_entries.c.released_at.desc().nulls_first(), changelog_entries.c.created_at)
+        rows = [row_to_dict(r) for r in conn.execute(q)]
+
+    category_order = ["added", "changed", "fixed", "removed"]
+
+    # Group by version
+    versions: dict[str | None, list[dict]] = defaultdict(list)
+    for row in rows:
+        versions[row["version"]].append(row)
+
+    # Single-version render: emit just the one block, no file-level header, so
+    # the append-only release flow can prepend it into the existing file.
+    if version is not None:
+        entries = versions.get(version)
+        if not entries:
+            return ""
+        block: list[str] = []
+        _render_version_block(version, entries, category_order, block)
+        return "\n".join(block)
+
+    lines = ["# Changelog\n", ""]
+
+    # Unreleased first
+    if include_unreleased and None in versions:
+        lines.append("## [Unreleased]")
+        lines.append("")
+        _render_version_entries(versions[None], category_order, lines)
+
+    # Released versions (sorted by released_at of each version's first entry, desc)
+    released = {k: v for k, v in versions.items() if k is not None}
+    for ver in sorted(released, key=lambda v: released[v][0].get("released_at") or "", reverse=True):
+        _render_version_block(ver, released[ver], category_order, lines)
+
+    return "\n".join(lines)
+
+
+def _render_version_block(
+    version: str, entries: list[dict], category_order: list[str], lines: list[str]
+) -> None:
+    """Append a `## [version] - DATE` header (date from the first entry's
+    released_at, or today when unreleased) followed by its category sections.
+    Shared by the full-file render and the single-version render so the two
+    paths can never drift apart."""
+    released_at = entries[0].get("released_at")
+    if released_at:
+        date_str = released_at.strftime("%Y-%m-%d") if hasattr(released_at, "strftime") else str(released_at)[:10]
+    else:
+        date_str = date.today().isoformat()
+    lines.append(f"## [{version}] - {date_str}")
+    lines.append("")
+    _render_version_entries(entries, category_order, lines)
+
+
+def _render_version_entries(entries: list[dict], category_order: list[str], lines: list[str]) -> None:
+    by_category: dict[str, list[dict]] = defaultdict(list)
+    for e in entries:
+        by_category[e["category"]].append(e)
+
+    for cat in category_order:
+        if cat not in by_category:
+            continue
+        lines.append(f"### {cat.capitalize()}")
+        lines.append("")
+        for e in by_category[cat]:
+            entry_text = e["entry"]
+            if e.get("component"):
+                entry_text = f"{entry_text} ({e['component']})"
+            lines.append(f"- {entry_text}")
+        lines.append("")

dct/hooks/check-changelog-on-stop.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# dct global Stop hook — non-blocking reminder after every turn.
+# Checks if app files changed without unreleased changelog entries.
+# Install: ~/.claude/hooks/dct-check-changelog-on-stop.sh
+
+# Require dct CLI
+command -v dct >/dev/null || exit 0
+
+# Check if we're in a dct-registered project
+project=$(dct project detect 2>/dev/null)
+if [ -z "$project" ]; then
+  exit 0
+fi
+
+# #222: opt-in — only remind for projects that manage their changelog in dct.
+if ! dct project manages-changelog "$project" 2>/dev/null; then
+  exit 0
+fi
+
+# Exempt patterns
+exempt_re="^\.(claude|github|cursor|vscode|gstack)/|^docs/|^scripts/|^tests/|^test_|conftest\.py$|CLAUDE\.md$|README\.md$|LICENSE|\.gitignore$|^changelog|^CHANGELOG|^VERSION$|pyproject\.toml$|Cargo\.toml$|package\.json$"
+
+# Check for modified/staged/untracked app files
+changed=$(git diff --name-only 2>/dev/null; git diff --cached --name-only 2>/dev/null; git ls-files --others --exclude-standard 2>/dev/null)
+[ -z "$changed" ] && exit 0
+
+# Deduplicate and filter exempt files
+app_files=$(echo "$changed" | sort -u | grep -vE "$exempt_re")
+[ -z "$app_files" ] && exit 0
+
+# Check if changelog was modified
+changelog_changed=$(echo "$changed" | sort -u | grep -iE "^changelog|^CHANGELOG" | head -1)
+if [ -n "$changelog_changed" ]; then
+  exit 0
+fi
+
+# Check dct DB for unreleased entries
+count=$(dct clog count --project "$project" 2>/dev/null)
+if [ "${count:-0}" -gt 0 ]; then
+  exit 0
+fi
+
+# Reminder (non-blocking — always exit 0)
+file_count=$(echo "$app_files" | wc -l | tr -d ' ')
+echo ""
+echo "📝 Reminder: ${file_count} app file(s) changed in ${project}/ but no changelog entry found."
+echo "   Use /clog to add an entry."
+echo ""
+exit 0

dct/hooks/check-changelog.sh

@@ -0,0 +1,143 @@
+#!/bin/bash
+# dct global hook — PreToolUse for Bash(git commit*)
+# Blocks commits without changelog entries (staged changelog file OR dct DB entry).
+# Opt-in (#222): enforces ONLY projects with manages_changelog=TRUE — a project
+# keeping its own changelog opts out via `dct project changelog <slug> off`.
+# Install: ~/.claude/hooks/dct-check-changelog.sh
+
+# Consume stdin (required by hook protocol)
+input=$(cat)
+
+# Require jq
+command -v jq >/dev/null || exit 0
+
+# Require dct CLI
+command -v dct >/dev/null || exit 0
+
+# Extract command from hook input
+command=$(echo "$input" | jq -r '.tool_input.command // ""' 2>/dev/null)
+
+# Only check git commit commands
+case "$command" in
+  *"git commit"*) ;;
+  *) exit 0 ;;
+esac
+
+# Skip amend commits (strip message content to avoid false matches)
+flags=$(echo "$command" | sed 's/ -m [^ ]*//g; s/ -m ".*"//g; s/ --message[= ][^ ]*//g; s/ --message ".*"//g')
+case "$flags" in
+  *"--amend"*) exit 0 ;;
+esac
+
+# Release-commit bypass: skip hook entirely when commit message starts with "release:"
+# /release skill produces clean release commits with zero unreleased entries after stamping.
+# Two forms to handle: inline -m "release: ..." and HEREDOC heredoc where the first line
+# of the message body is "release: ...".
+
+# Form 1 — inline -m "..." / -m '...' / --message="..."
+inline_msg=$(echo "$command" | sed -n \
+  -e 's/.*-m "\([^"]*\)".*/\1/p' \
+  -e "s/.*-m '\([^']*\)'.*/\1/p" \
+  -e 's/.*--message="\([^"]*\)".*/\1/p' \
+  | head -1)
+case "$inline_msg" in
+  release:*) exit 0 ;;
+esac
+
+# Form 2 — HEREDOC: multi-line command containing a line that starts with "release:"
+if echo "$command" | grep -qE '^release:'; then
+  exit 0
+fi
+
+# Check if we're in a dct-registered project
+project=$(dct project detect 2>/dev/null)
+if [ -z "$project" ]; then
+  exit 0  # Not a dct project — pass through
+fi
+
+# #222: opt-in — only enforce projects that manage their changelog in dct.
+# A project registered for item-tracking but keeping its own changelog opts out
+# via `dct project changelog <slug> off` and is skipped here.
+if ! dct project manages-changelog "$project" 2>/dev/null; then
+  exit 0
+fi
+
+# Get staged files
+staged=$(git diff --cached --name-only 2>/dev/null)
+if [ -z "$staged" ]; then
+  exit 0  # Nothing staged
+fi
+
+# Exempt patterns — files that don't require changelog entries
+exempt_patterns=(
+  "^\.claude/"
+  "^\.github/"
+  "^\.cursor/"
+  "^\.vscode/"
+  "^\.gstack/"
+  "^docs/"
+  "^scripts/"
+  "^tests/"
+  "^test_"
+  "conftest\.py$"
+  "CLAUDE\.md$"
+  "CLAUDE\.local\.md$"
+  "AGENTS\.md$"
+  "README\.md$"
+  "LICENSE"
+  "\.gitignore$"
+  "^changelog"
+  "^CHANGELOG"
+  "^VERSION$"
+  "pyproject\.toml$"
+  "Cargo\.toml$"
+  "package\.json$"
+  "biome\.json$"
+  "Dockerfile"
+  "docker-compose"
+)
+
+# Check if ALL staged files are exempt
+has_app_code=false
+while IFS= read -r file; do
+  is_exempt=false
+  for pattern in "${exempt_patterns[@]}"; do
+    if echo "$file" | grep -qE "$pattern"; then
+      is_exempt=true
+      break
+    fi
+  done
+  if [ "$is_exempt" = false ]; then
+    has_app_code=true
+    break
+  fi
+done <<< "$staged"
+
+if [ "$has_app_code" = false ]; then
+  exit 0  # All files are exempt
+fi
+
+# Check for changelog in staged files
+has_changelog=false
+while IFS= read -r file; do
+  case "$file" in
+    changelog*|CHANGELOG*|changelog_unreleased*) has_changelog=true; break ;;
+  esac
+done <<< "$staged"
+
+# If no changelog file staged, check dct database for unreleased entries
+if [ "$has_changelog" = false ]; then
+  count=$(dct clog count --project "$project" 2>/dev/null)
+  if [ "${count:-0}" -gt 0 ]; then
+    has_changelog=true
+  fi
+fi
+
+if [ "$has_changelog" = true ]; then
+  exit 0
+fi
+
+# Block the commit
+reason="App code staged but no changelog entry found for project '$project'. Add a changelog entry with /clog or stage a changelog file."
+echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"$reason\"}}"
+exit 2

dct/hooks/dct-plan-autoscan.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# dct-plan-autoscan.sh — PostToolUse hook for Claude Code.
+#
+# Rescans plan-like markdown files (plans, specs, ADRs, roadmaps, backlogs,
+# retros) after an Edit/Write/MultiEdit. Runs in the background so the user
+# never waits. Handles brand-new plans (ULID injection on first save) and
+# re-sync of already-tracked plans.
+#
+# Follows the five hook rules from dct CLAUDE.md:
+#   1. No interactive prompts (non-interactive only).
+#   2. Consume stdin (Claude Code hooks supply JSON there).
+#   3. Graceful when deps missing (command -v dct / jq).
+#   4. Exit codes meaningful: 0 = pass-through, non-zero avoided.
+#   5. No message-content inspection needed here (not a commit hook).
+set -euo pipefail
+
+# Rule 2: consume stdin even if we partially inspect it.
+input=$(cat)
+
+# Rule 3: graceful on missing deps — dct or jq absent means no-op.
+command -v dct >/dev/null || exit 0
+command -v jq  >/dev/null || exit 0
+
+# Extract tool name + file path from the JSON payload CC hooks pass.
+tool=$(echo "$input" | jq -r '.tool_name // empty' 2>/dev/null || true)
+file=$(echo "$input" | jq -r '.tool_input.file_path // empty' 2>/dev/null || true)
+
+# Only trigger on edit/write-style tools.
+case "$tool" in
+    Edit|Write|MultiEdit) ;;
+    *) exit 0 ;;
+esac
+
+# Only act on .md files matching our discovery patterns.
+case "$file" in
+    */docs/plans/*.md|*/docs/specs/*.md|*/docs/adr/*.md|*/docs/retros/*.md) ;;
+    */ROADMAP.md|*ROADMAP.md|*/TODOS.md|*TODOS.md|*/FUTURE.md|*FUTURE.md) ;;
+    */BACKLOG.md|*BACKLOG.md) ;;
+    *) exit 0 ;;
+esac
+
+# Must exist (edit may have been rejected / the file was deleted).
+[ -f "$file" ] || exit 0
+
+# Fire-and-forget: detach a background rescan, log to a unique temp file so
+# parallel hook invocations don't clobber each other. The `disown` is key —
+# without it, the hook would block until the subprocess exits, defeating the
+# whole point of the background pattern.
+log_dir="${TMPDIR:-/tmp}"
+log="${log_dir%/}/dct-rescan-$(date +%s)-$$.log"
+nohup dct plan rescan "$file" --quiet --resolve-uncertain >"$log" 2>&1 &
+disown
+
+exit 0

dct/hooks/dct-task-mirror.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# dct-task-mirror.sh — PreToolUse hook for Claude Code.
+#
+# Mirrors TaskCreate / TodoWrite calls to dct checkpoints. Thin shell
+# dispatcher: validates payload, checks config gate, detects project,
+# then delegates actual work to `dct _task-mirror` CLI subcommand (which
+# uses the venv-installed Python with dct importable — shell/system
+# python cannot reliably find dct on PYTHONPATH).
+#
+# Each todo becomes a `kind='cc-task'` checkpoint on a session-scoped item
+# titled "CC task list — session <id>". cc-task is non-blocking for
+# resolve_item gate semantics.
+#
+# Respects [mirror].task_to_dct config: auto (default) / ask / off.
+#
+# Follows the five hook rules from dct CLAUDE.md:
+#   1. No interactive prompts.
+#   2. Consume stdin.
+#   3. Graceful on missing deps.
+#   4. exit 0 on every path.
+#   5. No commit-message inspection.
+set -euo pipefail
+
+# Rule 2: drain stdin once; reuse for both tool detection and forwarding.
+input=$(cat)
+
+# Rule 3: graceful on missing deps.
+command -v jq  >/dev/null || exit 0
+command -v dct >/dev/null || exit 0
+
+tool=$(echo "$input" | jq -r '.tool_name // empty' 2>/dev/null || true)
+session_id=$(echo "$input" | jq -r '.session_id // "unknown"' 2>/dev/null || true)
+
+case "$tool" in
+    TaskCreate|TodoWrite) ;;
+    *) exit 0 ;;
+esac
+
+# Config gate.
+mode=$(dct config get mirror.task_to_dct 2>/dev/null || echo "auto")
+case "$mode" in
+    off|ask) exit 0 ;;
+    auto|"") ;;
+    *) exit 0 ;;
+esac
+
+# Project autodetect (hook CWD = current project).
+project=$(dct project detect 2>/dev/null || true)
+[ -z "$project" ] && exit 0
+
+log_dir="${TMPDIR:-/tmp}"
+log="${log_dir%/}/dct-task-mirror-$(date +%s)-$$.log"
+
+# Fire-and-forget. The background subshell pipes the payload to the
+# internal CLI worker and logs any output for diagnosis.
+{
+    nohup bash -c "printf '%s' \"\$1\" | dct _task-mirror --session-id \"\$2\" --project \"\$3\" >>\"\$4\" 2>&1" \
+        _ "$input" "$session_id" "$project" "$log" &
+    disown
+} </dev/null >/dev/null 2>&1
+
+exit 0