kctl-mm 0.2.0__tar.gz

kctl_mm-0.2.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local

kctl_mm-0.2.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: kctl-mm
+Version: 0.2.0
+Summary: Kodemeio Mattermost CLI — manage Mattermost Team Edition
+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_mm-0.2.0/README.md

@@ -0,0 +1,212 @@
+# kctl-mm
+
+Kodemeio CLI for managing Mattermost Team Edition instances. Part of the
+[kodemeio-platform](../../) monorepo.
+
+Manage users, teams, channels, posts, webhooks, bots, plugins, integrations,
+and server operations from the command line with profile-based multi-instance
+support.
+
+## Installation
+
+```bash
+# From workspace root (development)
+uv sync --all-extras --all-packages
+
+# Standalone install
+uv tool install ./packages/kctl-mm
+```
+
+## Quick Start
+
+```bash
+# 1. Configure a profile
+kctl-mm config init
+
+# 2. Check server health
+kctl-mm health
+
+# 3. List users
+kctl-mm users list
+
+# 4. List teams
+kctl-mm teams list
+
+# 5. List channels in a team
+kctl-mm channels list --team kodemeio
+```
+
+## Command Groups
+
+kctl-mm provides 24 command groups covering administration, messaging, server
+operations, and integrations for Mattermost Team Edition.
+
+### Admin & Config
+
+| Group | Description |
+|-------|-------------|
+| `config` | Profile management (init, add, use, show, validate, remove, set, profiles, current) |
+| `users` | User administration (list, get, create, deactivate, reactivate, update, reset-password) |
+| `teams` | Team administration (list, get, create, update, delete, add-member, remove-member) |
+| `channels` | Channel CRUD (list, get, create, update, delete, archive, add-member, remove-member) |
+| `permissions` | Role & permission management (list, get, assign, revoke) |
+| `mm-config` | Mattermost server config (show, get, set, patch, reload, diff) |
+
+### Messaging
+
+| Group | Description |
+|-------|-------------|
+| `posts` | Post management (create, get, update, delete, search, pin, unpin) |
+
+### Server Ops
+
+| Group | Description |
+|-------|-------------|
+| `status` | Server status and version info |
+| `logs` | Fetch and stream server logs |
+| `deploy` | Deploy / redeploy Mattermost stack |
+| `health` | Health checks (ping, DB, cluster, connectivity) |
+| `dashboard` | Overview dashboard with server stats |
+| `maintenance` | Server maintenance (recycle DB, reload config, clear cache) |
+| `jobs` | Background job management (list, get, cancel) |
+| `audit` | Audit log queries |
+| `import-export` | Bulk import / export (users, teams, channels, posts) |
+
+### Integrations
+
+| Group | Description |
+|-------|-------------|
+| `webhooks` | Incoming & outgoing webhook management |
+| `bots` | Bot account management (list, create, update, disable, assign-owner) |
+| `plugins` | Plugin management (list, install, enable, disable, remove, upload) |
+| `integrations` | Slash commands & OAuth apps |
+
+### Tools
+
+| Group | Description |
+|-------|-------------|
+| `doctor` | Diagnostic checks (config, connectivity, auth, API version) |
+| `self-update` | Check for PyPI updates and upgrade via `uv tool` |
+| `completions` | Generate/install shell completions (zsh, bash, fish) |
+| `skill` | Auto-generate SKILL.md from Typer introspection (hidden) |
+
+## Global Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--json` | | Output as JSON (shortcut for `--format json`) |
+| `--quiet` | `-q` | Suppress info messages |
+| `--format` | `-f` | Output format: `pretty`, `json`, `csv`, `yaml` |
+| `--no-header` | | Omit headers in CSV output |
+| `--profile` | `-p` | Config profile name |
+| `--url` | | API URL override |
+| `--token` | | Personal access token override |
+| `--version` | `-V` | Show version and exit |
+
+## Configuration
+
+kctl-mm uses the shared Kodemeio config framework at
+`~/.config/kodemeio/config.yaml` with service key `mm`.
+
+### Profile Schema Example
+
+```yaml
+mm:
+  active_profile: production
+  profiles:
+    production:
+      url: https://mm.kodeme.io
+      token: ${MM_TOKEN}
+      team: kodemeio
+    staging:
+      url: https://stg-mm.kodeme.io
+      token: ${MM_STAGING_TOKEN}
+      team: kodemeio
+```
+
+### Profile Setup
+
+```bash
+# Interactive setup
+kctl-mm config init
+
+# Manual profile
+kctl-mm config add production \
+  --url https://mm.kodeme.io \
+  --token YOUR_PERSONAL_ACCESS_TOKEN
+
+# Switch profiles
+kctl-mm config use production
+kctl-mm config current
+kctl-mm config profiles
+```
+
+### Multi-Instance Support
+
+Each profile can target a different Mattermost instance. Use `--profile` to
+override the active profile for a single command:
+
+```bash
+kctl-mm --profile staging health
+kctl-mm --profile production users list --json
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `KCTL_MM_URL` | Mattermost server URL |
+| `KCTL_MM_TOKEN` | Personal access token |
+| `KCTL_MM_PROFILE` | Default profile name |
+
+Environment variables override config file values. CLI flags (`--url`,
+`--token`) take highest precedence.
+
+## Shell Completions
+
+```bash
+# Generate completion script
+kctl-mm completions zsh
+
+# Install completions (writes to shell config dir)
+kctl-mm completions zsh --install
+kctl-mm completions bash --install
+kctl-mm completions fish --install
+```
+
+## Development
+
+```bash
+# Run tests
+uv run pytest tests/ -v
+
+# Lint
+uv run ruff check src/
+
+# Type check
+uv run mypy src/
+
+# Build
+uv build
+```
+
+### Project Structure
+
+```
+packages/kctl-mm/
+├── src/kctl_mm/
+│   ├── cli.py              # Main Typer app + command registration (Task 4)
+│   ├── core/               # Shared core (callbacks, client, config)
+│   └── commands/           # 24 command group modules
+├── tests/                  # pytest unit tests
+└── pyproject.toml          # Package metadata
+```
+
+## References
+
+- Design spec: [`docs/superpowers/specs/2026-04-13-kctl-mm-design.md`](../../docs/superpowers/specs/2026-04-13-kctl-mm-design.md)
+- Skill directory: [`skills/mattermost-admin/`](../../skills/mattermost-admin/)
+
+## License
+
+Internal -- Kodemeio Pte Ltd.

kctl_mm-0.2.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-mm"
+version = "0.2.0"
+description = "Kodemeio Mattermost CLI — manage Mattermost Team Edition"
+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-mm = "kctl_mm.cli:_run"
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+
+[project.entry-points."kctl_mm.plugins"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kctl_mm"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

kctl_mm-0.2.0/skills/mattermost-admin/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: mattermost-admin
+description: >
+  Mattermost team chat administration via kctl-mm CLI (24 groups, ~108 commands).
+  MUST use for ANY kctl-mm operation.
+  Triggers on: "activate", "activity", "archive", "assign", "audit", "bots", "cancel", "channels", "check", "cleanup", "completions", "compliance", "components", "config", "create-incoming", "create-outgoing", "current", "dashboard", "deactivate", "delete-incoming", "delete-outgoing", "demote", "deploy", "disable", "doctor", "down", "enable", "export", "full", "generate", "health", "import", "import-export", "init", "install", "integrations", "invite", "jobs", "json", "kctl-mm", "ldap-sync", "ldap-test", "list-incoming", "list-outgoing", "login", "logs", "maintenance", "members", "metrics", "mm-config", "oauth-create", "oauth-delete", "oauth-list", "optimize", "permissions", "plugins", "posts", "profile", "profiles", "promote", "pull", "quick", "rebuild", "reload", "remove", "rename", "reset-caches", "reset-pwd", "restart", "search", "security", "self-update", "skill", "status", "summary", "teams", "test-email", "unpin", "users", "vacuum".
+  Auto-generated: 2026-04-13
+  registry_hash: 5f677ba37de8
+---
+
+# mattermost-admin — kctl-mm CLI Reference
+
+> Auto-generated from `kctl-mm` command registry. Do not edit manually.
+> To regenerate: `kctl-mm skill generate`
+> To add custom content: edit `SKILL.extra.md` in the same directory.
+
+## Overview
+
+**CLI:** `kctl-mm`
+**Command groups:** 24
+**Total commands:** ~108
+**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-mm audit`
+
+Audit & compliance reports.
+
+| Command | Description |
+|---------|-------------|
+| `audit compliance <report_id> <out>` |  |
+| `audit login <username>` |  |
+| `audit security` |  |
+
+### `kctl-mm bots`
+
+Bot management.
+
+| Command | Description |
+|---------|-------------|
+| `bots create <username> <display>` |  |
+| `bots delete <bot_id>` |  |
+| `bots disable <bot_id>` |  |
+| `bots enable <bot_id>` |  |
+| `bots list` |  |
+
+### `kctl-mm channels`
+
+Channel management.
+
+| Command | Description |
+|---------|-------------|
+| `channels add <team_name> <channel_name> <user>` |  |
+| `channels archive <team_name> <channel_name>` |  |
+| `channels create <team_name> <channel_name> <display> [--private]` |  |
+| `channels get <team_name> <channel_name>` |  |
+| `channels list <team_name>` |  |
+| `channels members <team_name> <channel_name>` |  |
+| `channels remove <team_name> <channel_name> <user>` |  |
+| `channels rename <team_name> <channel_name> <new_display>` |  |
+
+### `kctl-mm completions`
+
+Generate or install shell completions.
+
+### `kctl-mm config`
+
+Manage CLI configuration and Mattermost profiles.
+
+| Command | Description |
+|---------|-------------|
+| `config add <name> [--url] [--token] [--team] [--set_default]` | Add or update a profile's Mattermost connection. |
+| `config current` | Show the active profile and connection status. |
+| `config init [--url] [--token] [--team] [--name]` | Initialize CLI configuration (interactive if no flags given). |
+| `config profiles` | List all profiles with Mattermost connection status. |
+| `config remove <name> [--force] [--service_only]` | Remove a profile or just its Mattermost config. |
+| `config set <key> <value> [--profile_arg]` | Set a configuration value for the Mattermost service. |
+| `config show` | Show full configuration (secrets masked). |
+| `config use <name>` | Switch the default profile. |
+| `config validate` | Validate the active profile's Mattermost connection. |
+
+**Examples:**
+```bash
+kctl-mm config set url https://mm.new.io
+kctl-mm config set token new-token-value
+kctl-mm config set default_profile production
+```
+
+### `kctl-mm dashboard`
+
+Operational dashboard.
+
+| Command | Description |
+|---------|-------------|
+| `dashboard activity` |  |
+| `dashboard full` |  |
+| `dashboard json` |  |
+| `dashboard summary` |  |
+| `dashboard watch [--interval]` |  |
+
+### `kctl-mm deploy`
+
+Deploy lifecycle operations.
+
+| Command | Description |
+|---------|-------------|
+| `deploy down` |  |
+| `deploy pull` |  |
+| `deploy rebuild` |  |
+| `deploy restart` |  |
+| `deploy up` |  |
+
+### `kctl-mm doctor`
+
+Diagnose kctl-mm configuration and connectivity.
+
+### `kctl-mm health`
+
+Health checks.
+
+| Command | Description |
+|---------|-------------|
+| `health components` |  |
+| `health json` |  |
+| `health metrics` |  |
+| `health quick` |  |
+| `health status` |  |
+
+### `kctl-mm import-export`
+
+Bulk import/export (mmctl).
+
+| Command | Description |
+|---------|-------------|
+| `import-export export <team> [--out]` |  |
+| `import-export import <local_path>` |  |
+| `import-export jobs` |  |
+
+### `kctl-mm integrations`
+
+OAuth / LDAP / SAML integrations (mmctl).
+
+| Command | Description |
+|---------|-------------|
+| `integrations ldap-sync` |  |
+| `integrations ldap-test` |  |
+| `integrations oauth-create <name> <callback_url>` |  |
+| `integrations oauth-delete <oauth_id>` |  |
+| `integrations oauth-list` |  |
+
+### `kctl-mm jobs`
+
+Job management.
+
+| Command | Description |
+|---------|-------------|
+| `jobs cancel <job_id>` |  |
+| `jobs list [--job_type]` |  |
+| `jobs status <job_id>` |  |
+
+### `kctl-mm logs`
+
+Tail Mattermost service logs.
+
+### `kctl-mm maintenance`
+
+Server maintenance commands.
+
+| Command | Description |
+|---------|-------------|
+| `maintenance cleanup` |  |
+| `maintenance optimize` | Alias for cleanup — Mattermost has no separate optimize endpoint. |
+| `maintenance reset-caches` |  |
+| `maintenance vacuum` |  |
+
+### `kctl-mm mm-config`
+
+Mattermost server config (REST + mmctl).
+
+| Command | Description |
+|---------|-------------|
+| `mm-config export <local_path>` |  |
+| `mm-config get <key>` |  |
+| `mm-config reload` |  |
+| `mm-config set <key> <value>` |  |
+| `mm-config show` |  |
+| `mm-config test-email` |  |
+
+### `kctl-mm permissions`
+
+Permissions & role management (mmctl).
+
+| Command | Description |
+|---------|-------------|
+| `permissions add <role> <perm>` |  |
+| `permissions assign <role> <user>` |  |
+| `permissions get <role>` |  |
+| `permissions list` |  |
+| `permissions remove <role> <perm>` |  |
+
+### `kctl-mm plugins`
+
+Plugin management (mmctl).
+
+| Command | Description |
+|---------|-------------|
+| `plugins delete <plugin_id>` |  |
+| `plugins disable <plugin_id>` |  |
+| `plugins enable <plugin_id>` |  |
+| `plugins install <local_path>` |  |
+| `plugins list` |  |
+
+### `kctl-mm posts`
+
+Post management.
+
+| Command | Description |
+|---------|-------------|
+| `posts create <channel_id> <message>` |  |
+| `posts delete <post_id>` |  |
+| `posts get <post_id>` |  |
+| `posts pin <post_id>` |  |
+| `posts search <team_id> <terms>` |  |
+| `posts unpin <post_id>` |  |
+
+### `kctl-mm self-update`
+
+Check for updates and upgrade kctl-mm.
+
+### `kctl-mm skill`
+
+Claude Code skill management.
+
+| Command | Description |
+|---------|-------------|
+| `skill generate [--output] [--install] [--check]` | Auto-generate SKILL.md from CLI command registry. |
+
+**Examples:**
+```bash
+kctl-mm skill generate
+kctl-mm skill generate --install
+kctl-mm skill generate --check
+```
+
+### `kctl-mm status`
+
+Show Mattermost service status.
+
+### `kctl-mm teams`
+
+Team management.
+
+| Command | Description |
+|---------|-------------|
+| `teams add <team_name> <user>` |  |
+| `teams archive <team_name>` |  |
+| `teams create <name> <display>` |  |
+| `teams delete <team_name> [--confirm]` |  |
+| `teams get <team_name>` |  |
+| `teams list` |  |
+| `teams members <team_name>` |  |
+| `teams remove <team_name> <user>` |  |
+
+### `kctl-mm users`
+
+User management.
+
+| Command | Description |
+|---------|-------------|
+| `users activate <username>` |  |
+| `users create <email> <username> <password>` |  |
+| `users deactivate <username>` |  |
+| `users demote <username>` |  |
+| `users get <username>` |  |
+| `users invite <email> <team>` |  |
+| `users list [--page] [--per_page]` |  |
+| `users promote <username>` |  |
+| `users reset-pwd <username>` |  |
+| `users search <query>` |  |
+
+### `kctl-mm webhooks`
+
+Webhook management.
+
+| Command | Description |
+|---------|-------------|
+| `webhooks create-incoming <channel_id> <display>` |  |
+| `webhooks create-outgoing <team_id> <trigger>` |  |
+| `webhooks delete-incoming <hook_id>` |  |
+| `webhooks delete-outgoing <hook_id>` |  |
+| `webhooks list` |  |
+| `webhooks list-incoming` |  |
+| `webhooks list-outgoing` |  |
+
+## Configuration
+
+Shared config: `~/.config/kodemeio/config.yaml`
+
+```bash
+kctl-mm config init       # Interactive setup
+kctl-mm config show       # Show current config
+kctl-mm config profiles   # List profiles
+kctl-mm config current    # Show active profile
+kctl-mm config validate   # Verify config
+```

kctl_mm-0.2.0/src/kctl_mm/__init__.py

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

kctl_mm-0.2.0/src/kctl_mm/__main__.py

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