Dokumen ini menjelaskan kenapa OpsTerm dirancang seperti ini — alasan di balik setiap keputusan teknis, termasuk trade-off yang diambil.
| # | Keputusan | Pilihan | Alternatif yang Ditolak |
|---|---|---|---|
| 1 | Bahasa | Python 3 | Go, Rust, Node.js, Bash |
| 2 | Arsitektur | Single file CLI | Modular package, Client-server |
| 3 | Dependencies | Zero (stdlib only) | PyYAML, requests, click |
| 4 | Config format | YAML (custom parser) | JSON, TOML, INI |
| 5 | AI Protocol | OpenAI-compatible API | LangChain, custom gRPC |
| 6 | SSH Method | Subprocess + system ssh | paramiko, asyncssh |
| 7 | State | File-based (no daemon) | SQLite daemon, Redis |
| 8 | Vault | Optional cryptography | Hardcoded key, no encryption |
| 9 | Completion | Generated script | Manual completion |
| 10 | Shell Integration | Zsh plugin | Hook shell, LD_PRELOAD |
OpsTerm butuh bahasa yang portable, zero-dep, dan gampang di-maintain.
Alasan:
Ada di mana-mana — Semua Linux & macOS punya Python 3. User tinggal download script, langsung jalan. Kalo Go/Rust, harus compile dulu atau download binary.
Stdlib kaya — argparse, json, sqlite3, urllib, hashlib, subprocess — semua built-in. Di Go/Rust, library-library ini butuh import eksternal atau stdlib yang kurang lengkap.
Maintainability — Python lebih gampang dibaca & dimodifikasi. Kontributor potensial lebih gampang ngerti kode.
File size — Script Python ~50KB vs Go binary ~10MB. Kecil, gampang di-copy ke server mana pun.
Rapid iteration — Fitur baru bisa langsung dipake tanpa compile. Edit → save → run.
Trade-off:
- Performance lebih rendah (tapi untuk CLI tool, ini gak kerasa)
- Butuh Python interpreter (tapi udah ada di semua system modern)
OpsTerm bisa aja dibikin sebagai Python package dengan pip install.
bin/ai)Alasan:
Portable — Copy 1 file ke server mana pun, langsung jalan. scp bin/ai server:~/.local/bin/
Zero setup — Ga perlu pip install, ga perlu python -m opsterm. Langsung ./ai.
Transparent — Isinya bisa dibaca & dipahami. Gak ada __pycache__, egg-info, dll.
Easy debugging — Kalo error, tinggal edit baris tertentu, gak perlu cari file di folder.
Trade-off:
- File besar (~1500 baris). Tapi masih kecil dibanding app lain.
- Semua fungsi dalam 1 file — susah di-test secara unit.
- Solusi: kode diorganisir dengan section headers (comments).
Banyak Python CLI tool pake PyYAML, requests, click, dll.
Alasan:
No install step — Clone repo → langsung jalan. Gak perlu pip install -r requirements.txt.
No version conflicts — Gak bakal bentrok sama library system atau project lain.
Works in any Python env — Virtual env, system Python, container, semuanya jalan.
Easy to audit — Semua kode yang jalan bisa dibaca. Gak ada hidden dependency.
Yang dikorbankan:
- YAML parser manual (~80 baris) — gak support full YAML spec, tapi cukup buat kebutuhan.
- HTTP client stdlib (urllib) — lebih verbose daripada requests, tapi fungsional.
- CLI parser stdlib (argparse) — kurang powerful daripada click, tapi cukup.
Config format buat server, workflow, dan AI settings.
Alasan:
Readability — YAML lebih enak dibaca manusia dibanding JSON. Comment, indentasi bersih.
User-friendly — Target user OpsTerm adalah DevOps engineer yang biasa pake YAML (Docker Compose, Kubernetes, Ansible, GitHub Actions).
No brackets — JSON penuh {} dan [] yang ganggu readability buat config panjang.
Trade-off:
- Custom parser → terbatas. Tapi subset YAML yang kita pake (mapping, list, scalar) stabil dan cukup.
- Inkonisten dengan "zero dep" — technically YAML parsing itu custom code, bukan dependency eksternal.
Bisa pake LangChain, LiteLLM, atau library abstraksi AI lainnya.
Alasan:
Zero dependency — Cuma urllib (stdlib). LangChain butuh 20+ dependencies.
Provider agnostic — Format OpenAI request/response udah jadi standar de-facto. DeepSeek, Ollama, vLLM, OpenRouter — semua support.
Simple — Chat Completion API cuma 1 endpoint, format sederhana.
Debug friendly — Request/response bisa di-log, di-inspect, di-test pake curl.
Trade-off:
- Gak ada retry logic, streaming, atau tool calling.
- Tapi untuk CLI tool yang blocking, ini gak masalah.
Bisa pake paramiko (SSH client library Python).
subprocess + /usr/bin/ssh)Alasan:
Feature parity — System SSH punya semua fitur: key management, ProxyJump, agent forwarding, compression, dll.
Zero dependency — paramiko butuh bcrypt, cryptography, pynacl, dll.
Familiar — Semua konfigurasi SSH (known_hosts, config, agent) jalan otomatis.
Interactive support — os.execvp() bisa ngasih SSH session interaktif penuh. paramiko gak bisa seamless.
Already configured — User pasti udah setup SSH key di system-nya.
Trade-off:
- Gak bisa parse SSH output secara real-time.
- Error handling terbatas (cuma exit code).
Beberapa tool pake background daemon yang nyimpen state di memory.
Alasan:
Zero resource — Gak ada background process. Gak consume RAM/CPU kalo gak dipake.
Crash-proof — Kalo terminal kill, data gak ilang. Semua di file.
Transparent — User bisa buka config langsung, edit pake editor teks.
Simple — Gak perlu manage process lifecycle, signal handling, lock files.
Trade-off:
- State dibaca dari disk setiap kali command → overhead dikit (<10ms).
- Gak bisa ada "real-time" notification.
Vault butuh cryptography yang gak ada di stdlib.
cryptography recommended, fallback tersediaAlasan:
Zero dep tetap berlaku — Fitur dasar OpsTerm jalan tanpa vault.
Security tetap prioritas — Vault pake AES via cryptography. Fallback XOR + HMAC kalo gak ada.
Progressive enhancement — User bisa mulai tanpa vault, install cryptography kalo butuh.
Completion bisa ditulis manual atau di-generate.
Alasan:
Always up-to-date — Kalo ada subcommand baru, completion otomatis update karena di-generate dari kode.
Zero additional file — ai completion bash langsung print ke stdout. Gak perlu file terpisah.
Works out of box — source <(ai completion bash) — 1 command, langsung jadi.
Shell integration bisa jadi bagian dari main script atau file terpisah.
zsh/opsterm.plugin.zsh)Alasan:
Bahasa berbeda — Zsh plugin pake Zsh script, bukan Python. Gabungin di file Python bakal campur aduk.
Zsh-only — Fitur shell hooks (preexec, precmd) cuma ada di Zsh.
Lazy loading — Plugin cuma di-load kalo user source di .zshrc. Gak nambah weight.
Familiar pattern — Zsh plugin format udah standar (oh-my-zsh, antigen, zplug).
Berdasarkan design decisions di atas, beberapa saran:
Python → Rust (masa depan) — Kalo performa & distribution jadi masalah, rewrite ke Rust buat single binary.
YAML → TOML — Kalo butuh config yang lebih strict (type safety), TOML lebih cocok. Tapi butuh library eksternal.
Add plugin system — Biar komunitas bisa nambah fitur tanpa edit core script.
Support Fish shell — Populer di kalangan developer modern.