troven 0.1.0__py3-none-any.whl

troven/__init__.py

@@ -0,0 +1,3 @@
+"""Troven - Git-native CLI for tracking change intents and speculative development."""
+
+__version__ = "0.1.0"

troven/__main__.py

@@ -0,0 +1,7 @@
+"""Entry point for python -m troven."""
+
+import sys
+from troven.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

troven/cli.py

@@ -0,0 +1,144 @@
+"""CLI argument parsing and command dispatch for Troven."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from troven import __version__
+from troven.commands.accept import execute_accept
+from troven.commands.create import execute_create
+from troven.commands.list_cmd import execute_list
+from troven.commands.open_cmd import execute_open
+from troven.commands.reject import execute_reject
+from troven.commands.show import execute_show
+from troven.errors import TrovenError
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="troven",
+        description="Git-native CLI for tracking change intents and speculative development.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    subparsers = parser.add_subparsers(dest="subcommand", title="subcommands", required=True)
+
+    # create
+    create_p = subparsers.add_parser(
+        "create",
+        help="Create a new troven worktree and initialize its change intent record.",
+    )
+    create_p.add_argument("name", help="Dash-separated name for the troven (e.g. 'fast-lexer-simd')")
+    create_p.add_argument("--from", dest="from_ref", help="Base branch, commit, or parent troven ID")
+    create_p.add_argument("--repo", dest="repo_url", help="Git repository URL to clone first")
+    create_p.add_argument("-f", "--force", action="store_true", help="Skip confirmation prompts")
+    create_p.add_argument("--no-exec", action="store_true", help="Initialize worktree without launching agent")
+    create_p.add_argument("command", nargs="*", help="Custom command to run in worktree (after --)")
+
+    # open
+    open_p = subparsers.add_parser(
+        "open",
+        help="Open an existing active or rejected troven in a worktree.",
+    )
+    open_p.add_argument("id", nargs="?", help="Troven ID (defaults to current branch/worktree)")
+    open_p.add_argument("--no-exec", action="store_true", help="Mount worktree without launching agent")
+    open_p.add_argument("command", nargs="*", help="Custom command to run in worktree (after --)")
+
+    # accept
+    accept_p = subparsers.add_parser(
+        "accept",
+        help="Incorporate an active troven's changes into the target branch.",
+    )
+    accept_p.add_argument("id", nargs="?", help="Troven ID (defaults to current worktree/branch)")
+    accept_p.add_argument("--into", dest="into_branch", help="Target branch (defaults to base_branch)")
+    accept_p.add_argument("-f", "--force", action="store_true", help="Bypass foreign repo confirmation")
+
+    # reject
+    reject_p = subparsers.add_parser(
+        "reject",
+        help="Close an active troven without merging; preserve rejection knowledge in archive ref.",
+    )
+    reject_p.add_argument("id", nargs="?", help="Troven ID (defaults to current worktree/branch)")
+
+    # list
+    list_p = subparsers.add_parser(
+        "list",
+        help="List all trovens in a hierarchical tree view.",
+    )
+    list_p.add_argument("--status", choices=["active", "accepted", "rejected"], help="Filter by status")
+
+    # show
+    show_p = subparsers.add_parser(
+        "show",
+        help="Print the full markdown record for a troven.",
+    )
+    show_p.add_argument("id", nargs="?", help="Troven ID (defaults to current worktree/branch)")
+
+    # install-skill
+    install_skill_p = subparsers.add_parser(
+        "install-skill",
+        help="Install the troven agent skill to ~/.agents/skills/troven and ~/.gemini/config/skills/troven.",
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        if args.subcommand == "create":
+            cmd = args.command
+            if cmd and cmd[0] == "--":
+                cmd = cmd[1:]
+            execute_create(
+                name=args.name,
+                from_ref=args.from_ref,
+                repo_url=args.repo_url,
+                force=args.force,
+                command=cmd,
+                no_exec=args.no_exec,
+            )
+        elif args.subcommand == "open":
+            cmd = args.command
+            if cmd and cmd[0] == "--":
+                cmd = cmd[1:]
+            execute_open(
+                troven_id=args.id,
+                command=cmd,
+                no_exec=args.no_exec,
+            )
+        elif args.subcommand == "accept":
+            execute_accept(
+                troven_id=args.id,
+                into_branch=args.into_branch,
+                force=args.force,
+            )
+        elif args.subcommand == "reject":
+            execute_reject(
+                troven_id=args.id,
+            )
+        elif args.subcommand == "list":
+            execute_list(
+                status_filter=args.status,
+            )
+        elif args.subcommand == "show":
+            execute_show(
+                troven_id=args.id,
+            )
+        elif args.subcommand == "install-skill":
+            from troven.commands.install_skill import execute_install_skill
+            execute_install_skill()
+        return 0
+    except TrovenError as err:
+        print(f"\033[31mError:\033[0m {err}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("\nAborted.", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

troven/commands/__init__.py

@@ -0,0 +1 @@
+"""Troven command implementations."""

troven/commands/accept.py

@@ -0,0 +1,134 @@
+"""Implementation of 'troven accept' subcommand."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+import sys
+
+from troven import git
+from troven.commands.open_cmd import detect_current_troven_id
+from troven.errors import (
+    InvalidStateError,
+    MergeConflictError,
+    RebaseConflictError,
+    TrovenError,
+    TrovenNotFoundError,
+)
+from troven.state import (
+    get_troven_file,
+    load_troven,
+    save_troven,
+    validate_summary_non_empty,
+)
+
+
+def execute_accept(
+    troven_id: str | None = None,
+    into_branch: str | None = None,
+    force: bool = False,
+) -> None:
+    """Incorporate active troven changes into the target branch."""
+    repo_root = git.get_main_repo_root()
+
+    if not troven_id:
+        detected = detect_current_troven_id(repo_root)
+        if not detected:
+            raise TrovenError(
+                "Troven ID required when not run from inside a troven worktree.",
+                remediation="Specify a troven ID: 'troven accept <id>' or run inside the worktree.",
+            )
+        troven_id = detected
+
+    clean_id = troven_id.removeprefix("troven/")
+    branch_name = f"troven/{clean_id}"
+
+    if not git.branch_exists(branch_name, cwd=repo_root):
+        raise TrovenNotFoundError(
+            f"Active branch '{branch_name}' not found.",
+            remediation=f"Check 'troven list' to view available trovens.",
+        )
+
+    # Locate worktree
+    worktree_dir = git.find_worktree_for_branch(branch_name, cwd=repo_root)
+
+    # Load and validate troven record from worktree if present, else base repo
+    if worktree_dir and worktree_dir.exists() and get_troven_file(worktree_dir, clean_id).exists():
+        md_source_dir = worktree_dir
+    else:
+        md_source_dir = repo_root
+    record = load_troven(md_source_dir, clean_id)
+    md_path = get_troven_file(md_source_dir, clean_id)
+
+    if record.status != "active":
+        raise InvalidStateError(
+            f"Troven '{clean_id}' is in state '{record.status}', not 'active'.",
+            remediation="Only active trovens can be accepted.",
+        )
+
+    # Gate-check summary
+    validate_summary_non_empty(record, md_path)
+
+    target_branch = into_branch or record.base_branch or "master"
+
+    # Foreign repo warning check
+    if not (repo_root / ".troven").exists() and not force and sys.stdin.isatty():
+        ans = input(
+            "This repository does not appear to use troven in its target branch.\n"
+            f"Accepting will add .troven/ to '{target_branch}'. Confirm? [y/N]: "
+        ).strip()
+        if ans.lower() not in ("y", "yes"):
+            print("Aborted.")
+            sys.exit(0)
+
+    # Ensure any pending .troven record changes inside worktree are committed to the branch
+    if worktree_dir and worktree_dir.exists():
+        wt_md = get_troven_file(worktree_dir, clean_id)
+        if wt_md.exists():
+            git.commit_files([wt_md], f"troven: record summary for {clean_id}", cwd=worktree_dir)
+
+    # Switch base repo to target branch
+    git.checkout_branch(target_branch, cwd=repo_root)
+
+    # Attempt fast-forward merge
+    print(f"Fast-forward merging '{branch_name}' into '{target_branch}'...")
+    if not git.merge_ff_only(branch_name, cwd=repo_root):
+        print(f"Branches have diverged. Attempting rebase inside worktree...")
+        if not worktree_dir or not worktree_dir.exists():
+            raise MergeConflictError(
+                f"Fast-forward merge failed and worktree for '{branch_name}' is not found locally.",
+                remediation=f"Open the troven with 'troven open {clean_id}', rebase onto '{target_branch}', and try again.",
+            )
+
+        if not git.rebase(target_branch, cwd=worktree_dir):
+            git.rebase_abort(cwd=worktree_dir)
+            raise RebaseConflictError(
+                f"Rebase of '{branch_name}' onto '{target_branch}' encountered conflicts.",
+                remediation=f"Resolve conflicts manually inside '{worktree_dir}' and run 'troven accept {clean_id}'.",
+            )
+
+        # After rebase, retry fast-forward merge
+        if not git.merge_ff_only(branch_name, cwd=repo_root):
+            raise MergeConflictError(
+                f"Fast-forward merge still failed after rebase.",
+                remediation=f"Inspect branch '{branch_name}' in '{worktree_dir}'.",
+            )
+
+    # Update troven record status to accepted
+    record.status = "accepted"
+    record.resolved_at = datetime.now(timezone.utc).astimezone().isoformat(timespec="seconds")
+    saved_md = save_troven(repo_root, record)
+
+    # Squash update of .troven record to target branch
+    git.commit_files([saved_md], f"troven: accept {clean_id}", cwd=repo_root)
+
+    # Cleanup worktree and branch
+    if worktree_dir and worktree_dir.exists():
+        print(f"Removing worktree at {worktree_dir}...")
+        git.remove_worktree(worktree_dir, force=True, cwd=repo_root)
+
+    print(f"Deleting branch '{branch_name}'...")
+    git.delete_branch(branch_name, force=True, cwd=repo_root)
+    git.prune_worktrees(cwd=repo_root)
+
+    print(f"\n\033[32m[Success]\033[0m Troven '{clean_id}' accepted into '{target_branch}'.")

troven/commands/create.py

@@ -0,0 +1,193 @@
+"""Implementation of 'troven create' subcommand."""
+
+from __future__ import annotations
+
+from datetime import date
+import os
+from pathlib import Path
+import re
+import sys
+
+from troven import git
+from troven.errors import (
+    InvalidNameError,
+    TrovenError,
+    TrovenExistsError,
+)
+from troven.state import (
+    TrovenRecord,
+    get_troven_file,
+    load_troven,
+    save_troven,
+)
+
+
+def validate_slug(name: str) -> None:
+    """Ensure name is lowercase alphanumeric with dashes."""
+    if not name or not re.match(r"^[a-z0-9]+(?:-[a-z0-9]+)*$", name):
+        raise InvalidNameError(
+            f"Invalid troven name: '{name}'.",
+            remediation="Use lowercase letters, numbers, and dashes (e.g. 'fast-lexer-simd').",
+        )
+
+
+def execute_create(
+    name: str,
+    from_ref: str | None = None,
+    repo_url: str | None = None,
+    force: bool = False,
+    command: list[str] | None = None,
+    no_exec: bool = False,
+) -> Path:
+    """Create a new troven worktree and initialize change record."""
+    validate_slug(name)
+
+    today = date.today().isoformat()
+    troven_id = f"{today}-{name}"
+
+    # Handle --repo URL clone
+    if repo_url:
+        target_dir = Path.cwd() / name
+        if target_dir.exists():
+            raise TrovenError(f"Target directory {target_dir} already exists.")
+        print(f"Cloning {repo_url} into {target_dir}...")
+        git.clone_repo(repo_url, target_dir)
+        repo_root = target_dir
+    else:
+        repo_root = git.get_main_repo_root()
+
+    branch_name = f"troven/{troven_id}"
+    md_path = get_troven_file(repo_root, troven_id)
+
+    # Check for collisions
+    if md_path.exists():
+        raise TrovenExistsError(
+            f"Troven record '{troven_id}' already exists at {md_path}.",
+            remediation="Choose a different name or inspect the existing troven with 'troven show'.",
+        )
+    if git.branch_exists(branch_name, cwd=repo_root):
+        raise TrovenExistsError(
+            f"Git branch '{branch_name}' already exists.",
+            remediation="Delete or rename the conflicting branch, or choose a different troven name.",
+        )
+
+    parent_id: str | None = None
+    forked_from_id: str | None = None
+    resolved_start_point = "HEAD"
+    base_branch = git.get_current_branch(cwd=repo_root)
+    if base_branch == "HEAD":
+        base_branch = "master"
+
+    # Resolve --from argument
+    if from_ref:
+        # Check if from_ref is a troven ID
+        clean_from = from_ref.removeprefix("troven/")
+        archive_ref = f"refs/archive/troven/{clean_from}"
+        active_branch = f"troven/{clean_from}"
+
+        if git.ref_exists(archive_ref, cwd=repo_root):
+            if not force and sys.stdin.isatty():
+                ans = input(f"Troven '{clean_from}' was rejected. Create a new troven based on it? [y/N]: ").strip()
+                if ans.lower() not in ("y", "yes"):
+                    print("Aborted.")
+                    sys.exit(0)
+            forked_from_id = clean_from
+            resolved_start_point = archive_ref
+        elif git.branch_exists(active_branch, cwd=repo_root):
+            if not force and sys.stdin.isatty():
+                ans = input(f"Troven '{clean_from}' is an active troven. Create a sub-troven from it? [y/N]: ").strip()
+                if ans.lower() not in ("y", "yes"):
+                    print("Aborted.")
+                    sys.exit(0)
+            parent_id = clean_from
+            resolved_start_point = active_branch
+            base_branch = active_branch
+        elif git.ref_exists(from_ref, cwd=repo_root) or git.branch_exists(from_ref, cwd=repo_root):
+            resolved_start_point = from_ref
+            base_branch = from_ref
+        else:
+            raise TrovenError(
+                f"Cannot resolve base ref: '{from_ref}'.",
+                remediation="Ensure the branch, commit, or troven ID exists.",
+            )
+
+    base_commit = git.get_head_sha(resolved_start_point, cwd=repo_root)
+
+    # Compute worktree directory
+    repo_name = repo_root.name
+    worktree_parent = repo_root.parent / f"{repo_name}-trovens"
+    worktree_dir = (worktree_parent / troven_id).resolve()
+
+    if worktree_dir.exists():
+        raise TrovenExistsError(
+            f"Worktree directory {worktree_dir} already exists.",
+            remediation="Remove the stale directory or pick a different name.",
+        )
+
+    # Create .troven/<id>.md record in base repo
+    record = TrovenRecord(
+        id=troven_id,
+        status="active",
+        version=1,
+        parent=parent_id,
+        forked_from=forked_from_id,
+        base_branch=base_branch,
+        base_commit=base_commit,
+    )
+    save_troven(repo_root, record)
+
+    # Commit the record to base branch if possible before branching
+    try:
+        git.commit_files([md_path], f"troven: start {troven_id}", cwd=repo_root)
+        if resolved_start_point == base_branch or resolved_start_point == "HEAD":
+            resolved_start_point = git.get_head_sha(base_branch, cwd=repo_root)
+    except Exception:
+        pass
+
+    # Create worktree
+    print(f"Creating worktree at {worktree_dir} on branch '{branch_name}'...")
+    git.add_worktree(
+        worktree_dir=worktree_dir,
+        branch_name=branch_name,
+        start_point=resolved_start_point,
+        cwd=repo_root,
+    )
+
+    # Ensure worktree has the .troven file in place
+    save_troven(worktree_dir, record)
+
+    # Remote sync setup
+    git.configure_archive_remote(cwd=repo_root)
+
+    print(f"Troven '{troven_id}' initialized.")
+
+    if no_exec:
+        return worktree_dir
+
+    # Change into worktree and run command / agent
+    os.chdir(worktree_dir)
+
+    if command:
+        print(f"Executing: {' '.join(command)}")
+        os.execvp(command[0], command)
+
+    agent_cmd = os.environ.get("TROVEN_AGENT", os.environ.get("AGENT", "agy"))
+    boot_prompt = (
+        f"You are working in an isolated troven worktree for '{troven_id}' on branch '{branch_name}'.\n"
+        f"Troven outcome record: .troven/{troven_id}.md\n"
+        f"Please review README.md for project setup, building, and validation/test commands.\n"
+        f"When ready, write your summary to ## Summary in .troven/{troven_id}.md before calling 'troven accept' or 'troven reject'."
+    )
+
+    # If agy, pass prompt via -i
+    if agent_cmd == "agy":
+        os.execvp("agy", ["agy", "-i", boot_prompt])
+    else:
+        # Default fallback to executing agent or shell
+        try:
+            os.execvp(agent_cmd, [agent_cmd])
+        except FileNotFoundError:
+            print(f"Agent '{agent_cmd}' not found in PATH. Dropping into bash shell in worktree.")
+            os.execvp("bash", ["bash"])
+
+    return worktree_dir

troven/commands/install_skill.py

@@ -0,0 +1,51 @@
+"""Implementation of 'troven install-skill' subcommand."""
+
+from __future__ import annotations
+
+import importlib.resources
+import os
+from pathlib import Path
+import shutil
+
+
+def get_skill_content() -> str:
+    """Read bundled SKILL.md content."""
+    try:
+        res = importlib.resources.files("troven").joinpath("skill/SKILL.md")
+        return res.read_text(encoding="utf-8")
+    except Exception:
+        # Fallback to local file if run from source tree
+        local_path = Path(__file__).resolve().parent.parent.parent.parent / "skills" / "troven" / "SKILL.md"
+        if local_path.exists():
+            return local_path.read_text(encoding="utf-8")
+        raise
+
+
+def execute_install_skill(user_only: bool = False) -> None:
+    """Install the troven agent skill into agent skill discovery directories."""
+    content = get_skill_content()
+
+    home = Path.home()
+    agents_dir = home / ".agents" / "skills" / "troven"
+    gemini_dir = home / ".gemini" / "config" / "skills" / "troven"
+
+    # Install into ~/.agents/skills/troven/SKILL.md
+    agents_dir.mkdir(parents=True, exist_ok=True)
+    (agents_dir / "SKILL.md").write_text(content, encoding="utf-8")
+    print(f"\033[32m[Installed]\033[0m Skill written to {agents_dir / 'SKILL.md'}")
+
+    # Symlink or write to ~/.gemini/config/skills/troven
+    gemini_skills = home / ".gemini" / "config" / "skills"
+    if gemini_skills.exists():
+        if gemini_dir.is_symlink() or gemini_dir.exists():
+            if gemini_dir.is_symlink():
+                gemini_dir.unlink()
+            elif gemini_dir.is_dir():
+                shutil.rmtree(gemini_dir)
+        try:
+            gemini_dir.symlink_to(agents_dir, target_is_directory=True)
+            print(f"\033[32m[Linked]\033[0m Symlinked {gemini_dir} -> {agents_dir}")
+        except Exception:
+            gemini_dir.mkdir(parents=True, exist_ok=True)
+            (gemini_dir / "SKILL.md").write_text(content, encoding="utf-8")
+            print(f"\033[32m[Installed]\033[0m Skill written to {gemini_dir / 'SKILL.md'}")

troven/commands/list_cmd.py

@@ -0,0 +1,79 @@
+"""Implementation of 'troven list' subcommand."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from troven import git
+from troven.state import TrovenRecord, list_all_trovens
+
+
+def format_status(status: str) -> str:
+    if status == "accepted":
+        return "\033[32maccepted\033[0m"
+    elif status == "rejected":
+        return "\033[33mrejected\033[0m"
+    elif status == "active":
+        return "\033[36mactive  \033[0m"
+    return status.ljust(8)
+
+
+def execute_list(
+    status_filter: str | None = None,
+) -> None:
+    """List all trovens in a hierarchical tree view."""
+    repo_root = git.get_main_repo_root()
+    all_records = list_all_trovens(repo_root)
+
+    if not all_records:
+        print("No trovens found in this repository.")
+        return
+
+    # Filter if requested
+    records_by_id = {r.id: r for r in all_records}
+
+    # Build parent -> children map
+    children_map: dict[str | None, list[TrovenRecord]] = {}
+    for r in all_records:
+        parent_id = r.parent if r.parent in records_by_id else None
+        children_map.setdefault(parent_id, []).append(r)
+
+    # Check local worktrees
+    worktrees = git.list_worktrees(cwd=repo_root)
+    active_branches = {wt.branch for wt in worktrees if wt.branch}
+    active_paths = {wt.path for wt in worktrees}
+
+    def has_local_worktree(rec: TrovenRecord) -> bool:
+        branch = f"troven/{rec.id}"
+        if branch in active_branches:
+            return True
+        expected_path = repo_root.parent / f"{repo_root.name}-trovens" / rec.id
+        return expected_path.exists()
+
+    def print_node(rec: TrovenRecord, prefix: str = "", is_last: bool = True) -> None:
+        if status_filter and rec.status != status_filter:
+            # Still process children if filter doesn't match
+            pass
+        else:
+            connector = "└─ " if is_last else "├─ "
+            date_prefix = rec.created_at[:10] if rec.created_at else "          "
+            status_str = format_status(rec.status)
+
+            wt_note = ""
+            if rec.status == "active" and not has_local_worktree(rec):
+                wt_note = " \033[90m[no local worktree]\033[0m"
+
+            ref_note = ""
+            if rec.status == "rejected" and rec.target_ref:
+                ref_note = f" \033[90m→ {rec.target_ref}\033[0m"
+
+            print(f"{prefix}{connector}{date_prefix}  [{status_str}]  {rec.id}{wt_note}{ref_note}")
+
+        children = children_map.get(rec.id, [])
+        new_prefix = prefix + ("   " if is_last else "│  ")
+        for i, child in enumerate(children):
+            print_node(child, prefix=new_prefix, is_last=(i == len(children) - 1))
+
+    root_nodes = children_map.get(None, [])
+    for i, root in enumerate(root_nodes):
+        print_node(root, prefix="", is_last=(i == len(root_nodes) - 1))