minicode-ai 0.10.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (128) hide show
  1. package/AGENTS.md +45 -0
  2. package/CHANGELOG.md +59 -4
  3. package/PLAN.md +491 -0
  4. package/README.md +2 -2
  5. package/cli/commands/acp.ts +485 -0
  6. package/cli/commands/auth.ts +7 -4
  7. package/cli/commands/config.ts +41 -27
  8. package/cli/commands/exec.ts +33 -12
  9. package/cli/commands/mcp.ts +3 -2
  10. package/cli/commands/memory.ts +1 -1
  11. package/cli/commands/pricing.ts +6 -4
  12. package/cli/commands/providers.ts +18 -8
  13. package/cli/commands/sessions.ts +11 -4
  14. package/cli/commands/skills.ts +3 -3
  15. package/cli/commands/stats.ts +3 -1
  16. package/cli/commands.ts +6 -0
  17. package/cli/index.ts +82 -57
  18. package/cli/model-manager.ts +6 -1
  19. package/cli/router.ts +7 -0
  20. package/cli/setup.ts +341 -5
  21. package/cli/tui.ts +54 -18
  22. package/docs/ARCHITECTURE.html +29 -22
  23. package/docs/CONTROL-PLANE-MAP.md +139 -0
  24. package/docs/HARNESS.md +150 -0
  25. package/docs/PLAN_UIUX_V6.md +209 -0
  26. package/docs/README.md +1 -1
  27. package/docs/SUMMARY.md +52 -0
  28. package/docs/TERMINAL_CONTRACT.md +367 -0
  29. package/docs/UI_RENDER_PIPELINE.md +165 -0
  30. package/docs/USAGE.md +11 -0
  31. package/docs/agents.md +31 -0
  32. package/docs/architecture.md +3 -3
  33. package/docs/choosing-mode.md +34 -0
  34. package/docs/cli.md +130 -0
  35. package/docs/concepts.md +53 -0
  36. package/docs/config-providers.md +87 -0
  37. package/docs/config.md +63 -0
  38. package/docs/contributing.md +79 -0
  39. package/docs/environment.md +95 -0
  40. package/docs/exec.md +73 -0
  41. package/docs/getting-started.md +102 -0
  42. package/docs/glossary.md +37 -0
  43. package/docs/mcp-lsp.md +54 -0
  44. package/docs/memory-sessions.md +63 -0
  45. package/docs/policy-sandbox.md +72 -0
  46. package/docs/pricing-budget.md +49 -0
  47. package/docs/quickstart.md +60 -0
  48. package/docs/repl.md +67 -0
  49. package/docs/security-model.md +95 -0
  50. package/docs/security.md +91 -0
  51. package/docs/skills.md +48 -0
  52. package/docs/terminal.md +79 -0
  53. package/docs/tools.md +123 -0
  54. package/docs/troubleshooting.md +40 -0
  55. package/docs/verify-benchmark.md +58 -0
  56. package/package.json +8 -5
  57. package/src/app/provider-layer.ts +12 -4
  58. package/src/app/session.ts +6 -0
  59. package/src/app/tool-layer.ts +2 -1
  60. package/src/constants.ts +35 -0
  61. package/src/lib/net.ts +6 -1
  62. package/src/lsp/client.ts +41 -8
  63. package/src/mcp/http-transport.ts +52 -15
  64. package/src/mcp/transport.ts +32 -1
  65. package/src/memory/files.ts +6 -5
  66. package/src/policy/allowlist.ts +1 -1
  67. package/src/policy/bash-guard.ts +154 -14
  68. package/src/policy/compaction.ts +57 -3
  69. package/src/policy/context.ts +4 -0
  70. package/src/policy/jail.ts +49 -4
  71. package/src/policy/permission.ts +152 -12
  72. package/src/policy/pricing.ts +12 -9
  73. package/src/presentation/adapter.ts +721 -0
  74. package/src/presentation/events.ts +324 -0
  75. package/src/presentation/label.ts +140 -0
  76. package/src/presentation/model.ts +172 -0
  77. package/src/presentation/reducer.ts +486 -0
  78. package/src/presentation/store.ts +256 -0
  79. package/src/providers/anthropic.ts +22 -4
  80. package/src/providers/detect.ts +2 -1
  81. package/src/providers/router.ts +13 -0
  82. package/src/repo/repomap.ts +2 -29
  83. package/src/session/checkpoint.ts +27 -9
  84. package/src/session/journal.ts +27 -5
  85. package/src/skills/loader.ts +88 -5
  86. package/src/telemetry/trace.ts +36 -15
  87. package/src/tools/ask_user.ts +73 -4
  88. package/src/tools/bash.ts +15 -17
  89. package/src/tools/glob.ts +10 -11
  90. package/src/tools/lsp.ts +3 -56
  91. package/src/tools/memory.ts +13 -12
  92. package/src/tools/task.ts +1 -0
  93. package/src/ui/approval/prompt.ts +14 -6
  94. package/src/ui/assistant/simple.ts +137 -26
  95. package/src/ui/assistant/turn-status.ts +16 -3
  96. package/src/ui/contract.ts +119 -0
  97. package/src/ui/footer.ts +21 -2
  98. package/src/ui/i18n/en.ts +34 -6
  99. package/src/ui/i18n/id.ts +34 -6
  100. package/src/ui/i18n/locale.ts +3 -1
  101. package/src/ui/input/input.ts +51 -4
  102. package/src/ui/input/prompt-engine.ts +46 -4
  103. package/src/ui/render/collapse.ts +13 -13
  104. package/src/ui/render/diff.ts +7 -2
  105. package/src/ui/render/format.ts +16 -8
  106. package/src/ui/render/highlight.ts +7 -3
  107. package/src/ui/render/markdown.ts +5 -1
  108. package/src/ui/render/sanitize.ts +29 -2
  109. package/src/ui/render/table.ts +8 -5
  110. package/src/ui/render/theme.ts +18 -4
  111. package/src/ui/render/width.ts +89 -10
  112. package/src/ui/runtime/motion.ts +16 -0
  113. package/src/ui/runtime/screen.ts +45 -0
  114. package/src/ui/runtime/spinner.ts +50 -4
  115. package/src/ui/runtime/statusline.ts +50 -1
  116. package/src/ui/screens/form.ts +42 -15
  117. package/src/ui/screens/model-manager.ts +26 -18
  118. package/src/ui/screens/picker.ts +47 -23
  119. package/src/ui/screens/provider-manager.ts +18 -12
  120. package/src/ui/screens/wizard.ts +24 -8
  121. package/src/ui/tui/app.ts +233 -27
  122. package/src/ui/tui/transcript.ts +269 -65
  123. package/vendor/minicore/LICENSE +21 -0
  124. package/vendor/minicore/VENDOR.md +6 -3
  125. package/vendor/minicore/package.json +6 -3
  126. package/vendor/minicore/src/core/loop.ts +12 -2
  127. package/vendor/minicore/src/core/snapshot.ts +4 -0
  128. package/vendor/minicore/src/providers/openai-compat.ts +76 -25
@@ -0,0 +1,165 @@
1
+ # UI Render Pipeline — peta jalur provider stream → terminal
2
+
3
+ Dokumen ini hasil audit stabilitas UI/UX terminal 2026-09-18 (baseline v0.9.27).
4
+ Sumber kebenaran perilaku tetap `docs/TERMINAL_CONTRACT.md` (FROZEN); dokumen
5
+ ini memetakan IMPLEMENTASI aktual per tahap beserta kontrak event dan temuan
6
+ audit. Angka test di sini diukur di Windows + Bun 1.4.2, suite penuh hijau.
7
+
8
+ Konvensi: `file:line` menunjuk simbol yang dimaksud. Aturan repo tetap berlaku:
9
+ `cli/` boleh impor `src/ui/` dan `src/`; `src/` non-ui DILARANG impor
10
+ `src/ui/`; `src/ui/` DILARANG impor `cli/`, `src/` non-ui, `#minicore`
11
+ (dijaga `test/ui-boundary.test.ts`).
12
+
13
+ ## 1. Jalur pipeline (9 tahap)
14
+
15
+ Tahap A — provider stream mentah: `src/providers/router.ts` (fallback +
16
+ `provider:text/extension/tool_call/finish`), `src/providers/guards.ts:32`
17
+ (timeout + text-cap + stream-guard tunggal), adapter `anthropic.ts`,
18
+ `responses.ts`, `effort.ts`. Dirakit di `src/app/provider-layer.ts`.
19
+
20
+ Tahap B — kernel emit ke `session.events`: `vendor/minicore/src/core/loop.ts`
21
+ (`turn:started`, `provider:text` per chunk, `provider:extension`
22
+ reasoning/usage/error, `context:compacted` reason `pressure:*`/`recovery`,
23
+ `step:started/completed`), `executor.ts` (`execution:started/completed`),
24
+ `session.ts` (`turn:completed` HANYA di jalur sukses).
25
+
26
+ Tahap C — tidak ada penerjemah `AgentEvent → UiEvent`: `src/ui/contract.ts:33`
27
+ `UiEvent` identik struktural dengan `AgentEvent` kernel; `cli/setup.ts`
28
+ menyerahkan `session.events` apa adanya ke `attachSimpleLogger` +
29
+ `attachTurnStatus` (dipasang segar per turn, dilepas di `finally` agar event
30
+ telat hening).
31
+
32
+ Tahap D — logger utama `src/ui/assistant/simple.ts:104`: append-only
33
+ scrollback, tanpa alternate screen. `provider:text` → `sanitizeAnsi` PER CHUNK
34
+ → `streamBuffer` → `flushBuf` (line-buffered) → `flushLine` (fence-state +
35
+ `decorateMarkdown` + `formatWrapped`) → `stdout`. Jawaban bisa minimize
36
+ (buffer 1MB + marker, dibuka via `/expand`).
37
+
38
+ Tahap E — garis status transient `src/ui/assistant/turn-status.ts`: satu baris
39
+ `stderr`, hidup hanya di fase sunyi (latch `turnOn && !textOn`), hilang saat
40
+ teks mengalir, hidup lagi saat tool berikut. `endTurn()` deterministik dari
41
+ driver `finally` (kernel tak emit `completed` saat gagal/abort).
42
+
43
+ Tahap F — arbitrator `src/ui/runtime/statusline.ts`: satu pemilik transient
44
+ (`turn` vs `spinner`); tulis asing saat painter aktif dikomit
45
+ (clear → tulis → repaint) sehingga diagnostik tak hilang; overlap = signal,
46
+ bukan crash. `paintWrite` tak pernah melempar (fail-closed Bun Windows).
47
+
48
+ Tahap G — status bar `src/ui/footer.ts` dirender `src/ui/tui/app.ts` sebagai
49
+ baris dasar frame fullscreen. Footer/chrome lama (`src/ui/runtime/chrome.ts`,
50
+ DECSTBM scroll-region, `MINICODE_FOOTER`) DIHAPUS bersama lapisan TUI lama —
51
+ alternate screen menggantikannya; nol byte di non-TTY. Footer baca
52
+ `session.contextTokens` kernel (bukan spend kumulatif).
53
+
54
+ Tahap H — primitif render `src/ui/render/`: `sanitize.ts` (hanya SGR lolos),
55
+ `markdown.ts` + `highlight.ts` (fence-state per baris, konten utuh),
56
+ `width.ts` (kolom: CJK/emoji 2, potong aman-SGR), `wrap.ts` (lebar dibaca
57
+ per baris → aman resize), `theme.ts` (getter warna/glyph, jangan di-`const`),
58
+ `errors.ts` (pesan actionable + redact), `collapse.ts` (buffer `/expand`
59
+ 200KB/entry, 500KB total), `diff.ts`/`table.ts`/`money.ts`/`format.ts`.
60
+
61
+ Tahap I — view murni vs controller: `src/ui/screens/` (props + callback,
62
+ tanpa IO) digerakkan `cli/` (`repl.ts`, `commands.ts`, `wizard.ts`,
63
+ `provider/model-manager.ts`, `approval/prompt.ts` via DI `ask`,
64
+ `setupWhenEmpty`, `setSubAgentSessionFactory`).
65
+
66
+ ## 2. Kontrak Event → UI
67
+
68
+ Kolom: S = bisa di-stream, D = bisa duplikat, O = bisa out-of-order,
69
+ I = bisa diinterupsi, L = bisa tiba setelah completion.
70
+
71
+ | Event | Producer | Representasi UI | S | D | O | I | L |
72
+ |---|---|---|---|---|---|---|---|
73
+ | assistant text | provider stream | stdout wrap + fence 2-spasi | ya | tidak (E1) | tidak | ya (abort) | tidak (detach flush 1x, E6) |
74
+ | tool call | model → kernel | `› nama target` muted (compact: diam) | tidak | tidak | tidak | ya | tidak |
75
+ | tool result | tool → executor | ledger hijau/merah; minimize → `+ label` + buffer | tidak | tidak | tidak | ya | tidak |
76
+ | reasoning | provider extension | expanded: live per baris; minimized: `+ thinking` + buffer | ya | tidak | tidak | ya | tidak |
77
+ | thinking effort | picker `/model` | badge + level per model | tidak | tidak | tidak | tidak | tidak |
78
+ | usage | provider extension | verbose saja; masuk budget watcher | ya | tidak | ya (tail pasca-finish) | ya | ya (diabaikan aman) |
79
+ | compaction | kernel loop | `── compacted: <reason>` kuning, reason verbatim | tidak | tidak | tidak | tidak | tidak |
80
+ | permission request | executor → `ask` DI | header stdout + `askLine y/a/n`, fail-closed non-TTY | tidak | tidak | tidak | ya (deny) | tidak |
81
+ | permission denied | executor | error tool penuh, tak pernah minimize + reason | tidak | tidak | tidak | tidak | tidak |
82
+ | sub-agent | delegate_task → bus parent | ledger `›` biasa + usage; tanpa view khusus | tidak | tidak (jurnal skip forward) | tidak | ya | tidak |
83
+ | error provider | provider extension | `pendingError` consume-once → satu `✗` oleh driver | tidak | tidak (E15) | tidak | ya | tidak |
84
+ | warning | budget/recovery/verify | `[budget]`/`[recovery]`/`[verify]` kuning stderr | tidak | tidak (warned80 sekali) | tidak | tidak | tidak |
85
+ | completion | kernel loop | flush + `finalizeAnswer` + footer idle | tidak | tidak | tidak | tidak | tidak |
86
+ | abort | user/Ctrl+C/Esc | `(stopped)` + cleanup `finally` | tidak | tidak | tidak | — | tidak |
87
+ | timeout | kernel `createTimeout` | `✗ timeout` + turn dibuang transaksional | tidak | tidak | tidak | — | ya (late work ke turnStore privat, dibuang) |
88
+ | budget exceeded | watcher/driver | `[budget] … stopping turn` + abort ber-kind | tidak | tidak (fire-once) | tidak | — | tidak |
89
+ | provider failure | recovery policy | retry/compact/throw deterministik; cap retryAfter 30 dtk | tidak | tidak | tidak | tidak | tidak |
90
+
91
+ Mismatch yang dicari, hasil: tidak ada event runtime yang diabaikan UI secara
92
+ diam-diam (`bus-debug.ts` hanya subscribe 7 tipe untuk debug, bukan render).
93
+ Satu-satunya state turunan yang disengaja: footer memakai `contextTokens`
94
+ (estimasi jendela) sementara `/status` memisahkan Context/Input/Output/Total/
95
+ Cost/Budget — didokumentasikan di `docs/CONTROL-PLANE-MAP.md`, bukan mismatch.
96
+
97
+ ## 3. State machine REPL (tidak eksplisit)
98
+
99
+ Tidak ada `enum` state; fase disimpulkan: `abort !== null` (busy),
100
+ `turnOn/textOn` (painter), `regionOn/detached` (chrome), plus ~14 flag
101
+ (`mode`, `escTimer`, `pending`, `nullStreak`, `warned80`, `activeSection`,
102
+ minimize toggles, buffer, `pendingError`, raw-mode listener). Invarian dijaga
103
+ `finally`/`detachUI`/`endTurn`, bukan type-state. Transisi ilegal yang
104
+ terbukti dicegah: painter saat teks mengalir, `endTurn` ganda, error ganda,
105
+ `+`/`-` di pipe, decoder bocor antar prompt, Tab membajak search.
106
+ Satu lubang nyata: listener approval `askLine` menempel DI ATAS `onBusyKey`
107
+ selama busy (byte Ctrl+C diterima keduanya) — aman fail-closed
108
+ (`raceAbort` → deny) tetapi observabilitas ganda. Lihat §5 temuan O1.
109
+
110
+ ## 4. Temuan audit 2026-09-18 (eksperimen di /tmp, repo tak diubah)
111
+
112
+ F1 HIGH — SGR terbelah antar-chunk merusak output model. `sanitizeAnsi`
113
+ diterapkan PER CHUNK (`simple.ts:287`): `["\x1b[", "32mHello"]` tampil
114
+ literal `32mHello`. Bukti: harness E3 `out="32mHellom\n"`. Kelas sama untuk
115
+ OSC tak-terminasi (menelan sisa chunk). Perbaikan terkecil: tahan ekor
116
+ escape tak-lengkap di buffer dan sambung ke chunk berikut sebelum sanitasi.
117
+
118
+ F2 MEDIUM — SGR model bocor mentah ke stdout non-TTY. `"\x1b[31mRed\x1b[0m"`
119
+ satu chunk lolos `sanitizeAnsi` (by-design) lalu ditulis ke pipe apa adanya
120
+ (`out="\u001b[31mRed\u001b[0m\n"`), melanggar kontrak non-TTY deterministik.
121
+ Perbaikan terkecil: strip SGR (atau render via `c.*`) saat `!isTTY`.
122
+
123
+ F3 LOW — buffer thinking `/expand` membuang kepala diam-diam
124
+ (`thinkingBuf.slice(-200_000)` tanpa marker seperti `, capped 1MB` pada
125
+ answer). Informasi diagnostik hilang tanpa jejak.
126
+
127
+ O1 LOW — listener ganda approval vs busy-key (§3). Fail-closed, catat saja.
128
+
129
+ Status hardening (sesudah audit): F1 diperbaiki via `createStreamSanitizer`
130
+ + `splitTrailingEscape` di `src/ui/render/sanitize.ts` (dipakai jalur teks
131
+ model/reasoning/bash di `simple.ts`, flush deterministik saat
132
+ completed/detach); F2 via kebijakan `stripSgr` non-TTY di `wOut`/`wErr` +
133
+ `rememberTurn` (cerminan `colorLevel` → `stdout.isTTY`); F3 via marker
134
+ `… (earlier thinking truncated)`; O1 didokumentasikan di `src/ui/tui/app.ts`
135
+ (busy-freeze + abort, tanpa refactor). Snap kiri/kanan: render pertama sesudah
136
+ geometri berubah
137
+ me-reset jangkar relatif askLine (`lastGeoCols/Rows` di `input.ts`) —
138
+ geometri lebar tak dilacak footer karena erase baris-absolut tak sound
139
+ pasca-reflow (terbukti model + ConPTY: reflow milik konsumen).
140
+ Dijaga `test/ansi-fragmentation.test.ts`
141
+ (termasuk properti semua-titik-belah ≡ whole-string),
142
+ `test/non-tty-output.test.ts`, `test/thinking-truncation.test.ts`,
143
+ `test/ui-combined.test.ts` (satu sistem: stream + tool + resize + footer),
144
+ `test/input-resize.test.ts` (gagal di kode lama: CUP ke anchor basi).
145
+
146
+ Batas yang TERVERIFIKASI BENAR (bukti harness + 178 test UI hijau):
147
+ token-by-token tepat-1x (E1), chunk 50KB utuh (E2), fence terbelah benar
148
+ termasuk yatim saat abort (E4/E4b), abort flush tepat-1x tanpa bocor ke turn
149
+ berikut (E6), urutan teks>tool>hasil (E7), permission fail-closed (E8),
150
+ kontrak budget murni vs gate (E9), tiga reason kompaksi tampil beda (E10),
151
+ forward sub-agent sebagai ledger biasa (E11), tool 5000-baris dipotong +
152
+ ANSI jahat dibuang (E12), decoder UTF-8 per-byte + ESC-split + paste 100KB
153
+ (E13), soak 50 turn tepat-1x 38ms +4.6MB tanpa ESC mentah (E14),
154
+ error consume-once + format actionable (E15), resize 120→20 mid-stream aman
155
+ (E5b), 10k events 151k ev/s tepat-1x (E17), CJK/emoji/wrap/truncate/fence
156
+ (E5), emphasis tak-seimbang lewat literal + tabel konten-tetap (fidelitas).
157
+
158
+ ## 5. Residual risk (jujur, belum dibuktikan di audit ini)
159
+
160
+ Jalur TTY-live (painter denyut, footer sticky DECSTBM, overlay picker,
161
+ tombol busy) hanya tercakup harness fake-TTY + 178 test; tidak ada sesi TTY
162
+ nyata di audit ini. Chaos kombinasi (stream+resize+abort serentak di TTY)
163
+ dan soak 100+ turn multitool belum dijalankan. Sub-agent tanpa view khusus:
164
+ indukan dibedakan hanya dari nama tool (cukup untuk 1 level, belum diuji
165
+ visual untuk delegasi bertingkat — yang memang dilarang: tanpa nesting).
package/docs/USAGE.md ADDED
@@ -0,0 +1,11 @@
1
+ # Minicode User Guide
2
+
3
+ > **Status: arsip legacy.** Isi panduan monolit ini kini terpelihara di halaman docs terpisah (tabel di bawah). Jangan tambah konten baru di sini; perbaiki di halaman tujuannya.
4
+ >
5
+ > | Butuh… | Baca… |
6
+ > |---|---|
7
+ > | Mulai cepat | [Quickstart](quickstart.md), [Instalasi](getting-started.md) |
8
+ > | Flag & env | [CLI](cli.md), [Environment Variables](environment.md) |
9
+ > | Tool & MCP/LSP | [Tools](tools.md), [MCP & LSP](mcp-lsp.md) |
10
+ > | Memory, sesi, recovery | [Memory & Sessions](memory-sessions.md) |
11
+ > | Keamanan & policy | [Security Model](security-model.md), [Policy & Sandbox](policy-sandbox.md) |
package/docs/agents.md ADDED
@@ -0,0 +1,31 @@
1
+ # Sub-Agents & Tasks
2
+
3
+
4
+ ## Konsep
5
+
6
+ Sub-agent = instans agent dengan **context terpisah** dari parent: memory, signal, dan budget sendiri. Pool concurrency 3 — maksimum 3 sub-agent hidup sekaligus — dan abort-aware (mewarisi AbortSignal parent; parent batal → anak berhenti).
7
+
8
+ Approval: `delegate_task` di-gate — TTY meminta persetujuan sekali per delegasi; non-TTY menolak. **Satu approval = delegasi ini saja**, tidak melebar ke delegasi lain.
9
+
10
+ ## Mode anak: `explore` / `plan`
11
+
12
+ | Mode anak | Kemampuan |
13
+ |---|---|
14
+ | `explore` | Subset read-only (12 tool) — cari/pahami kode, kembalikan temuan |
15
+ | `plan` | Read-only + `todo_read` (baca rencana parent), tetap tanpa mutasi dan tanpa `todo_write` |
16
+
17
+ Restriksi anak (selalu, tanpa kecuali): **tanpa** MCP, `git_commit`, memory-tulis, todo-tulis, job background, nesting (anak tidak bisa mendelegasi lagi). Plan-parent dipaksa explore saat mendelegasi.
18
+
19
+ ## Kenapa dibatasi
20
+
21
+ Sub-agent menjalankan task tanpa Anda di depan layar. Kalau anak bisa commit atau memanggil MCP, satu prompt parent bisa menghasilkan efek yang tak Anda persetujui. Dengan membatasi anak ke read-only, efek samping tetap satu: eksekusi di parent — yang ledger-nya selalu Anda lihat.
22
+
23
+ ## Recovery
24
+
25
+ Turn parent gagal **setelah** anak `committed`: jurnal menandai delegasi; saat resume model diberi warning `[recovery]` agar tidak mendelegasi ulang buta (efek anak sudah terjadi — yang benar adalah verifikasi hasilnya). Lihat [Keamanan](security.md) untuk jurnal recovery lengkap.
26
+
27
+ ## Lanjut
28
+
29
+ - [Tools](tools.md) — semua tool yang boleh dipakai anak.
30
+ - [Policy & Sandbox](policy-sandbox.md) — mode permission parent vs anak.
31
+ - [Otomasi & CI](exec.md) — delegasi di non-TTY (ditolak, fail-closed).
@@ -23,7 +23,7 @@ L3 vendor/minicore → kernel STATE/MODEL/ACTION/LOOP (freeze, zero-dep, via #m
23
23
 
24
24
  ## UI/UX terminal (kontrak FROZEN)
25
25
 
26
- Minicode **shell-native CLI, bukan TUI**. Tanpa alternate screen/panel/header permanen. Output append-only scrollback; picker/manager transient dan menghapus diri sendiri.
26
+ Sesi interaktif (`minicode` di TTY mampu) SELALU membuka TUI **fullscreen alternate screen**: transkrip ala shell + status bar satu baris + popup komposit di atas transkrip yang tetap terlihat (redup). Jalur non-interaktif (one-shot prompt, `exec`, pipe/redirect/CI, `TERM=dumb`, layar < 10 baris) tetap shell-first: cetak polos append-only ke scrollback tanpa cursor control.
27
27
 
28
28
  | Stream | Isi |
29
29
  |---|---|
@@ -31,9 +31,9 @@ Minicode **shell-native CLI, bukan TUI**. Tanpa alternate screen/panel/header pe
31
31
  | stderr | Progress/diagnostik: ledger tool (`› …` hijau/merah), reasoning (verbose), warning, error. Boleh transient bila TTY |
32
32
  | Keduanya | Warna hanya bila TTY (`stdout.isTTY`); `NO_COLOR` menang; `TERM`/`COLORTERM` tidak menyalakan warna di pipe |
33
33
 
34
- Satu-satunya arbitrator transient: `src/ui/runtime/statusline.ts` (`acquireTransientPaint` + `paintWrite`). Painter aktif (garis status turn vs spinner wizard) mutually exclusive; overlap = signal `[transient-paint]`, bukan crash. Foreign stderr writer (non-UI) boleh mentah — arbitrator mengkomitnya sebagai baris permanen bersih. 14 invariant + peta test (`terminal-contract`, `transient-arbitration`, `turn-status`, `tui-format`, `theme`, `repl-linear`, `ui-boundary`, `footer-render`, `footer-chrome`) ada di `TERMINAL_CONTRACT.md`.
34
+ Satu-satunya arbitrator transient: `src/ui/runtime/statusline.ts` (`acquireTransientPaint` + `paintWrite`). Painter aktif (garis status turn vs spinner wizard) mutually exclusive; overlap = signal `[transient-paint]`, bukan crash. Foreign stderr writer (non-UI) boleh mentah — arbitrator mengkomitnya sebagai baris permanen bersih. `beginInteractiveScreen` menahan semua painter itu selama layar interaktif memegang terminal. 30 invariant (I1–I30) + peta test (`tui-app`, `screen-buffer`, `tui-popup`, `transient-arbitration`, `input-resize`, `exit-codes`, `acp`, `ui-boundary`) ada di `TERMINAL_CONTRACT.md`.
35
35
 
36
- Lima primitif tampilan: prompt `minicode ›` (steril — status pindah ke footer), footer status lengket `✦ mode • model • cwd … 14.2k` (spark pulse saat busy/redup saat idle; mode pad anti-geser; konteks rata kanan `14.2k`; garis `faint`; `src/ui/footer.ts` render + `src/ui/runtime/chrome.ts` DECSTBM `setBusy()`; `MINICODE_FOOTER=off|print|sticky|auto`, non-TTY nol byte), activity (garis transient stderr `···` tanpa spark), ledger ` › name target` hijau / ` › name: …` merah (stderr, indent 2), teks model (stdout, wrapped, fence 2-spasi), error `✗ pesan actionable` sekali per kegagalan (`takePendingError`). `✓`/`✗` tetap untuk status/konfirmasi perintah (sync, auth, config, spinner).
36
+ Enam primitif tampilan (semuanya di dalam TUI fullscreen saat interaktif): transkrip `minicode ›` + jawaban model + ledger ` › name target` hijau / ` › name: …` merah; status bar satu baris `✦ mode • model • cwd … ctx` (spark pulse saat busy, redup saat idle, konteks rata kanan; `src/ui/tui/app.ts` render per frame); popup komposit satu kotak (`/model`, `/provider`, `/sessions`, form, approval) via `openAltScreen`/`paintRegion`; thinking redup + penanda `… thinking` (isi via `/expand`); error `✗ pesan actionable` sekali per kegagalan (`takePendingError`). `✓`/`✗` tetap untuk status/konfirmasi perintah (sync, auth, config, spinner).
37
37
 
38
38
  ## Modul kunci
39
39
 
@@ -0,0 +1,34 @@
1
+ # Memilih Mode
2
+
3
+ Satu pertanyaan, satu jawaban: **mode mana untuk tujuan saya?**
4
+
5
+ ## Kalau tujuan Anda X → gunakan Y
6
+
7
+ | Saya ingin… | Gunakan | Karena |
8
+ |---|---|---|
9
+ |Memahami repo tanpa mengubah apa pun | `readonly` (atau `--tool-scope explore`) | Hanya 18 tool baca yang lolos; tulis/bash/commit/deligasi ditolak di gerbang |
10
+ | Minta agen membuat perubahan | `auto` (default) | Tulis terjail + bash aman langsung jalan; yang berisiko (commit, MCP, delegasi) tetap minta izin sekali |
11
+ | Menyetujui setiap perubahan | `ask` | Tiap tool non-sepele menunggu jawaban; `todo`/`bash_output` tak ditanya (bookkeeping sendiri) |
12
+ | Menyusun rencana tanpa eksekusi | `plan` | Baca + tulis rencana (`todo_write`) + delegasi yang dipaksa read-only; tanpa mutasi file/git/memori |
13
+ | Otomasi/CI tanpa manusia | One-shot/`exec` + mode default | `ask_user`/gated otomatis ditolak di non-TTY (fail-closed, bukan gantung); hindari prompt yang butuh klarifikasi |
14
+ | Otonom penuh di mesin sendiri | `allow-all` + `--sandbox docker` (atau OS) + `--budget` | Tanpa prompt, TETAPI jail path + bash-guard tetap aktif; sandbox memberi isolasi nyata |
15
+
16
+ ## Rule of thumb
17
+
18
+ 1. **Default `auto` sudah benar untuk kerja harian.** Pindah mode hanya bila tujuan berubah, bukan karena takut umum.
19
+ 2. **`readonly` untuk baca, `plan` untuk berpikir.** Bedanya: `plan` boleh menulis rencana dan mendelegasikan penelahan; keduanya tak menyentuh file/git/memori Anda.
20
+ 3. **`ask` untuk wilayah asing** — repo orang, perintah yang belum Anda pahami. Jawab `always` hanya untuk pasangan tool+args spesifik yang sudah Anda nilai.
21
+ 4. **CI = non-interaktif = tanpa approval.** Jangan desain pipeline yang bergantung pada `ask_user` atau commit oleh agent; commit tetap keputusan manusia/Workflow.
22
+ 5. **`allow-all` mematikan prompt, bukan batas.** Path jail dan pola bash berbahaya tetap menolak. Pasangkan dengan sandbox + budget bila otonom.
23
+
24
+ ## Tradeoff yang jujur
25
+
26
+ - Semakin otonom → semakin cepat, semakin besar blast radius bila model salah paham. Tidak ada mode yang membuat model lebih bijak — mode hanya mengatur **apa yang boleh terjadi**.
27
+ - `allowlist` (otomatis saat tanpa sandbox OS) paling ketat untuk shell, tetapi model tetap bisa menulis file via tool terjail — pahami beda sumbunya: allowlist membatasi *perintah*, jail membatasi *file*.
28
+ - Ganti mode kapan pun: flag saat start, `/mode` atau Shift+Tab saat REPL berjalan.
29
+
30
+ ## Lanjut
31
+
32
+ - [Security Model](security-model.md) — apa yang ditegakkan tiap mode.
33
+ - [Policy & Sandbox](policy-sandbox.md) — tabel semantik presisi + bukti guard.
34
+ - [Otomasi & CI](exec.md) — batasan headless.
package/docs/cli.md ADDED
@@ -0,0 +1,130 @@
1
+ # CLI — Mode & Flags
2
+
3
+ Semua cara menjalankan Minicode: interaktif, sekali jalan, pipe, dan otomasi CI — plus flags dan environment.
4
+
5
+ ## Mode
6
+
7
+ | Perintah | Fungsi |
8
+ |---|---|
9
+ | `minicode` | Mode interaktif (REPL) + wizard bila belum ada provider |
10
+ | `minicode "prompt"` | Sekali jalan (headless) |
11
+ | `echo "prompt" \| minicode` | Via pipe |
12
+ | `minicode exec "prompt" [--json]` | Headless CI — event JSONL + baris `{"type":"summary"}` di stdout |
13
+ | `minicode acp` | Server JSON-RPC stdio untuk IDE (subset minimal: initialize/run/cancel/shutdown) |
14
+ | `minicode --interactive` | Paksa REPL |
15
+ | `minicode --provider <id> "prompt"` | Paksa provider agnostik tanpa ubah config (atau `provider::model`) |
16
+ | `minicode config add --baseUrl <url> --apiKey <key>` | Tambah provider LLM |
17
+ | `minicode config mcp add <id> --command <cmd> --args "<a1,a2>"` | Daftarkan MCP server stdio |
18
+ | `minicode config mcp add <id> --url <https://…>` | Daftarkan MCP server HTTP |
19
+ | `minicode config lsp add <ext> --command <cmd> --args "<a1,a2>"` | Daftarkan LSP server |
20
+ | `minicode auth login [provider]` | Login OAuth device-code |
21
+ | `minicode auth status\|logout\|list` | Kelola kredensial OAuth |
22
+ | `minicode pricing status\|sync\|show <model>\|clear` | Tabel harga estimasi biaya |
23
+ | `minicode skills list` | Daftar skill terpasang |
24
+ | `minicode sessions list` | Riwayat sesi |
25
+ | `minicode memory status [--json]` | Statistik vector RAG (rows, size, hit-rate) |
26
+ | `minicode doctor [--json]` | Diagnosis lokal |
27
+ | `minicode mcp serve` | Ekspos minicode sebagai MCP server |
28
+
29
+ Subcommand di-route di `cli/router.ts` (`stats`, `sessions`, `mcp`, `config`, `skills`, `providers`, `auth`, `pricing`, `exec`, `memory`, `doctor`, `acp`).
30
+
31
+ ## Flags
32
+
33
+ | Flag | Deskripsi |
34
+ |---|---|
35
+ | `--verbose` | Tampilkan reasoning & usage |
36
+ | `--verify` | Auto-verify + self-heal (detect: typecheck → test → tsconfig) |
37
+ | `--sandbox docker` | Bash di container ephemeral (`--network none`) |
38
+ | `--sandbox none` | Matikan sandbox otomatis (opt-out sadar) |
39
+ | `--sandbox os` | Paksa OS-native (bwrap/seatbelt). Sudah otomatis bila tersedia |
40
+ | `--ratelimit <rpm>` | Batas request LLM per menit |
41
+ | `--budget <usd>` | Batas biaya sesi; warn 80%, exit/break bila lewat; cost tak dikenal + pemakaian = over (fail-closed default) |
42
+ | `--budget-strict` | Penegasan eksplisit fail-closed di atas (back-compat) |
43
+ | `--tool-scope <s>` | `full` (default) \| `explore` = subset read-only 12 tool |
44
+ | `--plan` | Read-only plan mode |
45
+ | `--allowlist` | Bash hanya perintah aman |
46
+ | `--ask` | Tanya persetujuan setiap tool |
47
+ | `--allow-all` | Nonaktifkan semua sandbox (path jail tetap aktif) |
48
+ | `--model <name>` | Override model (`providerId::model` paksa provider) |
49
+ | `--provider <id>` | Paksa provider id agnostik |
50
+ | `--resume <id>` | Lanjutkan sesi (full history, bukan dump teks) |
51
+ | `--timeout <ms>` | Hard deadline per run (default 900000; 0 = Infinity) |
52
+ | `--cwd <path>` | Workspace root untuk tool file & jail |
53
+ | `--allow-local-config` | Percayai `.minicode/config.json` + allowlist lokal (default: diabaikan) |
54
+ | `--max-steps <n>` | Batas langkah tool (default 50) |
55
+ | `--context-window <n>` | Ukuran jendela konteks (token) |
56
+ | `--session <id>` | ID sesi (default random, disanitasi) |
57
+
58
+ Di REPL, **Shift+Tab** memutar permission (`auto` → `ask` → `plan` → `allowlist`) dan benar-benar mengubah keputusan, bukan label. Di baris kosong, **Tab** juga memutar mode (`auto` → `ask` → `plan` → `allowlist`).
59
+
60
+ ## Kapan memakai apa
61
+
62
+ | Tujuan | Pakai |
63
+ |---|---|
64
+ | Kerja harian biasa | Default (`auto`) — tulis aman langsung jalan, yang berisiko minta izin |
65
+ | Repo asing / perintah belum dipahami | `--ask`, jawab `always` hanya untuk pasangan tool+args yang sudah dinilai |
66
+ | Review tanpa eksekusi | `--plan` (+ `--tool-scope explore` bila ingin subset baca 12 tool) |
67
+ | CI tanpa manusia | `exec --json` + `--budget`/`--max-steps`; hindari prompt yang butuh klarifikasi |
68
+ | Otonom penuh di mesin sendiri | `--allow-all` + `--sandbox docker` (atau OS) + `--budget` |
69
+ | Model mahal tak terkendali | `--budget 0.50` + `--budget-strict` + `pricing sync` |
70
+
71
+ Detail alasan tiap mode di [Memilih Mode](choosing-mode.md).
72
+
73
+ ## Environment variables (ringkas)
74
+
75
+ Kepala tabel penuh ada di [Environment Variables](environment.md); yang paling sering dipakai:
76
+
77
+ | Variabel | Fungsi |
78
+ |---|---|
79
+ | `MINICODE_VERIFY_CMD` | Custom verify command |
80
+ | `MINICODE_SANDBOX` | `docker` \| `os` \| `none` |
81
+ | `MINICODE_SANDBOX_STRICT=1` | Tak pernah fallback host (default request eksplisit sudah fail-closed) |
82
+ | `MINICODE_SANDBOX_ALLOW_FALLBACK=1` | Izinkan fallback host secara eksplisit bila backend tak tersedia |
83
+ | `MINICODE_BUDGET_STRICT=1` | Sama dengan `--budget-strict` |
84
+ | `MINICODE_ALLOW_LOCAL_CONFIG=1` | Sama dengan `--allow-local-config` |
85
+ | `MINICODE_TOOL_SCOPE=explore` | Subset read-only |
86
+ | `MINICODE_GREP_ENGINE=js` | Paksa walker internal |
87
+ | `MINICODE_MEMORY_SCOPE` | `cwd` \| `global` \| `all` |
88
+ | `MINICODE_AUTO_MEMORY=0` | Matikan auto-simpan summary/snippet |
89
+ | `MINICODE_TELEMETRY=0` | Matikan `traces.jsonl` |
90
+ | `MINICODE_HOME` | Override home untuk DB lokal/global |
91
+ | `TAVILY_API_KEY` | Tavily web_search (fallback DDG bila kosong) |
92
+ | `NO_COLOR` | Matikan warna (menang atas TTY) |
93
+ | `MINICODE_ASCII=1` | Glyph ASCII untuk konsol tanpa UTF-8 |
94
+ | `MINICODE_STATUSLINE=rich` | Spinner tampilkan token + biaya sesi |
95
+
96
+ ## Config `.minicode/config.json`
97
+
98
+ ```json
99
+ {
100
+ "providers": [{ "id": "my-provider", "baseUrl": "...", "apiKey": "...", "models": ["gpt-4o"] }],
101
+ "mcpServers": [
102
+ { "id": "fs", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"] },
103
+ { "id": "remote", "url": "https://mcp.example.com/mcp", "headers": { "authorization": "Bearer xxx" } }
104
+ ],
105
+ "lspServers": [{ "ext": ".ts", "command": "typescript-language-server", "args": ["--stdio"] }],
106
+ "verifyCommand": "bun run typecheck",
107
+ "bashAllowlist": ["git status*", "bun test*", "npm run build*"]
108
+ }
109
+ ```
110
+
111
+ Global (`~/.minicode/config.json`) selalu dibaca. Lokal (`.minicode/config.json`)
112
+ adalah input repo tak terpercaya dan DIABAIKAN kecuali operator opt-in per
113
+ invokasi (`--allow-local-config` / `MINICODE_ALLOW_LOCAL_CONFIG=1`) — tanpa
114
+ itu MCP server lokal tidak di-spawn, endpoint provider lokal tidak dipakai,
115
+ `verifyCommand`/`bashAllowlist` lokal tidak berlaku. Tulis eksplisit
116
+ (`config add --local`) tak terpengaruh.
117
+
118
+ ## Anti-injeksi flag
119
+
120
+ `cli/args.ts:53` berhenti di prompt word pertama: prompt `"review --allow-all"` tidak mengaktifkan flag. `--cwd`/value-flag setelah nama subcommand diparse per-subcommand agar tidak menembus boundary prompt.
121
+
122
+ ## Exit codes
123
+
124
+ | Kode | Arti |
125
+ |---|---|
126
+ | `0` | Sukses, atau help yang memang diminta |
127
+ | `1` | Gagal runtime: provider error, budget lewat, turn gagal, setup gagal |
128
+ | `2` | Salah pakai: argumen hilang/malformed, subcommand asing |
129
+
130
+ Lookup yang gagal (provider/skill/sesi tak dikenal) = `1`: itu kegagalan operasi, bukan pemakaian. Skrip cukup cek `!= 0` untuk gagal; cek `== 2` untuk spesifik salah pakai.
@@ -0,0 +1,53 @@
1
+ # Konsep & Desain
2
+
3
+ Minicode itu apa, kenapa dibangun begitu, dan kenapa beberapa hal sengaja tidak ada. Halaman ini latar belakangnya; langkah praktis ada di [Instalasi](getting-started.md).
4
+
5
+ ## Dua benda, dua peran
6
+
7
+ | Nama | Apa |
8
+ |---|---|
9
+ | **MiniCore** | Kernel runtime `STATE / MODEL / ACTION / LOOP`. Inti di-freeze, zero-dependency, di-vendor ke `vendor/minicore` (19 file, ~72 KB). Bukan dependency — di-resolve lewat subpath imports `#minicore` |
10
+ | **Minicode** | Layer agencode di atasnya: tools, sub-agents, skills, hooks, policy/sandbox, providers, MCP/LSP, memory, sessions, repo-map, verifier, CLI shell-first |
11
+
12
+
13
+ ## Loop ReAct
14
+
15
+ Setiap prompt berjalan sebagai loop `Thought → Action → Observation` sampai jawaban final, batas `--max-steps` (default 50), atau `--timeout` (default 15 menit). Model menerima system prompt berisi `# Environment` (cwd + platform), repo-map ringkas, dan memory yang relevan — lalu memilih tool, melihat hasilnya, dan memilih langkah berikutnya. Tidak ada grafik alur tersembunyi: apa pun yang agent lakukan tampil sebagai ledger di layar.
16
+
17
+ ## Shell-first: non-interaktif polos, interaktif fullscreen
18
+
19
+ Minicode sengaja **tanpa framework TUI** (tanpa Ink/React, tanpa panel
20
+ permanen) dan membagi dua jalur secara tegas:
21
+
22
+ - **Non-interaktif** (one-shot prompt, `exec`, pipe/redirect/CI, `TERM=dumb`):
23
+ output mengalir **append-only ke scrollback** — hasil agen adalah artefak
24
+ terminal biasa yang bisa di-pipe, di-grep, dan tersimpan di scrollback Anda
25
+ sendiri.
26
+ - **Interaktif** (TTY mampu): satu tampilan **TUI fullscreen** alternate-screen
27
+ — transkrip ala shell + status bar satu baris + popup komposit; keluar =
28
+ buffer utama kembali persis (transkrip tidak di-dump ke scrollback).
29
+ - Warna hanya saat TTY; `NO_COLOR` selalu menang; output program tetap bersih dari cursor-control saat di-pipe.
30
+
31
+ Detail lengkap + kontrak FROZEN-nya di [Kontrak Terminal](terminal.md).
32
+
33
+ ## Kejujuran sebagai fitur
34
+
35
+ Beberapa keputusan desain lahir dari tidak mau berpura-pura:
36
+
37
+ - **Angka tidak ditulis permanen** di dokumentasi — jalankan `bun test` / `bun run gate:coverage` / lihat CI. Halaman yang mengklaim jumlah test akan usang begitu dipush.
38
+ - **Kegagalan dilaporkan apa adanya**: `auth login` menampilkan error server tanpa dipercantik; `--sync` jujur `{updated, failed}`; sandbox yang tidak tersedia **tidak** dilabeli aman — default turun ke `allowlist` dengan alasan dicetak sekali.
39
+ - **Ukur, bukan klaim**: bash-guard divalidasi korpus serangan + fuzz ber-seed (jalankan `bun run gate:bash` / `bun run extreme:fuzz`). Lihat [Keamanan](security.md).
40
+ - **Skor benchmark dilaporkan apa adanya** beserta batas validitasnya (lingkungan, ukuran sampel). Lihat [Verify & Benchmark](verify-benchmark.md).
41
+
42
+ ## Zero-dep runtime
43
+
44
+ Runtime tanpa dependency pihak ketiga; satu-satunya kebutuhan keras adalah **Bun** (`bun:sqlite` dipakai langsung — tidak jalan di Node.js). Parser markdown web, renderer tabel/diff, dan highlight juga mini buatan sendiri, bukan library. Manfaatnya: audit permukaan lebih kecil, install cepat, dan supply-chain yang bisa dibaca sambil duduk.
45
+
46
+ ## Bahasa
47
+
48
+ Dokumentasi dan komentar kode berbahasa **Indonesia** dengan istilah teknis tetap English (`provider`, `checkpoint`, `sandbox`, `jail`). Lihat [Glosarium](glossary.md) untuk daftar istilah.
49
+
50
+ ## Lanjut
51
+
52
+ - [Arsitektur](architecture.md) — tiga lapisan, boundary, alur satu prompt.
53
+ - [Quickstart](quickstart.md) — dari nol ke prompt pertama yang ter-verify.
@@ -0,0 +1,87 @@
1
+ # Config & Provider
2
+
3
+ ## 14 preset gateway
4
+
5
+ `Gateway >` hanya menampilkan `[0] Label` tanpa URL (minimalis, tanpa bocor endpoint).
6
+
7
+ | id | Label | Catatan |
8
+ |---|---|---|
9
+ | `openai` | OpenAI | gpt, o-series |
10
+ | `anthropic` | Anthropic | Claude, streaming `tool_use` |
11
+ | `openrouter` | OpenRouter | Gateway 75+ model |
12
+ | `deepseek` | DeepSeek | chat/reasoner |
13
+ | `opencode-zen` | OpenCode Zen | Gateway |
14
+ | `google` | Google Gemini | Konteks 1M, `thought_signature` pass-through |
15
+ | `ollama` | Ollama | Lokal, gratis, tanpa key |
16
+ | `qwen` | Qwen | Alibaba Qwen3-Coder (satu-satunya dengan spec OAuth terdaftar) |
17
+ | `groq` | Groq | Inferensi cepat |
18
+ | `together` | Together AI | Model terbuka |
19
+ | `fireworks` | Fireworks AI | — |
20
+ | `mistral` | Mistral AI | — |
21
+ | `cohere` | Cohere | — |
22
+ | `generic` | OpenAI-compatible umum | vLLM / LM Studio |
23
+ | `custom` | Custom URL | Pseudo-preset untuk baseUrl sendiri |
24
+
25
+ Alur: wizard & `/provider` (add `[0] OpenAI` … `[14] Custom URL`) → API key ter-masking → auto-detect models via `GET /models` timeout 4 dtk → provider otomatis pindah saat pilih model beda provider (tanpa restart, via `reloadProviders()` setelah `Gateway >2`).
26
+
27
+ ## Dua jalur autentikasi
28
+
29
+ ```bash
30
+ # 1. API key
31
+ minicode config add --baseUrl https://api.openai.com/v1 --apiKey sk-…
32
+
33
+ # 2. OAuth device-code (tanpa API key, tanpa kartu kredit) — RFC 8628
34
+ minicode auth list # provider yang mendukung
35
+ minicode auth login qwen # kode singkat → buka URL → tunggu persetujuan
36
+ minicode auth status # kredensial + kapan kedaluwarsa
37
+ minicode auth logout qwen
38
+ ```
39
+
40
+ Token di `~/.minicode/auth.json` (chmod 600), bukan `config.json`. Refresh otomatis margin 60 dtk. Provider OAuth yang belum login dibuang dari daftar dengan peringatan, bukan dikirim dengan header kosong.
41
+
42
+ > Kejujuran: device flow teruji lengkap ke server OAuth lokal (18 test: pending/slow_down/denied/expired/clamp), tapi endpoint/clientId provider belum semua terkonfirmasi live. `auth login chatgpt` fail-fast di non-TTY. Jangan baca token aplikasi desktop orang lain — itu pencurian kredensial.
43
+
44
+ ## Keyring OS (ganti plaintext config)
45
+
46
+ ```bash
47
+ minicode config set-key openrouter # pindah API key ke OS store, config tinggal referensi
48
+ minicode config delete-key openrouter # lupakan (provider nonaktif sampai di-set ulang)
49
+ ```
50
+
51
+ Windows memakai DPAPI user-scope (hanya user ini yang bisa membuka); selain itu berkas chmod 600 dengan label jujur `plain-file` (bukan keyring). Referensi hilang/rusak = provider di-skip dengan peringatan (fail-closed, seperti OAuth). Matikan paksa via `MINICODE_KEYSTORE_DISABLE=1`.
52
+
53
+ ## Model & thinking effort
54
+
55
+ ```
56
+ /model [cari] → picker provider::model, bisa difilter
57
+ Enter → pilih model (+ picker effort bila modelnya mendukung)
58
+ Esc → batal total
59
+ ```
60
+
61
+ Effort tersimpan di `ProviderEntry.reasoningEffort`, berlaku sesi berikutnya, tampil badge `[low|medium|high]`. **Default universal = omit** (tanpa param thinking): default bawaan tiap model sudah di-tune vendornya. Knob hanya dikirim ke keluarga terbukti, dalam bahasa native-nya: OpenAI reasoning (`o*`, `gpt-5/6` → `reasoning_effort`, level tervalidasi per model — pro = high saja); Claude ≤4.5 → budget `1024/2048/4096`; Claude ≥4.6/5 → adaptive + `output_config.effort`. **Selain itu tak pernah dikirimi param thinking** (DeepSeek, Gemini, Groq, Ollama, free-tier, custom). Bila model menolak param (400/500), request diulang sekali tanpa param + diingat per sesi + dicatat `[thinking]` di stderr. Picker effort hanya muncul untuk model yang mendukung; sisanya select langsung tanpa menyentuh effort tersimpan. `detectAndSave`/`auth login` mempertahankan effort (tidak reset diam-diam). Mutasi ditulis ke file scope asal (bukan hasil merge) agar tidak duplikat/shadowing.
62
+
63
+ Model override sekali jalan:
64
+
65
+ ```bash
66
+ minicode --model providerId::modelName "prompt"
67
+ minicode --provider openai "prompt"
68
+ minicode models --match gemini
69
+ ```
70
+
71
+ `MINICODE_PROVIDER_ORDER=openai,anthropic,deepseek` mengurutkan provider agnostik tanpa edit config.
72
+
73
+ ## Pin eksplisit `provider::model` (kontrak)
74
+
75
+ Model berformat `providerId::modelName` = PIN: request hanya ke provider
76
+ itu — **tanpa fallback lintas provider dan tanpa substitusi diam-diam**.
77
+ Gagal = error jujur dari provider yang dipilih (limit/saldo/error server),
78
+ user memilih model lanjutannya sendiri via `/model`. Alasan: fallback
79
+ otomatis pernah melempar user dari model gratis ke model berbayar provider
80
+ lain (tagihan tak terduga). Model bare (tanpa `::`) tetap perilaku lama
81
+ (first-match + substitusi + fallback rate_limit/server/network).
82
+
83
+ ## Build & router
84
+
85
+ Build provider terpusat di `src/providers/build.ts`. Router fallback untuk rate_limit/server/network (clone-error + base64 fix + retryAfter cap). Deteksi wire dari probe path `/responses` → hint `responses`; substring host hanya fallback. `max_tokens` 8192; stop `length` = peringatan eksplisit, bukan teks sunyi.
86
+
87
+ Responses API: `/v1/responses`, `previous_response_id` chaining per model, `store:false` default.
package/docs/config.md ADDED
@@ -0,0 +1,63 @@
1
+ # Config — File & Lokasi Data
2
+
3
+ Di mana pengaturan dan data Minicode tinggal, dan bagaimana file lokal yang tak tepercaya diperlakukan.
4
+
5
+ ## Skema `.minicode/config.json`
6
+
7
+ ```json
8
+ {
9
+ "providers": [{ "id": "my-provider", "baseUrl": "...", "apiKey": "...", "models": ["gpt-4o"] }],
10
+ "mcpServers": [
11
+ { "id": "fs", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"] },
12
+ { "id": "remote", "url": "https://mcp.example.com/mcp", "headers": { "authorization": "Bearer xxx" } }
13
+ ],
14
+ "lspServers": [{ "ext": ".ts", "command": "typescript-language-server", "args": ["--stdio"] }],
15
+ "verifyCommand": "bun run typecheck",
16
+ "bashAllowlist": ["git status*", "bun test*", "npm run build*"]
17
+ }
18
+ ```
19
+
20
+ - `providers` — bisa juga diisi lewat wizard/`minicode config add`/`/provider` (14 preset, lihat [Config & Provider](config-providers.md)).
21
+ - `mcpServers` — dua bentuk: stdio (`command`+`args`) dan HTTP (`url`+opsional `headers`). Detail transport di [MCP & LSP](mcp-lsp.md).
22
+ - `verifyCommand` — dipakai `--verify` bila auto-detect tidak menemukan (urutan deteksi: `typecheck` → `test` → `tsconfig`).
23
+ - `bashAllowlist` — pola koma/pola glob perintah bash yang dianggap aman (mode `allowlist`).
24
+
25
+ ## Global vs lokal
26
+
27
+ | File | Lokasi | Catatan |
28
+ |---|---|---|
29
+ | Global | `~/.minicode/config.json` | Berlaku semua workspace |
30
+ | Lokal | `.minicode/config.json` | Per repo; **diabaikan secara default** — aktif dengan `--allow-local-config` / `MINICODE_ALLOW_LOCAL_CONFIG=1` |
31
+
32
+ Merge dengan **prioritas lokal menang**. Mutasi (add/update provider, MCP, LSP) ditulis ke file scope asal — bukan hasil merge — agar tidak duplikat/shadowing. Semua tulis file config atomik (tmp+rename randomUUID) + chmod 600.
33
+
34
+ **Kenapa lokal default-diabaikan:** `.minicode/config.json` sering ikut ter-commit; repo yang Anda clone bisa mendaftarkan MCP server atau menyedot prompt lewat config. Percayai hanya di workspace milik Anda.
35
+
36
+ ## Token OAuth bukan di config
37
+
38
+ Kredensial OAuth di `~/.minicode/auth.json` (chmod 600) — terpisah dari config karena config lokal rawan ikut ter-commit sedangkan token rahasia berumur pendek. Provider OAuth menyimpan `apiKey: ""` di config dan mengambil token saat runtime. Detail di [Config & Provider](config-providers.md).
39
+
40
+ ## Lokasi data
41
+
42
+ | Path | Isi |
43
+ |---|---|
44
+ | `~/.minicode/config.json` | Config global |
45
+ | `~/.minicode/auth.json` | Token OAuth (chmod 600) |
46
+ | `.minicode/config.json` | Config lokal (default diabaikan) |
47
+ | `.minicode/sessions.db` | Sessions SQLite (WAL, capped + busy-retry) |
48
+ | `vector.db` | Index memory vector hybrid |
49
+ | `.minicode/repomap.json` | Cache repo-map (sig mtime) |
50
+ | `.minicode/traces.jsonl` | Telemetry per run (prompt di-scrub) |
51
+ | `.minicode/step-traces.jsonl` | Trace keputusan tool (sumber `minicode stats`) |
52
+ | `.minicode/checkpoints/` | Manifest checkpoint (cap 20 terbaru) |
53
+ | `.minicode/todos/<id>.json` + `.minicode/plans/<id>.md` | Rencana per sesi |
54
+ | `.minicode/.trash/` | Soft-delete `delete_file` (cap 100, gitignored) |
55
+ | `.minicode/MEMORY.md` + hierarki | File memory (global → lokal → root) |
56
+
57
+ Override home untuk semua DB lokal/global: `MINICODE_HOME` (terutama agar test hermetic di POSIX, di mana `homedir()` mengabaikan `$HOME`).
58
+
59
+ ## Lanjut
60
+
61
+ - [Environment Variables](environment.md) — semua `MINICODE_*`.
62
+ - [Memory & Sessions](memory-sessions.md) — isi `vector.db`, sesi, checkpoint.
63
+ - [Policy & Sandbox](policy-sandbox.md) — kenapa tulis config selalu atomik + chmod 600.