kctl-mm 0.2.0__py3-none-any.whl

kctl_mm/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

kctl_mm/__main__.py

@@ -0,0 +1,4 @@
+from kctl_mm.cli import _run
+
+if __name__ == "__main__":
+    _run()

kctl_mm/cli.py

@@ -0,0 +1,119 @@
+"""kctl-mm main CLI entry point."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from kctl_lib import handle_cli_error
+from kctl_lib.exceptions import KctlError
+
+from kctl_mm import __version__
+from kctl_mm.core.callbacks import AppContext
+from kctl_lib.self_update import notify_if_outdated
+
+app = typer.Typer(
+    name="kctl-mm",
+    help="Kodemeio Mattermost CLI - manage Mattermost Team Edition.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    pretty_exceptions_enable=False,
+)
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"kctl-mm {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: Annotated[bool, typer.Option("--json")] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", "-q")] = False,
+    output_format: Annotated[str, typer.Option("--format", "-f")] = "pretty",
+    no_header: Annotated[bool, typer.Option("--no-header")] = False,
+    profile: Annotated[str | None, typer.Option("--profile", "-p")] = None,
+    version: Annotated[bool | None, typer.Option("--version", "-V", callback=version_callback, is_eager=True)] = None,
+) -> None:
+    ctx.obj = AppContext(
+        json_mode=json_output,
+        quiet=quiet,
+        profile=profile,
+        format="json" if json_output else output_format,
+        no_header=no_header,
+    )
+    notify_if_outdated(ctx.obj.output, "kctl-mm", __version__)
+
+
+def _register() -> None:
+    from kctl_mm.commands import (
+        audit,
+        bots,
+        channels,
+        completions,
+        config_cmd,
+        dashboard,
+        deploy,
+        doctor,
+        health,
+        import_export,
+        integrations,
+        jobs,
+        logs,
+        maintenance,
+        mm_config,
+        permissions,
+        plugins,
+        posts,
+        self_update,
+        skill_cmd,
+        status,
+        teams,
+        users,
+        webhooks,
+    )
+
+    mapping = [
+        ("config", config_cmd),
+        ("doctor", doctor),
+        ("self-update", self_update),
+        ("completions", completions),
+        ("skill", skill_cmd),
+        ("status", status),
+        ("logs", logs),
+        ("deploy", deploy),
+        ("health", health),
+        ("dashboard", dashboard),
+        ("users", users),
+        ("teams", teams),
+        ("channels", channels),
+        ("permissions", permissions),
+        ("posts", posts),
+        ("mm-config", mm_config),
+        ("maintenance", maintenance),
+        ("webhooks", webhooks),
+        ("bots", bots),
+        ("plugins", plugins),
+        ("integrations", integrations),
+        ("jobs", jobs),
+        ("audit", audit),
+        ("import-export", import_export),
+    ]
+    for name, module in mapping:
+        app.add_typer(module.app, name=name)
+
+
+_register()
+
+
+def _run() -> None:
+    try:
+        app()
+    except KctlError as exc:
+        handle_cli_error(exc)
+
+
+if __name__ == "__main__":
+    _run()

kctl_mm/commands/audit.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import typer
+
+from kctl_mm.core.callbacks import AppContext
+
+app = typer.Typer(help="Audit & compliance reports.", no_args_is_help=True)
+
+
+def _c(ctx: typer.Context) -> AppContext:
+    return ctx.ensure_object(AppContext)
+
+
+@app.command("login")
+def login_cmd(ctx: typer.Context, username: str) -> None:
+    c = _c(ctx)
+    user = c.client.get_user_by_username(username)
+    user_id = user["id"] if isinstance(user, dict) else user
+    c.output.raw_json(c.client.list_user_audits(user_id))
+
+
+@app.command("security")
+def security_cmd(ctx: typer.Context) -> None:
+    c = _c(ctx)
+    c.output.raw_json(c.client.list_compliance_reports())
+
+
+@app.command("compliance")
+def compliance_cmd(
+    ctx: typer.Context,
+    report_id: str,
+    out: str = typer.Option(..., "--out", help="Local path to save report."),
+) -> None:
+    c = _c(ctx)
+    path = c.client.download_compliance_report(report_id, out)
+    typer.echo(path)

kctl_mm/commands/bots.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import typer
+
+from kctl_mm.core.callbacks import AppContext
+
+app = typer.Typer(help="Bot management.", no_args_is_help=True)
+
+
+def _c(ctx: typer.Context) -> AppContext:
+    return ctx.ensure_object(AppContext)
+
+
+@app.command("list")
+def list_cmd(ctx: typer.Context) -> None:
+    c = _c(ctx)
+    bots = c.client.list_bots()
+    rows = [[b.get("user_id", ""), b.get("username", ""), b.get("display_name", "")] for b in bots]
+    c.output.table(
+        "Bots",
+        [("ID", "dim"), ("Username", "cyan"), ("Display", "green")],
+        rows,
+        data_for_json=bots,
+    )
+
+
+@app.command("create")
+def create_cmd(ctx: typer.Context, username: str, display: str) -> None:
+    c = _c(ctx)
+    c.output.raw_json(c.client.create_bot(username, display))
+
+
+@app.command("enable")
+def enable_cmd(ctx: typer.Context, bot_id: str) -> None:
+    c = _c(ctx)
+    c.output.raw_json(c.client.enable_bot(bot_id))
+
+
+@app.command("disable")
+def disable_cmd(ctx: typer.Context, bot_id: str) -> None:
+    c = _c(ctx)
+    c.output.raw_json(c.client.disable_bot(bot_id))
+
+
+@app.command("delete")
+def delete_cmd(ctx: typer.Context, bot_id: str) -> None:
+    c = _c(ctx)
+    c.output.raw_json(c.client.delete_bot(bot_id))

kctl_mm/commands/channels.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from kctl_mm.core.callbacks import AppContext
+
+app = typer.Typer(help="Channel management.", no_args_is_help=True)
+
+
+def _c(ctx: typer.Context) -> AppContext:
+    return ctx.ensure_object(AppContext)
+
+
+@app.command("list")
+def list_cmd(ctx: typer.Context, team_name: str) -> None:
+    c = _c(ctx)
+    team = c.client.get_team_by_name(team_name)
+    channels = c.client.list_channels_for_team(team["id"])
+    rows = [[ch.get("id", ""), ch.get("name", ""), ch.get("display_name", ""), ch.get("type", "")] for ch in channels]
+    c.output.table(
+        "Channels",
+        [("ID", "dim"), ("Name", "cyan"), ("Display", "green"), ("Type", "yellow")],
+        rows,
+        data_for_json=channels,
+    )
+
+
+@app.command("get")
+def get_cmd(ctx: typer.Context, team_name: str, channel_name: str) -> None:
+    c = _c(ctx)
+    team = c.client.get_team_by_name(team_name)
+    c.output.raw_json(c.client.get_channel_by_name(team["id"], channel_name))
+
+
+@app.command("create")
+def create_cmd(
+    ctx: typer.Context,
+    team_name: str,
+    channel_name: str,
+    display: str,
+    private: bool = typer.Option(False, "--private"),
+) -> None:
+    c = _c(ctx)
+    team = c.client.get_team_by_name(team_name)
+    c.output.raw_json(c.client.create_channel(team["id"], channel_name, display, private=private))
+
+
+@app.command("archive")
+def archive_cmd(ctx: typer.Context, team_name: str, channel_name: str) -> None:
+    r = _c(ctx).mm_exec.mmctl(["channel", "archive", f"{team_name}:{channel_name}"])
+    typer.echo(r.stdout)
+
+
+@app.command("members")
+def members_cmd(ctx: typer.Context, team_name: str, channel_name: str) -> None:
+    c = _c(ctx)
+    team = c.client.get_team_by_name(team_name)
+    channel = c.client.get_channel_by_name(team["id"], channel_name)
+    c.output.raw_json(c.client.list_channel_members(channel["id"]))
+
+
+@app.command("add")
+def add_cmd(ctx: typer.Context, team_name: str, channel_name: str, user: str) -> None:
+    r = _c(ctx).mm_exec.mmctl(["channel", "users", "add", f"{team_name}:{channel_name}", user])
+    typer.echo(r.stdout)
+
+
+@app.command("remove")
+def remove_cmd(ctx: typer.Context, team_name: str, channel_name: str, user: str) -> None:
+    r = _c(ctx).mm_exec.mmctl(["channel", "users", "remove", f"{team_name}:{channel_name}", user])
+    typer.echo(r.stdout)
+
+
+@app.command("rename")
+def rename_cmd(ctx: typer.Context, team_name: str, channel_name: str, new_display: str) -> None:
+    c = _c(ctx)
+    team = c.client.get_team_by_name(team_name)
+    channel = c.client.get_channel_by_name(team["id"], channel_name)
+    c.output.raw_json(c.client.rename_channel(channel["id"], new_display))
+
+
+@app.command("patch")
+def patch_cmd(
+    ctx: typer.Context,
+    team_name: str,
+    channel_name: str,
+    display_name: Annotated[str | None, typer.Option("--display-name")] = None,
+    header: Annotated[str | None, typer.Option("--header")] = None,
+    purpose: Annotated[str | None, typer.Option("--purpose")] = None,
+) -> None:
+    """Patch channel metadata (display name, header, purpose)."""
+    c = _c(ctx)
+    team = c.client.get_team_by_name(team_name)
+    channel = c.client.get_channel_by_name(team["id"], channel_name)
+    fields = {
+        k: v for k, v in {"display_name": display_name, "header": header, "purpose": purpose}.items() if v is not None
+    }
+    if not fields:
+        c.output.warn("No fields to patch.")
+        return
+    c.output.raw_json(c.client.patch_channel(channel["id"], **fields))
+
+
+@app.command("sync-pinned")
+def sync_pinned_cmd(
+    ctx: typer.Context,
+    team_name: Annotated[str, typer.Argument(help="Team slug (e.g. 'tpp').")],
+    channel_name: Annotated[str, typer.Argument(help="Channel name (e.g. 'onboarding').")],
+    source_dir: Annotated[Path, typer.Argument(help="Directory containing NN-*.md pinned-post sources.")],
+    display_name: Annotated[
+        str | None, typer.Option("--display-name", help="Create channel with this display name if missing.")
+    ] = None,
+    header: Annotated[str | None, typer.Option("--header", help="Channel header (applied on every run).")] = None,
+    purpose: Annotated[str | None, typer.Option("--purpose", help="Channel purpose (applied on every run).")] = None,
+    private: Annotated[
+        bool, typer.Option("--private", help="Create the channel as private if it doesn't exist yet.")
+    ] = False,
+    state_file: Annotated[
+        Path | None,
+        typer.Option("--state-file", help="Path to persist post-id mapping. Default: <source_dir>/.synced-ids.json."),
+    ] = None,
+) -> None:
+    """Idempotently sync a channel's pinned posts from a directory of markdown files.
+
+    Creates the channel if missing, patches header/purpose, then for each file
+    matching ``NN-*.md`` (sorted): creates a new pinned post or updates the
+    previously-synced one, based on a state file keyed by filename.
+
+    Re-runs are safe — existing posts are updated in place (Mattermost preserves
+    post id + pin status), new files produce new pinned posts, and deletions are
+    not handled automatically (unpin manually if you want to remove a topic).
+    """
+    c = _c(ctx)
+    if not source_dir.is_dir():
+        c.output.error(f"source-dir {source_dir} does not exist or is not a directory")
+        raise typer.Exit(2)
+    state_path = state_file or (source_dir / ".synced-ids.json")
+    state: dict[str, str] = {}
+    if state_path.exists():
+        try:
+            state = json.loads(state_path.read_text())
+        except Exception:
+            c.output.warn(f"state file {state_path} unreadable — starting fresh")
+
+    team = c.client.get_team_by_name(team_name)
+    # Ensure channel exists
+    channel = None
+    try:
+        channel = c.client.get_channel_by_name(team["id"], channel_name)
+        if not isinstance(channel, dict) or "id" not in channel or len(channel.get("id", "")) != 26:
+            channel = None
+    except Exception:
+        channel = None
+    if channel is None:
+        c.output.info(f"channel #{channel_name} not found — creating")
+        channel = c.client.create_channel(
+            team["id"],
+            channel_name,
+            display_name or channel_name,
+            private=private,
+        )
+    channel_id = channel["id"]
+
+    if header is not None or purpose is not None or display_name is not None:
+        fields = {
+            k: v
+            for k, v in {"display_name": display_name, "header": header, "purpose": purpose}.items()
+            if v is not None
+        }
+        c.client.patch_channel(channel_id, **fields)
+        c.output.info("  patched channel metadata")
+
+    files = sorted(p for p in source_dir.glob("[0-9][0-9]-*.md"))
+    if not files:
+        c.output.warn("no NN-*.md files found in source-dir")
+        return
+
+    created = updated = failed = 0
+    for f in files:
+        slug = f.stem
+        body = f.read_text().strip()
+        existing = state.get(slug)
+        if existing:
+            try:
+                c.client.update_post(existing, body)
+                updated += 1
+                c.output.info(f"  ↻ updated {slug}")
+                continue
+            except Exception as e:
+                c.output.warn(f"  update of {slug} failed ({e}) — will recreate")
+        try:
+            post = c.client.create_post(channel_id, body)
+            pid = post["id"]
+            c.client.pin_post(pid)
+            state[slug] = pid
+            created += 1
+            c.output.success(f"  ＋ created + pinned {slug} ({pid})")
+        except Exception as e:
+            failed += 1
+            c.output.error(f"  create of {slug} failed: {e}")
+
+    state_path.write_text(json.dumps(state, indent=2, sort_keys=True))
+    c.output.success(f"sync complete: created={created} updated={updated} failed={failed} · state={state_path}")

kctl_mm/commands/completions.py

@@ -0,0 +1,32 @@
+"""Shell completions command for kctl-mm."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+app = typer.Typer(help="Generate or install shell completions.", no_args_is_help=False, invoke_without_command=True)
+
+
+@app.callback(invoke_without_command=True)
+def completions(
+    ctx: typer.Context,
+    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."""
+    if ctx.invoked_subcommand is not None:
+        return
+    from kctl_lib.completions import get_completion_script, install_completions
+
+    if install:
+        path = install_completions("kctl-mm", 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-mm", shell)
+        typer.echo(script)