kctl-zulip 0.9.4__tar.gz

kctl_zulip-0.9.4/.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_zulip-0.9.4/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: kctl-zulip
+Version: 0.9.4
+Summary: Kodemeio Zulip CLI — manage Zulip team chat
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: kctl-lib>=0.12.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_zulip-0.9.4/README.md

@@ -0,0 +1,209 @@
+# kctl-zulip
+
+Kodemeio CLI for managing Zulip team chat instances. Part of the
+[kodemeio-platform](../../) monorepo (22nd CLI tool).
+
+Manage streams, users, messages, emoji, presence, invitations, and more
+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-zulip
+```
+
+## Quick Start
+
+```bash
+# 1. Configure a profile
+kctl-zulip config init
+
+# 2. Check server health
+kctl-zulip health
+
+# 3. List users
+kctl-zulip users list
+
+# 4. List streams
+kctl-zulip streams list
+
+# 5. Send a message
+kctl-zulip messages send --stream general --topic "Hello" --content "Hi from kctl-zulip!"
+```
+
+## Command Groups
+
+kctl-zulip provides 22 command groups organized into five panels.
+
+### 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) |
+| `groups` | User group management (list, get, create, delete, add-members, remove-members) |
+| `realm` | Realm/organization settings (get, update, get-emoji, upload-emoji) |
+| `invitations` | Invite management (list, send, resend, revoke) |
+
+### Messaging
+
+| Group | Description |
+|-------|-------------|
+| `messages` | Send, fetch, search, edit, delete, and flag messages |
+| `streams` | Stream CRUD, subscribe, unsubscribe, archive |
+| `topics` | Topic listing, resolution, and deletion |
+| `announce` | Broadcast announcements to streams |
+| `drafts` | Draft message management (list, create, edit, delete) |
+| `scheduled` | Scheduled message management (list, create, delete) |
+
+### Personalization
+
+| Group | Description |
+|-------|-------------|
+| `emoji` | Custom emoji management (list, upload, delete) |
+| `reactions` | Message reaction management (add, remove, get) |
+| `presence` | User presence/status (get, set, list) |
+| `muted` | Muted users and topics (list, add, remove) |
+| `alert-words` | Alert word management (list, add, remove) |
+| `profile-fields` | Custom profile field management (list, create, update, delete, reorder) |
+| `linkifiers` | Linkifier/regex pattern management (list, create, update, delete) |
+
+### Monitoring
+
+| Group | Description |
+|-------|-------------|
+| `health` | Server health checks and connectivity verification |
+| `dashboard` | Overview dashboard with server stats |
+
+### 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 |
+| `--email` | | Auth email override |
+| `--api-key` | | API key override |
+| `--version` | `-V` | Show version and exit |
+
+## Configuration
+
+kctl-zulip uses the shared Kodemeio config framework at
+`~/.config/kodemeio/config.yaml` with service key `zulip`.
+
+### Profile Setup
+
+```bash
+# Interactive setup
+kctl-zulip config init
+
+# Manual profile
+kctl-zulip config add production \
+  --url https://zulip.kodeme.io \
+  --email bot@kodeme.io \
+  --api-key YOUR_API_KEY
+
+# Switch profiles
+kctl-zulip config use production
+kctl-zulip config current
+kctl-zulip config profiles
+```
+
+### Multi-Instance Support
+
+Each profile can target a different Zulip instance. Use `--profile` to
+override the active profile for a single command:
+
+```bash
+kctl-zulip --profile staging health
+kctl-zulip --profile production users list --json
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `KCTL_ZULIP_URL` | Zulip server URL |
+| `KCTL_ZULIP_EMAIL` | Bot email address |
+| `KCTL_ZULIP_API_KEY` | Bot API key |
+| `KCTL_ZULIP_PROFILE` | Default profile name |
+
+Environment variables override config file values. CLI flags (`--url`,
+`--email`, `--api-key`) take highest precedence.
+
+## Shell Completions
+
+```bash
+# Generate completion script
+kctl-zulip completions zsh
+
+# Install completions (writes to shell config dir)
+kctl-zulip completions zsh --install
+kctl-zulip completions bash --install
+kctl-zulip completions fish --install
+```
+
+See [docs/completions.md](docs/completions.md) for detailed instructions.
+
+## E2E Testing (Playwright)
+
+The `e2e/` directory contains Playwright-based API tests for verifying
+connectivity against a live Zulip instance.
+
+```bash
+cd packages/kctl-zulip/e2e
+pnpm install
+ZULIP_URL=https://zulip.kodeme.io npx playwright test
+npx playwright show-report
+```
+
+## 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-zulip/
+├── src/kctl_zulip/
+│   ├── cli.py              # Main Typer app + command registration
+│   ├── core/               # Shared core (callbacks, client, config)
+│   └── commands/           # 22 command group modules
+├── tests/                  # pytest unit tests (58 tests)
+├── e2e/                    # Playwright E2E tests
+├── docs/                   # Additional documentation
+├── skills/                 # SKILL.md for Claude Code
+└── pyproject.toml          # Package metadata
+```
+
+## License
+
+Internal -- Kodemeio Pte Ltd.

kctl_zulip-0.9.4/docs/completions.md

@@ -0,0 +1,71 @@
+# Shell Completions for kctl-zulip
+
+kctl-zulip supports tab-completion for commands, options, and arguments
+in zsh, bash, and fish shells.
+
+## Quick Install
+
+```bash
+kctl-zulip completions zsh --install
+kctl-zulip completions bash --install
+kctl-zulip completions fish --install
+```
+
+After installing, restart your shell or source the relevant config file.
+
+## Manual Setup
+
+### Zsh
+
+Generate the completion script and place it in your fpath:
+
+```bash
+kctl-zulip completions zsh > ~/.zfunc/_kctl-zulip
+```
+
+Ensure `~/.zfunc` is in your fpath. Add to `~/.zshrc` if not already present:
+
+```bash
+fpath=(~/.zfunc $fpath)
+autoload -Uz compinit && compinit
+```
+
+### Bash
+
+Generate and source the completion script:
+
+```bash
+kctl-zulip completions bash > ~/.local/share/bash-completion/completions/kctl-zulip
+```
+
+Or source it directly in `~/.bashrc`:
+
+```bash
+eval "$(kctl-zulip completions bash)"
+```
+
+### Fish
+
+Generate and place the completion file:
+
+```bash
+kctl-zulip completions fish > ~/.config/fish/completions/kctl-zulip.fish
+```
+
+Fish picks up completions automatically from this directory.
+
+## Verifying
+
+After installation, open a new terminal and type:
+
+```bash
+kctl-zulip <TAB>
+```
+
+You should see a list of available commands (config, users, streams, messages, etc.).
+
+## Troubleshooting
+
+- **Zsh completions not working**: Run `compinit` or delete `~/.zcompdump` and restart.
+- **Bash completions not loading**: Ensure `bash-completion` is installed (`apt install bash-completion`).
+- **Fish completions stale**: Delete the generated file and regenerate.

kctl_zulip-0.9.4/e2e/fixtures/zulip-test.ts

@@ -0,0 +1,19 @@
+import { test as base, expect } from "@playwright/test";
+
+const ZULIP_URL = process.env.ZULIP_URL || "https://zulip.kodeme.io";
+const ZULIP_EMAIL = process.env.ZULIP_EMAIL || "";
+const ZULIP_API_KEY = process.env.ZULIP_API_KEY || "";
+
+export interface ZulipFixtures {
+  zulipURL: string;
+  zulipEmail: string;
+  zulipAPIKey: string;
+}
+
+export const test = base.extend<ZulipFixtures>({
+  zulipURL: ZULIP_URL,
+  zulipEmail: ZULIP_EMAIL,
+  zulipAPIKey: ZULIP_API_KEY,
+});
+
+export { expect };

kctl_zulip-0.9.4/e2e/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "kctl-zulip-e2e",
+  "private": true,
+  "scripts": {
+    "test": "npx playwright test",
+    "test:headed": "npx playwright test --headed",
+    "report": "npx playwright show-report"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.48.0",
+    "typescript": "^5.6.0"
+  }
+}

kctl_zulip-0.9.4/e2e/playwright.config.ts

@@ -0,0 +1,24 @@
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./tests",
+  fullyParallel: false,
+  workers: 1,
+  timeout: 60_000,
+  retries: 0,
+  reporter: [["html", { open: "never" }]],
+  use: {
+    baseURL: process.env.ZULIP_URL || "https://zulip.kodeme.io",
+    screenshot: "only-on-failure",
+    trace: "retain-on-failure",
+  },
+  projects: [
+    { name: "setup", testMatch: /global-setup\.ts/ },
+    {
+      name: "desktop",
+      dependencies: ["setup"],
+      use: { viewport: { width: 1280, height: 720 } },
+      testMatch: /scenarios\/.*\.spec\.ts/,
+    },
+  ],
+});

kctl_zulip-0.9.4/e2e/tests/global-setup.ts

@@ -0,0 +1,6 @@
+import { test } from "../fixtures/zulip-test";
+
+test("verify environment", async ({ zulipURL }) => {
+  test.skip(!zulipURL, "ZULIP_URL not set");
+  console.log(`Zulip URL: ${zulipURL}`);
+});

kctl_zulip-0.9.4/e2e/tests/scenarios/health.spec.ts

@@ -0,0 +1,17 @@
+import { test, expect } from "../../fixtures/zulip-test";
+
+test.describe("Zulip Health", () => {
+  test("server settings endpoint returns 200", async ({
+    request,
+    zulipURL,
+  }) => {
+    test.skip(!zulipURL, "ZULIP_URL not set");
+
+    const response = await request.get(`${zulipURL}/api/v1/server_settings`);
+    expect(response.status()).toBe(200);
+
+    const body = await response.json();
+    expect(body).toHaveProperty("zulip_version");
+    expect(body.result).toBe("success");
+  });
+});

kctl_zulip-0.9.4/e2e/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["**/*.ts"]
+}

kctl_zulip-0.9.4/pyproject.toml

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