kcg-code 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,231 @@
-# Temporary Holding Version
+# kcgcode
 
-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.
+Control your [OpenCode](https://opencode.ai) agents from your phone. kcgcode runs a local bridge
+on your machine and serves a mobile-friendly web app (PWA) where you chat with agents, answer
+their permission prompts, manage projects and skills, and keep it all behind a lock screen when
+you reach it through a tunnel.
+
+> Only OpenCode is supported as an agent right now. Claude Code support is planned.
+
+## Features
+
+- **Chat with agents from anywhere.** Start sessions per project, stream replies live, stop a
+  running turn, and pick the model and agent mode (build, plan, or your own agents).
+- **Answer prompts on the go.** Permission requests and multi-question prompts from the agent
+  show up as cards you can approve, deny, or answer from your phone.
+- **Projects & sessions.** Organise work by folder inside a sandbox. The sidebar groups every
+  session by project, with live status and a quick search (`Ctrl/⌘ + K`).
+- **Rich input.** Mention files with `@`, attach images, and set per-project custom
+  instructions.
+- **Skills from [skills.sh](https://skills.sh).** Search the directory, see security audit
+  results before you install, and add skills to a project in one click. Installs run in the
+  background with live output, survive page refreshes, and can be cancelled. The agent picks up
+  new skills automatically, waiting for any running chat to finish first.
+- **App lock.** Protect the app with a PIN or password before exposing it. It comes with a lock
+  screen showing your profile photo or avatar, auto-lock after inactivity, signed-in device
+  management, and brute-force protection.
+- **Installable PWA** with light, dark, or system theme.
+- **Terminal dashboard.** `kcgcode` shows the server status right in your terminal.
+
+## Requirements
+
+- [Bun](https://bun.com) 1.1 or newer
+- [OpenCode](https://opencode.ai) installed and on your `PATH` (kcgcode starts `opencode serve`
+  for each project)
+- Internet access for skills.sh search and skill installs (installs use `bunx skills`)
+
+## Install
+
+```bash
+bun i -g kcgcode
+```
+
+Or from a local clone:
+
+```bash
+bun pm pack
+bun i -g ./kcgcode-0.1.0.tgz
+```
+
+## Quick start
+
+```bash
+# create ~/.kcgcode (config, sandbox, data)
+kcgcode init
+
+# start the server + terminal dashboard (works from any directory)
+kcgcode
+
+# custom port, open the browser
+kcgcode start --port 4000 --open
+```
+
+Open the printed URL in your browser. Projects are folders inside the sandbox root from your
+config.
+
+## Using it from your phone
+
+By default the server only listens on `127.0.0.1`, so it's reachable from this machine only.
+To use it from your phone:
+
+1. **Set a lock first.** Open **Settings → Security** and turn on the app lock (PIN or
+   password). Until a lock is set, anyone who can reach the address can control your agents and
+   run commands on your machine. The sidebar shows a "Not protected" warning while there's no
+   lock.
+2. **Expose it.** Either:
+   - Turn on **Settings → Remote access** (built in, see below), or
+   - Use an HTTPS tunnel such as Cloudflare Tunnel or ngrok, pointed at the kcgcode port, or
+   - Bind to your LAN with `kcgcode --host 0.0.0.0` and open `http://<your-ip>:3000` on the
+     same network. Traffic isn't encrypted on plain HTTP, so prefer a tunnel.
+3. Open the URL on your phone, unlock, and optionally add it to your home screen.
+
+Only tunnel the kcgcode port. The per-project `opencode serve` processes have no password of
+their own and should stay local.
+
+### Remote access (`https://<name>.<your-domain>`)
+
+kcgcode can publish itself at your own subdomain through a kcgcode tunnel server you host
+(see [`reverse-proxy/`](reverse-proxy)).
+
+1. Set an app lock. Remote access can't be turned on without one, and removing the lock turns
+   it off.
+2. **Settings → Remote access → Connect.** kcgcode shows a code, a link, and a QR code.
+3. Open the link on any device (your phone works), sign in with Google, check that the code
+   matches, and approve. First time only: pick a name (3–20 lowercase letters, numbers, or
+   hyphens).
+4. kcgcode connects and turns the tunnel on. It downloads `frpc` v0.71.0 to `~/.kcgcode/bin`
+   (SHA-256 verified; an existing `frpc` on `PATH` is used instead). The tunnel reconnects on its
+   own and comes back after a restart.
+
+Google sign-in happens entirely on the tunnel service, so kcgcode never holds Google
+credentials. What it stores is a device token (revocable, per machine) and the tunnel secret, in
+SQLite plus `frpc.toml` (mode 0600) next to it. Neither is ever sent to the browser.
+Under **Advanced**, **Unlink this computer** revokes the device token on the server and
+**Reset security key** issues a new frp secret if you think it leaked.
+
+The tunnel server URL is baked into the published npm package, so users don't configure
+anything. `KCG_TUNNEL_API_URL` overrides it, for example to point at your own server.
+
+| Environment variable | Default |
+| --- | --- |
+| `KCG_TUNNEL_API_URL` | The URL built into the package (none in a git checkout) |
+| `KCG_FRPC_PATH` | auto (`~/.kcgcode/bin/frpc`, then `PATH`, then download) |
+
+## Security
+
+When a lock is set:
+
+- Every API route and the WebSocket require a signed-in session. The only exceptions are the
+  lock screen's status, login, and profile photo.
+- The PIN or password is stored as an argon2id hash. Sessions use an `HttpOnly`,
+  `SameSite=Strict` cookie, marked `Secure` over HTTPS. The database only stores a hash of the
+  session token.
+- Requests from other sites are rejected (Origin check, including the WebSocket).
+- Auto-lock (5 min to 1 hour, or never) is enforced by the server, not just the UI. Locking,
+  changing the lock, or signing out a device also closes that device's live connection.
+- Failed attempts are rate limited per IP and globally, since tunnels can hide the real IP.
+  Repeated failures pause all logins for up to 15 minutes.
+- PINs must be 6–12 digits, and trivial patterns like `111111` or `123456` are rejected.
+  Passwords need at least 8 characters.
+
+**Forgot your PIN or password?** Run this on the host machine:
+
+```bash
+kcgcode reset-lock
+```
+
+It removes the lock and signs out every device, but keeps your profile. Set a new lock right
+away if the app is exposed.
+
+Skills run with your agent's full permissions. Review a skill and its audit before installing.
+
+## CLI
+
+| Command | Description |
+| --- | --- |
+| `kcgcode` / `kcgcode start` | Run the server + live dashboard |
+| `kcgcode init` | Create `~/.kcgcode` (config, sandbox, data) |
+| `kcgcode reset-lock` | Remove the app lock and sign out all devices |
+| `kcgcode --help` | Show help |
+| `kcgcode --version` | Show version |
+
+| Option | Description |
+| --- | --- |
+| `-p, --port <n>` | HTTP port (default `3000`, env `KCG_PORT`) |
+| `-H, --host <h>` | Bind host (default `127.0.0.1`, env `KCG_HOST`) |
+| `-c, --config <f>` | Config path (default `~/.kcgcode/config.json`) |
+| `--open` | Open the web app in your browser |
+| `--allow-sleep` | Let the OS sleep while running (by default kcgcode keeps the machine awake so the tunnel stays connected) |
+
+Dashboard keys: `q` quit · `o` open browser · `Ctrl+C` stop.
+
+| Environment variable | Description |
+| --- | --- |
+| `KCG_PORT` | HTTP port |
+| `KCG_HOST` | Bind host |
+| `KCG_CONFIG_PATH` | Config file path |
+| `KCG_DB_PATH` | SQLite path (default `~/.kcgcode/data/kcg-code.sqlite`) |
+| `KCG_ALLOW_SLEEP=1` | Same as `--allow-sleep` |
+
+## Config & data location
+
+The runtime mode is detected from the entrypoint:
+
+| | **dev** (`bun dev` / `src/index.ts`) | **cli** (`kcgcode` global binary) |
+| --- | --- | --- |
+| Config | `./kcg-code.config.json` if present, else `~/.kcgcode/config.json` | `~/.kcgcode/config.json` |
+| SQLite | `./data/kcg-code.sqlite` | `~/.kcgcode/data/kcg-code.sqlite` |
+| Uploads | `./data/uploads` | `~/.kcgcode/data/uploads` |
+| Sandbox (init) | `./sandbox` | `~/.kcgcode/sandbox` |
+| HMR | on | off (`NODE_ENV=production`) |
+
+Global CLI layout:
+
+```
+~/.kcgcode/
+  config.json              # sandboxRoot
+  sandbox/                 # default agent workspace
+  data/
+    kcg-code.sqlite        # projects, sessions, messages, app lock
+    uploads/               # image attachments
+```
+
+Config file resolution order:
+
+1. `--config <path>` / `KCG_CONFIG_PATH` (always wins)
+2. **cli**: `~/.kcgcode/config.json` (cwd is ignored)
+3. **dev**: `./kcg-code.config.json` if present, else `~/.kcgcode/config.json`
+
+```json
+{
+  "sandboxRoot": "/absolute/path/to/your/workspace"
+}
+```
+
+Skills installed from the Skills page go into the project folder under `.agents/skills/`.
+
+## Develop
+
+Copy `.env.example` to `.env`. Bun loads it automatically, and it's gitignored. Set
+`KCG_TUNNEL_API_URL` to your tunnel server to use Remote access while developing.
+
+```bash
+bun install
+bun dev             # dev server with HMR (uses ./kcg-code.config.json if present)
+bun test
+bun run lint
+bun run typecheck
+bun run build
+```
+
+### Publishing
+
+`bun publish` (or `bun pm pack`) runs `prepack`, which writes `KCG_TUNNEL_API_URL` from `.env`
+into `src/build-config.ts`. `postpack` then resets it, so the URL never ends up in git.
+Publishing fails if the variable is missing or isn't `https://`. Check what gets published with:
+
+```bash
+bun pm pack && tar -xOzf kcgcode-*.tgz package/src/build-config.ts
+```
+
+Built with [Bun](https://bun.com).

package/bin/kcgcode.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env bun
+/**
+ * Entry global CLI `kcgcode` (`bun i -g kcgcode`).
+ *
+ * Menandai mode runtime `cli` lebih dulu agar config/db/uploads
+ * resolve ke `~/.kcgcode`, bukan path lokal cwd.
+ */
+import { setRunMode } from "../src/runtime";
+
+setRunMode("cli");
+
+const { runCli } = await import("../src/cli/index");
+await runCli(process.argv.slice(2));

package/bun-env.d.ts

@@ -0,0 +1,19 @@
+// Generated by `bun init`
+
+declare module "*.svg" {
+  /**
+   * A path to the SVG file
+   */
+  const path: `${string}.svg`;
+  export = path;
+}
+
+declare module "*.css" {}
+
+declare module "*.module.css" {
+  /**
+   * A record of class names to their corresponding CSS module classes
+   */
+  const classes: { readonly [key: string]: string };
+  export = classes;
+}

package/kcg-code.config.example.json

@@ -0,0 +1,3 @@
+{
+  "sandboxRoot": "/absolute/path/to/your/workspace"
+}

package/package.json

@@ -1,6 +1,86 @@
 {
   "name": "kcg-code",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Control CLI AI agents (OpenCode / Claude Code) from your phone — mobile PWA + local headless bridge.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "kcgcode": "./bin/kcgcode.ts"
+  },
+  "files": [
+    "bin",
+    "src",
+    "public",
+    "styles",
+    "bun-env.d.ts",
+    "tsconfig.json",
+    "README.md",
+    "kcg-code.config.example.json"
+  ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "keywords": [
+    "bun",
+    "cli",
+    "tui",
+    "opencode",
+    "claude-code",
+    "ai-agent",
+    "pwa",
+    "mobile"
+  ],
+  "scripts": {
+    "dev": "bun --hot src/index.ts",
+    "start": "NODE_ENV=production bun src/index.ts",
+    "kcgcode": "bun bin/kcgcode.ts",
+    "build": "bun run build.ts",
+    "test": "bun test",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "typecheck": "tsc --noEmit",
+    "prepack": "bun scripts/stamp-build-config.ts",
+    "postpack": "bun scripts/stamp-build-config.ts --reset"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.296",
+    "@radix-ui/react-label": "^2.1.7",
+    "@radix-ui/react-select": "^2.2.6",
+    "@radix-ui/react-slot": "^1.2.3",
+    "@shadcn/react": "^0.3.0",
+    "@simplewebauthn/browser": "14.0.0",
+    "@simplewebauthn/server": "14.0.3",
+    "bun-plugin-tailwind": "^0.1.2",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cn": "^0.2.5",
+    "ink": "^7.1.1",
+    "lucide-react": "^1",
+    "motion": "13.4.6",
+    "picocolors": "^1.1.1",
+    "radix-ui": "^1.6.7",
+    "react": "^19",
+    "react-dom": "^19",
+    "react-markdown": "10.1.0",
+    "remark-gfm": "4.0.1",
+    "shiki": "4.4.3",
+    "sonner": "2.0.8",
+    "tailwind-merge": "^3.3.1",
+    "tw-animate-css": "^1.4.0",
+    "uqr": "0.1.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.7",
+    "@types/bun": "latest",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "fast-check": "^4.9.0",
+    "react-reconciler": "0.33.0",
+    "tailwindcss": "^4.1.11",
+    "typescript": "^6"
+  },
+  "peerDependencies": {
+    "typescript": "^6"
+  }
+}

package/public/logo.svg

@@ -0,0 +1 @@
+<svg id="Bun" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 80 70"><title>Bun Logo</title><path id="Shadow" d="M71.09,20.74c-.16-.17-.33-.34-.5-.5s-.33-.34-.5-.5-.33-.34-.5-.5-.33-.34-.5-.5-.33-.34-.5-.5-.33-.34-.5-.5-.33-.34-.5-.5A26.46,26.46,0,0,1,75.5,35.7c0,16.57-16.82,30.05-37.5,30.05-11.58,0-21.94-4.23-28.83-10.86l.5.5.5.5.5.5.5.5.5.5.5.5.5.5C19.55,65.3,30.14,69.75,42,69.75c20.68,0,37.5-13.48,37.5-30C79.5,32.69,76.46,26,71.09,20.74Z"/><g id="Body"><path id="Background" d="M73,35.7c0,15.21-15.67,27.54-35,27.54S3,50.91,3,35.7C3,26.27,9,17.94,18.22,13S33.18,3,38,3s8.94,4.13,19.78,10C67,17.94,73,26.27,73,35.7Z" style="fill:#fbf0df"/><path id="Bottom_Shadow" data-name="Bottom Shadow" d="M73,35.7a21.67,21.67,0,0,0-.8-5.78c-2.73,33.3-43.35,34.9-59.32,24.94A40,40,0,0,0,38,63.24C57.3,63.24,73,50.89,73,35.7Z" style="fill:#f6dece"/><path id="Light_Shine" data-name="Light Shine" d="M24.53,11.17C29,8.49,34.94,3.46,40.78,3.45A9.29,9.29,0,0,0,38,3c-2.42,0-5,1.25-8.25,3.13-1.13.66-2.3,1.39-3.54,2.15-2.33,1.44-5,3.07-8,4.7C8.69,18.13,3,26.62,3,35.7c0,.4,0,.8,0,1.19C9.06,15.48,20.07,13.85,24.53,11.17Z" style="fill:#fffefc"/><path id="Top" d="M35.12,5.53A16.41,16.41,0,0,1,29.49,18c-.28.25-.06.73.3.59,3.37-1.31,7.92-5.23,6-13.14C35.71,5,35.12,5.12,35.12,5.53Zm2.27,0A16.24,16.24,0,0,1,39,19c-.12.35.31.65.55.36C41.74,16.56,43.65,11,37.93,5,37.64,4.74,37.19,5.14,37.39,5.49Zm2.76-.17A16.42,16.42,0,0,1,47,17.12a.33.33,0,0,0,.65.11c.92-3.49.4-9.44-7.17-12.53C40.08,4.54,39.82,5.08,40.15,5.32ZM21.69,15.76a16.94,16.94,0,0,0,10.47-9c.18-.36.75-.22.66.18-1.73,8-7.52,9.67-11.12,9.45C21.32,16.4,21.33,15.87,21.69,15.76Z" style="fill:#ccbea7;fill-rule:evenodd"/><path id="Outline" d="M38,65.75C17.32,65.75.5,52.27.5,35.7c0-10,6.18-19.33,16.53-24.92,3-1.6,5.57-3.21,7.86-4.62,1.26-.78,2.45-1.51,3.6-2.19C32,1.89,35,.5,38,.5s5.62,1.2,8.9,3.14c1,.57,2,1.19,3.07,1.87,2.49,1.54,5.3,3.28,9,5.27C69.32,16.37,75.5,25.69,75.5,35.7,75.5,52.27,58.68,65.75,38,65.75ZM38,3c-2.42,0-5,1.25-8.25,3.13-1.13.66-2.3,1.39-3.54,2.15-2.33,1.44-5,3.07-8,4.7C8.69,18.13,3,26.62,3,35.7,3,50.89,18.7,63.25,38,63.25S73,50.89,73,35.7C73,26.62,67.31,18.13,57.78,13,54,11,51.05,9.12,48.66,7.64c-1.09-.67-2.09-1.29-3-1.84C42.63,4,40.42,3,38,3Z"/></g><g id="Mouth"><g id="Background-2" data-name="Background"><path d="M45.05,43a8.93,8.93,0,0,1-2.92,4.71,6.81,6.81,0,0,1-4,1.88A6.84,6.84,0,0,1,34,47.71,8.93,8.93,0,0,1,31.12,43a.72.72,0,0,1,.8-.81H44.26A.72.72,0,0,1,45.05,43Z" style="fill:#b71422"/></g><g id="Tongue"><path id="Background-3" data-name="Background" d="M34,47.79a6.91,6.91,0,0,0,4.12,1.9,6.91,6.91,0,0,0,4.11-1.9,10.63,10.63,0,0,0,1-1.07,6.83,6.83,0,0,0-4.9-2.31,6.15,6.15,0,0,0-5,2.78C33.56,47.4,33.76,47.6,34,47.79Z" style="fill:#ff6164"/><path id="Outline-2" data-name="Outline" d="M34.16,47a5.36,5.36,0,0,1,4.19-2.08,6,6,0,0,1,4,1.69c.23-.25.45-.51.66-.77a7,7,0,0,0-4.71-1.93,6.36,6.36,0,0,0-4.89,2.36A9.53,9.53,0,0,0,34.16,47Z"/></g><path id="Outline-3" data-name="Outline" d="M38.09,50.19a7.42,7.42,0,0,1-4.45-2,9.52,9.52,0,0,1-3.11-5.05,1.2,1.2,0,0,1,.26-1,1.41,1.41,0,0,1,1.13-.51H44.26a1.44,1.44,0,0,1,1.13.51,1.19,1.19,0,0,1,.25,1h0a9.52,9.52,0,0,1-3.11,5.05A7.42,7.42,0,0,1,38.09,50.19Zm-6.17-7.4c-.16,0-.2.07-.21.09a8.29,8.29,0,0,0,2.73,4.37A6.23,6.23,0,0,0,38.09,49a6.28,6.28,0,0,0,3.65-1.73,8.3,8.3,0,0,0,2.72-4.37.21.21,0,0,0-.2-.09Z"/></g><g id="Face"><ellipse id="Right_Blush" data-name="Right Blush" cx="53.22" cy="40.18" rx="5.85" ry="3.44" style="fill:#febbd0"/><ellipse id="Left_Bluch" data-name="Left Bluch" cx="22.95" cy="40.18" rx="5.85" ry="3.44" style="fill:#febbd0"/><path id="Eyes" d="M25.7,38.8a5.51,5.51,0,1,0-5.5-5.51A5.51,5.51,0,0,0,25.7,38.8Zm24.77,0A5.51,5.51,0,1,0,45,33.29,5.5,5.5,0,0,0,50.47,38.8Z" style="fill-rule:evenodd"/><path id="Iris" d="M24,33.64a2.07,2.07,0,1,0-2.06-2.07A2.07,2.07,0,0,0,24,33.64Zm24.77,0a2.07,2.07,0,1,0-2.06-2.07A2.07,2.07,0,0,0,48.75,33.64Z" style="fill:#fff;fill-rule:evenodd"/></g></svg>

package/public/manifest.json

@@ -0,0 +1,18 @@
+{
+  "name": "KCG Code",
+  "short_name": "KCG Code",
+  "description": "Kontrol CLI AI Agent (OpenCode / Claude Code) dari perangkat mobile.",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#0a0a0a",
+  "theme_color": "#0a0a0a",
+  "lang": "id",
+  "icons": [
+    {
+      "src": "/logo.svg",
+      "sizes": "any",
+      "type": "image/svg+xml",
+      "purpose": "any"
+    }
+  ]
+}

package/public/sw.js

@@ -0,0 +1,49 @@
+// KCG Code service worker (Requirement 8.1).
+// - Cache-first untuk asset statis (JS/CSS bundle hasil build.ts).
+// - Network-only (pass-through) untuk `/api/*` dan koneksi WebSocket `/ws`,
+//   agar kontrol CLI_Agent tidak pernah disajikan dari cache basi.
+
+const CACHE_NAME = "kcg-code-v1";
+const PRECACHE = ["/", "/manifest.json", "/logo.svg"];
+
+self.addEventListener("install", (event) => {
+  event.waitUntil(
+    caches
+      .open(CACHE_NAME)
+      .then((cache) => cache.addAll(PRECACHE))
+      .catch(() => {}),
+  );
+  self.skipWaiting();
+});
+
+self.addEventListener("activate", (event) => {
+  event.waitUntil(
+    caches
+      .keys()
+      .then((keys) =>
+        Promise.all(keys.filter((key) => key !== CACHE_NAME).map((key) => caches.delete(key))),
+      ),
+  );
+  self.clients.claim();
+});
+
+self.addEventListener("fetch", (event) => {
+  const url = new URL(event.request.url);
+
+  // Network-only untuk API dan WebSocket.
+  if (url.pathname.startsWith("/api/") || url.pathname === "/ws") return;
+
+  // Cache-first untuk asset statis.
+  event.respondWith(
+    caches.match(event.request).then((cached) => {
+      if (cached) return cached;
+      return fetch(event.request).then((response) => {
+        if (response.ok && url.origin === self.location.origin) {
+          const clone = response.clone();
+          caches.open(CACHE_NAME).then((cache) => cache.put(event.request, clone));
+        }
+        return response;
+      });
+    }),
+  );
+});

package/src/App.tsx

@@ -0,0 +1,39 @@
+/**
+ * Akar aplikasi KCG Code.
+ *
+ * Layout, navigasi, dan pemetaan URL -> halaman dipegang `AppShell`
+ * (`components/layout/AppShell.tsx`) — pola yang sama dengan kcgcode
+ * (`src/App.tsx` merender shell, halaman hidup di `src/pages/*`).
+ */
+
+import { domAnimation, LazyMotion, MotionConfig } from "motion/react";
+import { AuthGate } from "@/components/auth/AuthGate";
+import { AppShell } from "@/components/layout/AppShell";
+import { Toaster } from "@/components/ui/sonner";
+import "./index.css";
+
+export function App() {
+  // Kunci aplikasi: shell (dan semua request datanya) baru dirender setelah
+  // lock screen dibuka.
+  //
+  // Motion (animasi masuk/keluar komponen):
+  // - `LazyMotion` + `domAnimation` + komponen `m.*` (`motion/react-m`)
+  //   menjaga bundle kecil (tanpa fitur drag/layout). `strict` melempar
+  //   error bila ada yang tak sengaja memakai `motion.*` (bundle penuh).
+  // - `reducedMotion="user"`: animasi transform dimatikan bila pengguna
+  //   memilih reduce motion di sistemnya (opacity tetap).
+  return (
+    <LazyMotion features={domAnimation} strict>
+      <MotionConfig reducedMotion="user">
+        <AuthGate>
+          <AppShell />
+        </AuthGate>
+        {/* Toast global (juga tampil di lock screen). Atas-tengah agar tidak
+            menutupi kartu instalasi skill di kanan bawah. */}
+        <Toaster position="top-center" closeButton />
+      </MotionConfig>
+    </LazyMotion>
+  );
+}
+
+export default App;

package/src/__tests__/manifest.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Unit test validitas PWA manifest (task 21.4, Requirement 8.1).
+ *
+ * Memverifikasi field wajib web app manifest (`name`, `short_name`,
+ * `start_url`, `display`, `icons`) ada dan bernilai valid agar Client dapat
+ * di-install sebagai Progressive Web App.
+ */
+import { expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+
+interface ManifestIcon {
+  src: string;
+  sizes: string;
+  type: string;
+  purpose?: string;
+}
+
+interface Manifest {
+  name: string;
+  short_name: string;
+  start_url: string;
+  display: string;
+  description?: string;
+  icons: ManifestIcon[];
+}
+
+function readManifest(): Manifest {
+  const raw = readFileSync("public/manifest.json", "utf8");
+  return JSON.parse(raw) as Manifest;
+}
+
+test("21.4: manifest.json adalah JSON valid", () => {
+  expect(() => readManifest()).not.toThrow();
+});
+
+test("21.4: field wajib ada dan bernilai valid", () => {
+  const manifest = readManifest();
+
+  // name & short_name berupa string non-kosong
+  expect(typeof manifest.name).toBe("string");
+  expect(manifest.name.length).toBeGreaterThan(0);
+  expect(typeof manifest.short_name).toBe("string");
+  expect(manifest.short_name.length).toBeGreaterThan(0);
+
+  // start_url adalah path/URL absolut valid
+  expect(typeof manifest.start_url).toBe("string");
+  expect(manifest.start_url.startsWith("/")).toBe(true);
+
+  // display stand-alone (prasyarat instalasi PWA)
+  expect(manifest.display).toBe("standalone");
+
+  // icons: array non-kosong dengan src & type valid
+  expect(Array.isArray(manifest.icons)).toBe(true);
+  expect(manifest.icons.length).toBeGreaterThan(0);
+  for (const icon of manifest.icons) {
+    expect(typeof icon.src).toBe("string");
+    expect(icon.src.startsWith("/")).toBe(true);
+    expect(typeof icon.type).toBe("string");
+    expect(icon.type.length).toBeGreaterThan(0);
+  }
+});

package/src/build-config.ts

@@ -0,0 +1,9 @@
+/**
+ * Build-time constants, stamped into the npm package by `scripts/stamp-build-config.ts`
+ * (`prepack`) and reset to empty by `postpack`, so the repo never contains a
+ * deployment-specific value.
+ *
+ * Do not edit by hand: set `KCG_TUNNEL_API_URL` in `.env` for development, and
+ * it's baked in automatically when you run `bun publish` / `bun pm pack`.
+ */
+export const BUILD_TUNNEL_API_URL: string = "https://code.kcgapp.tech";

package/src/cli/__tests__/daemon.test.ts

@@ -0,0 +1,84 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { parseArgs } from "../args";
+import { childArgv, daemonStatePath, isAlive, runningDaemon, writeDaemonState } from "../daemon";
+
+describe("parseArgs daemon", () => {
+  test("start -d + command stop/status/logs", () => {
+    expect(parseArgs(["start", "-d"]).detach).toBe(true);
+    expect(parseArgs(["--detach", "-p", "4000"])).toMatchObject({
+      command: "start",
+      detach: true,
+      port: 4000,
+    });
+    expect(parseArgs(["stop"]).command).toBe("stop");
+    expect(parseArgs(["status"]).command).toBe("status");
+    expect(parseArgs(["logs", "-f", "-n", "20"])).toMatchObject({
+      command: "logs",
+      follow: true,
+      lines: 20,
+    });
+    expect(parseArgs(["logs", "-n", "abc"]).command).toBe("invalid");
+  });
+
+  test("childArgv meneruskan opsi server, tanpa -d / --open", () => {
+    const args = parseArgs([
+      "start",
+      "-d",
+      "--open",
+      "-p",
+      "4000",
+      "-H",
+      "0.0.0.0",
+      "--allow-sleep",
+    ]);
+    expect(childArgv(args)).toEqual([
+      "start",
+      "--port",
+      "4000",
+      "--host",
+      "0.0.0.0",
+      "--allow-sleep",
+    ]);
+  });
+});
+
+describe("daemon state", () => {
+  let dir: string;
+  const prevDb = process.env.KCG_DB_PATH;
+
+  beforeEach(() => {
+    dir = mkdtempSync(path.join(tmpdir(), "kcg-daemon-"));
+    process.env.KCG_DB_PATH = path.join(dir, "kcg.sqlite");
+  });
+  afterEach(() => {
+    if (prevDb === undefined) delete process.env.KCG_DB_PATH;
+    else process.env.KCG_DB_PATH = prevDb;
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const state = (pid: number) => ({
+    pid,
+    port: 3000,
+    hostname: "127.0.0.1",
+    localUrl: "http://127.0.0.1:3000",
+    publicUrl: null,
+    startedAt: Date.now(),
+    logFile: path.join(dir, "kcgcode.log"),
+  });
+
+  test("state dengan pid hidup dikembalikan", async () => {
+    await writeDaemonState(state(process.pid));
+    expect(isAlive(process.pid)).toBe(true);
+    expect((await runningDaemon())?.pid).toBe(process.pid);
+  });
+
+  test("state basi (pid mati) dibersihkan", async () => {
+    const dead = Bun.spawnSync(["true"]).pid;
+    await writeDaemonState(state(dead));
+    expect(await runningDaemon()).toBeNull();
+    expect(existsSync(daemonStatePath())).toBe(false);
+  });
+});