███████╗██╗  ██╗███████╗██╗  ██╗
 ╚══███╔╝██║  ██║██╔════╝██║  ██║
   ███╔╝ ███████║█████╗  ███████║
  ███╔╝  ██╔══██║██╔══╝  ██╔══██║
 ███████╗██║  ██║███████╗██║  ██║
 ╚══════╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝

Modern Desktop Application Runtime & SDK

Zhex menjalankan aplikasi desktop dari satu berkas manifest package.zx: jendela native, IPC ter-izin, package manager deterministik, bundler, packaging installer, dan peralatan pengembangan AI — semuanya bawaan, tanpa dependensi runtime.

Versi tampilan Zhex adalah 0.01.1 (Neon) — yang tercetak di zhex version, banner, dan DOCS.md. Di npm ia tersimpan sebagai 0.1.2 karena spesifikasi semver melarang leading-zero; Zhex selalu menampilkan versi aslinya.

Quickstart

npm install -g @nillzx/zhex
zhex            # pengguna baru? wizard setup langsung muncul

Wizard setup 4 langkah: nama (huruf kecil) → password (dikonfirmasi dua kali) → ID Zhex berformat 5-5-5 (XXDJD-ABDAX-XADJA, tanda hubung otomatis, maks 15 karakter) → pilih fitur (W/S untuk navigasi, Enter untuk memilih ○ → ✓, A untuk memilih semua). Profil tersimpan aman di ~/.zhex/profile.json (hash scrypt) dan dipakai oleh zhex login.

zhex init my-app --template desktop
cd my-app
zhex install
zhex dev        # jendela aplikasi desktop asli — bukan tab browser
zhex . build    # pipeline installer → file siap pasang di folder installer/

Catatan: perintah CLI tetap bernama zhex meskipun nama paket npm-nya @nillzx/zhex (npm menolak nama zhex polos lewat proteksi typosquatting).

Personalisasi & dokumentasi

zhex settings                  # menu interaktif: Nama · Font banner · Tema warna
zhex settings --theme ocean    # langsung: neon | ocean | sunset | matrix | mono
zhex settings --font slim      # block | slim | bold
zhex settings list             # daftar + pratinjau tema & font

Tema mengubah warna seluruh CLI (banner, prompt, loading, panel) dan tersimpan di ~/.zhex/settings.json.

zhex docs                      # loading dulu, lalu DOCS.md tercipta di proyek

zhex docs menyusun panduan lengkap format .zx langsung dari proyekmu — baris pertamanya selalu Version = zhex 0.01.1, lalu penjelasan cara kerja parser, referensi package.zx, zhex.config.zx, zhex.lock, ringkasan manifest-mu sendiri, perintah harian, dan galeri error umum.

Membangun proyek AI (bukan fitur chat)

Zhex tidak punya fitur AI-chat — yang ada adalah peralatan supaya kamu bisa membangun aplikasi AI sendiri, jalan offline sejak detik pertama (mock provider) dan live dalam satu perintah:

zhex ai init chatku                    # scaffold proyek AI (template ai-chat)
cd chatku
zhex install
zhex ai check                          # provider siap? key valid? latensi berapa?
zhex ai set-key <token> --provider zai # pasang key (zai/openai/groq/ollama)
zhex dev                               # jendela desktop, UI chat buatanmu jalan

Di dalam app: import { createAI } from "@zhex/ai" → ai.chat, ai.stream, ai.embed, dan ai.agent (tool-calling otonom). Detail di docs/ai.md.

Fitur utama

• Runtime desktop — boot manifest → policy → renderer host → IPC → window → adapter; graceful shutdown satu perintah (Ctrl+C); zhex run membuka jendela aplikasi desktop asli (Chromium app-mode / Electron), bukan tab browser.
• Format .zx — superset JSON (komentar, koma akhir, kunci tanpa kutip, string backtick multiline) dengan error presisi Line / Expected / Found.
• IPC v1 — envelope req/res/ev over WebSocket milik sendiri: id UUID, timeout 15 s, cap 1 MB, depth 8, plain-object only, handshake auth token.
• Model izin — 17 permission dideklarasikan di package.zx (filesystem, network, storage, clipboard, …), fail-closed, wildcard filesystem.*, sandbox resolveWithin.
• Package manager — virtual store gaya pnpm (.zhex/packages + symlink ke zhex_modules/ — Zhex tidak pernah membuat node_modules di proyekmu), cache content-addressed + deteksi tamper, zhex.lock deterministik, --frozen untuk CI.
• Peralatan AI (@zhex/ai) — untuk membangun proyek AI-mu sendiri: chat, streaming SSE, embeddings, agent tool-calling; provider preset Z.AI/GLM, OpenAI, Groq, Ollama + mock offline; zhex ai init/models/set-key/check/status; key store aman ~/.zhex/ai.json.
• Akun lokal & login — wizard setup pengguna baru (nama lowercase → password terkonfirmasi → ID 5-5-5 otomatis → pemilih fitur interaktif), profil scrypt di ~/.zhex/profile.json, zhex login memverifikasi ID + password.
• Pipeline installer — zhex <app> build: 4 tahap berwarna (folder → unduh peralatan → build → installer) dengan loading bar di bawah console; hasil di folder installer/: -setup.exe (NSIS, dobel-klik), .deb (dpkg), .app + zip (macOS).
• Bundler internal — module graph, tree shaking, code splitting dynamic import, minify ASI-safe, sourcemap v3, cache inkremental.
• Packaging — portable launcher (sh/cmd), .deb asli via ar-writer sendiri (diterima dpkg-deb), NSIS generator, .app bundle + Info.plist, AppDir; BUILD_INFO.zx deterministik.
• Multi-bahasa — adapter JavaScript (ESM/CJS in-process), TypeScript (Node 22.6+ type stripping + fallback transpile), Python (sidecar NDJSON tanpa dependensi).
• Registry npm-compatible — --registry / package.zx / env ZHEX_REGISTRY; publish protokol npm dengan sha1+sha512; LocalRegistry untuk test offline.
• DX dev mode — CSS hot swap nyata, JS live reload + hot handler, error overlay, console forwarding, zhex debug --ipc-trace.

Arsitektur

Monorepo 19 package, TypeScript strict NodeNext, zero runtime dependency:

| Package | Tanggung jawab | |---|---| | @zhex/core | error system, logger, spinner, semver, fswrap+SRI, tar, http, proc, paths | | @zhex/parser | format .zx: tokenizer → AST → validator → writer (preservasi komentar) | | @zhex/registry | RegistryClient, auth store, LocalRegistry | | @zhex/pm | resolver, cache, downloader, extractor, linker, lockfile, installer | | @zhex/ipc | frame RFC 6455, WsServer, protokol v1, IpcServer/IpcClient | | @zhex/native | kontrak window backend + capabilities jujur + discovery | | @zhex/bridge | BrowserBackend (app-mode) + ElectronBackend + BackendManager | | @zhex/runtime | RuntimeSession, PermissionPolicy, service berizin | | @zhex/renderer | HTTP host + HMR + overlay + client.js/hmr.js | | zhex (SDK) | zhex.app/window/ipc/fs/storage/crypto/… untuk aplikasi | | @zhex/ai | peralatan AI developer: chat, stream, embed, agent, probe provider, preset + mock offline | | @zhex/bundler | graph, treeshake, chunks, minify, sourcemap, cache | | @zhex/builder | portable, deb, NSIS, .app, AppDir | | @zhex/debugger | inspector args, state dump, IPC tracer | | @zhex/adapter-js / -ts / -py | adapter bahasa | | @zhex/cli | 20+ perintah CLI (setup/init/install/dev/build/package/ai/login/…) | | @zhex/templates | 7 template proyek (termasuk AI Chat neon) |

Contoh

package.zx

{
  name: "my-app",
  version: "1.0.0",
  description: "Aplikasi desktop pertamaku",
  runtime: { language: "javascript", entry: "src/main.js" },
  app: { name: "My App", executable: "MyApp", icon: "assets/icon.png" },
  dependencies: { "@nillzx/zhex": "^1.0.0" },
  permissions: ["system.info", "window.create", "storage.read", "storage.write"],
  scripts: { dev: "zhex dev", start: "zhex run", build: "zhex build" },
  registry: { default: "https://registry.npmjs.org" },
}

src/main.js

import { zhex } from "@nillzx/zhex";

await zhex.app.create({ name: "My App" });

zhex.ipc.handle("greet", (name) => ({ message: `Halo, ${name}!` }));

const count = (await zhex.storage.get("launches")) ?? 0;
await zhex.storage.set("launches", count + 1);
console.log(`launch #${count + 1}`);

src/renderer.js — di halaman, IPC tersedia sebagai window.zhexIpc:

const res = await window.zhexIpc.invoke("greet", "Zhex");
document.querySelector("#app").textContent = res.message;

Dokumentasi

| Dokumen | Isi | |---|---| | docs/getting-started.md | instalasi, quickstart, struktur proyek, template | | docs/package-zx.md | format .zx, zhex.config.zx, zhex.lock | | docs/cli.md | 17 perintah CLI + flag | | docs/runtime.md | sesi, bridge, HMR, layout .zhex/ | | docs/ipc.md | protokol IPC v1 + contoh | | docs/permissions.md | model izin & sandbox | | docs/python.md | adapter Python + zhex.py | | docs/javascript.md | adapter JS/TS + contoh app | | docs/building.md | bundler + packaging | | docs/publishing.md | login, publish, dry-run | | docs/registry.md | abstraksi registry & LocalRegistry | | docs/architecture.md | monorepo, virtual store, decision records | | docs/security.md | threat model & mitigasi |

Pengembangan

npm install
npm run build          # tsc -b --force (18 package, deterministik, aman buildinfo basi)
npm run rebuild        # alias build --force
npm test               # node --test (10 file test eksplisit, aman di semua shell)
npm run smoke          # smoke: load dist tiap package + uji ringkas + CLI
npm run clean          # hapus semua dist & artefak build
npm run zip            # kemas release zip (deterministik, artefak otomatis dikecualikan)

Struktur:

zhex/
├── core/ parser/ registry/ package-manager/ ipc/ native/   # fondasi
├── bridge/ renderer/ runtime/ sdk/ debugger/               # runtime
├── bundler/ builder/                                       # build & package
├── adapters/{javascript,typescript,python}/                # bahasa
├── cli/ templates/ examples/ extensions/vscode/            # tooling
├── tests/{unit,security,integration}/                      # node:test
└── docs/                                                   # dokumentasi (Bahasa Indonesia)

Roadmap

• [x] 1.0.0 (Argon) — runtime, SDK, package manager, bundler, packaging, CLI, 6 template, ekstensi VS Code
• [x] 1.1.0 (Neon) — toolkit AI @zhex/ai (chat/stream/embed/agent), CLI zhex ai, template ai-chat, folder zhex_modules (tanpa node_modules), zhex login/whoami interaktif, UI CLI berwarna (gradient neon)
• [x] 1.2.0 (Neon) — wizard setup pengguna baru (nama/password/ID 5-5-5/pemilih fitur), zhex login akun lokal, pipeline zhex <app> build → folder installer/ + toolchain NSIS terunduh otomatis, zhex run jendela desktop asli, ai chat dihapus (fokus peralatan developer AI: ai init/check), pembaca ZIP internal
• [x] 0.01.1 (Neon) — versi tampilan 0.01.1 (npm 0.1.2, semver menolak leading-zero), zhex settings (nama/font banner/tema warna: neon·ocean·sunset·matrix·mono), zhex docs → DOCS.md dengan header Version = zhex 0.01.1 + panduan lengkap format .zx
• [x] 0.01.1 patch (npm 0.1.2) — perbaikan UI PowerShell: semua menu/picker & loading bar kini sadar-lebar-terminal (anti teks duplikat saat wrap), ID prompt dua baris, zhex init di folder terlindungi (mis. System32) kini memberi pesan ramah + langkah konkret (E_FS_PERMISSION), bukan E_INTERNAL
• [ ] Backend webkit
• [ ] Hot-restart untuk sidecar Python
• [ ] Menu & tray untuk backend non-electron
• [ ] Advisory feed untuk 0 vulnerabilities yang sesungguhnya

License

MIT — The Zhex Authors.