Struktur Repositori

Dokumentasi lengkap struktur folder dan konvensi penamaan repositori dotfiles.

Layout Direktori

dotfiles/
├── README.md              # Entry point dokumentasi utama
├── CHANGELOG.md           # Riwayat perubahan dan versi
├── HANDOVER.md            # Panduan transfer kepemilikan
├── .gitignore             # Aturan Git ignore
├── Makefile               # Target automation
├── Brewfile               # Manifest paket Homebrew (declaratif)
│
├── docs/                  # Dokumentasi
│   ├── SPECIFICATION.md   # Spesifikasi lengkap mesin
│   ├── PERFORMA.md        # Hasil pengukuran performa
│   ├── PERMISSIONS.md     # Audit permission macOS
│   ├── APPLICATIONS.md    # Katalog aplikasi terinstall
│   ├── MACOS.md           # Preferensi sistem macOS (hasil pengukuran)
│   ├── ANIMASI.md         # Setelan animasi
│   ├── AMOLED.md          # Perubahan tema
│   ├── TOOLCHAIN.md       # Tool di luar Homebrew (uv, ty, writer CLI)
│   ├── INVENTORY.md       # Inventaris versi (auto-generated)
│   ├── SETUP.md           # Panduan setup lengkap
│   └── STRUCTURE.md       # File ini
│
├── config/                # File konfigurasi
│   ├── starship/          # Starship prompt
│   │   └── starship.toml
│   ├── kaku/              # Kaku terminal
│   │   └── kaku.lua
│   ├── opencode/          # OpenCode AI
│   │   └── AGENTS.md
│   ├── yazi/              # Yazi file manager
│   │   ├── yazi.toml
│   │   ├── keymap.toml
│   │   ├── theme.toml
│   │   └── flavors/
│   │       ├── kaku-dark.yazi
│   │       └── kaku-light.yazi
│   ├── zsh/               # Konfigurasi shell
│   │   └── .zshrc
│   └── git/               # Konfigurasi Git
│       └── .gitconfig
│
├── scripts/               # Script automation
│   ├── lib/
│   │   ├── symlinks.sh    # Manifest symlink (sumber kebenaran)
│   │   └── log.sh         # Pustaka warna dan fungsi log bersama
│   ├── bootstrap.sh       # Siapkan mesin kosong (CLT, brew, clone, paket)
│   ├── install.sh         # Symlink installer (dukung DRY_RUN=1)
│   ├── backup.sh          # Backup konfigurasi
│   ├── restore.sh         # Restore konfigurasi
│   ├── verify.sh          # Verifikasi instalasi
│   ├── audit.sh           # Audit sistem
│   ├── doctor.sh          # Health check read-only (paket, symlink, setelan)
│   ├── clean.sh           # Pembersih symlink
│   ├── inventory.sh       # Generate inventaris versi (--write)
│   ├── update.sh          # Update brew + refresh inventaris
│   ├── macos-settings.sh  # Setelan macOS (apply/status/revert/check)
│   ├── lint.sh            # Quality gate
│   ├── prose-check.py     # Deteksi teks kacau & kalimat campuran bahasa
│   └── hooks.sh           # Installer git hooks
│
├── tests/                 # Test bats (22 test, jalankan: make test)
│   ├── lib.bash           # Helper: potret filesystem, parser manifest
│   ├── install.bats
│   ├── lint.bats
│   └── symlinks.bats
│
└── agents/                # Resource AI agent
    └── AGENT.md           # Instruksi agent

Konvensi Penamaan

File

Direktori

Mapping Symlink

Sumber kebenaran pemetaan ini adalah scripts/lib/symlinks.sh. install.sh, verify.sh, clean.sh, dan inventory.sh semuanya membaca file yang sama, jadi daftar ini tidak bisa lagi tidak sinkron antar-script.

Symlink berikut dibuat oleh make install:

Sengaja TIDAK di-symlink

Keduanya ada di .gitignore. Untuk service.json, file aslinya tetap ada di ~/.config/opencode/service.json sebagai file biasa (bukan symlink) dengan permission 600.

Kepemilikan File Konfigurasi

Dikelola oleh Dotfiles

• config/starship/starship.toml — Fully managed
• config/kaku/kaku.lua — Bagian user overrides dikelola
• config/opencode/AGENTS.md — Instruksi global OpenCode
• config/yazi/*.toml — Fully managed
• config/yazi/flavors/ — Fully managed
• config/zsh/.zshrc — Fully managed
• config/git/.gitconfig — Fully managed, TANPA identitas user

Dikelola oleh Aplikasi

• ~/.config/kaku/state.json — Kaku app state
• ~/.config/kaku/last_session.json — Session restore
• ~/.config/kaku/ai_inline_capability — AI capability token
• ~/.config/kaku/zsh/kaku.zsh — Auto-generated shell integration
• ~/.config/kaku/session_content/ — Data session
• ~/.config/opencode/service.json — Kredensial runtime OpenCode (permission 600)

Dikelola User (Tidak di Dotfiles)

• ~/.gitconfig.local — Identitas Git (nama + email), di-include oleh repo
• ~/.z — Riwayat direktori zsh
• ~/.zsh_history — Command history
• ~/.ssh/ — SSH keys dan config

Konvensi Git

Commit Message

Mengikuti Conventional Commits :

<type>(<scope>): <description>

[optional body]

[optional footer]

Tipe:

• feat: — Fitur atau konfigurasi baru
• fix: — Bug fix atau koreksi
• docs: — Perubahan dokumentasi
• style: — Formatting, tanpa perubahan konten
• refactor: — Restructuring kode
• chore: — Maintenance tasks

Contoh:

feat(starship): tambah custom git status symbols
docs(setup): tambah troubleshooting section
fix(kaku): perbaiki font size configuration

Branching

• main — Konfigurasi stabil dan working
• Feature branches untuk perubahan eksperimental

Keamanan

Jangan Di-commit

• SSH private key (~/.ssh/id_*)
• API key atau token
• Password atau kredensial
• File .env dengan nilai asli
• Data session atau cache
• Informasi identitas personal

Aman Di-commit

• Konfigurasi aplikasi (tanpa secret)
• Shell aliases dan functions
• Konfigurasi Git (tanpa info user)
• Dokumentasi
• Script dan automation

Maintenance

Task Reguler

Catatan Update

Aplikasi di folder ini terbagi dua kelompok dengan mekanisme berbeda:

• Dikelola Homebrew — make update akan menaikkan versinya otomatis. Daftar ada di Brewfile.
• Dikelola manual (DMG) — tidak ada cask Homebrew resmi, jadi make update hanya menampilkan URL sumber dan versi terinstall; pembaruan tetap dilakukan manual. Daftar ada di array MANUAL_APPS pada scripts/update.sh.

Setiap kali make inventory dijalankan, docs/INVENTORY.md ditulis ulang dengan versi aktual — berguna sebagai jejak audit perubahan.

Menambah Konfigurasi Baru

1. Buat direktori: mkdir -p config/appname/
2. Tambah file config: config/appname/config.ext
3. Tambahkan satu baris ke scripts/lib/symlinks.sh. Ini satu-satunya tempat yang perlu diubah — install.sh, verify.sh, clean.sh, dan inventory.sh membacanya dari manifest yang sama.
4. Update .gitignore bila file itu state runtime, bukan konfigurasi
5. Update docs/STRUCTURE.md (tabel mapping dan pohon direktori)
6. Jalankan make lint dan make verify
7. Commit: feat(config): tambah konfigurasi appname

Poin 3 ditambahkan sebagai respons atas kesalahan nyata: sebelumnya daftar symlink di-hardcode di lima file terpisah, sehingga config/zsh/ ter-commit tanpa pernah ter-symlink dan tidak ada script yang menyadarinya.

Menambah Paket Homebrew

Repositori ini memakai Brewfile deklaratif.

1. Pasang paketnya (butuh persetujuan user lebih dulu)
2. Jalankan brew bundle dump --file=Brewfile --force
3. Periksa diff: brew bundle dump hanya mencantumkan paket leaf, jadi dependency tidak akan muncul. Bila sebuah script bergantung pada paket yang merupakan dependency transitif (seperti ripgrep), tambahkan eksplisit agar provisioning tidak rapuh.
4. Commit: feat(brew): tambah pkgname