Şirket içi kullanım için CLI oluşturmak

• Geliştirme ekibinde, organizasyonun bilgisini toplamak ve korumak için yararlı yöntemlerden biri; kullanışlı snippet, script veya iş akışı koleksiyonunu büyütmektir
• Bu yüzden birçok repoda Makefile, bash scriptleri gibi şeyler oluşturulur
• Peki organizasyon genelinde yararlı araçların kurulumu, boilerplate kod üretimi veya kimsenin hatırlamadığı karmaşık AWS komutlarını çalıştırma gibi işleri nasıl yapmalı?
  • Slack veya Shopify gibi bazı şirketlerin kendi şirket içi CLI'ları vardır
  • Modern terminal Warp'ta iş akışlarını dokümante edip paylaşmayı sağlayan özellikler bulunur
• Organizasyon içi bir CLI'ı yapmak kolaydır. Örnek olarak acme adlı bir şirket için CLI oluşturuluyor

CLI tasarım gereksinimleri

• acme <command> ile her yerden komut çalıştırılabilen ortak bir giriş noktası olmalı
  • Tüm geliştiriciler, belirli bir repoya önce gitmek zorunda kalmadan her yerden acme <command> çalıştırarak komutu tetikleyebilmelidir
• Geliştiricilerin yeni komutlara kolayca katkı yapabilmesi sağlanmalı
• acme update ile yeni sürüm kolayca dağıtılabilmeli
• Çapraz platform desteği olmalı (ör. acme download something çalıştırıldığında Linux'ta curl, Windows'ta Invoke-WebRequest kullanılmalı)
• acme list ile kullanılabilir komutların listesini ve kısa açıklamalarını görebilmek mümkün olmalı

just ile projeye başlamak

• just, make benzeri ama komut çalıştırmaya odaklanan bir araçtır
• Çapraz platform destekler ve platforma özgü komutları da çalıştırabilir
• Diğer seçenekler arasında Slack'in magic-cli aracı (Ruby biliyorsanız başlamak için harikadır) veya make vardır

Projeyi kurmak

• just kurun. Buradaki talimatları izleyin
• ~/acme/cli klasörünü oluşturun ve köke şu justfile dosyasını ekleyin:

default:  
  just --list  
  
# arch ve os adını göster  
os-info:  
  echo "Arch: {{arch()}}"  
  echo "OS: {{os()}}"  

• just dokümantasyonunda komutlara "recipes" denir
• Recipe belirtmeden just çalıştırıldığında, justfile içindeki ilk recipe çalışır. Genelde ilk recipe adını default koymak yaygın bir desendir

$ just  
just --list  
Available recipes:  
    default  
    os-info # Show arch and os name  

• default recipe'si just list çalıştırır. Tüm recipe listesini ve yorumları gösterir
• default recipe'sini gizlemek iyi olur
• Bir recipe çalıştırıldığında, her komut yürütülmeden önce ekrana yazdırılır. Bu çıktıyı @ önekiyle kaldırabilirsiniz. Makefile'a benzer

[private]  
@default:  
  just --list  
  
# arch ve os adını göster  
@os-info:  
  echo "Arch: {{arch()}}"  
  echo "OS: {{os()}}"  

acme alias'ını oluşturmak

• acme <command> biçiminde çalıştırmak için .bashrc içine alias ekleyin

  alias acme='just --justfile ~/acme/cli/justfile'  
  

• Yeni alias'ı yüklemek için source ~/.bashrc veya exec bash çalıştırın

Yeni recipe yazmak

Basit bir recipe

• AWS IAM kullanıcı/rol bilgisini getirmek

  @aws-id:  
    aws sts get-caller-identity  
  

  • Kimsenin hatırlamadığı komutları basitleştirmek, muhtemelen şirket içi CLI'ın ana kullanım senaryosudur
  • awscli'nin çapraz platform olduğunu varsaydığımız için bu recipe, nereden çağrılırsa çağrılsın çalışır

Platforma özgü recipe'ler

• systemd gibi araçlar içeren snippet'ler, yalnızca geliştirici Linux makinesi kullanıyorsa gösterilsin
• [linux] niteliğini kullanarak recipe'nin sadece Linux'ta görünmesini sağlayın

[linux]  
@list-systemd-services:  
  systemctl list-units --type=service  

Çapraz platform recipe'leri

• Klasör boyutunu bulmayı Windows ve Linux için ayrı ayrı uygulamak

  [windows]  
  [no-cd]  
  get-folder-size path:  
    (Get-ChildItem "{{path}}" -Recurse -Force | Measure-Object -Property Length -Sum).Sum / 1MB  
  
  [linux]  
  [no-cd]  
  get-folder-size path:  
    du -sh {{path}}  
  

Script recipe'leri

• Recipe içine tam bir script gömebilirsiniz
• Shebang(#!) ile başlayan recipe'ler ayrı dosya olarak kaydedilip çalıştırılır
• İş akışında if-else, döngüler, değişken saklama ve işleme gibi biraz daha karmaşık mantık gerektiğinde kullanışlıdır

# Say hello world in sh  
hello-world-sh:  
  #!/usr/bin/env sh  
  hello='Yo'  
  echo "$hello from a shell script!"  

• Bu, güçlü script yetenekleri olan programlama dillerinden yararlanabileceğiniz anlamına gelir. Bazı işler Bash yerine Python'da daha kolay yapılabilir

# scale jpg image by 50%  
[no-cd]  
scale-jpg path:  
  #!/usr/bin/env python3  
  
  import PIL.Image  
  image = PIL.Image.open("{{path}}")  
  factor = 0.5  
  image = image.resize((round(image.width * factor), round(image.height * factor)))  
  image.save("{{path}}.s50.jpg")  

• Tüm geliştiricilerin bilgisayarında Python kurulu olmayabilir; kurulu olsa bile pillow yüklü olmayabilir. nix kullanarak bağımlılıkları dahil script çalıştırabilirsiniz:

# scale jpg image by 50%  
[no-cd]  
scale-jpg path:  
  #! /usr/bin/env nix-shell  
  #! nix-shell -i python3 -p python3Packages.pillow  
  
  import PIL.Image  
  ...  

Recipe'leri dağıtmak

• Kendi dağıtım mekanizmanızı sıfırdan kurmak yerine git kullanın
• GitHub'da bir repo oluşturun ve şu ana kadar yaptıklarınızı push edin

$ git init  
$ git commit -m "first commit"  
$ git branch -M main  
$ git remote add origin [e-mail]:acme/cli.git  
$ git push -u origin main  

• Artık bu repoya erişimi olan herkes PR açarak değişiklik katkısı yapabilir
• acme update recipe'si ile git pull işlemini otomatikleştirin

# Update the Acme CLI  
@update:  
  git fetch  
  git checkout main  

Dokümantasyon

• Şirket içi araçların başarısında benimsenme çok önemlidir; yeni kullanıcıların aracı kurup keşfedebilmesi için iyi bir kullanım kılavuzu şarttır
• README içinde kurulum ve kullanım talimatlarını verin

# Acme CLI  
  
## Prerequisites  
  
`just`: Install just [here](https://github.com/casey/just/blob/master/README.md#installation)  
  
## Installation  
  
Clone this repo:  
...  
  
Set up the `acme` alias:  
...  
  
## Usage  
  
List all available recipes:  
...  

• Artık tüm Acme Corp geliştiricileri bunu kullanabilir!
• Şirket içi Slack'e mesaj gönderip herkesi denemeye teşvik edebilir, herkesin kendi snippet'lerini eklemesini sağlayabilirsiniz

Ek özellikler

• Completion, TAB tuşuna basıldığında alt komutları, dosya yollarını, seçenekleri vb. otomatik tamamlayan mekanizmadır
• Çoğu shell bu özelliği sunar ve çoğu büyük CLI aracı completion kurmanın bir yolunu sağlar
  • Python'un Click'i, Golang'ın Cobra'sı, Rust'ın clap'i gibi çoğu büyük CLI framework'ü completion'ı otomatik olarak üretebilir
• Just, just --completion <shell> çalıştırılarak completion üretebilir

[bus710]

Uzun zamandır şirket içi DX tasarımının platform mühendisliği için önemli bir konu olduğu görülüyor.