kctl-linear 0.2.0__py3-none-any.whl

kctl_linear/__init__.py

@@ -0,0 +1,3 @@
+"""kctl-linear: Linear project management."""
+
+__version__ = "0.2.0"

kctl_linear/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as python -m kctl_linear."""
+
+from kctl_linear.cli import _run
+
+_run()

kctl_linear/cli.py

@@ -0,0 +1,131 @@
+"""Main CLI entry point for kctl-linear."""
+
+from __future__ import annotations
+
+
+from typing import Annotated
+
+import typer
+from kctl_lib import KctlError, handle_cli_error
+
+from kctl_linear import __version__
+from kctl_linear.commands.config_cmd import app as config_app
+from kctl_linear.commands.cycles import app as cycles_app
+from kctl_linear.commands.dashboard import app as dashboard_app
+from kctl_linear.commands.health import app as health_app
+from kctl_linear.commands.issues import app as issues_app
+from kctl_linear.commands.labels import app as labels_app
+from kctl_linear.commands.projects import app as projects_app
+from kctl_linear.commands.teams import app as teams_app
+from kctl_linear.commands.users import app as users_app
+from kctl_linear.core.callbacks import AppContext
+from kctl_linear.core.plugins import discover_and_load_plugins
+from kctl_linear.commands.skill_cmd import app as skill_app
+from kctl_linear.commands.doctor_cmd import app as doctor_app
+from kctl_lib.self_update import notify_if_outdated
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"kctl-linear {__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="kctl-linear",
+    help="Linear project management",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    pretty_exceptions_enable=False,
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: Annotated[bool, typer.Option("--json", help="Output as JSON")] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Suppress info messages")] = False,
+    profile: Annotated[str | None, typer.Option("--profile", "-p", help="Config profile name")] = None,
+    format: Annotated[str, typer.Option("--format", "-f", help="Output format: pretty, json, csv, yaml")] = "pretty",
+    no_header: Annotated[bool, typer.Option("--no-header", help="Omit header row in CSV output")] = False,
+    version: Annotated[
+        bool, typer.Option("--version", "-V", callback=version_callback, is_eager=True, help="Show version")
+    ] = False,
+) -> None:
+    """Linear project management."""
+    ctx.ensure_object(dict)
+    ctx.obj = AppContext(
+        json_mode=json_output,
+        quiet=quiet,
+        profile=profile,
+        format=format,
+        no_header=no_header,
+    )
+    notify_if_outdated(ctx.obj.output, "kctl-linear", __version__)
+
+
+# Command group registration
+app.add_typer(config_app, name="config")
+app.add_typer(health_app, name="health")
+app.add_typer(dashboard_app, name="dashboard")
+app.add_typer(issues_app, name="issues")
+app.add_typer(cycles_app, name="cycles")
+app.add_typer(projects_app, name="projects")
+app.add_typer(teams_app, name="teams")
+app.add_typer(labels_app, name="labels")
+app.add_typer(users_app, name="users")
+app.add_typer(skill_app, name="skill", hidden=True)
+app.add_typer(doctor_app, name="doctor")
+
+# Load third-party plugins via entry points
+discover_and_load_plugins(app)
+
+
+@app.command("self-update")
+def self_update_cmd(ctx: typer.Context) -> None:
+    """Check for updates and upgrade kctl-linear."""
+    actx = ctx.obj
+    out = actx.output
+
+    from kctl_lib.self_update import check_update
+    from kctl_lib.self_update import update as do_update
+
+    latest = check_update("kctl-linear", __version__)
+    if latest:
+        out.info(f"Updating to {latest}...")
+        do_update("kctl-linear")
+        out.success(f"Updated to {latest}")
+    else:
+        out.success("Already up to date")
+
+
+@app.command()
+def completions(
+    shell: Annotated[str, typer.Argument(help="Shell type: zsh, bash, fish")] = "zsh",
+    install: Annotated[bool, typer.Option("--install", help="Install completions")] = False,
+) -> None:
+    """Generate or install shell completions."""
+    from kctl_lib.completions import get_completion_script, install_completions
+
+    if install:
+        path = install_completions("kctl-linear", shell)
+        if path:
+            typer.echo(f"Completions installed to {path}")
+        else:
+            typer.echo(f"Could not install completions for {shell}", err=True)
+            raise typer.Exit(code=1)
+    else:
+        script = get_completion_script("kctl-linear", shell)
+        typer.echo(script)
+
+
+def _run() -> None:
+    """Entry point with error handling."""
+    try:
+        app()
+    except KctlError as e:
+        handle_cli_error(e)
+
+
+if __name__ == "__main__":
+    _run()

kctl_linear/commands/config_cmd.py

@@ -0,0 +1,201 @@
+"""Config profile management commands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from kctl_linear.core.callbacks import AppContext
+from kctl_linear.core.config import (
+    SERVICE_KEY,
+    ServiceConfig,
+    get_all_services_in_profile,
+    get_profile_names,
+    get_service_config,
+    remove_profile,
+    resolve_active_profile_name,
+    set_default_profile,
+    set_service_config,
+)
+
+app = typer.Typer(help="Profile and configuration management.")
+
+
+@app.command()
+def init(ctx: typer.Context) -> None:
+    """Interactive config setup."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    profile_name = typer.prompt("Profile name", default="default")
+    api_key = typer.prompt("Linear API key", hide_input=True)
+    default_team = typer.prompt("Default team key (e.g., KOD)", default="")
+    svc = ServiceConfig(api_key=api_key, default_team=default_team)
+    set_service_config(profile_name, svc)
+    set_default_profile(profile_name)
+    out.success(f"Config saved to profile '{profile_name}'")
+
+
+@app.command()
+def add(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Profile name")],
+) -> None:
+    """Add a new config profile."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    api_key = typer.prompt("Linear API key", hide_input=True)
+    default_team = typer.prompt("Default team key (e.g., KOD)", default="")
+    svc = ServiceConfig(api_key=api_key, default_team=default_team)
+    set_service_config(name, svc)
+    out.success(f"Profile '{name}' added")
+
+
+@app.command()
+def use(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Profile name to activate")],
+) -> None:
+    """Switch active config profile."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    available = get_profile_names()
+    if name not in available:
+        out.error(f"Profile '{name}' not found. Available: {', '.join(available)}")
+        raise typer.Exit(1)
+    set_default_profile(name)
+    out.success(f"Switched to profile '{name}'")
+
+
+@app.command()
+def show(ctx: typer.Context) -> None:
+    """Show current configuration."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    active = resolve_active_profile_name(actx.profile)
+    profiles = get_profile_names()
+    if out.json_mode:
+        out.raw_json({"active_profile": active, "profiles": {n: get_all_services_in_profile(n) for n in profiles}})
+        return
+    out.header("Configuration")
+    out.kv("Active profile", active)
+    for name in profiles:
+        marker = " (active)" if name == active else ""
+        out.header(f"Profile: {name}{marker}")
+        services = get_all_services_in_profile(name)
+        for svc_name, svc_data in services.items():
+            out.text(f"  [bold]{svc_name}:[/bold]")
+            if isinstance(svc_data, dict):
+                for k, v in svc_data.items():
+                    out.kv(f"    {k}", str(v))
+
+
+@app.command()
+def validate(ctx: typer.Context) -> None:
+    """Validate current config completeness."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    active = resolve_active_profile_name(actx.profile)
+    svc = get_service_config(active)
+    issues: list[str] = []
+    if not svc.api_key:
+        issues.append("api_key is not set")
+    if not svc.default_team:
+        issues.append("default_team is not set (optional but recommended)")
+    if out.json_mode:
+        out.raw_json({"profile": active, "valid": not any("api_key" in i for i in issues), "issues": issues})
+        return
+    if any("api_key" in i for i in issues):
+        out.error(f"Profile '{active}' has issues:")
+        for issue in issues:
+            out.text(f"  - {issue}")
+        raise typer.Exit(1)
+    if issues:
+        out.warn(f"Profile '{active}' has warnings:")
+        for issue in issues:
+            out.text(f"  - {issue}")
+    else:
+        out.success(f"Profile '{active}' is valid")
+
+
+@app.command()
+def remove(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Profile name to remove")],
+) -> None:
+    """Remove a config profile."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    available = get_profile_names()
+    if name not in available:
+        out.error(f"Profile '{name}' not found")
+        raise typer.Exit(1)
+    remove_profile(name)
+    out.success(f"Profile '{name}' removed")
+
+
+@app.command("set")
+def set_(
+    ctx: typer.Context,
+    key: Annotated[str, typer.Argument(help="Config key")],
+    value: Annotated[str, typer.Argument(help="Config value")],
+) -> None:
+    """Set a single config value."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    active = resolve_active_profile_name(actx.profile)
+    svc = get_service_config(active)
+    if key not in ServiceConfig.model_fields:
+        out.error(f"Unknown key '{key}'. Valid: {', '.join(ServiceConfig.model_fields)}")
+        raise typer.Exit(1)
+    data = svc.model_dump()
+    data[key] = value
+    set_service_config(active, ServiceConfig(**data))
+    out.success(f"Set {key}={value} in profile '{active}'")
+
+
+@app.command()
+def profiles(ctx: typer.Context) -> None:
+    """List all config profiles."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    active = resolve_active_profile_name(actx.profile)
+    names = get_profile_names()
+    if out.json_mode:
+        out.raw_json({"profiles": names, "active": active})
+        return
+    rows = [[name, "active" if name == active else ""] for name in names]
+    out.table("Profiles", [("Name", "cyan"), ("Status", "green")], rows)
+
+
+@app.command()
+def current(ctx: typer.Context) -> None:
+    """Show active profile and resolved context."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    active = resolve_active_profile_name(actx.profile)
+    svc = get_service_config(active)
+    if out.json_mode:
+        out.raw_json({"profile": active, **svc.model_dump()})
+        return
+    fields = [(k, str(v) or "(not set)") for k, v in svc.model_dump().items()]
+    sections = [("Active Profile", [("Name", active)] + fields)]
+    out.detail("Current Config", sections)
+
+
+@app.command()
+def test(ctx: typer.Context) -> None:
+    """Test API connection with current configuration."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    active = resolve_active_profile_name(actx.profile)
+    out.info(f"Testing profile '{active}' \u2192 {SERVICE_KEY}")
+    try:
+        data = actx.client.query("{ viewer { id name email } }")
+        viewer = data.get("viewer", {})
+        name = viewer.get("name", "unknown")
+        email = viewer.get("email", "")
+        out.success(f"Connected \u2014 authenticated as '{name}' ({email})")
+    except Exception as e:
+        out.error(f"Connection failed: {e}")
+        raise typer.Exit(1) from e

kctl_linear/commands/cycles.py

@@ -0,0 +1,205 @@
+"""Cycle (sprint) management commands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from kctl_linear.core.callbacks import AppContext
+from kctl_linear.core.client import (
+    CYCLE_CURRENT_QUERY,
+    CYCLE_SHOW_QUERY,
+    CYCLES_LIST_QUERY,
+)
+
+app = typer.Typer(help="Cycle (sprint) management.")
+
+
+@app.command()
+def current(
+    ctx: typer.Context,
+    team: Annotated[str | None, typer.Option("--team", "-t", help="Team key")] = None,
+) -> None:
+    """Show current active cycle with progress and issues."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    team_key = team or actx.default_team
+    data = actx.client.query(CYCLE_CURRENT_QUERY, {"teamKey": team_key})
+    cycles = data.get("cycles", {}).get("nodes", [])
+
+    if not cycles:
+        out.info("No active cycle")
+        return
+
+    cycle = cycles[0]
+
+    if out.json_mode:
+        out.raw_json(cycle)
+        return
+
+    progress = cycle.get("progress", 0)
+    progress_pct = f"{progress * 100:.0f}%" if isinstance(progress, (int, float)) else str(progress)
+
+    sections = [
+        (
+            "Current Cycle",
+            [
+                ("Name", cycle.get("name") or f"Cycle {cycle.get('number', '?')}"),
+                ("Progress", progress_pct),
+                ("Starts", (cycle.get("startsAt") or "")[:10]),
+                ("Ends", (cycle.get("endsAt") or "")[:10]),
+            ],
+        ),
+    ]
+    out.detail("Active Cycle", sections)
+
+    issues = cycle.get("issues", {}).get("nodes", [])
+    if issues:
+        rows = [
+            [
+                issue.get("identifier", ""),
+                issue.get("title", "")[:50],
+                str(issue.get("priority", "-")),
+                issue.get("state", {}).get("name", ""),
+                (issue.get("assignee") or {}).get("name", ""),
+            ]
+            for issue in issues
+        ]
+        out.table(
+            f"Cycle Issues ({len(issues)})",
+            [("ID", "cyan"), ("Title", "white"), ("P", "yellow"), ("State", "green"), ("Assignee", "magenta")],
+            rows,
+        )
+
+
+@app.command("list")
+def list_(
+    ctx: typer.Context,
+    team: Annotated[str | None, typer.Option("--team", "-t", help="Team key")] = None,
+    limit: Annotated[int, typer.Option("--limit", "-n", help="Max results")] = 20,
+) -> None:
+    """List past and upcoming cycles."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    team_key = team or actx.default_team
+    data = actx.client.query(CYCLES_LIST_QUERY, {"teamKey": team_key, "first": limit})
+    cycles = data.get("cycles", {}).get("nodes", [])
+
+    if out.json_mode:
+        out.raw_json(cycles)
+        return
+
+    if not cycles:
+        out.info("No cycles found")
+        return
+
+    rows = [
+        [
+            str(c.get("number", "")),
+            c.get("name") or f"Cycle {c.get('number', '?')}",
+            (c.get("startsAt") or "")[:10],
+            (c.get("endsAt") or "")[:10],
+            f"{(c.get('progress', 0) or 0) * 100:.0f}%",
+        ]
+        for c in cycles
+    ]
+    out.table(
+        f"Cycles ({len(cycles)})",
+        [("Num", "cyan"), ("Name", "white"), ("Start", "yellow"), ("End", "yellow"), ("Progress", "green")],
+        rows,
+    )
+
+
+@app.command()
+def show(
+    ctx: typer.Context,
+    cycle_id: Annotated[str, typer.Argument(help="Cycle ID (UUID)")],
+) -> None:
+    """Show cycle details: scope, completed, remaining issues."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    data = actx.client.query(CYCLE_SHOW_QUERY, {"id": cycle_id})
+    cycle = data.get("cycle", {})
+
+    if out.json_mode:
+        out.raw_json(cycle)
+        return
+
+    progress = cycle.get("progress", 0)
+    progress_pct = f"{progress * 100:.0f}%" if isinstance(progress, (int, float)) else str(progress)
+    issues = cycle.get("issues", {}).get("nodes", [])
+
+    sections = [
+        (
+            "Cycle Details",
+            [
+                ("Name", cycle.get("name") or f"Cycle {cycle.get('number', '?')}"),
+                ("Number", str(cycle.get("number", ""))),
+                ("Progress", progress_pct),
+                ("Starts", (cycle.get("startsAt") or "")[:10]),
+                ("Ends", (cycle.get("endsAt") or "")[:10]),
+                ("Total Issues", str(len(issues))),
+            ],
+        ),
+    ]
+    out.detail(f"Cycle {cycle.get('number', '?')}", sections)
+
+    if issues:
+        rows = [
+            [
+                issue.get("identifier", ""),
+                issue.get("title", "")[:50],
+                issue.get("state", {}).get("name", ""),
+                (issue.get("assignee") or {}).get("name", ""),
+                str(issue.get("estimate") or "-"),
+            ]
+            for issue in issues
+        ]
+        out.table(
+            "",
+            [("ID", "cyan"), ("Title", "white"), ("State", "green"), ("Assignee", "magenta"), ("Est", "yellow")],
+            rows,
+        )
+
+
+@app.command()
+def stats(
+    ctx: typer.Context,
+    team: Annotated[str | None, typer.Option("--team", "-t", help="Team key")] = None,
+) -> None:
+    """Show velocity trends across recent cycles."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    team_key = team or actx.default_team
+    data = actx.client.query(CYCLES_LIST_QUERY, {"teamKey": team_key, "first": 10})
+    cycles = data.get("cycles", {}).get("nodes", [])
+
+    if out.json_mode:
+        out.raw_json({"cycles": len(cycles), "data": cycles})
+        return
+
+    if not cycles:
+        out.info("No cycles found for velocity analysis")
+        return
+
+    out.header("Velocity Trends (last 10 cycles)")
+    rows = [
+        [
+            str(c.get("number", "")),
+            c.get("name") or f"Cycle {c.get('number', '?')}",
+            f"{(c.get('progress', 0) or 0) * 100:.0f}%",
+            (c.get("startsAt") or "")[:10],
+            (c.get("endsAt") or "")[:10],
+        ]
+        for c in cycles
+    ]
+    out.table(
+        "",
+        [("Num", "cyan"), ("Name", "white"), ("Completion", "green"), ("Start", "yellow"), ("End", "yellow")],
+        rows,
+    )

kctl_linear/commands/dashboard.py

@@ -0,0 +1,84 @@
+"""Dashboard — quick overview of my issues, current cycle, active projects."""
+
+from __future__ import annotations
+
+import typer
+
+from kctl_linear.core.callbacks import AppContext
+from kctl_linear.core.client import DASHBOARD_QUERY
+
+app = typer.Typer(help="Quick overview dashboard.")
+
+
+@app.callback(invoke_without_command=True)
+def dashboard(ctx: typer.Context) -> None:
+    """Show my issues, current cycle progress, and active projects."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    client = actx.client
+
+    variables: dict[str, str | None] = {"teamKey": actx.default_team}
+    data = client.query(DASHBOARD_QUERY, variables)
+
+    viewer = data.get("viewer", {})
+    my_issues = viewer.get("assignedIssues", {}).get("nodes", [])
+    cycles = data.get("cycles", {}).get("nodes", [])
+    projects = data.get("projects", {}).get("nodes", [])
+
+    if out.json_mode:
+        out.raw_json(
+            {
+                "viewer": {"name": viewer.get("name"), "email": viewer.get("email")},
+                "my_issues": my_issues,
+                "current_cycle": cycles[0] if cycles else None,
+                "active_projects": projects,
+            }
+        )
+        return
+
+    # My issues
+    out.header(f"My Issues ({len(my_issues)})")
+    if my_issues:
+        rows = [
+            [
+                issue.get("identifier", ""),
+                issue.get("title", "")[:60],
+                str(issue.get("priority", "")),
+                issue.get("state", {}).get("name", ""),
+            ]
+            for issue in my_issues
+        ]
+        out.table(
+            "",
+            [("ID", "cyan"), ("Title", "white"), ("Priority", "yellow"), ("State", "green")],
+            rows,
+        )
+    else:
+        out.info("No active issues assigned to you")
+
+    # Current cycle
+    if cycles:
+        cycle = cycles[0]
+        progress = cycle.get("progress", 0)
+        progress_pct = f"{progress * 100:.0f}%" if isinstance(progress, (int, float)) else str(progress)
+        out.header("Current Cycle")
+        out.kv("Name", cycle.get("name") or f"Cycle {cycle.get('number', '?')}")
+        out.kv("Progress", progress_pct)
+        out.kv("Starts", cycle.get("startsAt", "")[:10])
+        out.kv("Ends", cycle.get("endsAt", "")[:10])
+    else:
+        out.header("Current Cycle")
+        out.info("No active cycle")
+
+    # Active projects
+    if projects:
+        out.header(f"Active Projects ({len(projects)})")
+        rows = [
+            [
+                proj.get("name", ""),
+                f"{(proj.get('progress', 0) or 0) * 100:.0f}%",
+                (proj.get("targetDate") or "")[:10],
+            ]
+            for proj in projects
+        ]
+        out.table("", [("Name", "cyan"), ("Progress", "green"), ("Target", "yellow")], rows)

kctl_linear/commands/doctor_cmd.py

@@ -0,0 +1,58 @@
+"""Doctor diagnostic checks for kctl-linear."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import typer
+
+from kctl_lib.doctor_base import CheckResult, DoctorCheck, run_doctor
+
+from kctl_linear.core.callbacks import AppContext
+
+
+@dataclass
+class ConfigCheck:
+    """Check that configuration is present."""
+
+    name: str = "Configuration"
+    profile: str | None = None
+
+    def run(self) -> CheckResult:
+        try:
+            from kctl_linear.core.config import get_service_config, resolve_active_profile_name
+
+            profile = resolve_active_profile_name(self.profile)
+            cfg = get_service_config(profile)
+            if not cfg.api_key:
+                return CheckResult(
+                    name=self.name,
+                    status="fail",
+                    message="No API key configured",
+                    fix_command="kctl-linear config init",
+                )
+            return CheckResult(name=self.name, status="ok", message=f"Profile: {profile}")
+        except Exception as e:
+            return CheckResult(
+                name=self.name,
+                status="fail",
+                message=str(e),
+                fix_command="kctl-linear config init",
+            )
+
+
+app = typer.Typer(help="Run diagnostic checks.", invoke_without_command=True)
+
+
+@app.callback(invoke_without_command=True)
+def doctor(ctx: typer.Context) -> None:
+    """Run all diagnostic checks."""
+    if ctx.invoked_subcommand is not None:
+        return
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    checks: list[DoctorCheck] = [ConfigCheck(profile=actx.profile)]
+    all_passed = run_doctor(checks, out)  # type: ignore[arg-type]
+    if not all_passed:
+        raise typer.Exit(code=1)