claude-code-conductor 0.2.0__py3-none-any.whl

c3/cli.py

@@ -0,0 +1,63 @@
+"""C3 CLI entry point.
+
+Each subcommand registers its parser through ``register(subparsers)`` and
+exposes a ``handle(args) -> int`` function. Keeping each subcommand in its own
+module (``cli_*.py``) keeps the dispatch table small and isolates the
+implementation details.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from c3 import __version__
+from c3 import cli_doctor, cli_init, cli_list, cli_po, cli_update
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="c3",
+        description="Claude Code Conductor - multi-agent orchestration framework",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"c3 {__version__}",
+    )
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+    sub.required = True
+
+    cli_init.register(sub)
+    cli_update.register(sub)
+    cli_list.register(sub)
+    cli_doctor.register(sub)
+    cli_po.register(sub)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    _force_utf8_streams()
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.handler(args)
+
+
+def _force_utf8_streams() -> None:
+    """Reconfigure stdout/stderr to UTF-8 so Japanese output renders correctly on Windows.
+
+    No-op on platforms where stdout is already UTF-8 or where ``reconfigure`` is unavailable.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
+        try:
+            reconfigure(encoding="utf-8")
+        except (ValueError, OSError):
+            pass
+
+
+if __name__ == "__main__":
+    sys.exit(main())

c3/cli_doctor.py

@@ -0,0 +1,135 @@
+"""``c3 doctor`` - diagnose the C3 installation health."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+
+from c3.paths import claude_root_for
+from c3.po.detect import detect_po
+
+_OK = "OK"
+_WARN = "WARN"
+_ERR = "ERR"
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    parser = subparsers.add_parser(
+        "doctor",
+        help="Run diagnostics on the local C3 setup",
+    )
+    parser.add_argument(
+        "--check",
+        choices=["all", "po-only"],
+        default="all",
+        help="Limit checks to a subset (default: all)",
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Print only failures and warnings",
+    )
+    parser.set_defaults(handler=handle)
+
+
+def handle(args: argparse.Namespace) -> int:
+    color = _supports_color()
+    findings: list[tuple[str, str, str]] = []  # (status, label, detail)
+
+    if args.check == "po-only":
+        findings.append(_check_po())
+    else:
+        findings.append(_check_claude_dir())
+        findings.append(_check_settings_json())
+        findings.append(_check_claude_binary())
+        findings.append(_check_po())
+
+    exit_code = 0
+    for status, label, detail in findings:
+        if args.quiet and status == _OK:
+            continue
+        print(_format(status, label, detail, color=color))
+        if status == _ERR:
+            exit_code = 1
+
+    return exit_code
+
+
+def _check_claude_dir() -> tuple[str, str, str]:
+    root = claude_root_for(Path.cwd())
+    if root is None:
+        return (
+            _WARN,
+            ".claude/ directory",
+            "not found from cwd; run `c3 init` to scaffold one",
+        )
+    return _OK, ".claude/ directory", str(root / ".claude")
+
+
+def _check_settings_json() -> tuple[str, str, str]:
+    root = claude_root_for(Path.cwd())
+    if root is None:
+        return _WARN, "settings.json", "skipped (.claude/ not found)"
+    settings = root / ".claude" / "settings.json"
+    if not settings.is_file():
+        return _WARN, "settings.json", f"missing at {settings}"
+    try:
+        json.loads(settings.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        return _ERR, "settings.json", f"invalid JSON: {exc}"
+    return _OK, "settings.json", str(settings)
+
+
+def _check_claude_binary() -> tuple[str, str, str]:
+    path = shutil.which("claude")
+    if path is None:
+        return (
+            _WARN,
+            "claude binary",
+            "not on PATH; install Claude Code CLI before running parallel-orchestra",
+        )
+    return _OK, "claude binary", path
+
+
+def _check_po() -> tuple[str, str, str]:
+    available, version, cli_path = detect_po()
+    if available:
+        ver = version or "unknown version"
+        return _OK, "parallel-orchestra", f"{ver} at {cli_path}"
+    return (
+        _WARN,
+        "parallel-orchestra",
+        (
+            "not installed (optional). 並列実行を使うには "
+            "`pip install parallel-orchestra` を実行してください。"
+            "詳細: https://pypi.org/project/parallel-orchestra/"
+        ),
+    )
+
+
+def _supports_color() -> bool:
+    if os.environ.get("NO_COLOR"):
+        return False
+    if not sys.stdout.isatty():
+        return False
+    return True
+
+
+def _format(status: str, label: str, detail: str, *, color: bool) -> str:
+    icon = {
+        _OK: "[OK]",
+        _WARN: "[WARN]",
+        _ERR: "[ERR]",
+    }[status]
+    if color:
+        ansi = {
+            _OK: "\033[32m",
+            _WARN: "\033[33m",
+            _ERR: "\033[31m",
+        }[status]
+        icon = f"{ansi}{icon}\033[0m"
+    return f"  {icon} {label}: {detail}"

c3/cli_init.py

@@ -0,0 +1,70 @@
+"""``c3 init`` - scaffold ``.claude/`` into the current project."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+from c3.paths import templates_dir
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    parser = subparsers.add_parser(
+        "init",
+        help="Scaffold a fresh .claude/ directory into the current project",
+        description=(
+            "Copy the bundled C3 .claude/ template into the current working "
+            "directory. Refuses to overwrite an existing .claude/ unless "
+            "--force is given."
+        ),
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite an existing .claude/ directory without confirmation",
+    )
+    parser.add_argument(
+        "--target",
+        type=Path,
+        default=None,
+        help="Destination directory (defaults to the current working directory)",
+    )
+    parser.set_defaults(handler=handle)
+
+
+def handle(args: argparse.Namespace) -> int:
+    target_root: Path = (args.target or Path.cwd()).resolve()
+    dest = target_root / ".claude"
+
+    if dest.exists() and not args.force:
+        print(
+            f"refusing to overwrite existing directory: {dest}\n"
+            "Pass --force to overwrite or run `c3 update` for a diff-aware merge.",
+            file=sys.stderr,
+        )
+        return 1
+
+    template = templates_dir()
+    if dest.exists() and args.force:
+        shutil.rmtree(dest)
+
+    target_root.mkdir(parents=True, exist_ok=True)
+    copied = _copytree(template, dest)
+    print(f"initialized {dest} ({copied} files copied)")
+    return 0
+
+
+def _copytree(src: Path, dst: Path) -> int:
+    """Copy src -> dst recursively; return number of regular files written."""
+    dst.mkdir(parents=True, exist_ok=True)
+    count = 0
+    for entry in src.iterdir():
+        target = dst / entry.name
+        if entry.is_dir():
+            count += _copytree(entry, target)
+        elif entry.is_file():
+            shutil.copy2(entry, target)
+            count += 1
+    return count

c3/cli_list.py

@@ -0,0 +1,69 @@
+"""``c3 list-agents`` / ``list-skills`` / ``list-commands`` - inspect installed assets."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+from c3.paths import claude_root_for
+
+_FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+_DESCRIPTION_RE = re.compile(r"^description:\s*(.+?)\s*$", re.MULTILINE)
+_H1_RE = re.compile(r"^#\s+(.+?)\s*$", re.MULTILINE)
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    for kind in ("agents", "skills", "commands"):
+        parser = subparsers.add_parser(
+            f"list-{kind}",
+            help=f"List installed {kind} in the project's .claude/{kind}/",
+        )
+        parser.add_argument(
+            "--target",
+            type=Path,
+            default=None,
+            help="Project root (defaults to walking up from cwd to find .claude/)",
+        )
+        parser.set_defaults(handler=handle, kind=kind)
+
+
+def handle(args: argparse.Namespace) -> int:
+    start = (args.target or Path.cwd()).resolve()
+    root = claude_root_for(start)
+    if root is None:
+        print(
+            f"no .claude/ directory found at or above {start}",
+            file=sys.stderr,
+        )
+        return 1
+
+    target_dir = root / ".claude" / args.kind
+    if not target_dir.is_dir():
+        print(f"no .claude/{args.kind}/ directory at {root}", file=sys.stderr)
+        return 1
+
+    files = sorted(p for p in target_dir.glob("*.md") if p.is_file())
+    if not files:
+        print(f"(no {args.kind} found)")
+        return 0
+
+    width = max(len(p.stem) for p in files)
+    for path in files:
+        summary = _summary(path)
+        print(f"  {path.stem.ljust(width)}  {summary}")
+    return 0
+
+
+def _summary(path: Path) -> str:
+    text = path.read_text(encoding="utf-8")
+    fm_match = _FRONTMATTER_RE.match(text)
+    if fm_match:
+        desc_match = _DESCRIPTION_RE.search(fm_match.group(1))
+        if desc_match:
+            return desc_match.group(1).strip("\"'")
+    h1_match = _H1_RE.search(text)
+    if h1_match:
+        return h1_match.group(1)
+    return ""

c3/cli_po.py

@@ -0,0 +1,102 @@
+"""``c3 po`` - thin wrapper around the parallel-orchestra CLI."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from c3.paths import claude_root_for
+from c3.po.detect import detect_po
+from c3.po.manifest import validate_manifest
+from c3.po.run import run_manifest
+
+
+_NOT_INSTALLED_MSG = (
+    "parallel-orchestra is not installed. "
+    "並列実行を使うには `pip install parallel-orchestra` を実行してください。"
+    "詳細: https://pypi.org/project/parallel-orchestra/"
+)
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    parser = subparsers.add_parser(
+        "po",
+        help="Run a plan-report as a parallel-orchestra manifest",
+    )
+    inner = parser.add_subparsers(dest="po_command", metavar="<subcommand>")
+    inner.required = True
+
+    dry = inner.add_parser(
+        "dry-run",
+        help="Validate the manifest without executing tasks",
+    )
+    dry.add_argument("manifest", type=Path)
+    dry.set_defaults(handler=_handle_dry_run)
+
+    run = inner.add_parser(
+        "run",
+        help="Execute the manifest",
+    )
+    run.add_argument("manifest", type=Path)
+    run.add_argument("--max-workers", type=int, default=None)
+    run.add_argument("--report", type=Path, default=None)
+    run.add_argument("--quiet", action="store_true")
+    run.add_argument("--claude-exe", default=None)
+    run.set_defaults(handler=_handle_run)
+
+
+def _ensure_po_available() -> int:
+    available, _, _ = detect_po()
+    if not available:
+        print(_NOT_INSTALLED_MSG, file=sys.stderr)
+        return 1
+    return 0
+
+
+def _preflight(manifest: Path) -> int:
+    if not manifest.is_file():
+        print(f"manifest not found: {manifest}", file=sys.stderr)
+        return 2
+    root = claude_root_for(manifest.parent) or claude_root_for(Path.cwd())
+    if root is None:
+        print("could not locate .claude/ directory for agent lookup", file=sys.stderr)
+        return 2
+    errors = validate_manifest(manifest, root)
+    if errors:
+        for err in errors:
+            print(err, file=sys.stderr)
+        return 2
+    return 0
+
+
+def _handle_dry_run(args: argparse.Namespace) -> int:
+    rc = _preflight(args.manifest)
+    if rc != 0:
+        return rc
+    if (rc := _ensure_po_available()) != 0:
+        return rc
+    result = run_manifest(args.manifest, dry_run=True)
+    if result.status == "not_installed":
+        print(_NOT_INSTALLED_MSG, file=sys.stderr)
+        return 1
+    return result.exit_code if result.exit_code >= 0 else 1
+
+
+def _handle_run(args: argparse.Namespace) -> int:
+    rc = _preflight(args.manifest)
+    if rc != 0:
+        return rc
+    if (rc := _ensure_po_available()) != 0:
+        return rc
+    result = run_manifest(
+        args.manifest,
+        max_workers=args.max_workers,
+        report=args.report,
+        quiet=args.quiet,
+        claude_exe=args.claude_exe,
+    )
+    if result.status == "not_installed":
+        print(_NOT_INSTALLED_MSG, file=sys.stderr)
+        return 1
+    return result.exit_code if result.exit_code >= 0 else 1

c3/cli_update.py

@@ -0,0 +1,117 @@
+"""``c3 update`` - bring the project's ``.claude/`` up to date with the package template."""
+
+from __future__ import annotations
+
+import argparse
+import filecmp
+import shutil
+import sys
+from pathlib import Path
+
+from c3.paths import templates_dir
+
+# Files that the user is expected to edit locally; never overwrite them.
+# These match the .gitignore entries used in the C3 source repo.
+_LOCAL_FILES: tuple[str, ...] = (
+    "docs/decisions.md",
+    "docs/taxonomy.md",
+    "docs/game-studios-research.md",
+    "memory/patterns.json",
+    "memory/agent-audit.log",
+)
+_LOCAL_DIRS: tuple[str, ...] = (
+    "memory/sessions",
+    "reports",
+    "tmp",
+)
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    parser = subparsers.add_parser(
+        "update",
+        help="Refresh .claude/ from the bundled template (skips local files)",
+        description=(
+            "Compare the project's .claude/ to the bundled template and "
+            "overwrite framework files that differ. User-managed files "
+            "(reports/, memory/sessions/, docs/decisions.md, etc.) are "
+            "always skipped."
+        ),
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would change without writing anything",
+    )
+    parser.add_argument(
+        "--target",
+        type=Path,
+        default=None,
+        help="Destination directory (defaults to the current working directory)",
+    )
+    parser.set_defaults(handler=handle)
+
+
+def handle(args: argparse.Namespace) -> int:
+    target_root: Path = (args.target or Path.cwd()).resolve()
+    dest = target_root / ".claude"
+    if not dest.is_dir():
+        print(
+            f"no .claude/ directory found in {target_root}. "
+            "Run `c3 init` first.",
+            file=sys.stderr,
+        )
+        return 1
+
+    template = templates_dir()
+    actions = list(_walk_diff(template, dest))
+    if not actions:
+        print("up to date")
+        return 0
+
+    if args.dry_run:
+        print(f"{len(actions)} file(s) would change:")
+        for action, path in actions:
+            print(f"  {action}: {path.relative_to(dest)}")
+        return 0
+
+    for action, abs_path in actions:
+        rel = abs_path.relative_to(dest)
+        src = template / rel
+        if action == "add" or action == "update":
+            abs_path.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src, abs_path)
+            print(f"  {action}: {rel}")
+
+    print(f"{len(actions)} file(s) updated")
+    return 0
+
+
+def _walk_diff(template: Path, dest: Path):
+    """Yield (action, absolute_dest_path) tuples for files that differ.
+
+    Only ``add`` and ``update`` are emitted; we never delete files in dest.
+    """
+    for src_file in _iter_files(template):
+        rel = src_file.relative_to(template)
+        if _is_local(rel):
+            continue
+        target = dest / rel
+        if not target.exists():
+            yield "add", target
+        elif not filecmp.cmp(src_file, target, shallow=False):
+            yield "update", target
+
+
+def _iter_files(root: Path):
+    for entry in root.iterdir():
+        if entry.is_dir():
+            yield from _iter_files(entry)
+        elif entry.is_file():
+            yield entry
+
+
+def _is_local(rel: Path) -> bool:
+    rel_posix = rel.as_posix()
+    if rel_posix in _LOCAL_FILES:
+        return True
+    return any(rel_posix == d or rel_posix.startswith(d + "/") for d in _LOCAL_DIRS)

c3/paths.py

@@ -0,0 +1,64 @@
+"""Path resolution helpers for C3.
+
+Two responsibilities:
+- locate the user project's ``.claude/`` directory by walking upward from a cwd
+- locate the bundled ``.claude/`` template (works for both regular installs and
+  editable installs)
+"""
+
+from __future__ import annotations
+
+from importlib.resources import files as _resource_files
+from pathlib import Path
+
+
+def claude_root_for(start: Path | str) -> Path | None:
+    """Walk up from ``start`` and return the nearest directory containing ``.claude/``.
+
+    Returns ``None`` if no ``.claude/`` is found before the filesystem root.
+    """
+    here = Path(start).resolve()
+    candidates = [here, *here.parents]
+    for candidate in candidates:
+        if (candidate / ".claude").is_dir():
+            return candidate
+    return None
+
+
+def templates_dir() -> Path:
+    """Return the path to the bundled ``.claude/`` template.
+
+    Resolution order:
+
+    1. Dev source: walk up from this file looking for a sibling ``.claude/``
+       next to a ``pyproject.toml``. This makes editable installs (``pip install
+       -e .``) reflect live edits to the source ``.claude/`` without rebuilding.
+       In a wheel-installed environment the ``.py`` files live under
+       ``site-packages/`` and this lookup naturally returns no match.
+    2. Installed location: ``importlib.resources.files("c3") / "_template" / ".claude"``.
+       This is the path produced by hatchling's build hook + ``force-include``
+       during ``pip install``.
+
+    Raises ``FileNotFoundError`` if neither location exists. This usually means
+    the package was built without the template (manually copied source tree) -
+    reinstall via pip to fix.
+    """
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        candidate = parent / ".claude"
+        if candidate.is_dir() and (parent / "pyproject.toml").is_file():
+            return candidate
+
+    try:
+        bundled = _resource_files("c3").joinpath("_template", ".claude")
+        bundled_path = Path(str(bundled))
+        if bundled_path.is_dir():
+            return bundled_path
+    except (ModuleNotFoundError, FileNotFoundError, AttributeError):
+        pass
+
+    raise FileNotFoundError(
+        "Could not locate the bundled .claude/ template. "
+        "Reinstall claude-code-conductor with "
+        "`pip install --force-reinstall claude-code-conductor`."
+    )

c3/po/__init__.py

@@ -0,0 +1,11 @@
+"""parallel-orchestra (PO) integration helpers.
+
+This package only invokes PO via its CLI (subprocess). It deliberately does
+not import ``parallel_orchestra`` so that C3 stays loosely coupled and is
+unaffected by PO's internal API changes.
+"""
+
+from c3.po.detect import detect_po
+from c3.po.run import RunResult, run_manifest
+
+__all__ = ["detect_po", "run_manifest", "RunResult"]

c3/po/detect.py

@@ -0,0 +1,44 @@
+"""Runtime detection of the parallel-orchestra (PO) installation.
+
+The authoritative signal is ``shutil.which`` because PO is invoked as a
+subprocess. ``importlib.metadata`` provides the version for diagnostics but
+its absence does not flip availability to False (e.g. pipx-installed PO can
+expose the binary while hiding the metadata from the caller's interpreter).
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from importlib.metadata import PackageNotFoundError, version
+
+
+def detect_po() -> tuple[bool, str | None, str | None]:
+    """Return ``(is_available, version, cli_path)``.
+
+    ``is_available`` is ``True`` iff ``parallel-orchestra`` is on PATH.
+    ``version`` is the package version reported by ``importlib.metadata``,
+    or ``None`` if the metadata is not queryable from this interpreter.
+    ``cli_path`` is the absolute path returned by ``shutil.which`` (or ``None``).
+
+    Never raises.
+    """
+    cli_path = shutil.which("parallel-orchestra")
+    try:
+        ver = version("parallel-orchestra")
+    except PackageNotFoundError:
+        ver = None
+    return cli_path is not None, ver, cli_path
+
+
+def main() -> int:
+    """CLI helper: print key=value lines and exit 0/1 based on availability."""
+    available, ver, cli_path = detect_po()
+    print(f"available={'true' if available else 'false'}")
+    print(f"version={ver if ver is not None else 'None'}")
+    print(f"cli_path={cli_path if cli_path is not None else 'None'}")
+    return 0 if available else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())