pjctx 0.1.0__tar.gz

pjctx-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.pytest_cache/
+.coverage
+htmlcov/
+*.so
+.DS_Store
+.claude/
+pyproject.toml
+uv.lock
+
+# PJContext local data
+.pjctx/

pjctx-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: pjctx
+Version: 0.1.0
+Summary: Capture and restore AI coding context across sessions
+License-Expression: MIT
+Keywords: ai,cli,context,developer-tools
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: gitpython>=3.1
+Requires-Dist: pyperclip>=1.8
+Requires-Dist: rich>=13.0
+Requires-Dist: watchdog>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PJContext (pjctx)
+
+Capture and restore AI coding context across sessions. Stop wasting 10-15 minutes re-explaining your project every time you start a new AI coding session.
+
+## Installation
+
+```bash
+pip install pjctx
+# or
+pipx install pjctx
+```
+
+### Via npm (for Node.js developers)
+
+```bash
+npm install -g pjctx
+```
+
+> Requires Python 3.9+ and pip. The npm package automatically installs the Python package during setup.
+
+For development:
+
+```bash
+git clone <repo-url>
+cd pjctx
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```bash
+# Initialize in your git repo
+pjctx init
+
+# Save context (interactive)
+pjctx save
+
+# Save context (quick, one-liner)
+pjctx save "Refactoring payment service to event sourcing"
+
+# Save context (auto-detect from git)
+pjctx save --auto
+
+# Resume — copies prompt to clipboard, paste into any AI tool
+pjctx resume
+
+# Resume with specific format
+pjctx resume --format xml
+pjctx resume --format compact
+pjctx resume --no-copy  # print to stdout
+```
+
+## Commands
+
+### `pjctx init`
+Initialize `.pjctx/` in the current git repo. Adds `.pjctx/` to `.gitignore`.
+
+### `pjctx save [message]`
+Save current coding context. Three modes:
+- **Interactive** (no args): Rich prompts walk through task, approaches, decisions, next steps
+- **Quick** (`pjctx save "message"`): Auto-fill git data, message only
+- **Auto** (`--auto`): No prompts, git-detected changes, carries forward previous context
+
+Options: `--auto`, `-t/--tag TAG` (repeatable)
+
+### `pjctx resume`
+Generate a resume prompt from the latest context and copy it to clipboard. Paste into any AI coding tool (Cursor, Claude Code, Copilot, Windsurf) to instantly restore context.
+
+Options: `-f/--format [default|xml|compact]`, `--no-copy`, `-b/--branch BRANCH`
+
+### `pjctx log`
+Show context history as a table.
+
+Options: `-b/--branch BRANCH`, `-n/--limit N`, `--all`
+
+### `pjctx diff`
+Show changes since last context save.
+
+Options: `--stat` (default), `--full`
+
+### `pjctx handoff [@user]`
+Create a handoff context for another developer. Carries forward all context fields and adds handoff note.
+
+### `pjctx share`
+Remove `.pjctx/` from `.gitignore` and commit it to git for team sharing.
+
+### `pjctx watch`
+Watch for file changes and auto-save context at intervals.
+
+Options: `-i/--interval SECONDS` (default: 300)
+
+### `pjctx hook install|uninstall|status`
+Manage git post-commit hook for automatic context saving after each commit.
+
+## Storage
+
+Context is stored locally in `.pjctx/` within your repo, scoped by branch:
+
+```
+.pjctx/
+├── config.json
+├── contexts/
+│   ├── main/
+│   │   ├── 2024-01-15T10-30-00.json
+│   │   └── latest.json
+│   └── feature/payment-refactor/
+│       └── latest.json
+└── hooks/
+```
+
+## Prompt Formats
+
+- **default**: Markdown briefing document with headers
+- **xml**: Structured XML for tools that parse it
+- **compact**: Dense single paragraph for token-limited contexts
+
+## License
+
+MIT

pjctx-0.1.0/README.md

@@ -0,0 +1,119 @@
+# PJContext (pjctx)
+
+Capture and restore AI coding context across sessions. Stop wasting 10-15 minutes re-explaining your project every time you start a new AI coding session.
+
+## Installation
+
+```bash
+pip install pjctx
+# or
+pipx install pjctx
+```
+
+### Via npm (for Node.js developers)
+
+```bash
+npm install -g pjctx
+```
+
+> Requires Python 3.9+ and pip. The npm package automatically installs the Python package during setup.
+
+For development:
+
+```bash
+git clone <repo-url>
+cd pjctx
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```bash
+# Initialize in your git repo
+pjctx init
+
+# Save context (interactive)
+pjctx save
+
+# Save context (quick, one-liner)
+pjctx save "Refactoring payment service to event sourcing"
+
+# Save context (auto-detect from git)
+pjctx save --auto
+
+# Resume — copies prompt to clipboard, paste into any AI tool
+pjctx resume
+
+# Resume with specific format
+pjctx resume --format xml
+pjctx resume --format compact
+pjctx resume --no-copy  # print to stdout
+```
+
+## Commands
+
+### `pjctx init`
+Initialize `.pjctx/` in the current git repo. Adds `.pjctx/` to `.gitignore`.
+
+### `pjctx save [message]`
+Save current coding context. Three modes:
+- **Interactive** (no args): Rich prompts walk through task, approaches, decisions, next steps
+- **Quick** (`pjctx save "message"`): Auto-fill git data, message only
+- **Auto** (`--auto`): No prompts, git-detected changes, carries forward previous context
+
+Options: `--auto`, `-t/--tag TAG` (repeatable)
+
+### `pjctx resume`
+Generate a resume prompt from the latest context and copy it to clipboard. Paste into any AI coding tool (Cursor, Claude Code, Copilot, Windsurf) to instantly restore context.
+
+Options: `-f/--format [default|xml|compact]`, `--no-copy`, `-b/--branch BRANCH`
+
+### `pjctx log`
+Show context history as a table.
+
+Options: `-b/--branch BRANCH`, `-n/--limit N`, `--all`
+
+### `pjctx diff`
+Show changes since last context save.
+
+Options: `--stat` (default), `--full`
+
+### `pjctx handoff [@user]`
+Create a handoff context for another developer. Carries forward all context fields and adds handoff note.
+
+### `pjctx share`
+Remove `.pjctx/` from `.gitignore` and commit it to git for team sharing.
+
+### `pjctx watch`
+Watch for file changes and auto-save context at intervals.
+
+Options: `-i/--interval SECONDS` (default: 300)
+
+### `pjctx hook install|uninstall|status`
+Manage git post-commit hook for automatic context saving after each commit.
+
+## Storage
+
+Context is stored locally in `.pjctx/` within your repo, scoped by branch:
+
+```
+.pjctx/
+├── config.json
+├── contexts/
+│   ├── main/
+│   │   ├── 2024-01-15T10-30-00.json
+│   │   └── latest.json
+│   └── feature/payment-refactor/
+│       └── latest.json
+└── hooks/
+```
+
+## Prompt Formats
+
+- **default**: Markdown briefing document with headers
+- **xml**: Structured XML for tools that parse it
+- **compact**: Dense single paragraph for token-limited contexts
+
+## License
+
+MIT

pjctx-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pjctx"
+version = "0.1.0"
+description = "Capture and restore AI coding context across sessions"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+keywords = ["ai", "context", "developer-tools", "cli"]
+dependencies = [
+    "click>=8.0",
+    "rich>=13.0",
+    "pyperclip>=1.8",
+    "gitpython>=3.1",
+    "watchdog>=3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+
+[project.scripts]
+pjctx = "pjctx.cli:cli"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pjctx"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pjctx-0.1.0/src/pjctx/__init__.py

@@ -0,0 +1,3 @@
+"""PJContext — Capture and restore AI coding context."""
+
+__version__ = "0.1.0"

pjctx-0.1.0/src/pjctx/cli.py

@@ -0,0 +1,128 @@
+"""Click CLI group and command wiring."""
+
+from __future__ import annotations
+
+import click
+
+from pjctx import __version__
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="pjctx")
+@click.option("--verbose", "-v", is_flag=True, help="Enable verbose output.")
+@click.pass_context
+def cli(ctx: click.Context, verbose: bool) -> None:
+    """PJContext — Capture and restore AI coding context."""
+    ctx.ensure_object(dict)
+    ctx.obj["verbose"] = verbose
+
+
+# Lazy-load commands to keep --help/--version fast
+
+
+@cli.command()
+@click.pass_context
+def init(ctx: click.Context) -> None:
+    """Initialize .pjctx/ in the current repo."""
+    from pjctx.commands.init import run_init
+    run_init(ctx.obj)
+
+
+@cli.command()
+@click.argument("message", required=False)
+@click.option("--auto", "auto_mode", is_flag=True, help="Auto-detect from git, no prompts.")
+@click.option("--tag", "-t", multiple=True, help="Add tags.")
+@click.pass_context
+def save(ctx: click.Context, message: str | None, auto_mode: bool, tag: tuple[str, ...]) -> None:
+    """Save current context. Interactive if no message given."""
+    from pjctx.commands.save import run_save
+    run_save(ctx.obj, message=message, auto_mode=auto_mode, tags=list(tag))
+
+
+@cli.command()
+@click.option("--format", "-f", "fmt", default="default",
+              type=click.Choice(["default", "xml", "compact"]),
+              help="Prompt format.")
+@click.option("--no-copy", is_flag=True, help="Print to stdout instead of clipboard.")
+@click.option("--branch", "-b", default=None, help="Resume from a specific branch.")
+@click.pass_context
+def resume(ctx: click.Context, fmt: str, no_copy: bool, branch: str | None) -> None:
+    """Generate a resume prompt from the latest context."""
+    from pjctx.commands.resume import run_resume
+    run_resume(ctx.obj, fmt=fmt, no_copy=no_copy, branch=branch)
+
+
+@cli.command()
+@click.option("--branch", "-b", default=None, help="Show log for a specific branch.")
+@click.option("--limit", "-n", default=10, help="Max entries to show.")
+@click.option("--all", "all_branches", is_flag=True, help="Show logs across all branches.")
+@click.pass_context
+def log(ctx: click.Context, branch: str | None, limit: int, all_branches: bool) -> None:
+    """Show context history."""
+    from pjctx.commands.log import run_log
+    run_log(ctx.obj, branch=branch, limit=limit, all_branches=all_branches)
+
+
+@cli.command()
+@click.option("--stat/--full", default=True, help="Show stat summary or full diff.")
+@click.pass_context
+def diff(ctx: click.Context, stat: bool) -> None:
+    """Show changes since last context save."""
+    from pjctx.commands.diff import run_diff
+    run_diff(ctx.obj, stat_only=stat)
+
+
+@cli.command()
+@click.argument("user", required=False)
+@click.pass_context
+def handoff(ctx: click.Context, user: str | None) -> None:
+    """Create a handoff context for another user."""
+    from pjctx.commands.handoff import run_handoff
+    run_handoff(ctx.obj, user=user)
+
+
+@cli.command()
+@click.pass_context
+def share(ctx: click.Context) -> None:
+    """Share .pjctx/ by committing it to git."""
+    from pjctx.commands.share import run_share
+    run_share(ctx.obj)
+
+
+@cli.command()
+@click.option("--interval", "-i", default=300, help="Auto-save interval in seconds.")
+@click.pass_context
+def watch(ctx: click.Context, interval: int) -> None:
+    """Watch for file changes and auto-save context."""
+    from pjctx.commands.watch import run_watch
+    run_watch(ctx.obj, interval=interval)
+
+
+@cli.group()
+def hook() -> None:
+    """Manage git hooks for auto-save."""
+    pass
+
+
+@hook.command("install")
+@click.pass_context
+def hook_install(ctx: click.Context) -> None:
+    """Install post-commit hook."""
+    from pjctx.commands.hook import run_install
+    run_install(ctx.obj)
+
+
+@hook.command("uninstall")
+@click.pass_context
+def hook_uninstall(ctx: click.Context) -> None:
+    """Uninstall post-commit hook."""
+    from pjctx.commands.hook import run_uninstall
+    run_uninstall(ctx.obj)
+
+
+@hook.command("status")
+@click.pass_context
+def hook_status(ctx: click.Context) -> None:
+    """Check hook installation status."""
+    from pjctx.commands.hook import run_status
+    run_status(ctx.obj)

pjctx-0.1.0/src/pjctx/commands/diff.py

@@ -0,0 +1,48 @@
+"""pjctx diff — Show changes since last context save."""
+
+from __future__ import annotations
+
+from pjctx.core.config import find_repo_root, get_pjctx_dir
+from pjctx.core.git_ops import get_current_branch, get_diff_summary, get_full_diff, get_files_changed
+from pjctx.core.storage import load_latest
+from pjctx import ui
+
+
+def run_diff(obj: dict, stat_only: bool = True) -> None:
+    repo_root = find_repo_root()
+    if repo_root is None:
+        ui.error("Not inside a git repository.")
+        raise SystemExit(1)
+
+    if not get_pjctx_dir(repo_root).exists():
+        ui.error("Not initialized. Run 'pjctx init' first.")
+        raise SystemExit(1)
+
+    branch = get_current_branch(repo_root)
+    last_ctx = load_latest(repo_root, branch)
+
+    if last_ctx:
+        ui.info(f"Last save: {last_ctx.timestamp[:19]} — {last_ctx.message}")
+    else:
+        ui.warning("No previous context. Showing all current changes.")
+
+    if stat_only:
+        summary = get_diff_summary(repo_root)
+        files = get_files_changed(repo_root)
+        if not summary and not files:
+            ui.info("No changes since last save.")
+            return
+        if summary:
+            ui._console().print(summary)
+        if files:
+            ui.info("Changed files:")
+            for f in files:
+                ui._console().print(f"  {f}")
+    else:
+        full = get_full_diff(repo_root)
+        if not full:
+            ui.info("No changes since last save.")
+            return
+        from rich.syntax import Syntax
+        syntax = Syntax(full, "diff", theme="monokai")
+        ui._console().print(syntax)

pjctx-0.1.0/src/pjctx/commands/handoff.py

@@ -0,0 +1,60 @@
+"""pjctx handoff — Create a handoff context for another user."""
+
+from __future__ import annotations
+
+from pjctx.core.config import find_repo_root, get_pjctx_dir
+from pjctx.core.context import Context
+from pjctx.core.git_ops import get_current_branch, get_files_changed, get_diff_summary
+from pjctx.core.storage import save_context, load_latest
+from pjctx import ui
+
+
+def run_handoff(obj: dict, user: str | None = None) -> None:
+    repo_root = find_repo_root()
+    if repo_root is None:
+        ui.error("Not inside a git repository.")
+        raise SystemExit(1)
+
+    if not get_pjctx_dir(repo_root).exists():
+        ui.error("Not initialized. Run 'pjctx init' first.")
+        raise SystemExit(1)
+
+    branch = get_current_branch(repo_root)
+
+    # Resolve target user
+    target = user
+    if target and target.startswith("@"):
+        target = target[1:]
+    if not target:
+        target = ui.prompt("Handoff to (username)")
+        if not target:
+            ui.error("Username required.")
+            raise SystemExit(1)
+
+    # Load previous context to carry forward
+    prev = load_latest(repo_root, branch)
+
+    # Gather handoff note
+    handoff_note = ui.prompt("Handoff note (what they need to know)")
+
+    files_changed = get_files_changed(repo_root)
+    diff_summary = get_diff_summary(repo_root)
+
+    ctx = Context(
+        message=f"Handoff to {target}",
+        task=prev.task if prev else "",
+        approaches_tried=prev.approaches_tried if prev else [],
+        current_approach=prev.current_approach if prev else "",
+        decisions=prev.decisions if prev else [],
+        next_steps=prev.next_steps if prev else [],
+        branch=branch,
+        files_changed=files_changed,
+        git_diff_summary=diff_summary,
+        handoff_to=target,
+        handoff_note=handoff_note,
+        tags=prev.tags if prev else [],
+    )
+
+    path = save_context(repo_root, ctx)
+    ui.success(f"Handoff context saved for @{target} → {path.name}")
+    ui.info("They can run 'pjctx resume' to pick up the context.")

pjctx-0.1.0/src/pjctx/commands/hook.py

@@ -0,0 +1,117 @@
+"""pjctx hook — Install/uninstall/status for git post-commit hook."""
+
+from __future__ import annotations
+
+import os
+import stat
+
+from pjctx.core.config import find_repo_root, get_pjctx_dir
+from pjctx.core.git_ops import get_hooks_dir
+from pjctx import ui
+
+HOOK_NAME = "post-commit"
+MARKER_START = "# --- pjctx auto-save start ---"
+MARKER_END = "# --- pjctx auto-save end ---"
+HOOK_BODY = """\
+# --- pjctx auto-save start ---
+if command -v pjctx >/dev/null 2>&1; then
+    pjctx save --auto 2>/dev/null || true
+fi
+# --- pjctx auto-save end ---
+"""
+
+
+def run_install(obj: dict) -> None:
+    repo_root = find_repo_root()
+    if repo_root is None:
+        ui.error("Not inside a git repository.")
+        raise SystemExit(1)
+
+    if not get_pjctx_dir(repo_root).exists():
+        ui.error("Not initialized. Run 'pjctx init' first.")
+        raise SystemExit(1)
+
+    hooks_dir = get_hooks_dir(repo_root)
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+    hook_path = hooks_dir / HOOK_NAME
+
+    if hook_path.exists():
+        content = hook_path.read_text()
+        if MARKER_START in content:
+            ui.warning("Hook already installed.")
+            return
+        # Append to existing hook
+        if not content.endswith("\n"):
+            content += "\n"
+        content += "\n" + HOOK_BODY
+    else:
+        content = "#!/bin/sh\n\n" + HOOK_BODY
+
+    hook_path.write_text(content)
+    # Make executable
+    hook_path.chmod(hook_path.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+
+    ui.success("Post-commit hook installed.")
+    ui.info("Context will auto-save after each commit.")
+
+
+def run_uninstall(obj: dict) -> None:
+    repo_root = find_repo_root()
+    if repo_root is None:
+        ui.error("Not inside a git repository.")
+        raise SystemExit(1)
+
+    hooks_dir = get_hooks_dir(repo_root)
+    hook_path = hooks_dir / HOOK_NAME
+
+    if not hook_path.exists():
+        ui.warning("No post-commit hook found.")
+        return
+
+    content = hook_path.read_text()
+    if MARKER_START not in content:
+        ui.warning("pjctx hook not found in post-commit.")
+        return
+
+    # Remove our section
+    lines = content.splitlines(keepends=True)
+    new_lines: list[str] = []
+    inside = False
+    for line in lines:
+        if MARKER_START in line:
+            inside = True
+            continue
+        if MARKER_END in line:
+            inside = False
+            continue
+        if not inside:
+            new_lines.append(line)
+
+    remaining = "".join(new_lines).strip()
+    if remaining == "#!/bin/sh" or not remaining:
+        # Remove the file entirely if only shebang left
+        hook_path.unlink()
+        ui.success("Post-commit hook removed.")
+    else:
+        hook_path.write_text(remaining + "\n")
+        ui.success("pjctx section removed from post-commit hook.")
+
+
+def run_status(obj: dict) -> None:
+    repo_root = find_repo_root()
+    if repo_root is None:
+        ui.error("Not inside a git repository.")
+        raise SystemExit(1)
+
+    hooks_dir = get_hooks_dir(repo_root)
+    hook_path = hooks_dir / HOOK_NAME
+
+    if not hook_path.exists():
+        ui.info("Post-commit hook: [bold red]not installed[/]")
+        return
+
+    content = hook_path.read_text()
+    if MARKER_START in content:
+        ui.info("Post-commit hook: [bold green]installed[/]")
+    else:
+        ui.info("Post-commit hook: [bold yellow]exists but pjctx not found[/]")