tasktree-manager 2.9.0__tar.gz → 2.10.0__tar.gz

{tasktree_manager-2.9.0 → tasktree_manager-2.10.0}/CHANGELOG.md

@@ -15,6 +15,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Git hooks support
 - Custom task metadata
 
+## [2.10.0] - 2026-07-23
+
+### Added
+- **cli**: Add headless CLI for task management
+
+
 ## [2.9.0] - 2026-07-14
 
 ### Added

{tasktree_manager-2.9.0 → tasktree_manager-2.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tasktree-manager
-Version: 2.9.0
+Version: 2.10.0
 Summary: TUI application for managing worktree-based tasks
 License-File: LICENSE
 Requires-Python: >=3.10

{tasktree_manager-2.9.0 → tasktree_manager-2.10.0}/README.md

@@ -18,6 +18,7 @@
 - ⌨️ **Keyboard-First** - Navigate and control everything without touching the mouse
 - 🚀 **Fast & Responsive** - Parallel git operations with loading indicators
 - 🔧 **Flexible Configuration** - TOML config file, custom keybindings, environment variables
+- 🤖 **Headless CLI** - Create, list, and delete tasks from scripts and AI agents without opening the TUI
 
 ## 📊 Status Indicators
 
@@ -63,6 +64,22 @@ On first run, you'll configure:
 
 For detailed workflows and examples, see the [User Guide](docs/user-guide.md).
 
+### Headless CLI
+
+Running `tasktree-manager` with arguments skips the TUI — useful for scripts and AI-agent
+workflows (e.g. a skill that creates a Jira ticket and then the matching task):
+
+```bash
+tasktree-manager create DIC-1901-argocd-tls --repos backend,frontend  # --base overrides the default base branch
+tasktree-manager list --json     # tasks with repos and dirty state (plain text without --json)
+tasktree-manager repos           # available repos in REPOS_DIR
+tasktree-manager add-repo DIC-1901-argocd-tls infra
+tasktree-manager delete DIC-1901-argocd-tls   # refuses on unfinished work; --force overrides
+```
+
+Exit code is 0 on success, 1 on failure with the reason on stderr. `delete` runs the same
+safety check as the TUI (uncommitted, unpushed, or unmerged work blocks deletion).
+
 ## 📖 Documentation
 
 **Complete guides:**

{tasktree_manager-2.9.0 → tasktree_manager-2.10.0}/pyproject.toml

@@ -70,7 +70,7 @@ version-file = "tasktree_manager/_version.py"
 # Semantic Release Configuration
 [tool.semantic_release]
 version_toml = ["pyproject.toml:tool.semantic_release.version"]
-version = "2.9.0"
+version = "2.10.0"
 tag_format = "v{version}"
 branch = "main"
 commit_message = "chore(release): {version} [skip ci]"

{tasktree_manager-2.9.0 → tasktree_manager-2.10.0}/tasktree_manager/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.9.0'
-__version_tuple__ = version_tuple = (2, 9, 0)
+__version__ = version = '2.10.0'
+__version_tuple__ = version_tuple = (2, 10, 0)
 
 __commit_id__ = commit_id = None

{tasktree_manager-2.9.0 → tasktree_manager-2.10.0}/tasktree_manager/app.py

@@ -2,6 +2,7 @@
 
 import json
 import subprocess
+import sys
 import threading
 import time
 from pathlib import Path
@@ -1681,7 +1682,11 @@ class TaskTreeApp(App):
 
 
 def main():
-    """Entry point for the tasktree-manager application."""
+    """Entry point: TUI with no arguments, headless CLI otherwise."""
+    if len(sys.argv) > 1:
+        from .cli import run_cli
+
+        raise SystemExit(run_cli(sys.argv[1:]))
     app = TaskTreeApp()
     app.run()
 

tasktree_manager-2.10.0/tasktree_manager/cli.py

@@ -0,0 +1,198 @@
+"""Headless CLI for tasktree-manager.
+
+Running ``tasktree-manager`` with no arguments starts the TUI; any argument
+routes here instead. Built for scripts and automation (e.g. Claude skills
+that create a task and then work in its worktrees): plain text on stdout,
+errors on stderr, exit code 0 on success and 1 on failure.
+"""
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .services.config import Config
+from .services.git_ops import GitOps
+from .services.task_manager import TaskManager
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser for the headless CLI."""
+    parser = argparse.ArgumentParser(
+        prog="tasktree-manager",
+        description="Manage git worktree-based tasks (run with no arguments for the TUI).",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    create = sub.add_parser("create", help="Create a task with worktrees for the given repos")
+    create.add_argument("name", help="Task name (also used as the branch name)")
+    create.add_argument(
+        "--repos",
+        required=True,
+        help="Comma-separated repo names from REPOS_DIR (e.g. repo-a,repo-b)",
+    )
+    create.add_argument(
+        "--base",
+        default=None,
+        help="Base branch for the worktrees (default: git.default_base_branch from config)",
+    )
+    create.set_defaults(func=cmd_create)
+
+    list_parser = sub.add_parser("list", help="List tasks with their repos and dirty state")
+    list_parser.add_argument("--json", action="store_true", dest="as_json", help="Output JSON")
+    list_parser.set_defaults(func=cmd_list)
+
+    repos = sub.add_parser("repos", help="List available repos in REPOS_DIR (one per line)")
+    repos.set_defaults(func=cmd_repos)
+
+    delete = sub.add_parser("delete", help="Delete a task and its worktrees")
+    delete.add_argument("name", help="Task name")
+    delete.add_argument(
+        "--force",
+        action="store_true",
+        help="Delete even with uncommitted, unpushed or unmerged work",
+    )
+    delete.set_defaults(func=cmd_delete)
+
+    add_repo = sub.add_parser("add-repo", help="Add a repo worktree to an existing task")
+    add_repo.add_argument("name", help="Task name")
+    add_repo.add_argument("repo", help="Repo name from REPOS_DIR")
+    add_repo.add_argument("--base", default=None, help="Base branch for the worktree")
+    add_repo.set_defaults(func=cmd_add_repo)
+
+    return parser
+
+
+def _error(message: str) -> int:
+    print(f"error: {message}", file=sys.stderr)
+    return 1
+
+
+def _unknown_repos_error(config: Config, repos: list[str]) -> str | None:
+    """Return an error message if any repo is not in REPOS_DIR, else None."""
+    available = config.get_available_repos()
+    unknown = [r for r in repos if r not in available]
+    if unknown:
+        return (
+            f"unknown repo(s): {', '.join(unknown)}; "
+            f"available: {', '.join(available) or '(none)'}"
+        )
+    return None
+
+
+def cmd_create(manager: TaskManager, config: Config, args: argparse.Namespace) -> int:
+    """Create a task with worktrees for the given repos."""
+    repos = [r.strip() for r in args.repos.split(",") if r.strip()]
+    if not repos:
+        return _error("--repos needs at least one repo name")
+    error = _unknown_repos_error(config, repos)
+    if error:
+        return _error(error)
+    if manager.get_task(args.name):
+        return _error(f"task already exists: {args.name}")
+
+    base = args.base or config.default_base_branch
+    task = manager.create_task(args.name, repos, base)
+    # CLI-created tasks may never pass through the TUI's lazy Claude prep,
+    # so materialize CLAUDE.md files and worktree settings right away
+    manager.ensure_claude_md_files(task)
+    manager.ensure_worktree_settings(task)
+
+    repo_list = ", ".join(wt.name for wt in task.worktrees)
+    print(f"Created task {task.name} at {task.path} ({len(task.worktrees)} repo(s): {repo_list})")
+    return 0
+
+
+def cmd_list(manager: TaskManager, config: Config, args: argparse.Namespace) -> int:
+    """List tasks with their repos and dirty state."""
+    tasks = manager.list_tasks()
+    dirty: dict[str, bool] = {}
+    for task in tasks:
+        statuses = GitOps.get_statuses_parallel(task.worktrees)
+        dirty[task.name] = any(s.is_dirty for s in statuses.values())
+
+    if args.as_json:
+        payload = [
+            {
+                "name": task.name,
+                "path": str(task.path),
+                "repos": [wt.name for wt in task.worktrees],
+                "dirty": dirty[task.name],
+            }
+            for task in tasks
+        ]
+        print(json.dumps(payload, indent=2))
+        return 0
+
+    if not tasks:
+        print("No tasks")
+        return 0
+    for task in tasks:
+        state = "dirty" if dirty[task.name] else "clean"
+        repos = ", ".join(wt.name for wt in task.worktrees) or "(no repos)"
+        print(f"{task.name}\t{state}\t{repos}")
+    return 0
+
+
+def cmd_repos(manager: TaskManager, config: Config, args: argparse.Namespace) -> int:
+    """List available repos (handles nested repos, unlike a plain ls)."""
+    for repo in config.get_available_repos():
+        print(repo)
+    return 0
+
+
+def cmd_delete(manager: TaskManager, config: Config, args: argparse.Namespace) -> int:
+    """Delete a task after a safety check (bypass with --force)."""
+    task = manager.get_task(args.name)
+    if not task:
+        return _error(f"no such task: {args.name}")
+
+    report = manager.check_task_safety(task)
+    if not report.is_safe() and not args.force:
+        print(f"error: task {args.name} has unfinished work:", file=sys.stderr)
+        for issue in report.dirty + report.unpushed + report.unmerged:
+            print(f"  {issue.repo_name}: {issue.details}", file=sys.stderr)
+        print("use --force to delete anyway", file=sys.stderr)
+        return 1
+
+    manager.finish_task(task)
+    print(f"Deleted task {args.name}")
+    return 0
+
+
+def cmd_add_repo(manager: TaskManager, config: Config, args: argparse.Namespace) -> int:
+    """Add a repo worktree to an existing task."""
+    task = manager.get_task(args.name)
+    if not task:
+        return _error(f"no such task: {args.name}")
+    error = _unknown_repos_error(config, [args.repo])
+    if error:
+        return _error(error)
+    if any(wt.name == args.repo for wt in task.worktrees):
+        print(f"Repo {args.repo} already in task {args.name}")
+        return 0
+
+    base = args.base or config.default_base_branch
+    manager.add_repo_to_task(task, args.repo, base)
+    print(f"Added {args.repo} to task {args.name}")
+    return 0
+
+
+def run_cli(argv: list[str], config: Config | None = None) -> int:
+    """Parse argv and run the matching subcommand, returning an exit code."""
+    args = build_parser().parse_args(argv)
+    if config is None:
+        config = Config.load()
+    config.ensure_dirs()
+    manager = TaskManager(config)
+    try:
+        return args.func(manager, config, args)
+    except FileNotFoundError as e:
+        return _error(f"repository not found: {e}")
+    except PermissionError:
+        return _error("permission denied: check directory permissions")
+    except ValueError as e:
+        return _error(str(e))
+    except Exception as e:  # same taxonomy as the TUI worker: keep output clean
+        return _error(f"{type(e).__name__}: {e}")

tasktree_manager-2.10.0/tests/test_cli.py

@@ -0,0 +1,237 @@
+"""Tests for the headless CLI (tasktree_manager/cli.py)."""
+
+import json
+import subprocess
+
+import pytest
+
+from tasktree_manager.cli import run_cli
+
+
+def cli(config, *argv):
+    """Run the CLI against the test config."""
+    return run_cli(list(argv), config=config)
+
+
+@pytest.fixture
+def cli_config(config, sample_repos):
+    """Config whose default base branch matches the sample repos' actual branch.
+
+    CI runners have no init.defaultBranch configured, so fixture repos may be
+    on master while the config default is main; tests that rely on the default
+    base branch must line the two up.
+    """
+    _, branch = sample_repos
+    config.default_base_branch = branch
+    return config
+
+
+@pytest.fixture
+def repo_with_origin(config, tmp_path):
+    """A repo in REPOS_DIR whose branch is pushed to a bare origin remote.
+
+    check_merged() compares HEAD against origin/<base>, so only a repo
+    with a remote can ever count as "merged" (and thus safe to delete).
+    Returns the default branch name.
+    """
+    remote = tmp_path / "origin" / "repo-remote.git"
+    remote.mkdir(parents=True)
+    subprocess.run(["git", "init", "--bare"], cwd=remote, capture_output=True, check=True)
+
+    repo = config.repos_dir / "repo-remote"
+    repo.mkdir()
+    subprocess.run(["git", "init"], cwd=repo, capture_output=True, check=True)
+    subprocess.run(
+        ["git", "config", "user.email", "test@test.com"], cwd=repo, capture_output=True, check=True
+    )
+    subprocess.run(
+        ["git", "config", "user.name", "Test User"], cwd=repo, capture_output=True, check=True
+    )
+    subprocess.run(
+        ["git", "remote", "add", "origin", str(remote)], cwd=repo, capture_output=True, check=True
+    )
+    (repo / "README.md").write_text("# repo-remote\n")
+    subprocess.run(["git", "add", "."], cwd=repo, capture_output=True, check=True)
+    subprocess.run(["git", "commit", "-m", "Initial"], cwd=repo, capture_output=True, check=True)
+    subprocess.run(
+        ["git", "push", "-u", "origin", "HEAD"], cwd=repo, capture_output=True, check=True
+    )
+    branch = subprocess.run(
+        ["git", "branch", "--show-current"], cwd=repo, capture_output=True, text=True
+    ).stdout.strip()
+    return branch
+
+
+class TestCreate:
+    def test_create_task(self, cli_config, capsys):
+        code = cli(cli_config, "create", "DIC-1901-argocd-tls", "--repos", "repo-alpha,repo-beta")
+        assert code == 0
+        out = capsys.readouterr().out
+        assert "Created task DIC-1901-argocd-tls" in out
+        assert "2 repo(s)" in out
+
+        task_path = cli_config.tasks_dir / "DIC-1901-argocd-tls"
+        assert (task_path / "repo-alpha" / ".git").exists()
+        assert (task_path / "repo-beta" / ".git").exists()
+        # Branch name matches task name
+        result = subprocess.run(
+            ["git", "branch", "--show-current"],
+            cwd=task_path / "repo-alpha",
+            capture_output=True,
+            text=True,
+        )
+        assert result.stdout.strip() == "DIC-1901-argocd-tls"
+        # Task CLAUDE.md is materialized at create time (no TUI lazy prep)
+        assert (task_path / "CLAUDE.md").exists()
+
+    def test_create_with_base(self, config, sample_repos, capsys):
+        _, branch = sample_repos
+        code = cli(config, "create", "task-x", "--repos", "repo-alpha", "--base", branch)
+        assert code == 0
+
+    def test_create_unknown_repo(self, config, sample_repos, capsys):
+        code = cli(config, "create", "task-x", "--repos", "no-such-repo")
+        assert code == 1
+        err = capsys.readouterr().err
+        assert "unknown repo(s): no-such-repo" in err
+        assert "repo-alpha" in err  # lists available repos
+        assert not (config.tasks_dir / "task-x").exists()
+
+    def test_create_duplicate(self, cli_config, capsys):
+        assert cli(cli_config, "create", "task-x", "--repos", "repo-alpha") == 0
+        capsys.readouterr()
+        code = cli(cli_config, "create", "task-x", "--repos", "repo-beta")
+        assert code == 1
+        assert "task already exists" in capsys.readouterr().err
+
+    def test_create_invalid_name(self, config, sample_repos, capsys):
+        code = cli(config, "create", "../escape", "--repos", "repo-alpha")
+        assert code == 1
+        assert "error:" in capsys.readouterr().err
+
+    def test_create_empty_repos(self, config, sample_repos, capsys):
+        code = cli(config, "create", "task-x", "--repos", " , ")
+        assert code == 1
+        assert "at least one repo" in capsys.readouterr().err
+
+
+class TestList:
+    def test_list_empty(self, config, capsys):
+        assert cli(config, "list") == 0
+        assert "No tasks" in capsys.readouterr().out
+
+    def test_list_plain(self, cli_config, capsys):
+        cli(cli_config, "create", "task-x", "--repos", "repo-alpha,repo-beta")
+        capsys.readouterr()
+        assert cli(cli_config, "list") == 0
+        out = capsys.readouterr().out
+        assert "task-x" in out
+        assert "clean" in out
+        assert "repo-alpha, repo-beta" in out
+
+    def test_list_json(self, cli_config, capsys):
+        cli(cli_config, "create", "task-x", "--repos", "repo-alpha")
+        capsys.readouterr()
+        assert cli(cli_config, "list", "--json") == 0
+        payload = json.loads(capsys.readouterr().out)
+        assert len(payload) == 1
+        assert payload[0]["name"] == "task-x"
+        assert payload[0]["repos"] == ["repo-alpha"]
+        assert payload[0]["dirty"] is False
+        assert payload[0]["path"] == str(cli_config.tasks_dir / "task-x")
+
+    def test_list_json_empty(self, config, capsys):
+        assert cli(config, "list", "--json") == 0
+        assert json.loads(capsys.readouterr().out) == []
+
+    def test_list_dirty(self, cli_config, capsys):
+        cli(cli_config, "create", "task-x", "--repos", "repo-alpha")
+        (cli_config.tasks_dir / "task-x" / "repo-alpha" / "dirty.txt").write_text("x\n")
+        capsys.readouterr()
+        assert cli(cli_config, "list", "--json") == 0
+        payload = json.loads(capsys.readouterr().out)
+        assert payload[0]["dirty"] is True
+
+
+class TestDelete:
+    def test_delete_clean(self, config, repo_with_origin, capsys):
+        cli(config, "create", "task-x", "--repos", "repo-remote", "--base", repo_with_origin)
+        capsys.readouterr()
+        assert cli(config, "delete", "task-x") == 0
+        assert "Deleted task task-x" in capsys.readouterr().out
+        assert not (config.tasks_dir / "task-x").exists()
+
+    def test_delete_unmerged_refuses(self, cli_config, capsys):
+        # Repos without a remote can never verify a merge -> treated as unmerged
+        cli(cli_config, "create", "task-x", "--repos", "repo-alpha")
+        capsys.readouterr()
+        assert cli(cli_config, "delete", "task-x") == 1
+        assert "unfinished work" in capsys.readouterr().err
+        assert (cli_config.tasks_dir / "task-x").exists()
+
+    def test_delete_missing(self, config, capsys):
+        assert cli(config, "delete", "nope") == 1
+        assert "no such task" in capsys.readouterr().err
+
+    def test_delete_dirty_refuses(self, cli_config, capsys):
+        cli(cli_config, "create", "task-x", "--repos", "repo-alpha")
+        (cli_config.tasks_dir / "task-x" / "repo-alpha" / "dirty.txt").write_text("x\n")
+        capsys.readouterr()
+        assert cli(cli_config, "delete", "task-x") == 1
+        err = capsys.readouterr().err
+        assert "unfinished work" in err
+        assert "--force" in err
+        assert (cli_config.tasks_dir / "task-x").exists()
+
+    def test_delete_dirty_force(self, cli_config, capsys):
+        cli(cli_config, "create", "task-x", "--repos", "repo-alpha")
+        (cli_config.tasks_dir / "task-x" / "repo-alpha" / "dirty.txt").write_text("x\n")
+        capsys.readouterr()
+        assert cli(cli_config, "delete", "task-x", "--force") == 0
+        assert not (cli_config.tasks_dir / "task-x").exists()
+
+
+class TestAddRepo:
+    def test_add_repo(self, cli_config, capsys):
+        cli(cli_config, "create", "task-x", "--repos", "repo-alpha")
+        capsys.readouterr()
+        assert cli(cli_config, "add-repo", "task-x", "repo-beta") == 0
+        assert "Added repo-beta to task task-x" in capsys.readouterr().out
+        assert (cli_config.tasks_dir / "task-x" / "repo-beta" / ".git").exists()
+
+    def test_add_repo_already_present(self, cli_config, capsys):
+        cli(cli_config, "create", "task-x", "--repos", "repo-alpha")
+        capsys.readouterr()
+        assert cli(cli_config, "add-repo", "task-x", "repo-alpha") == 0
+        assert "already in task" in capsys.readouterr().out
+
+    def test_add_repo_missing_task(self, config, sample_repos, capsys):
+        assert cli(config, "add-repo", "nope", "repo-alpha") == 1
+        assert "no such task" in capsys.readouterr().err
+
+    def test_add_repo_unknown_repo(self, cli_config, capsys):
+        cli(cli_config, "create", "task-x", "--repos", "repo-alpha")
+        capsys.readouterr()
+        assert cli(cli_config, "add-repo", "task-x", "no-such-repo") == 1
+        assert "unknown repo(s)" in capsys.readouterr().err
+
+
+class TestRepos:
+    def test_repos(self, config, sample_repos, capsys):
+        assert cli(config, "repos") == 0
+        assert capsys.readouterr().out.splitlines() == ["repo-alpha", "repo-beta", "repo-gamma"]
+
+    def test_repos_empty(self, config, capsys):
+        assert cli(config, "repos") == 0
+        assert capsys.readouterr().out == ""
+
+
+class TestParser:
+    def test_no_command_exits(self, config):
+        with pytest.raises(SystemExit):
+            run_cli([], config=config)
+
+    def test_version_exits(self, config, capsys):
+        with pytest.raises(SystemExit) as exc_info:
+            run_cli(["--version"], config=config)
+        assert exc_info.value.code == 0