kctl-linear 0.2.0__tar.gz

kctl_linear-0.2.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.venv/
+.env

kctl_linear-0.2.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: kctl-linear
+Version: 0.2.0
+Summary: Kodemeio Linear CLI — project and sprint tracking
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: kctl-lib>=0.4.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.35.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'

kctl_linear-0.2.0/README.md

@@ -0,0 +1,68 @@
+# kctl-linear
+
+Linear project and sprint tracking CLI. Uses the Linear GraphQL API.
+
+## Installation
+
+```bash
+uv tool install kctl-linear
+# or editable install for development
+uv tool install --editable packages/kctl-linear
+```
+
+## Quick Start
+
+```bash
+# Configure
+kctl-linear config init
+kctl-linear config show
+
+# Common workflows
+kctl-linear dashboard                    # Overview: issues, cycles, projects
+kctl-linear issues list                  # List all issues
+kctl-linear issues search "bug login"    # Search issues by keyword
+kctl-linear issues create               # Create a new issue
+kctl-linear cycles current              # Active sprint details
+kctl-linear projects list               # List all projects
+```
+
+## Command Groups
+
+| Group       | Subcommands                          | Description                        |
+|-------------|--------------------------------------|------------------------------------|
+| `config`    | init, add, use, show, validate, ...  | Profile and API key management     |
+| `dashboard` | (root)                               | Summary view of issues and sprints |
+| `issues`    | list, show, create, update, comment, search | Issue lifecycle management  |
+| `cycles`    | list, show, current, stats           | Sprint / cycle tracking            |
+| `projects`  | list, show                           | Project listing and details        |
+| `teams`     | list, show                           | Team membership and info           |
+| `labels`    | list, create                         | Issue label management             |
+| `users`     | list, me                             | Workspace user listing             |
+| `health`    | check                                | API connectivity check             |
+
+## Configuration
+
+Config is stored in `~/.config/kodemeio/config.yaml` under the `linear` key.
+
+```bash
+kctl-linear config init          # Interactive setup (API key, workspace)
+kctl-linear config add myprofile # Add a named profile
+kctl-linear config use myprofile # Switch active profile
+kctl-linear config show          # Display current config (secrets masked)
+```
+
+Required fields: `api_key`, `team_id` (optional default team).
+
+## Global Options
+
+`--json`, `--format/-f` (pretty/json/csv/yaml), `--quiet/-q`, `--profile/-p`, `--no-header`, `--version/-V`
+
+## Development
+
+```bash
+cd packages/kctl-linear
+uv sync --all-extras
+uv run pytest tests/ -v
+uv run mypy src/
+uv run ruff check src/
+```

kctl_linear-0.2.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-linear"
+version = "0.2.0"
+description = "Kodemeio Linear CLI — project and sprint tracking"
+requires-python = ">=3.12"
+dependencies = [
+    "kctl-lib>=0.4.0",
+    "typer>=0.15.0",
+    "rich>=13.9.0",
+    "pydantic>=2.10.0",
+    "pyyaml>=6.0.2",
+    "httpx>=0.28.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.0",
+    "pytest-httpx>=0.35.0",
+    "ruff>=0.9.0",
+    "mypy>=1.14.0",
+    "types-PyYAML>=6.0.0",
+]
+
+[project.scripts]
+kctl-linear = "kctl_linear.cli:_run"
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+
+[project.entry-points."kctl_linear.plugins"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kctl_linear"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

kctl_linear-0.2.0/skills/linear-admin/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: linear-admin
+description: >
+  Linear project tracking administration via kctl-linear CLI (10 groups, ~31 commands).
+  MUST use for ANY kctl-linear operation.
+  Triggers on: "check", "comment", "config", "current", "cycles", "dashboard", "generate", "health", "init", "issues", "kctl-linear", "labels", "profile", "profiles", "projects", "remove", "search", "skill", "stats", "teams", "test", "users", "validate".
+  Auto-generated: 2026-04-05
+  registry_hash: 1da478e9bb45
+---
+
+# linear-admin — kctl-linear CLI Reference
+
+> Auto-generated from `kctl-linear` command registry. Do not edit manually.
+> To regenerate: `kctl-linear skill generate`
+> To add custom content: edit `SKILL.extra.md` in the same directory.
+
+## Overview
+
+**CLI:** `kctl-linear`
+**Command groups:** 10
+**Total commands:** ~31
+**Install:** `cd cli && uv tool install --editable .`
+
+## Global Options
+
+| Flag | Description |
+|------|-------------|
+| `--json` | JSON output |
+| `--quiet`, `-q` | Suppress info messages |
+| `--format`, `-f` | Output format: pretty/json/csv/yaml |
+| `--no-header` | Omit CSV header row |
+| `--profile`, `-p` | Config profile name |
+| `--version`, `-V` | Show version |
+
+## Command Reference
+
+### `kctl-linear config`
+
+Profile and configuration management.
+
+| Command | Description |
+|---------|-------------|
+| `config add <name>` | Add a new config profile. |
+| `config current` | Show active profile and resolved context. |
+| `config init` | Interactive config setup. |
+| `config profiles` | List all config profiles. |
+| `config remove <name>` | Remove a config profile. |
+| `config set <key> <value>` | Set a single config value. |
+| `config show` | Show current configuration. |
+| `config test` | Test API connection with current configuration. |
+| `config use <name>` | Switch active config profile. |
+| `config validate` | Validate current config completeness. |
+
+### `kctl-linear cycles`
+
+Cycle (sprint) management.
+
+| Command | Description |
+|---------|-------------|
+| `cycles current [--team]` | Show current active cycle with progress and issues. |
+| `cycles list [--team] [--limit]` | List past and upcoming cycles. |
+| `cycles show <cycle_id>` | Show cycle details: scope, completed, remaining issues. |
+| `cycles stats [--team]` | Show velocity trends across recent cycles. |
+
+### `kctl-linear dashboard`
+
+Quick overview dashboard.
+
+### `kctl-linear health`
+
+API health check.
+
+### `kctl-linear issues`
+
+Issue management.
+
+| Command | Description |
+|---------|-------------|
+| `issues comment <issue_id> <body>` | Add a comment to an issue. |
+| `issues create <title> [--team] [--description] [--priority] [--assignee]` | Create a new issue. |
+| `issues list [--team] [--state] [--assignee] [--limit]` | List issues with optional filters. |
+| `issues search <query> [--limit]` | Full-text search for issues. |
+| `issues show <issue_id>` | Show issue details, comments, and history. |
+| `issues update <issue_id> [--state] [--assignee] [--priority] [--title] [--description]` | Update an existing issue. |
+
+### `kctl-linear labels`
+
+Label management.
+
+| Command | Description |
+|---------|-------------|
+| `labels create <name> [--color] [--team]` | Create a new label. |
+| `labels list [--team]` | List all labels, optionally filtered by team. |
+
+### `kctl-linear projects`
+
+Project tracking.
+
+| Command | Description |
+|---------|-------------|
+| `projects list` | List active projects with progress. |
+| `projects show <project_id>` | Show project details, milestones, and member issues. |
+
+### `kctl-linear skill`
+
+Claude Code skill management.
+
+| Command | Description |
+|---------|-------------|
+| `skill generate [--output] [--install] [--check]` | Auto-generate SKILL.md from CLI command registry. |
+
+**Examples:**
+```bash
+kctl-linear skill generate
+kctl-linear skill generate --install
+kctl-linear skill generate --check
+```
+
+### `kctl-linear teams`
+
+Team information.
+
+| Command | Description |
+|---------|-------------|
+| `teams list` | List all teams with member counts. |
+| `teams show <team_id>` | Show team members, workflow states, and labels. |
+
+### `kctl-linear users`
+
+User information.
+
+| Command | Description |
+|---------|-------------|
+| `users list` | List all workspace members. |
+| `users me` | Show current authenticated user. |
+
+## Configuration
+
+Shared config: `~/.config/kodemeio/config.yaml`
+
+```bash
+kctl-linear config init       # Interactive setup
+kctl-linear config show       # Show current config
+kctl-linear config profiles   # List profiles
+kctl-linear config current    # Show active profile
+kctl-linear config validate   # Verify config
+```

kctl_linear-0.2.0/src/kctl_linear/__init__.py

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

kctl_linear-0.2.0/src/kctl_linear/__main__.py

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

kctl_linear-0.2.0/src/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-0.2.0/src/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