@ywldan/karsa 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karsa contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,208 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# ▚▞ Karsa
+
+**"Ember in the terminal"** — agentic coding CLI berbasis Rust yang ringan,
+dengan TUI fullscreen, daemon multi-sesi, dan keamanan berlapis.
+
+`v0.1.0` · Rust 2024 · workspace 17 crate · semua teks UI Bahasa Indonesia
+
+</div>
+
+---
+
+## Tangkapan layar
+
+Frame berikut adalah tangkapan **nyata** dari TUI (pty + emulasi ANSI `pyte`,
+binary `target/release/karsa`):
+
+```text
+ karsa  default · mock                                                      ctx 0% ·  · - t/s · 0s ·
+ℹ ▚▞ karsa v0.1.0 — ketik prompt; `/` palette; Ctrl+C 2× keluar           TODO  FILES  PLAN  MCP  TAB
+                                                                        ────────────────────────────
+ℹ mcp: 1 server aktif — 1 terhubung, 0 gagal (rincian `/mcp`)
+╭ /cmd · ⏎ kirim · ⇧⏎ antri · ↑ riwayat ───────────────────────────────────────────────────────────╮
+│▸                                                                                                 │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+(Warna asli: palet *dark orange × black* dari `karsa-theme`; tangkapan teks
+kehilangan warna. Rekaman animasi/asciinema menyusul — lihat [Kurang](#yang-masih-kurang).)
+
+## Ini apa?
+
+**Karsa** adalah pengkodean bersama agen (agentic coding harness) seperti jcode /
+Claude Code, tetapi di terminal Rust: satu binary, TUI fullscreen `ratatui +
+crossterm`, lapisan provider pluggable, sistem tool dengan izin bertingkat, sesi
+JSONL, daemon multi-klien via unix socket, dan protokol NDJSON bermigrasi
+(`karsa-sdk`) — semua dirancang untuk lingkungan offline/self-hosted dengan
+endpoint OpenAI-compatible apa pun.
+
+Silahkan lihat dokumen lengkap spesifikasi di [`KARSA-BUILD.md`](KARSA-BUILD.md)
+(= sumber kebenaran proyek & roadmap Fase 0–6).
+
+## Fungsi utama
+
+| Area | Fungsi |
+|---|---|
+| **TUI** | fullscreen (3 layout `zen/split/wide`, panel `TODO/FILES/PLAN/MCP`, mode status `rich/slim/off`), palette `/` dengan autocomplete, markdown render, Git/`vim` opsional (⚠ *stub*: `/keybinds`, `/vim`) |
+| **Headless** | `karsa run "<prompt>"` (`-p`): `--output-format text\|json\|stream-json`, `--resume`, `--model/provider`, `--effort`, `--allowed-tools`, `--permission-mode` |
+| **Provider** | lapisan pluggable `Provider`: kind `openai-compatible` (SSE toleran, retry 429/5xx, non-stream fallback), auth `env/file/command/none`, kind `mock` buat uji; wizard `/provider add` + CLI `provider add/test/use/list` |
+| **Tool & izin** | 12 tool bawaan (`read_file`, `write_file`, `edit_file`, `multi_edit`, `patch`, `ls`, `glob`, `grep`, `run_cmd`, `todo_write`, `plan_submit`, `skill`), 4 mode izin (`ask/workspace-write/read-only/yolo`), risiko terklasifikasi (`safe/needs-approval/destructive`), path-guard workspace |
+| **Hooks** | 5 mata acak (`session_start`, `user_prompt_submit`, `pre_tool_use`, `post_tool_use`, `stop`) via shell commands + `KARSA_TOOL`; exit 2 = blokir |
+| **Sesi** | `~/.karsa/sessions/<id>.jsonl` + index `sessions.json`, `/resume`, `/fork`, `/export`, checkpoint & `/undo`, kompaksi otomatis per ambang konteks |
+| **MCP** | klien MCP transport `stdio` + `http`, proxy menjadi tool `mcp__<server>__<tool>`, panel dan CLI `mcp add/list` |
+| **Skill** | skill di `~/.karsa/skills/<n>/SKILL.md` — deskripsi masuk system prompt, isi dimuat lazy via tool `skill`; skill bawaan tersemat (feature `embed`) |
+| **Daemon** | `karsa daemon start/stop/status` — server unix socket multi-klien, tiap klien = 1 agen ber-nama, turn paralel, pesan antar agen (DM/broadcast), jejak konflik file + lock ber-umur turn; TUI `/daemon status|attach <id>|detach` mengikuti file sesi dekat waktu nyata |
+| **karsa-sdk** | protokol NDJSON versi 1 (`hello/ping/turn/stop/message/broadcast/sessions/swarm/bye`) + client async + `karsa sdk schema` |
+| **Slash commands** | **68 perintah tepat terdaftar** (≥ 58 syarat §15.3) dengan metadata (alias, argumen, summary, help, scope); yang belum tersedia tampil `not-implemented` — tidak pernah senyap |
+
+## Mulai cepat
+
+```bash
+# bangun
+cargo build --release -p karsa-cli
+alias karsa='/home/ubuntu/Karsa/target/release/karsa'   # sesuaikan jalur
+
+# TUI
+karsa
+
+# headless
+karsa run "jelaskan repo ini dengan singkat" -p  # = karsa -p "..."
+
+# endpoint mock lokal untuk uji tanpa API key
+karsa provider add --name mock --kind openai-compatible \
+  --base-url http://127.0.0.1:8992/v1 --auth none --model mock-1
+
+# daemon multi-sesi + klien socket
+karsa daemon start
+karsa sdk schema   # protokol NDJSON lengkap
+```
+
+Config di `KARSA_HOME` (default `$HOME`): `$KARSA_HOME/.karsa/config.toml`.
+Preseden: **flag CLI > env `KARSA_*` > `.karsa/config.toml` proyek >
+`~/.karsa/config.toml` global > default bawaan** (komentar file dipertahankan).
+
+Rincian: [`PROVIDERS.md`](docs/PROVIDERS.md) ·
+[`SLASH_COMMANDS.md`](docs/SLASH_COMMANDS.md) · [`THEME.md`](docs/THEME.md) ·
+[`LAYOUT.md`](docs/LAYOUT.md) · [`SECURITY.md`](docs/SECURITY.md) ·
+dokumen self-dev: [`KARSA.md`](KARSA.md).
+
+## CLI
+
+```text
+karsa                    # TUI (default)
+karsa run|run -p "..."   # headless satu shot
+karsa config get|set|list|edit|path
+karsa provider list|add|...   # kelola endpoint
+karsa sessions list|show|resume|rm
+karsa doctor [--deep]    # ⚠ --deep diparse tapi belum menambah cek
+karsa mcp list|add|...
+karsa skills | context | plan <prompt>
+karsa sdk schema         # skema protokol NDJSON
+karsa daemon start|stop|status
+karsa completions <shell>
+karsa about / --help
+```
+
+
+## Arsitektur (17 crate)
+
+| Crate | Tanggung jawab |
+|---|---|
+| `karsa-theme` | satu-satunya sumber warna: 24 token semantik, deteksi profil terminal, tema `\*.toml` |
+| `karsa-config` | schema config + loader berlapis + editor TOML aman-komentar |
+| `karsa-slash` | parser/registry/palette/dispatch slash (§15) |
+| `karsa-security` | mode izin, path guard, risiko, klasisifikasi, authorizer |
+| `karsa-tools` | trait `Tool`, `ToolCtx`, registry + laporan tool bawaan, hook runner, skill lazy |
+| `karsa-core` | loop agent, mesin turn, komposer konteks, hitung token (§8) |
+| `karsa-provider-core` | tipe inti provider: pesan/tool/event streaming/`WireApi`/`CancelToken` |
+| `karsa-provider-compat` | generik `openai-compatible` + parser SSE toleran + retry + `MockProvider` |
+| `karsa-provider-anthropic` / `-ollama` / `-openai` | kerangka provider native (belum dirute broker; stub saat ini) |
+| `karsa-mcp` | klien MCP `stdio` + `http`, proxy ke `mcp__<server>__<tool>` |
+| `karsa-store` | sesi JSONL + `sessions.json` + ekspor markdown |
+| `karsa-git` | helper git via subprocess (ringan, §4.2) |
+| `karsa-tui` | aplikasi `ratatui`: state, renderer, markdown-lite, input |
+| `karsa-sdk` | protokol NDJSON + `KarsaClient` async (§17) |
+| `karsa-cli` | binary: `engine` (rakit agent bersama run/daemon), `run`, `tui_cmd`, `daemon`, `doctor`, dispatch |
+
+### Deteksi daemon (§17)
+
+```text
+[klien karsa / klien extern] --unix-- \(daemon.sock) karsa daemon-server
+                                        ├─ 1 klien = 1 agen (rename via hello)
+                                        ├─ turn paralel per koneksi (id balasan = id permintaan)
+                                        ├─ agent_message / broadcast → swarm_note (id 0)
+                                        └─ jejak akses file → swarm_conflict + lock .karsa/locks/
+```
+
+## Angka terukur (binary `release`; diukur nyata, bukan karangan)
+
+| Metrik | Syarat (§21) | Hasil |
+|---|---|---|
+| First frame TUI | < 30 ms | **13,7 ms** (debug 10–34 ms) |
+| RSS idle | < 40 MB | **6,3 MB** (debug 17,4 MB) |
+| Ukuran binary | < 20 MB | **4,2 MB** (`opt-level="z"` + LTO + strip) |
+| `cargo tree` runtime | < 350 crates | **185** crates unik |
+| Test workspace | hijau | **143 pass / 0 fail** |
+| fmt + clippy | bersih | 0 temuan |
+
+## Uji & gerbang
+
+Unit = Rust (`cargo test`); integrasi = provider `mock` (server SSE/file lokal
+`/tmp/opencode/mock-openai.py`, mode `normal/tool/mcp/compact/dm`); gerbang pty =
+simulasi terminal via `pyte`, menguji TUI ujung-ke-ujung (wizard, extensi, MCP, daemon,
+swarm, `/swarm`). Semua hijau selangkah per milestone — hasil terakhir:
+
+```text
+gate-dmn 23/23  ·  gate-swarm 17/17  ·  pty-swm 1/1
+pty-wiz 9/9  ·  pty-ext 10/10  ·  pty-mcp 8/8
+cargo test --workspace: 143 pass / 0 fail
+```
+
+## Yang masih kurang
+
+Kejujuran (hasil audit DoD hari ini, detail di `KARSA-BUILD.md` §21):
+
+- **Gate #9 docs** — ✅ dicatat (dokumen set ini).
+- **Gate #2 provider** — ◐ lulus sebagian: 2 endpoint terbukti di gerbang (mock +
+  self-hosted), tapi **hanya 1 kind nyata**: `openai-compatible`. Kind
+  `anthropic` / `ollama` di broker masih `NotImplementedProvider` (stub yang
+  beri pesan jelas); crate `karsa-provider-{anthropic,ollama,openai}` ada
+  tapi belum dirutekan. `providers test` tersedia.
+- **Gate #8 benchmark di README** — ✅ setelah dokumen ini; tapi **CI benchmark**
+  (blokir regresi 10%) sentinel belum diadopsi.
+- **`/doctor --deep`** — ⚠ flag CLI diparser tapi belum menambah cek (diabaikan).
+- **Pendudukan / replay TUI** — tangkapan teks nyata di dokumen ini;
+  **screenshot/asciinema grafis** belum.
+- **Snapshot TUI (`TestBackend` golden)** + **fuzz SSE/prompt-injection** (§20) — belum ada.
+- **Event daemon**: `TurnStart/TurnEnd/State/Compact` belum dikirim lewat protokol
+  (dokumentasi parity di commit `feat(daemon)`); manajer MCP hangat per-daemon
+  belum. ✅ **`/daemon status|attach|detach` di TUI** sudah nyata — attach mengikuti
+  file sesi JSONL (hanya-baca, per-socket event tidak dipancarkan antar-klien);
+  memakai turn sesi orang lain menunggu request `subscribe` protokol.
+- **Mode izenhaks**: `write_file` di daemon mematuhi mode config; default `ask`
+  menolak headless (pesan: `mode ask — headless tak bisa tanya`).
+- **`/bench`, self-dev mode, audit alokasi/cap RSS** — belum dibuat.
+- ✅ **self-update `karsa update`** sudah nyata (cek `--check` + pasang
+  atomik; kontrak sumber di `update.rs`; gerbang `gate-update` 9/9).
+- **`karsa update`** stub (cetak pesan).
+- **Slash stub**: masih ada beberapa perintah di registry dgn `Handler::Stub`
+  (lihat dokumen `SLASH_COMMANDS.md` untuk daftar tak-silent).
+
+## Struktur proyek
+
+```text
+Cargo.toml           # workspace; profile release z/lto/strip
+KARSA-BUILD.md       # spesifikasi build + roadmap Fase 0–6 + DoD
+KARSA.md             # arsitektur self-dev (untuk introspeksi Karsa sendiri)
+README.md            # dokumen ini
+docs/                # PROVIDERS · SLASH_COMMANDS · THEME · LAYOUT · SECURITY
+crates/              # 17 crate — lihat tabel Arsitektur
+```
+
+## Lisensi & kredit
+
+MIT (file [`LICENSE`](LICENSE)). Desain terinspirasi
+**jcode** (1jehuang, https://github.com/1jehuang/jcode) — kredit di `/about`.
+UI default **Bahasa Indonesia** (`[ui] language = "id"`, fallback `en`).

package/bin/karsa.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+const { execSync } = require('child_process');
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+
+const platform = os.platform();
+const arch = os.arch();
+
+let binaryName = 'karsa';
+if (platform === 'win32') {
+  binaryName += '.exe';
+}
+
+// Determine the directory where this script resides
+const __dirname = path.dirname(process.mainModule.filename);
+const binaryPath = path.join(__dirname, '..', binaryName);
+
+// If the binary exists next to the script (in the package root), run it
+if (fs.existsSync(binaryPath)) {
+  try {
+    execSync(`"${binaryPath}" ${process.argv.slice(2).join(' ')}`, { stdio: 'inherit' });
+  } catch (e) {
+    process.exit(e.code);
+  }
+} else {
+  // Fallback: try to run from PATH (in case user installed globally via other means)
+  try {
+    execSync(`${binaryName} ${process.argv.slice(2).join(' ')}`, { stdio: 'inherit' });
+  } catch (e) {
+    console.error(`Karsa binary not found. Please install it via cargo install karsa-cli or download a release from GitHub.`);
+    process.exit(1);
+  }
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@ywldan/karsa",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Karsa - Rust agentic coding CLI",
+  "bin": {
+    "karsa": "./bin/karsa.js"
+  },
+  "files": [
+    "bin/",
+    "README.md",
+    "karsa"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ywildan/karsa-cli-landing.git"
+  },
+  "keywords": [
+    "cli",
+    "coding",
+    "agent",
+    "rust",
+    "terminal"
+  ],
+  "author": "Karsa contributors",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/ywildan/karsa-cli-landing/issues"
+  },
+  "homepage": "https://github.com/ywildan/karsa-cli-landing#readme"
+}