cc-pushback 0.1.0__tar.gz

cc_pushback-0.1.0/LICENSE

@@ -0,0 +1,133 @@
+Required Notice: Copyright Yasyf Mohamedali (https://github.com/yasyf/cc-pushback)
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

cc_pushback-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: cc-pushback
+Version: 0.1.0
+Summary: Learn your pushback style from past Claude Code feedback and code reviews, and replicate it with a language model.
+Keywords: 
+Author: Yasyf Mohamedali
+Author-email: Yasyf Mohamedali <yasyfm@gmail.com>
+License-Expression: PolyForm-Noncommercial-1.0.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Dist: aiohttp>=3.10
+Requires-Dist: anyio>=4.4
+Requires-Dist: cc-transcript>=0.7,<0.8
+Requires-Dist: click>=8
+Requires-Dist: spawnllm>=0.1
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: ty>=0.0.44 ; extra == 'dev'
+Requires-Dist: ruff>=0.8 ; extra == 'dev'
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/yasyf/cc-pushback
+Project-URL: Documentation, https://yasyf.github.io/cc-pushback/
+Project-URL: Repository, https://github.com/yasyf/cc-pushback
+Project-URL: Issues, https://github.com/yasyf/cc-pushback/issues
+Project-URL: Changelog, https://github.com/yasyf/cc-pushback/blob/main/CHANGELOG.md
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# cc-pushback
+
+[![PyPI](https://img.shields.io/pypi/v/cc-pushback.svg)](https://pypi.org/project/cc-pushback/)
+[![Python](https://img.shields.io/pypi/pyversions/cc-pushback.svg)](https://pypi.org/project/cc-pushback/)
+[![Docs](https://img.shields.io/github/actions/workflow/status/yasyf/cc-pushback/docs.yml?branch=main&label=docs)](https://yasyf.github.io/cc-pushback/)
+[![License: PolyForm-Noncommercial-1.0.0](https://img.shields.io/badge/License-PolyForm--Noncommercial--1.0.0-blue.svg)](https://github.com/yasyf/cc-pushback/blob/main/LICENSE)
+
+cc-pushback mines your Claude Code transcripts for the moments you pushed back — corrections, interrupts, rejected plans, code-review comments, "no, do it this way" — and collects them, with the surrounding conversational context, into a local database. That corpus is the raw material for learning your pushback style; this first release builds it.
+
+## Install
+
+No install needed — run everything through [uvx](https://docs.astral.sh/uv/):
+
+```bash
+uvx cc-pushback --help
+```
+
+`uvx` fetches cc-pushback into a throwaway environment and runs it. To add it
+to a project instead:
+
+```bash
+uv add cc-pushback
+```
+
+## Quickstart
+
+Scan your transcripts for the moments you pushed back and accumulate them into a
+local feedback database:
+
+```bash
+uvx cc-pushback scan
+```
+
+```
+scanned 412 files, 1473 new rows
+```
+
+`scan` is incremental and idempotent. Each transcript is parsed only when it is
+new or has changed since the last scan, and every candidate is keyed by a content
+digest, so re-running over unchanged inputs adds nothing. Recording a file and
+inserting its candidates commit in one transaction — interrupt a scan and the
+database is never left half-written. A transcript that fails to parse (one Claude
+Code is still writing, say) is skipped and retried next time, never aborting the run.
+
+The database lives at `~/.cc-pushback/feedback.db` by default (override with
+`--db`). Inspect what has been collected:
+
+```bash
+uvx cc-pushback stats          # counts by source kind, and the scanned-file count
+uvx cc-pushback list           # recent feedback, newest first
+uvx cc-pushback list --source plan_review --limit 50
+```
+
+### What gets collected
+
+`scan` runs four detectors over each transcript:
+
+- **Transcript messages** (`transcript_message`) — the pushback you typed
+  mid-session, after trivial acknowledgements and structural noise are filtered out.
+- **Plan reviews** (`plan_review`) — rejected `ExitPlanMode` plans (with the
+  feedback you gave) and plan-mode re-entries right after an edit cycle, i.e.
+  "let's rethink this."
+- **Interrupts and rejections** (`interrupt_rejection`) — permission denials and
+  `[Request interrupted by user]` corrections, with the denied tool and your
+  follow-up captured.
+- **Review comments** (`review_comment`) — structured code-review messages
+  exploded into one row per inline comment.
+
+Each row carries the conversational window around the feedback — the assistant
+action it responded to, plus a few turns either side — captured at collection
+time, because transcripts are ephemeral.
+
+Restrict to specific kinds with `--source` (repeatable), or force a full re-mine
+of every transcript (after a detector change, say) with `--full`:
+
+```bash
+uvx cc-pushback list --source transcript_message --source plan_review
+uvx cc-pushback scan --full
+```
+
+### Mining transcripts from another machine
+
+Transcripts live under `~/.claude/projects`. To mine a remote machine's history,
+mirror its projects directory locally with `rsync`, then scan that directory:
+
+```bash
+rsync -az yasyf@yasyf:.claude/projects/ ~/.cc-pushback/mirrors/yasyf/
+uvx cc-pushback scan --transcripts ~/.cc-pushback/mirrors/yasyf/
+```
+
+`--transcripts` is repeatable, so you can fold several mirrors into one scan.
+Because discovery is mtime-keyed, repeating the `rsync` and re-scanning only
+ingests what changed.
+
+## What problems does this solve?
+
+- **Your corrections evaporate.** Every "don't do it that way" you've typed into Claude Code is sitting unused in transcript files. cc-pushback turns that history into a structured dataset.
+- **CLAUDE.md only captures what you remember to write down.** Most of your taste is tacit — you only notice a rule when it's violated. Collecting real pushbacks recovers the rules you never articulated.
+- **The signal is buried in noise.** Trivial acknowledgements, structural reminders, and tool chatter drown out the moments that matter; cc-pushback keeps the pushback and discards the rest.
+
+## Docs
+
+[Read the docs](https://yasyf.github.io/cc-pushback/) for the full guide and API reference.

cc_pushback-0.1.0/README.md

@@ -0,0 +1,103 @@
+# cc-pushback
+
+[![PyPI](https://img.shields.io/pypi/v/cc-pushback.svg)](https://pypi.org/project/cc-pushback/)
+[![Python](https://img.shields.io/pypi/pyversions/cc-pushback.svg)](https://pypi.org/project/cc-pushback/)
+[![Docs](https://img.shields.io/github/actions/workflow/status/yasyf/cc-pushback/docs.yml?branch=main&label=docs)](https://yasyf.github.io/cc-pushback/)
+[![License: PolyForm-Noncommercial-1.0.0](https://img.shields.io/badge/License-PolyForm--Noncommercial--1.0.0-blue.svg)](https://github.com/yasyf/cc-pushback/blob/main/LICENSE)
+
+cc-pushback mines your Claude Code transcripts for the moments you pushed back — corrections, interrupts, rejected plans, code-review comments, "no, do it this way" — and collects them, with the surrounding conversational context, into a local database. That corpus is the raw material for learning your pushback style; this first release builds it.
+
+## Install
+
+No install needed — run everything through [uvx](https://docs.astral.sh/uv/):
+
+```bash
+uvx cc-pushback --help
+```
+
+`uvx` fetches cc-pushback into a throwaway environment and runs it. To add it
+to a project instead:
+
+```bash
+uv add cc-pushback
+```
+
+## Quickstart
+
+Scan your transcripts for the moments you pushed back and accumulate them into a
+local feedback database:
+
+```bash
+uvx cc-pushback scan
+```
+
+```
+scanned 412 files, 1473 new rows
+```
+
+`scan` is incremental and idempotent. Each transcript is parsed only when it is
+new or has changed since the last scan, and every candidate is keyed by a content
+digest, so re-running over unchanged inputs adds nothing. Recording a file and
+inserting its candidates commit in one transaction — interrupt a scan and the
+database is never left half-written. A transcript that fails to parse (one Claude
+Code is still writing, say) is skipped and retried next time, never aborting the run.
+
+The database lives at `~/.cc-pushback/feedback.db` by default (override with
+`--db`). Inspect what has been collected:
+
+```bash
+uvx cc-pushback stats          # counts by source kind, and the scanned-file count
+uvx cc-pushback list           # recent feedback, newest first
+uvx cc-pushback list --source plan_review --limit 50
+```
+
+### What gets collected
+
+`scan` runs four detectors over each transcript:
+
+- **Transcript messages** (`transcript_message`) — the pushback you typed
+  mid-session, after trivial acknowledgements and structural noise are filtered out.
+- **Plan reviews** (`plan_review`) — rejected `ExitPlanMode` plans (with the
+  feedback you gave) and plan-mode re-entries right after an edit cycle, i.e.
+  "let's rethink this."
+- **Interrupts and rejections** (`interrupt_rejection`) — permission denials and
+  `[Request interrupted by user]` corrections, with the denied tool and your
+  follow-up captured.
+- **Review comments** (`review_comment`) — structured code-review messages
+  exploded into one row per inline comment.
+
+Each row carries the conversational window around the feedback — the assistant
+action it responded to, plus a few turns either side — captured at collection
+time, because transcripts are ephemeral.
+
+Restrict to specific kinds with `--source` (repeatable), or force a full re-mine
+of every transcript (after a detector change, say) with `--full`:
+
+```bash
+uvx cc-pushback list --source transcript_message --source plan_review
+uvx cc-pushback scan --full
+```
+
+### Mining transcripts from another machine
+
+Transcripts live under `~/.claude/projects`. To mine a remote machine's history,
+mirror its projects directory locally with `rsync`, then scan that directory:
+
+```bash
+rsync -az yasyf@yasyf:.claude/projects/ ~/.cc-pushback/mirrors/yasyf/
+uvx cc-pushback scan --transcripts ~/.cc-pushback/mirrors/yasyf/
+```
+
+`--transcripts` is repeatable, so you can fold several mirrors into one scan.
+Because discovery is mtime-keyed, repeating the `rsync` and re-scanning only
+ingests what changed.
+
+## What problems does this solve?
+
+- **Your corrections evaporate.** Every "don't do it that way" you've typed into Claude Code is sitting unused in transcript files. cc-pushback turns that history into a structured dataset.
+- **CLAUDE.md only captures what you remember to write down.** Most of your taste is tacit — you only notice a rule when it's violated. Collecting real pushbacks recovers the rules you never articulated.
+- **The signal is buried in noise.** Trivial acknowledgements, structural reminders, and tool chatter drown out the moments that matter; cc-pushback keeps the pushback and discards the rest.
+
+## Docs
+
+[Read the docs](https://yasyf.github.io/cc-pushback/) for the full guide and API reference.

cc_pushback-0.1.0/cc_pushback/__init__.py

@@ -0,0 +1,28 @@
+"""Collect developer pushback signals from existing Claude Code transcripts."""
+
+from __future__ import annotations
+
+from cc_pushback.context import ContextSnapshot, ContextTurn, build_snapshot
+from cc_pushback.detectors import Detector, detect
+from cc_pushback.models import DedupKey, FeedbackCandidate, SourceKind, dedup_key
+from cc_pushback.scan import ScanReport, scan
+from cc_pushback.spec import PUSHBACK_SPEC
+from cc_pushback.store import FeedbackStore
+
+# Not the retired export-control convention: this exists only so great-docs' API
+# reference skips the SourceKind (Literal) and DedupKey (NewType) aliases, which its
+# dynamic walker cannot render ("Cannot handle auto for object kind: TYPE_ALIAS").
+# great-docs documents __all__ when present; keep it in sync with the re-exports above.
+__all__ = [
+    "PUSHBACK_SPEC",
+    "ContextSnapshot",
+    "ContextTurn",
+    "Detector",
+    "FeedbackCandidate",
+    "FeedbackStore",
+    "ScanReport",
+    "build_snapshot",
+    "dedup_key",
+    "detect",
+    "scan",
+]

cc_pushback-0.1.0/cc_pushback/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from cc_pushback.cli import main
+
+if __name__ == "__main__":
+    main()

cc_pushback-0.1.0/cc_pushback/claude.py

@@ -0,0 +1,46 @@
+"""A thin shell-out to the ``claude`` CLI for a single headless completion.
+
+Argv construction and envelope parsing come from the shared ``spawnllm`` library;
+the spawn stays local (``anyio.run_process``). It uses the user's existing Claude
+Code auth (no API key), so the package stays offline unless ``claude`` is
+actually on the path.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+import anyio
+from spawnllm import ClaudeCliBackend, parse_result_envelope
+
+CLAUDE_TIMEOUT = 180
+
+
+def claude_available() -> bool:
+    """Returns whether the ``claude`` CLI is on ``PATH``."""
+    return shutil.which("claude") is not None
+
+
+async def run_claude(prompt: str, *, system: str, model: str) -> str:
+    """Runs one headless ``claude`` turn and returns its text result.
+
+    Args:
+        prompt: The user message to send.
+        system: The system prompt.
+        model: The model to run, for example ``claude-sonnet-4-6``.
+
+    Returns:
+        The assistant's text response — the ``result`` field of the JSON output.
+
+    Raises:
+        subprocess.SubprocessError: If ``claude`` exits non-zero, times out, or
+            reports an error in its JSON envelope.
+    """
+    argv = ClaudeCliBackend.cc_sentiment(system_prompt=system).build_argv(prompt, model=model)
+    try:
+        with anyio.fail_after(CLAUDE_TIMEOUT):
+            result = await anyio.run_process(argv, check=True)
+    except TimeoutError as exc:
+        raise subprocess.TimeoutExpired(argv, CLAUDE_TIMEOUT) from exc
+    return parse_result_envelope(result.stdout, argv=argv, stderr=result.stderr)

cc_pushback-0.1.0/cc_pushback/cli.py

@@ -0,0 +1,138 @@
+"""The ``cc-pushback`` command-line interface: scan, stats, list, and view-samples."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+
+import anyio
+import click
+from cc_transcript import CLAUDE_PROJECTS_DIR
+
+from cc_pushback.models import PUSHBACK_SOURCE_KINDS, SourceKind
+from cc_pushback.report import Sample, build_summary, render_html
+from cc_pushback.scan import scan as run_scan
+from cc_pushback.serve import serve
+from cc_pushback.store import FeedbackStore
+
+SOURCE_KINDS = [*PUSHBACK_SOURCE_KINDS]
+
+
+def coro[**P, R](fn: Callable[P, Awaitable[R]]) -> Callable[P, R]:
+    """Adapts an async command body into the sync callback Click expects."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        return anyio.run(functools.partial(fn, *args, **kwargs))
+
+    return wrapper
+
+
+@click.group()
+@click.version_option(package_name="cc-pushback")
+def main() -> None:
+    """Collect developer pushback signals from existing Claude Code transcripts."""
+
+
+@main.command()
+@click.option(
+    "--transcripts",
+    "transcripts",
+    multiple=True,
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    help="Transcript directories to scan. Defaults to ~/.claude/projects.",
+)
+@click.option("--full", is_flag=True, help="Re-scan every transcript, ignoring recorded mtimes.")
+@click.option(
+    "--db",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help="Database path. Defaults to ~/.cc-pushback/feedback.db.",
+)
+@coro
+async def scan(transcripts: tuple[Path, ...], full: bool, db: Path | None) -> None:
+    """Scan transcripts for feedback, incrementally.
+
+    Each transcript is parsed only when new or modified since the last scan, and
+    every candidate is inserted with ``INSERT OR IGNORE`` keyed by a content
+    digest, so re-running ``scan`` over unchanged inputs is a no-op. Recording a
+    file and inserting its candidates commit in one transaction.
+    """
+    roots = transcripts or (CLAUDE_PROJECTS_DIR,)
+    async with await FeedbackStore.open(db or FeedbackStore.default_path()) as store:
+        report = await run_scan(store, roots, full=full)
+    click.echo(f"scanned {report.scanned} files, {report.inserted} new rows")
+
+
+@main.command()
+@click.option(
+    "--db",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help="Database path. Defaults to ~/.cc-pushback/feedback.db.",
+)
+@coro
+async def stats(db: Path | None) -> None:
+    """Print ingestion counts by source kind and the scanned-file count."""
+    async with await FeedbackStore.open(db or FeedbackStore.default_path()) as store:
+        report = await store.stats()
+    click.echo(f"total: {report.total}  files: {report.files}")
+    for kind, count in report.by_source.items():
+        click.echo(f"  {kind}: {count}")
+
+
+@main.command(name="list")
+@click.option(
+    "--source",
+    "source",
+    type=click.Choice(SOURCE_KINDS),
+    default=None,
+    help="Restrict to one source kind.",
+)
+@click.option("--limit", type=int, default=20, show_default=True, help="Maximum events to show.")
+@click.option(
+    "--db",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help="Database path. Defaults to ~/.cc-pushback/feedback.db.",
+)
+@coro
+async def list_(source: SourceKind | None, limit: int, db: Path | None) -> None:
+    """List recent feedback events, newest first."""
+    async with await FeedbackStore.open(db or FeedbackStore.default_path()) as store:
+        rows = await store.recent(source_kind=source, limit=limit)
+    for row in rows:
+        click.echo(f"[{row['source_kind']}] {row['occurred_at']}  {str(row['text'])[:200]}")
+
+
+@main.command(name="view-samples")
+@click.option(
+    "--db",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help="Database path. Defaults to ~/.cc-pushback/feedback.db.",
+)
+@click.option(
+    "--llm/--no-llm",
+    default=True,
+    show_default=True,
+    help="Summarize with the claude CLI when it is on PATH, else use heuristics.",
+)
+@click.option("--model", default="claude-sonnet-4-6", show_default=True, help="Model for the claude CLI summary.")
+@click.option("--port", type=int, default=0, show_default=True, help="Port to serve on; 0 picks a free one.")
+@click.option("--open", "open_", is_flag=True, help="Open the page in a browser once serving.")
+@coro
+async def view_samples(db: Path | None, llm: bool, model: str, port: int, open_: bool) -> None:
+    """Render every collected sample into one HTML page and serve it locally.
+
+    The page leads with a corpus summary and highlights, then lists every sample
+    with a kind filter, a free-text search, and an expandable context window. It is
+    built in memory and served over a transient HTTP server whose URL is printed;
+    press Ctrl-C to stop. The summary is written by the ``claude`` CLI when ``--llm``
+    is set and ``claude`` is installed, falling back to deterministic heuristics.
+    """
+    async with await FeedbackStore.open(db or FeedbackStore.default_path()) as store:
+        samples = [Sample.from_row(row) for row in await store.events()]
+    summary = await build_summary(samples, use_llm=llm, model=model)
+    await serve(render_html(samples, summary).encode("utf-8"), port=port, open_browser=open_)

cc_pushback-0.1.0/cc_pushback/context.py

@@ -0,0 +1,11 @@
+"""Re-exports the conversational-window primitive from the mining domain.
+
+Deprecated: import these names from :mod:`cc_transcript.domains.mining`. This shim
+keeps cc-pushback's historical import paths working for at least one release.
+"""
+
+from __future__ import annotations
+
+from cc_transcript.domains.mining import ContextSnapshot, ContextTurn, build_snapshot, trigger_for, turn_for
+
+__all__ = ["ContextSnapshot", "ContextTurn", "build_snapshot", "trigger_for", "turn_for"]