zesdex/TODO.md

TODO — Rewrite Zesdex Rust → TypeScript/Bun

Plan lengkap migrasi in-place dari Rust (11 crate, clean architecture 4 lapis) ke monorepo TypeScript/Bun. Bahasa Indonesia, commit pakai Conventional Commits.

Status: Fase 0–6 semua selesai. Rust source dihapus, build CI/Docker/release pakai Bun, flake.lock Rust/Nix dibersihkan, wire-shape lama terbaca. Base: bun run check bersih, 70 test hijau.

---

Prinsip & peta pemetaan

Rust	TS/Bun
serde_json	JSON.stringify/parse + zod
chrono	Date / Date.now() (epoch ms)
uuid	crypto.randomUUID()
sha2, base64 URL_SAFE_NO_PAD	node:crypto / Buffer.toString('base64url')
reqwest	fetch / bun HTTP
rusqlite	bun:sqlite
argon2	@node-rs/argon2
jsonwebtoken	node:crypto HMAC HS256
rmcp	@modelcontextprotocol/sdk
ratatui/crossterm	library TUI Bun / ink
tiktoken-rs	@dqbd/tiktoken (cl100k_base)
clap	Bun.argv / commander
tokio semaphore	Bun async + concurrency pool
libc PID lock	node:fs O_EXCL + process.kill liveness
Rust generics S<R: Repo>	DI via constructor interface
Arc<Mutex<T>>	objek mutable (array/objek di ToolCtx)

Struktur target

apps/
  packages/            # ✅ sudah ada: domain, application, infrastructure
  interfaces/
    cli/               # gateway + TUI        [baru]
    api/               # REST API            [baru]
    daemon/            # daemon + IPC        [baru]
    ws/                # WebSocket server    [baru]
    grpc/              # stub                [baru]
    web/               # static server       [baru]

---

✅ Selesai

Fase 0 — Bootstrap monorepo

• package.json root (workspaces), tsconfig.json strict, .gitignore
• Paket domain, application, infrastructure (workspace @zesdex/*)
• bun install + bun test jalan

Fase 1 — Domain layer

• core: ChatMessage, Conversation, ChatRequest/Response/StreamEvent, SseParser, ToolCall, repairJson, sanitizeToolArguments, ToolCallResult, UsageStats, Store
• auth: Session, SessionId (path-traversal), OAuthToken/Config, repo/service trait
• cms: AppConfig, ProviderConfig, ModelRole, Settings+resolveEffectiveModel, SettingsPatch, Memory, EditLog, repo/service trait
• agent: Origin, Toast, AgentStatus, TurnEvent, SessionRuntime, AgentTurnParams, AgentProgress, ExecutionModel
• workflow/subagent: WorkflowScript/NodeDirective, AccessTier, prompt builders
• 27 test domain

Fase 2 — Application layer

• ports: ProviderService, PasswordService, TokenService, AuthService
• AgentTurnServiceImpl (loop 50 iter, auto-compact 60k, adaptive token, temp, ErrorTracker, bounded parallel)
• OAuthUseCase (PKCE S256 + CSRF state)
• SessionServiceImpl, MemoryServiceImpl, SettingsServiceImpl, ConversationServiceImpl
• 11 test application

Fase 3a — LLM client

• LlmClient (fetch, retry 10x backoff+jitter, abort 401/402/403)
• resolve_api_key, is_auth_error, backoff_for_error

Fase 3b — Tool system (commit a291dd1)

• Tool interface, ToolCtx/ToolCtxBuilder, InfrastructureToolExecutor
• Registry: allTools (37), toolDefs, toolIsRisky, toolIsParallelSafe
• FS: read, write, edit, delete · Guard: graduated checks, resolve_path sandbox
• Search: grep, glob (matcher ringan)
• Shell: bash (timeout), bash_output, bash_kill · Filter: checkGitDestructive, checkCredentialRead
• Git: git_operator, git_worktree, git_cred
• Memory: remember, forget, recall
• Util: cd, dir_list, dir_cache_update, pong, todowrite, todofinish
• Reasoning/Plan: sequential_think, plan_enter, plan_ready
• Web: web_search (async → SearXNG)
• Semantic: semantic_search, rebuild_index, list_symbols (index multi-bahasa)
• Best-practice: best_practice, commit_convention + BestPracticeEngine
• Agent/Workflow: spawn_agents, spawn_pipeline, parallel_delegate, workflow_run, note_finding, read_findings, hive_mind (delegasi ke placeholder 3c/3d)
• 16 test tool system

Fase 3e — Persistence

• File repos: settings, app_config (+ auto-detect kredensial Claude), conversation, edits.jsonl, markdown memory, rewind blob, session, oauth, session lock
• writeJsonAtomic, slugify, buildWorkspaceTree, runCommand

Fase 3c — Subagent engine

Sumber Rust: apps/infrastructure/src/subagent/{engine,division,context,provider,spawn}.rs, subagent/auto/*

• AccessTier.toolsFor(access) — tools/division.ts: Read / Write / Full yang mem-filter registry
• run_agent loop (tools/engine.ts): MAX_ITERATIONS=25, TOOL_OUTPUT_MAX_CHARS=12_000, MAX_CONSECUTIVE_TOOL_ERRORS=3, MAX_PARALLEL_TOOLS=8; recovery note setelah 3 error beruntun
• SubagentContext (subagent/context.ts) — directive, toolCtx, access, baseURL, apiKey, model
• spawn_subagent — spawn_tools.ts — runAgent berbasis HTTP provider + config_resolver
• resolve_subagent_provider (subagent/provider.ts) — pilih provider/model subagent dari settings + app_config
• spawn_tools.ts — isi body spawnAgents (paralel) & spawnPipeline (berurutan)
• delegate.ts — runParallelDelegation untuk parallel_delegate
• http_provider.ts — shared HTTP provider service builder
• Auto-reviewer (subagent/auto/*) — spawn_background_review: git diff → LLM review → perbaiki; wiring review_enabled (yang sekarang no-op di Review agent)
• Placeholder di apps/packages/infrastructure/src/subagent/* diisi penuh

Fase 3d — Workflow + hive-mind

Sumber Rust: apps/infrastructure/src/workflow/{script,mod,docs}.rs, workflow/engine/{execution,phases,primitives}.rs, workflow/hive_mind/{complexity,cycle,synthesis,live,types}.rs

• parse_workflow_script(yaml) — parser YAML workflow (workflow/script.ts)
• execute_workflow(script, ctx) — eksekusi multi-phase (workflow/engine.ts + workflow/orchestrate.ts)
• Phase primitives: run sub-agent per node (executePrimitive)
• execute_cycle(cycle, ctx) — hive-mind cycle, concurrency 8, kumpulkan NodeOutput (workflow/cycle.ts)
• synthesize_consensus(node_outputs, ctx) — konsensus via LLM + fallback concat (workflow/synthesis.ts)
• complexity_heuristic — pilih apakah cukup 1 cycle / butuh banyak (workflow/complexity.ts)
• docs.ts — tulis convergence/decision doc (workflow/docs.ts)
• Isi body WorkflowRun & HiveMind tool (ganti placeholder) di tools/workflow.ts
• orchestrate.ts — top-level executeWorkflow + executeHiveMind entry points

---

⬜ Yang belum dikerjakan

Fase 3f — Auth infrastructure

Sumber Rust: apps/infrastructure/src/auth/{password,jwt,oauth_loopback,mod}.rs

• password.ts — Argon2 via @node-rs/argon2 (hash + verify), port PasswordService
• jwt.ts — HMAC HS256 via node:crypto (access + refresh token, typ, exp), port TokenService
• oauth_loopback.ts — server TCP loopback lokal utk terima redirect OAuth; port oauth_loopback
• mod.ts (index.ts) — composisi ke AuthService
• Tambah dep @node-rs/argon2 di infrastructure/package.json

Fase 3g — IPC + bgbash

Sumber Rust: apps/infrastructure/src/ipc/{frame,protocol,server,client,conn}.rs, apps/infrastructure/src/bgbash/{job,control}.rs

• ipc/frame.ts — length-prefixed framing via node:net (kirim/terima bingkai biner)
• ipc/conn.ts — Connection framed JSON socket; ipc/protocol.ts — wire types
• ipc/server.ts + ipc/client.ts — Unix socket server + attach client; protocol message (NLJSON/binary)
• bgbash/job.ts — BashJob (pid, output file, log), spawnBashJob
• bgbash/control.ts — registry job global: register, cancel(job_id), is_running
• Wire bash tool run_in_background → spawnBashJob + register; bash_kill → cancel
• Update bash_output untuk baca dari registry/output dir

Fase 4 — Gateway + CLI + TUI

Sumber Rust: apps/gateway/src/{lib,main}.rs, apps/interfaces/tui/src/**

• apps/interfaces/cli/ (paket Bun):
  • Parser arg: --api/--daemon/--attach/--ws/--grpc/--web, dispatch mode (args.ts)
  • Logging ke file (index.ts)
  • run_single_process — komposisi root: wire semua implementasi konkret sekali (compose.ts) + REPL loop
  • Bootstrap seed (bootstrap.ts) — wire-shape settings lama terbaca
• CLI: parser arg + dispatch + single-process REPL loop + bootstrap seed (Smoke: bun run cli --help, bun run bootstrap jalan; loop turn + tool read/write)
• TUI mode (@zesdex/tui, tanpa ncurses — render garis ANSI):
  • Event loop raw-mode stdin (run.ts) + key decode (decodeKey)
  • Key dispatcher handleKey → Action[] + overlay/autocomplete/editor handling (controller.ts)
  • Action enum + applyAction dispatcher (action.ts) + slash-command parse/apply (command.ts)
  • InputState (buffer/cursor/history/autocomplete) + AppStateRest state machine (state.ts)
  • Renderer ringan (render.ts): transcript, input, overlay, status — 20 unit tests hijau
• Bootstrap seed (bootstrap) — bun run bootstrap seed defaults, wire-shape settings lama terbaca

Fase 5 — Server interface: api / daemon / ws / grpc / web

Sumber Rust: apps/interfaces/{api,daemon,ws,grpc,web}/src/**, apps/infrastructure/src/middleware/*

• API (apps/interfaces/api/):
  • Endpoint: auth (login/register/refresh, rate-limited), sessions CRUD, conversations, chat/completions proxy, health
  • JWT middleware, CORS
  • DTO (dto/)
• Smoke bun run api: health 200; register/login 200; wrong-pwd 401; protected-no-token 401; create/list/delete session; add conversation msg
• daemon — IPC agent-driver loop (Submit/Close) over per-session Unix socket; streaming token frames; wire CLI --daemon/--attach
• ws — handler /ws, protokol token/connected/done/error; smoke: no-token rejected 401, with-token welcome
• grpc — stub (health endpoint); smoke: /grpc/health 200
• web — static server + proteksi traversal; smoke: / serves index, traversal 404
• CLI --api/--ws/--grpc/--web dispatch → start server masing-masing (smoke: bun run cli --api --api-port → health 200)

Fase 6 — Bersih-bersih + verifikasi akhir

• Hapus semua sisa crate Rust: apps/{domain,application,infrastructure,gateway,bootstrap,interfaces/*} file .rs, Cargo.toml, Cargo.lock, .cargo/, lefthook.yml
• Update install.sh → Bun
• Update CI workflow: .github/workflows/{ci,release}.yml → bun install/bun test/bun run check
• Update Dockerfile → Bun (multi-stage, --compile single binary; d build verified)
• Ganti/luruskan tool release (semantic-release) ke pipeline Bun (release.yml test job → bun; prepareCmd → bun run check)
• flake.lock dead (Rust/Nix era) dihapus — deploy infra 100% Bun (deploy.yml bun build --compile + scp binary)
• Berkas jadi: hapus folder Rust yang sudah kosong dari apps/ + Cargo.toml/lock + .cargo + lefthook
• Verifikasi akhir: tsc --noEmit exit 0, bun test 74 hijau, bun run cli --help jalan
• Wire-shape lama terbaca — settings.json (Rust-era shape: api_keys/provider/model/review_*) dimuat true di headless + TUI; repos direct JSON parser. Verified: --headless "1+1" → "2", TUI header tunjuk claude-opus-5.

---

Verifikasi global (tiap fase)

• bun run build / tsc --noEmit tanpa error (strict)
• bun test — port test Rust ke *.test.ts (SseParser, repairJson, resolveEffectiveModel, SessionId, turn_service, tool system, subagent, workflow)
• Smoke: bun run cli --help; agent mode TUI dengan model stub/lokal; pastikan loop turn + tool read/write
• Server: bun run api + hit health/auth; bun run ws + connect
• Commit tiap fase dengan message Bahasa Indonesia + Conventional Commits; test hijau sebelum lanjut

Catatan

• Registry tool = 38 (terhitung workflow_run, note_finding, read_findings, hive_mind; ExploreCodebase tidak diport).
• Tool.run boleh return string | Promise<string>.
• spawn_agents/spawn_pipeline/parallel_delegate sudah terisi penuh via 3c.
• Workflow/hive-mind tools sudah terisi penuh via 3d.