luang-cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,199 @@
-# Temporary Holding Version
+# luang-cli
 
-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.
+CLI Agent Orchestration **Luang** — login device flow, sinkronisasi provider AI local, daemon agent (heartbeat + polling tugas), dan manajemen task dari terminal.
+
+- **Zero-dependency**: tidak ada `npm install` — hanya bawaan Node.js (`fetch`, `node:fs`, `node:readline`, `child_process`).
+- **Node.js ≥ 18** (butuh global `fetch`).
+- API default: `https://api.luang.id` · Dashboard: `https://app.luang.id`
+
+---
+
+## Instalasi
+
+Dari folder repo ini (lokal):
+
+```bash
+npm i -g .
+```
+
+Setelah package dipublish, cukup:
+
+```bash
+npm i -g luang-cli
+```
+
+Cek instalasi:
+
+```bash
+luang-cli help
+```
+
+---
+
+## Konfigurasi lokal
+
+File config: `~/.luang-cli/config.json` (dibuat otomatis saat login simpan key):
+
+```json
+{
+  "api_url": "https://api.luang.id",
+  "app_url": "https://app.luang.id",
+  "key": null,
+  "default_provider": null,
+  "providers": {}
+}
+```
+
+Override (urutan: flag → env → config):
+
+| Sumber | Tutorial |
+|---|---|
+| `LUANG_API_URL` | Timpa `api_url` |
+| `LUANG_APP_URL` | Timpa `app_url` |
+| `LUANG_KEY` | Timpa key (tanpa menyentuh config) |
+| `--api <url>` | Timpa URL API di command mana pun |
+
+---
+
+## Alur login → verify (device flow)
+
+1. Jalankan:
+
+   ```bash
+   luang-cli login --name "Laptop Kantor"
+   ```
+
+2. CLI meminta `device_code` + `user_code` dari `POST /api/v1/agent/device/start`.
+   Kode besar ditampilkan gaya banner ASCII dan browser dibuka ke `verify_url`
+   (bila browser gagal, URL tetap dicetak — cukup buka manual).
+3. Masukkan `user_code` di dashboard, lalu **approve**.
+4. CLI mem-poll `GET /api/v1/agent/device/poll` tiap 2 detik (batas 10 menit):
+   - `approved` + `api_key` → key tersimpan, CLI mencetak nama sesi, tenant, dan prefix key (`lk_xxxxxx…`).
+   - `approved` **tanpa** `api_key` → key sudah pernah diambil sebelumnya; pakai key lama atau buat sesi agent baru di dashboard.
+   - `denied` / `expired` → pesan jelas + exit 1.
+5. Verifikasi:
+
+   ```bash
+   luang-cli whoami
+   ```
+
+---
+
+## Daftar command
+
+| Command | Fungsi | Contoh |
+|---|---|---|
+| `login` | Login device flow via browser | `luang-cli login --name "Laptop Kantor"` |
+| `logout` | Hapus API key tersimpan (`-y` tanpa konfirmasi) | `luang-cli logout -y` |
+| `whoami` | Info sesi, tenant, izin | `luang-cli whoami` |
+| `provider list` | Deteksi + tabel provider (`--json`) | `luang-cli provider list` |
+| `provider add` | Tambah/override provider di config | `luang-cli provider add opencode --exec_template 'opencode run "{task}"'` |
+| `provider remove` | Hapus provider dari config | `luang-cli provider remove codex` |
+| `provider default` | Set default provider (dipakai `agent --exec`) | `luang-cli provider default opencode` |
+| `agent` | Daemon heartbeat + polling tugas | `luang-cli agent --interval 5 --exec` |
+| `task list` | Daftar tugas (filter) | `luang-cli task list --status todo` |
+| `task create` | Buat tugas (butuh izin admin) | `luang-cli task create --title "Refactor auth" --priority high --due 2026-11-01` |
+| `task status` | Ubah status tugas | `luang-cli task status TGS-12 in_progress --note "mulai analisis"` |
+| `status` | Ringkasan CLI (key/tenant/izin/provider) | `luang-cli status` |
+| `mcp-config` | Snippet konfigurasi MCP | `luang-cli mcp-config` |
+
+Bantuan per command: `luang-cli <command> --help` (contoh `luang-cli agent --help`).
+
+---
+
+## Izin agent di dashboard
+
+Beberapa aksi butuh izin yang diberikan admin/owner lewat dashboard
+(**Agents → izin**):
+
+| Aksi CLI | Izin | Field |
+|---|---|---|
+| `task create` | Bisa-buat-tugas | `can_create_tasks` (HTTP 403 bila belum aktif) |
+| `agent --exec` / `task status` | Bisa-update-tugas | `can_update_tasks` |
+
+Cek izin kapan pun dengan `luang-cli whoami` atau `luang-cli status`.
+
+---
+
+## Integrasi provider (manual)
+
+`luang-cli provider list` mendeteksi otomatis:
+
+- `~/.claude` → `claude_code`
+- `~/.codex` → `codex`
+- `~/.config/opencode` atau `~/.opencode` → `opencode`
+- `~/.gemini` → `gemini_cli`
+- plus `which(1)` untuk binary `claude`, `codex`, `opencode`, `gemini`
+
+Bila tidak terdeteksi (atau butuh aturan khusus), daftarkan manual:
+
+```bash
+luang-cli provider add claude_code --path /usr/local/bin/claude \
+  --exec_template 'claude -p "{task}"'
+luang-cli provider add codex      --exec_template 'codex exec "{task}"'
+luang-cli provider add opencode   --exec_template 'opencode run "{task}"'
+luang-cli provider default opencode
+```
+
+`{task}` pada `exec_template` otomatis diganti **judul + deskripsi** tugas.
+Template tanpa `{task}` tidak bisa dipakai mode `--exec`.
+Bila key sudah ada, daftar provider otomatis disinkron ke server lewat
+`POST /api/v1/agent/heartbeat`.
+
+---
+
+## Daemon agent
+
+```bash
+luang-cli agent            # heartbeat 30 detik, poll tugas 5 detik
+luang-cli agent --interval 10 --exec
+```
+
+- Heartbeat (`POST /api/v1/agent/heartbeat`) tiap 30 detik.
+- Polling `GET /api/v1/agent/tasks` tiap `--interval` detik (default 5).
+- Perubahan tugas dicetak satu baris: `TGS-1  Judul  In Progress  [agent_status] note`.
+- State daftar run disimpan di `~/.luang-cli/state.json` (terakhir `agent_updated_at`/`updated_at` per tugas + riwayat tugas yang sudah dieksekusi).
+- `--exec`: tugas berstatus `To-Do` yang belum dijalankan, saat default provider punya `exec_template` berisi `{task}`:
+  1. konfirmasi `y/N` di terminal,
+  2. status dikirim `in_progress` (`agent_status: menjalankan`),
+  3. template dijalankan via `child_process.exec` setelah `{task}` diganti,
+  4. exit 0 → `done` ("selesai", note `exec exit 0`); gagal → `review` ("gagal", note `exit code N`).
+- `Ctrl+C` menghentikan daemon dengan bersih (exit 0).
+
+---
+
+## Konfigurasi MCP
+
+`luang-cli mcp-config` mencetak blok JSON siap-tempel untuk klien MCP
+(endpoint `POST /api/v1/agent/mcp`, autentikasi header `X-CLI-Key`):
+
+```json
+{
+  "mcpServers": {
+    "luang": {
+      "type": "http",
+      "url": "https://api.luang.id/api/v1/agent/mcp",
+      "headers": {
+        "X-CLI-Key": "lk_xxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+Ganti `lk_xxxxxxxx` dengan key asli (bila sudah `login`, CLI menuliskannya
+otomatis).
+
+---
+
+## Troubleshooting
+
+| Gejala | Solusi |
+|---|---|
+| `❌ Belum login` | Jalankan `luang-cli login`, atau set env `LUANG_KEY` |
+| HTTP 401 di semua command | Key ditolak → `luang-cli logout` lalu `login` ulang |
+| HTTP 403 saat `task create` | Minta admin aktifkan izin **Bisa-buat-tugas** |
+| Timeout 15 detik | Cek jaringan / coba `--api <url>` menunjuk API yang benar |
+| Tabel provider kosong | Daftar manual `provider add <type> --exec_template '…'` |
+| `--exec` tidak berjalan | Pastikan `provider default <type>` + template berisi `{task}` |
+| Mulai bersih | Hapus `~/.luang-cli/state.json` (riwayat eksekusi & status) |

package/bin/luang-cli.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+'use strict';
+
+// bin/luang-cli.js — entry point CLI Luang: parsing argumen, dispatch, help.
+
+const pkg = require('../package.json');
+const core = require('../lib/core');
+const c = require('../lib/commands');
+const ag = require('../lib/agent');
+
+const OVERVIEW = `luang-cli v${pkg.version} — CLI Agent Orchestration Luang
+
+Penggunaan: luang-cli <command> [sub] [opsi]
+
+Command:
+  login       Login device flow via browser        luang-cli login --name "Laptop"
+  logout      Hapus API key tersimpan              luang-cli logout [-y]
+  whoami      Info sesi agent, tenant & izin       luang-cli whoami
+  provider    Kelola provider CLI coding           luang-cli provider list
+  agent       Daemon heartbeat + polling tugas     luang-cli agent [--interval 5] [--exec]
+  task        Kelola tugas (list|create|status)    luang-cli task list
+  status      Ringkasan CLI (key, tenant, izin)    luang-cli status
+  mcp-config  Snippet konfigurasi MCP klien        luang-cli mcp-config
+
+Opsi global:
+  --api <url>   Override URL API (default https://api.luang.id)
+  -h, --help    Bantuan (juga: luang-cli help <command>) · --version
+
+Detail: luang-cli help <command>`;
+
+const TOPICS = {
+  login: `luang-cli login — login via device flow
+
+Penggunaan:
+  luang-cli login [--name <label>]
+
+Opsi:
+  --name <label>   Nama sesi/agent (default: hostname — CLI)
+
+Alur:
+  1. CLI meminta device_code + user_code dari API
+  2. Browser terbuka ke halaman verify (bila gagal, URL cukup dicetak)
+  3. Masukkan user_code di dashboard, klik approve
+  4. API key tersimpan di ~/.luang-cli/config.json
+     "approved" tanpa api_key berarti key sudah pernah diambil sebelumnya.
+
+Contoh:
+  luang-cli login
+  luang-cli login --name "Laptop Kantor"`,
+
+  logout: `luang-cli logout — hapus API key dari ~/.luang-cli/config.json
+
+Penggunaan:
+  luang-cli logout [-y]
+
+Opsi:
+  -y, --yes   Langsung hapus tanpa konfirmasi
+
+Catatan: env LUANG_KEY (bila ter-set) tetap override.`,
+
+  whoami: `luang-cli whoami — info sesi agent dari GET /api/v1/agent/me
+
+Penggunaan:
+  luang-cli whoami
+
+Menampilkan: nama sesi, status, key id, tenant, last seen,
+izin can_update_tasks / can_create_tasks, dan provider terdaftar.`,
+
+  provider: `luang-cli provider — kelola provider CLI coding
+
+Penggunaan:
+  luang-cli provider list [--json]
+      Deteksi otomatis: ~/.claude (claude_code), ~/.codex (codex),
+      ~/.config/opencode atau ~/.opencode (opencode), ~/.gemini (gemini_cli),
+      plus which(1) untuk claude, codex, opencode, gemini.
+      Bila key ada, hasil langsung disinkron via POST /api/v1/agent/heartbeat.
+  luang-cli provider add <type> [--path P] [--exec_template T]
+  luang-cli provider remove <type>
+  luang-cli provider default <type>
+
+Param exec_template:
+  {task} diganti judul + deskripsi tugas saat mode --exec.
+  Contoh: 'claude -p "{task}"', 'opencode run "{task}"', 'codex exec "{task}"'
+
+Contoh:
+  luang-cli provider add opencode --exec_template 'opencode run "{task}"'
+  luang-cli provider default opencode`,
+
+  agent: `luang-cli agent — daemon agent (heartbeat + polling tugas)
+
+Penggunaan:
+  luang-cli agent [--interval N] [--exec]
+
+Opsi:
+  --interval N   Jeda polling GET /api/v1/agent/tasks (detik, default 5)
+  --exec         Eksekusi otomatis tugas "To-Do" yang belum dijalankan
+
+Perilaku:
+  • POST /api/v1/agent/heartbeat tiap 30 detik
+  • Polling GET /api/v1/agent/tasks tiap N detik; baris berubah dicetak:
+      TGS-1  Judul  In Progress  [agent_status] note
+  • State: ~/.luang-cli/state.json
+  • --exec: tugas To-Do + default provider punya exec_template berisi {task}
+    perlu konfirmasi y/N lalu dijalankan; sebelum eksekusi status di-set
+    in_progress ("menjalankan"), lalu done ("selesai") bila exit 0,
+    review ("gagal") bila gagal.
+  • Ctrl+C menghentikan daemon dengan bersih.`,
+
+  task: `luang-cli task — kelola tugas
+
+Penggunaan:
+  luang-cli task list [--status todo|in_progress|review|done]
+  luang-cli task create --title "Judul" [--desc "…"] [--priority high|medium|low] [--due 2026-01-02]
+  luang-cli task status <TGS-12|uuid> <todo|in_progress|review|done> [--note "…"] [--agent-status "…"]
+
+Catatan:
+  • task create butuh izin admin "Bisa-buat-tugas" (can_create_tasks)
+  • task status butuh izin "Bisa-update-tugas" (can_update_tasks)
+
+Contoh:
+  luang-cli task list --status todo
+  luang-cli task create --title "Refactor auth" --priority high --due 2026-11-01
+  luang-cli task status TGS-12 in_progress --note "mulai analisis"`,
+
+  status: `luang-cli status — ringkasan CLI
+
+Penggunaan:
+  luang-cli status
+
+Menampilkan: API/App URL, key prefix, tenant, izin,
+default provider & provider lokal, lokasi config/state.`,
+
+  'mcp-config': `luang-cli mcp-config — snippet konfigurasi MCP
+
+Penggunaan:
+  luang-cli mcp-config
+
+Mencetak blok JSON mcpServers untuk klien MCP: endpoint
+POST /api/v1/agent/mcp dengan header X-CLI-Key. Key dipakai dari
+config bila sudah login, selain itu placeholder.`,
+
+  help: OVERVIEW,
+};
+
+// ── Parsing argumen ──────────────────────────────────────────────────────────
+
+const VALUE_FLAGS = new Set([
+  'name', 'path', 'exec_template', 'interval', 'status', 'title', 'desc',
+  'description', 'priority', 'due', 'note', 'agent-status', 'api',
+]);
+
+function parseArgs(argv) {
+  const pos = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') {
+      for (const x of argv.slice(i + 1)) pos.push(x);
+      break;
+    }
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      if (eq > 2) {
+        flags[a.slice(2, eq)] = a.slice(eq + 1);
+        continue;
+      }
+      const name = a.slice(2);
+      const next = argv[i + 1];
+      if (VALUE_FLAGS.has(name) && next !== undefined && !next.startsWith('-')) {
+        flags[name] = next;
+        i++;
+      } else {
+        flags[name] = true;
+      }
+    } else if (a.startsWith('-') && a.length >= 2) {
+      const name = a.slice(1);
+      if (name === 'h') flags.help = true;
+      else flags[name] = true;
+    } else {
+      pos.push(a);
+    }
+  }
+  return { pos, flags };
+}
+
+function printHelp(topic) {
+  const t = TOPICS[topic || 'help'];
+  if (!t) {
+    console.error(`❌ Command tidak dikenal: ${topic}`);
+    console.error('');
+    console.log(OVERVIEW);
+    return 1;
+  }
+  console.log(t);
+  return 0;
+}
+
+// ── Dispatch ─────────────────────────────────────────────────────────────────
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const flags = args.flags;
+  const cmd = args.pos[0];
+
+  if (flags.version === true) {
+    console.log(`luang-cli v${pkg.version}`);
+    return 0;
+  }
+  if (!cmd || flags.help === true) {
+    return printHelp(cmd || 'help');
+  }
+  if (cmd === 'help') {
+    return printHelp(args.pos[1] || 'help');
+  }
+
+  const rt = core.resolveRuntime(core.loadConfig(), flags);
+  switch (cmd) {
+    case 'login':
+      return c.cmdLogin(rt, args);
+    case 'logout':
+      return c.cmdLogout(rt, args);
+    case 'whoami':
+      return c.cmdWhoami(rt, args);
+    case 'provider':
+      return c.cmdProvider(rt, args);
+    case 'agent':
+      return ag.cmdAgent(rt, args);
+    case 'task':
+      return ag.cmdTask(rt, args);
+    case 'status':
+      return ag.cmdStatus(rt, args);
+    case 'mcp-config':
+      return ag.cmdMcpConfig(rt, args);
+    default: {
+      console.error(`❌ Command tidak dikenal: ${cmd}`);
+      console.error('   Jalankan `luang-cli help` untuk daftar command.');
+      return 1;
+    }
+  }
+}
+
+main()
+  .then((code) => process.exit(code === undefined ? 0 : code))
+  .catch((e) => {
+    console.error(`❌ ${e && e.message ? e.message : e}`);
+    process.exit(1);
+  });