dctracker 1.0.0__py3-none-any.whl

dct/setup.py

@@ -0,0 +1,258 @@
+"""Init workflow helpers: register MCP user-scope, install hook, install skills."""
+
+import json
+import os
+import shutil
+import subprocess
+from datetime import datetime
+from pathlib import Path
+
+from dct.config import Config
+
+SKILLS_DIR = Path(__file__).resolve().parent / "skills"
+HOOKS_DIR = Path(__file__).resolve().parent / "hooks"
+CLAUDE_SKILLS_DIR = Path.home() / ".claude" / "skills"
+CLAUDE_HOOKS_DIR = Path.home() / ".claude" / "hooks"
+CLAUDE_JSON = Path.home() / ".claude.json"
+CLAUDE_SETTINGS = Path.home() / ".claude" / "settings.json"
+
+# Canonical wiring of the four dct hooks into ~/.claude/settings.json.
+# event/matcher come from each hook script's own header (the authoritative
+# self-description) — e.g. dct-task-mirror.sh declares PreToolUse on
+# TodoWrite|TaskCreate. matcher=None means the event takes no matcher (Stop).
+HOOK_WIRING = [
+    {"script": "dct-check-changelog.sh", "event": "PreToolUse",
+     "matcher": "Bash", "timeout": 10},
+    {"script": "dct-check-changelog-on-stop.sh", "event": "Stop",
+     "matcher": None, "timeout": 5},
+    {"script": "dct-plan-autoscan.sh", "event": "PostToolUse",
+     "matcher": "Edit|Write|MultiEdit", "timeout": None},
+    {"script": "dct-task-mirror.sh", "event": "PreToolUse",
+     "matcher": "TodoWrite|TaskCreate", "timeout": None},
+]
+
+def discover_skills() -> list[str]:
+    """Skill directories shipped inside the package (each holds a SKILL.md).
+
+    Derived from the filesystem on every call — dct/skills/ is the single
+    source of truth. Never reintroduce a hardcoded name list: a stale one
+    silently dropped plan-status and plan-resolve-uncertain from every
+    install for two releases.
+    """
+    if not SKILLS_DIR.is_dir():
+        return []
+    return sorted(p.name for p in SKILLS_DIR.iterdir() if (p / "SKILL.md").is_file())
+
+
+def register_mcp(config: Config) -> tuple[bool, str]:
+    """Register dct MCP server at user scope (~/.claude.json).
+
+    Uses the `dct server` subcommand as the stdio entry point — requires that
+    `dct` itself is installed in PATH (via `uv tool install`, `pipx install`,
+    or `pip install`). Zero hardcoded filesystem paths in the resulting config.
+
+    Tries `claude mcp add --scope user` CLI first; falls back to direct
+    ~/.claude.json edit if `claude` CLI is unavailable.
+    """
+    server_cmd = ["dct", "server"]
+
+    if shutil.which("claude"):
+        cmd = ["claude", "mcp", "add", "dct", "--scope", "user", "--"] + server_cmd
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        if result.returncode == 0:
+            return True, "registered via `claude mcp add --scope user`"
+        if "already exists" in (result.stderr + result.stdout).lower():
+            return True, "already registered"
+        # fall through to direct edit
+
+    # Fallback: direct ~/.claude.json edit
+    data = {}
+    if CLAUDE_JSON.exists():
+        with open(CLAUDE_JSON) as f:
+            data = json.load(f)
+    data.setdefault("mcpServers", {})["dct"] = {
+        "type": "stdio",
+        "command": server_cmd[0],
+        "args": server_cmd[1:],
+    }
+    with open(CLAUDE_JSON, "w") as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+    return True, "registered via direct ~/.claude.json edit"
+
+
+def install_hook(config: Config | None = None) -> bool:
+    """Symlink dct hooks into ~/.claude/hooks/ (single source of truth, #224).
+
+    Installs four hooks as SYMLINKS to the packaged dct/hooks/ directory (like
+    install_skills) — site-packages for a wheel install, the repo working tree
+    for an editable one, where a repo fix is live immediately without reinstall.
+    Copies drift from source — a stale installed copy is exactly what masked the
+    #223 clog-count bug timeline. The installed name is `dct-`-prefixed while the
+    packaged source is not (e.g. dct/hooks/check-changelog.sh → dct-check-changelog.sh):
+    - dct-check-changelog.sh (PreToolUse) — blocks commits without changelog
+    - dct-check-changelog-on-stop.sh (Stop) — reminds user at session end
+    - dct-plan-autoscan.sh (PostToolUse, v0.2.0) — re-scans plan-like MD files
+      in the background after edit/write, injecting ULIDs and updating DB state
+    - dct-task-mirror.sh (PostToolUse) — mirrors Claude Code tasks into dct
+
+    Each hook is independently optional: a source missing from the dct repo (old
+    checkout) is skipped silently. An existing pre-#224 regular-file copy is
+    replaced in place by the symlink. Wiring into `~/.claude/settings.json` is
+    handled separately by `wire_hooks_into_settings()` — called from `dct init`
+    (consent-gated) or via `dct hooks wire`; manual reference in docs/hooks.md.
+
+    Caveat: a symlinked hook tracks the repo WORKING TREE, including uncommitted
+    edits — intentional for a dev checkout (instant fixes) but means a dirty repo
+    affects live hook behaviour. `config` is accepted for call-site symmetry with
+    the other install_* helpers but is unused.
+    """
+    CLAUDE_HOOKS_DIR.mkdir(parents=True, exist_ok=True)
+    installed = 0
+
+    for src_name, dst_name in [
+        ("check-changelog.sh", "dct-check-changelog.sh"),
+        ("check-changelog-on-stop.sh", "dct-check-changelog-on-stop.sh"),
+        ("dct-plan-autoscan.sh", "dct-plan-autoscan.sh"),
+        ("dct-task-mirror.sh", "dct-task-mirror.sh"),
+    ]:
+        src = HOOKS_DIR / src_name
+        dst = CLAUDE_HOOKS_DIR / dst_name
+        if not src.exists():
+            continue
+        # Replace any existing symlink OR a pre-#224 regular-file copy in place.
+        if dst.is_symlink() or dst.exists():
+            dst.unlink()
+        dst.symlink_to(src)
+        installed += 1
+
+    return installed > 0
+
+
+def wire_hooks_into_settings(settings_path: Path | None = None) -> dict:
+    """Merge the four dct hook entries into ~/.claude/settings.json (idempotent).
+
+    Merge semantics:
+    - Missing or empty settings file → treated as ``{}`` and created.
+    - Idempotency probe is GLOBAL by script basename: a hook already mentioned
+      anywhere in ``hooks`` (any event, any matcher group, any path form —
+      absolute, ``~``-relative, with or without ``bash `` prefix) is skipped.
+      This deliberately respects a user's custom placement of a dct hook.
+    - A missing event list or matcher group is created; an existing group with
+      the same matcher gets the entry appended. User-defined hooks and all
+      unrelated top-level keys are never modified.
+    - Before the first actual write of a pre-existing file, the original is
+      copied to ``settings.json.bak-dct-<timestamp>`` next to it.
+    - The write is atomic (temp file + ``os.replace``).
+    - Malformed JSON or a non-object ``hooks`` key raises ``ValueError`` and
+      NOTHING is written — never destructive.
+
+    Returns a summary dict: ``{"added": [script names], "skipped": [...],
+    "backup": str | None, "settings_path": str}``.
+    """
+    if settings_path is None:
+        settings_path = CLAUDE_SETTINGS
+    settings_path = Path(settings_path)
+
+    raw = settings_path.read_text() if settings_path.exists() else None
+    if raw is None or not raw.strip():
+        settings = {}
+    else:
+        try:
+            settings = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise ValueError(
+                f"{settings_path} is not valid JSON ({exc}) — fix it manually; "
+                "nothing was written"
+            ) from exc
+    if not isinstance(settings, dict):
+        raise ValueError(
+            f"{settings_path}: top-level JSON must be an object; nothing was written"
+        )
+    hooks = settings.setdefault("hooks", {})
+    if not isinstance(hooks, dict):
+        raise ValueError(
+            f"{settings_path}: 'hooks' must be an object, "
+            f"found {type(hooks).__name__}; nothing was written"
+        )
+
+    existing_commands = []
+    for groups in hooks.values():
+        if not isinstance(groups, list):
+            continue
+        for group in groups:
+            if not isinstance(group, dict):
+                continue
+            for hook in group.get("hooks") or []:
+                if isinstance(hook, dict):
+                    existing_commands.append(str(hook.get("command", "")))
+
+    added, skipped = [], []
+    for spec in HOOK_WIRING:
+        name = spec["script"]
+        if any(name in cmd for cmd in existing_commands):
+            skipped.append(name)
+            continue
+        entry = {"type": "command", "command": f"bash {CLAUDE_HOOKS_DIR / name}"}
+        if spec["timeout"] is not None:
+            entry["timeout"] = spec["timeout"]
+        groups = hooks.setdefault(spec["event"], [])
+        target = next(
+            (g for g in groups
+             if isinstance(g, dict) and g.get("matcher") == spec["matcher"]),
+            None,
+        )
+        if target is None:
+            target = {"hooks": []}
+            if spec["matcher"] is not None:
+                target["matcher"] = spec["matcher"]
+            groups.append(target)
+        target.setdefault("hooks", []).append(entry)
+        added.append(name)
+
+    backup = None
+    if added:
+        if raw is not None and raw.strip():
+            stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+            backup_path = settings_path.with_name(
+                f"{settings_path.name}.bak-dct-{stamp}"
+            )
+            backup_path.write_text(raw)
+            backup = str(backup_path)
+        settings_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp_path = settings_path.with_name(settings_path.name + ".dct-tmp")
+        tmp_path.write_text(json.dumps(settings, indent=2, ensure_ascii=False) + "\n")
+        os.replace(tmp_path, settings_path)
+
+    return {
+        "added": added,
+        "skipped": skipped,
+        "backup": backup,
+        "settings_path": str(settings_path),
+    }
+
+
+def install_skills(config: Config) -> bool:
+    """Symlink every packaged skill (dct/skills/*) into ~/.claude/skills/.
+
+    Sources come from the installed package — site-packages for a wheel
+    install, the repo working tree for an editable one (where a repo fix is
+    live without reinstall).
+    """
+    CLAUDE_SKILLS_DIR.mkdir(parents=True, exist_ok=True)
+    installed = 0
+
+    for name in discover_skills():
+        src = SKILLS_DIR / name
+        dst = CLAUDE_SKILLS_DIR / name
+
+        # Remove existing symlink or directory
+        if dst.is_symlink():
+            dst.unlink()
+        elif dst.exists():
+            continue  # don't overwrite non-symlink dirs
+
+        dst.symlink_to(src)
+        installed += 1
+
+    return installed > 0

dct/skills/clog/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: clog
+description: |
+  Add a changelog entry to dct database.
+  Use when: "clog", "changelog", "dodaj do changelogu", "add changelog entry",
+  "log this change", "record change", or when committing and changelog needs an entry.
+  Natural past-tense triggers (use after finishing a change):
+  "zmieniłem", "poprawiłem", "naprawiłem", "dodałem", "usunąłem", "zrobiłem",
+  "zrefaktorowałem", "zaktualizowałem",
+  "I added", "I fixed", "I changed", "I removed", "I refactored",
+  "just fixed", "just added", "logged a change", "note this change".
+---
+
+# /clog — Add Changelog Entry
+
+## Workflow
+
+### Step 1: Gather from context
+From the current work, determine:
+- **project**: Auto-detect from CWD, or ask
+- **category**: added, changed, fixed, removed (see mapping below)
+- **entry**: Concise description of the change (English, ~1 sentence)
+- **component**: Module/subsystem (optional)
+- **source_file**: Main file changed (optional)
+- **related_item_id**: If this change resolves a tracked item (optional)
+
+### Step 2: Confirm
+```
+Changelog entry:
+  [added] New Python parser support (parser)
+  File: cmd/parse.go
+```
+Wait for confirmation.
+
+### Step 3: Create
+Call `mcp__dct__add_changelog(project, category, entry, ...)`.
+
+### Step 4: Report
+```
+✓ Changelog #15 [added] — New Python parser support
+```
+
+## Category mapping
+| Change type | category |
+|---|---|
+| New feature, new file, new capability | added |
+| Refactor, rename, restructure, update behavior | changed |
+| Bug fix, crash fix, correction | fixed |
+| Deleted code, removed feature, deprecated | removed |
+
+## Conventional commit → category
+| Prefix | category |
+|---|---|
+| feat: | added |
+| fix: | fixed |
+| refactor:, chore:, perf: | changed |
+| revert: | removed |
+
+## Multiple entries
+
+If a commit touches multiple areas, create multiple changelog entries —
+one per logical change. Example: refactor that also fixes a bug and adds
+a helper:
+
+```
+✓ Changelog #20 [changed] — Extracted shared auth validation (core/auth)
+✓ Changelog #21 [fixed]   — Token refresh race condition on concurrent login (core/auth)
+✓ Changelog #22 [added]   — is_expired() helper on Session model (core/auth)
+```
+
+Each entry is a separate `add_changelog` call. Don't concatenate changes
+into one entry — it makes the generated changelog.md harder to skim at
+release time.

dct/skills/commit/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: commit
+description: |
+  Create a git commit following dct changelog-first workflow and conventional commit format.
+  Use when: "commit", "commit this", "zapisz", "save this", "commitnij", or when the
+  user has finished implementing something and the natural next step is to commit.
+---
+
+# /commit — Git Commit (dct-aware)
+
+Universal commit workflow. Works in any dct-registered project — auto-detects from CWD.
+Mirrors the global hook's exemption rules so the first attempt passes.
+
+## Workflow
+
+### Step 1: Pre-flight parallel probe
+
+Run these 4 Bash commands **in parallel** (one message, four tool calls):
+
+```
+git status
+git diff --cached --stat
+git diff --stat
+git log --oneline -5
+```
+
+If nothing changed AND nothing staged → inform user "Clean tree, nothing to commit" and stop.
+If only untracked files with no staged or modified files → ask user whether to track them.
+
+### Step 2: Detect project and fetch current_version
+
+Call `mcp__dct__list_projects()` and match longest project path prefix against CWD.
+
+- If CWD is inside a registered project → remember `slug`, `current_version`.
+- If not a dct project → `current_version` is null, continue without version suffix.
+
+### Step 2b: Version-bump detection — redirect to /release
+
+If staged changes look like a version bump (matching any of the conditions
+below), STOP and suggest `/release` to the user instead of committing here:
+
+- `changelog.md` / `CHANGELOG.md` is staged AND contains a new `## [X.Y.Z]` heading
+- Any of `pyproject.toml`, `Cargo.toml`, `package.json`, `tauri.conf.json`, `plugin.json` has a staged `version = "..."` change
+- `mcp__dct__count_unreleased_changelog(project)` returned a large batch (≥10) that looks release-ready
+
+Present via `AskUserQuestion`:
+- question: "Staged changes look like a version bump. Prefer /release?"
+- options: `"Run /release instead"` / `"No — regular commit"` / `"Cancel"`.
+
+Release commits use the literal `release: vX.Y.Z` format (no scope, no version
+suffix on subject) — different from regular /commit messages.
+
+### Step 3: Changelog guard
+
+If project detected:
+- Call `mcp__dct__count_unreleased_changelog(project)`.
+- If count == 0 AND staged files contain non-exempt code (see Exempt patterns below):
+  - Prompt user via AskUserQuestion: "No unreleased changelog entry. Add one now? [Yes, via /clog] [Skip, changelog not needed for this commit] [Cancel]"
+  - On "Yes" → invoke `/clog` or call `mcp__dct__add_changelog` inline.
+  - On "Skip" → proceed but warn this may hit the commit hook.
+  - On "Cancel" → stop.
+
+**Exempt patterns** (no changelog required if ALL staged files match):
+- `.claude/`, `.claude-plugin/`, `.github/`, `.cursor/`, `.vscode/`, `.gstack/`
+- `docs/`, `scripts/`, `tests/`, `dct/skills/`, `test_*.py`, `conftest.py`
+- `CLAUDE.md`, `CLAUDE.local.md`, `AGENTS.md`, `README.md`, `LICENSE*`
+- `changelog.md`, `CHANGELOG*`, `.gitignore`
+- Config files: `pyproject.toml`, `Cargo.toml`, `package.json`, `biome.json`, `tsconfig*.json`
+
+### Step 4: Stage files explicitly
+
+Show user the proposed staging plan:
+```
+Files to stage:
+  dct/core/items.py
+  tests/test_items.py
+```
+
+Stage each path **by name** — one per `git add <path>` call, or multiple paths in one call
+listed explicitly. NEVER:
+- `git add -A`
+- `git add .`
+- `git add *`
+
+NEVER stage (blacklist):
+- `.env`, `.env.*` (any env files)
+- `credentials*`, `secrets*`, `*.pem`, `*.key`
+- Binaries, generated artifacts (`dist/`, `build/`, `target/`, `*.pyc`)
+
+### Step 5: Draft and commit
+
+Build the commit message with conventional format:
+
+```
+<type>(<scope>): <description> (v<current_version>)
+```
+
+- `type` ∈ {feat, fix, refactor, chore, docs, test, perf, style, revert}
+- `scope` = component name (match project's component taxonomy: `core`, `cli`, `server`, etc.)
+- `description` = imperative, lowercase, no trailing period, ≤ 72 chars
+- `(v<version>)` suffix — **OMIT if `current_version` is null** or if this IS the release commit.
+
+**Release commits** have a different format (set by `/release`):
+```
+release: vX.Y.Z
+```
+
+Execute via HEREDOC to preserve formatting:
+
+```bash
+git commit -m "$(cat <<'EOF'
+<type>(<scope>): <description> (v<version>)
+
+Optional body paragraph explaining WHY (not what).
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+### Step 6: Hook-reject recovery
+
+If the dct hook (or any project hook) rejects the commit:
+
+1. Read the hook's error message carefully — it tells you exactly what's missing.
+2. Fix the underlying issue (usually: add changelog entry via `/clog`).
+3. Re-stage any new files from the fix.
+4. Create a **NEW** commit — do NOT `git commit --amend`. Amend modifies the PREVIOUS commit, which may not exist (rejected commits don't happen).
+5. Never bypass with `--no-verify`, `--no-gpg-sign`, or similar escape hatches.
+
+### Step 7: Verify
+
+After successful commit:
+```bash
+git log --oneline -3
+git status
+```
+
+Report to user:
+```
+✓ Committed abc1234 — feat(core): add checkpoint CRUD (v0.1.0)
+```
+
+## Rules (hard)
+
+- NEVER commit without user approval of the staging plan AND message draft.
+- NEVER stage `.env`, credentials, binaries, or anything matching the blacklist.
+- NEVER use `git add -A`, `git add .`, or broad globs.
+- NEVER use `--amend` unless the user explicitly asks (to edit a successful commit).
+- NEVER use `--no-verify`. Hooks exist for reasons — if blocked, fix and re-commit.
+- NEVER force-push to main/master branches.
+- ALWAYS include `Co-Authored-By` trailer with Claude's model identifier.
+- Release commits use literal `release: vX.Y.Z` format — no scope, no description.