kcg-code 0.1.0 → 0.2.0

package/README.md

@@ -155,6 +155,7 @@ Skills run with your agent's full permissions. Review a skill and its audit befo
 | `-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.
 
@@ -164,6 +165,7 @@ Dashboard keys: `q` quit · `o` open browser · `Ctrl+C` stop.
 | `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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kcg-code",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Control CLI AI agents (OpenCode / Claude Code) from your phone — mobile PWA + local headless bridge.",
   "license": "MIT",
   "type": "module",
@@ -44,6 +44,7 @@
     "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",

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);
+  });
+});

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

@@ -1,5 +1,14 @@
 import { describe, expect, test } from "bun:test";
-import { type DashboardInfo, renderDashboard } from "../dashboard";
+import {
+  activeProvider,
+  bestUrl,
+  type DashboardInfo,
+  menuItems,
+  portInputError,
+  renderDashboard,
+  renderSnapshot,
+  takeSnapshot,
+} from "../dashboard";
 
 function makeInfo(overrides: Partial<DashboardInfo> = {}): DashboardInfo {
   return {
@@ -20,17 +29,43 @@ function makeInfo(overrides: Partial<DashboardInfo> = {}): DashboardInfo {
 }
 
 describe("renderDashboard", () => {
-  test("logo KCG + card SERVER dan ACTIVITY", () => {
+  test("logo KCG + status simpel Running", () => {
     const frame = renderDashboard(makeInfo(), "0.1.0");
     expect(frame).toContain("kcgcode");
     expect(frame).toContain("v0.1.0");
     expect(frame).toContain("██╗");
-    expect(frame).toContain("SERVER");
-    expect(frame).toContain("ACTIVITY");
-    expect(frame).toContain("active job");
+    expect(frame).toContain("Running");
+    expect(frame).toContain("Local");
+    expect(frame).toContain("PID");
+    expect(frame).toContain("up 0s");
+    expect(frame).toContain("Tunnel");
+    expect(frame).toContain("Open in browser");
+    expect(frame).toContain("↑↓ move");
     expect(frame).not.toContain("CONFIG");
   });
 
+  test("baris Awake menampilkan status keep-awake", () => {
+    const on = renderDashboard(
+      makeInfo({
+        keepAwake: { status: () => ({ active: true, method: "systemd-inhibit", error: null }) },
+      }),
+      "0.1.0",
+    );
+    expect(on).toContain("Awake");
+    expect(on).toContain("sleep blocked");
+
+    const off = renderDashboard(
+      makeInfo({
+        keepAwake: {
+          status: () => ({ active: false, method: null, error: "disabled (--allow-sleep)" }),
+        },
+      }),
+      "0.1.0",
+    );
+    expect(off).toContain("off · disabled");
+    expect(renderDashboard(makeInfo(), "0.1.0")).not.toContain("Awake");
+  });
+
   test("stats berubah saat data store berubah (refresh in-place)", () => {
     let sessions: { id: string; status: string; title: string | null }[] = [];
     const info = makeInfo({
@@ -50,13 +85,140 @@ describe("renderDashboard", () => {
     });
 
     const before = renderDashboard(info, "0.1.0");
-    expect(before).toContain("sessions");
+    expect(before).toContain("Sessions");
 
     sessions = [{ id: "s9", status: "running", title: "fresh" }];
     const after = renderDashboard(info, "0.1.0");
-    expect(after).toContain("fresh");
-    expect(after).toContain("TUNNEL");
+    expect(after).toContain("1 running");
+    expect(after).toContain("Tunnel");
     expect(after).toContain("https://demo.example.com");
     expect(after).not.toBe(before);
   });
+
+  test("menu simpel + info provider kcg/lhr", () => {
+    const info = makeInfo({
+      server: {
+        store: {
+          listProjects: () => [],
+          listSessions: () => [],
+          getTunnelSettings: () => ({ provider: "lhr" }),
+        },
+        tunnel: {
+          status: () => ({ phase: "stopped", account: null, error: null, pairing: null }),
+        },
+        lhr: {
+          status: () => ({ phase: "online", url: "https://abc.lhr.life", error: null }),
+        },
+        tunnelProvider: () => "lhr" as const,
+      } as unknown as DashboardInfo["server"],
+    });
+
+    expect(activeProvider(info)).toBe("lhr");
+    expect(bestUrl(info)).toEqual({ label: "public (lhr)", url: "https://abc.lhr.life" });
+    expect(menuItems({}).map((m) => m.id)).toEqual([
+      "open",
+      "copy",
+      "qr",
+      "detail",
+      "port",
+      "background",
+      "quit",
+    ]);
+
+    const frame = renderDashboard(info, "0.1.0", { showQr: true, showDetail: true, menuIndex: 2 });
+    expect(frame).toContain("Running");
+    expect(frame).toContain("TUNNEL DETAIL");
+    expect(frame).toContain("OPEN ON PHONE");
+    expect(frame).toContain("lhr");
+    expect(frame).toContain("https://abc.lhr.life");
+    expect(frame).toContain("Hide phone QR");
+  });
+
+  test("URL publik punya baris sendiri", () => {
+    const info = makeInfo({
+      server: {
+        store: { listProjects: () => [], listSessions: () => [] },
+        tunnel: {
+          status: () => ({
+            phase: "online",
+            account: { url: "https://me.example.com" },
+            error: null,
+          }),
+        },
+      } as unknown as DashboardInfo["server"],
+    });
+    const frame = renderDashboard(info, "0.1.0");
+    expect(frame).toMatch(/Public\s+https:\/\/me\.example\.com/);
+    expect(frame).toContain("kcg · online");
+  });
+
+  test("konfirmasi quit saat ada session running", () => {
+    const frame = renderDashboard(makeInfo(), "0.1.0", { confirm: "quit" });
+    expect(frame).toContain("press q again");
+    expect(renderDashboard(makeInfo(), "0.1.0")).not.toContain("press q again");
+  });
+
+  test("form ganti port + catatan port fallback", () => {
+    const info = makeInfo({ portNote: "3000 in use", port: 3001 });
+    const frame = renderDashboard(info, "0.1.0", {
+      portInput: "40",
+      portError: "Enter a port number",
+    });
+    expect(frame).toContain("CHANGE PORT");
+    expect(frame).toContain("current 3001");
+    expect(frame).toContain("› 40");
+    expect(frame).toContain("Enter a port number");
+    expect(frame).toContain("(3000 in use)");
+    expect(frame).toContain("esc cancel");
+    expect(renderDashboard(makeInfo(), "0.1.0")).not.toContain("CHANGE PORT");
+  });
+
+  test("status Restarting saat ganti port", () => {
+    expect(renderDashboard(makeInfo({ restarting: true }), "0.1.0")).toContain("Restarting");
+  });
+});
+
+describe("portInputError", () => {
+  test("validasi input port", () => {
+    expect(portInputError("")).not.toBeNull();
+    expect(portInputError("0")).not.toBeNull();
+    expect(portInputError("70000")).not.toBeNull();
+    expect(portInputError("80")).toContain("1024");
+    expect(portInputError("4000")).toBeNull();
+  });
+});
+
+describe("mode background (dashboard untuk daemon)", () => {
+  test("menu Stop / Run in foreground / Close dashboard", () => {
+    expect(menuItems({}, "background").map((m) => m.id)).toEqual([
+      "open",
+      "copy",
+      "qr",
+      "detail",
+      "port",
+      "foreground",
+      "stop",
+      "quit",
+    ]);
+  });
+
+  test("render snapshot daemon", () => {
+    const snap = { ...takeSnapshot(makeInfo()), mode: "background" as const, pid: 4242 };
+    const frame = renderSnapshot(snap, "0.1.0");
+    expect(frame).toContain("Running in background");
+    expect(frame).toContain("PID 4242");
+    expect(frame).toContain("Stop server");
+    expect(frame).toContain("Close dashboard");
+    expect(frame).toContain("server keeps running");
+    expect(frame).toContain("q close");
+    expect(frame).not.toContain("Run in background");
+
+    const busy = renderSnapshot({ ...snap, restarting: true, busyLabel: "Stopping…" }, "0.1.0");
+    expect(busy).toContain("Stopping…");
+  });
+
+  test("snapshot bisa diserialisasi ke daemon.json", () => {
+    const snap = takeSnapshot(makeInfo(), "background");
+    expect(JSON.parse(JSON.stringify(snap))).toEqual(snap);
+  });
 });

package/src/cli/__tests__/keep-awake.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+import { parseArgs } from "../args";
+import { disabledKeepAwake, inhibitCommand, startKeepAwake } from "../keep-awake";
+
+describe("inhibitCommand", () => {
+  test("linux: systemd-inhibit memblok sleep & idle, child cat terikat stdin", () => {
+    const cmd = inhibitCommand("linux", 123);
+    expect(cmd?.[0]).toBe("systemd-inhibit");
+    expect(cmd).toContain("--what=sleep:idle");
+    expect(cmd).toContain("--mode=block");
+    expect(cmd?.at(-1)).toBe("cat");
+  });
+
+  test("darwin: caffeinate menunggu pid kcgcode", () => {
+    expect(inhibitCommand("darwin", 123)).toEqual(["caffeinate", "-i", "-s", "-w", "123"]);
+  });
+
+  test("platform lain tidak didukung", () => {
+    expect(inhibitCommand("freebsd", 123)).toBeNull();
+  });
+});
+
+describe("startKeepAwake", () => {
+  test("platform tak didukung → nonaktif dengan alasan", async () => {
+    const ka = await startKeepAwake("aix");
+    expect(ka.status()).toEqual({ active: false, method: null, error: "unsupported on aix" });
+    ka.stop();
+  });
+
+  test("disabledKeepAwake melaporkan --allow-sleep", () => {
+    expect(disabledKeepAwake().status().active).toBe(false);
+    expect(disabledKeepAwake().status().error).toContain("--allow-sleep");
+  });
+});
+
+describe("parseArgs --allow-sleep", () => {
+  test("default keep awake", () => {
+    expect(parseArgs([]).allowSleep).toBeUndefined();
+  });
+
+  test("flag mengizinkan sleep", () => {
+    expect(parseArgs(["start", "--allow-sleep"]).allowSleep).toBe(true);
+  });
+});

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

@@ -0,0 +1,86 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { resolveConfig, saveConfigPort } from "../../config";
+import { choosePort, portIsFree, requestedPort } from "../port";
+
+describe("requestedPort", () => {
+  test("prioritas flag > env > config > default", () => {
+    expect(requestedPort({ flag: 1, env: "2", config: 3 })).toEqual({ port: 1, source: "flag" });
+    expect(requestedPort({ env: "2", config: 3 })).toEqual({ port: 2, source: "env" });
+    expect(requestedPort({ env: "abc", config: 3 })).toEqual({ port: 3, source: "config" });
+    expect(requestedPort({})).toEqual({ port: 3000, source: "default" });
+  });
+});
+
+describe("choosePort", () => {
+  const busy = (taken: number[]) => (_h: string, p: number) => !taken.includes(p);
+
+  test("port kosong dipakai apa adanya", async () => {
+    expect(await choosePort("127.0.0.1", { port: 3000, source: "default" }, busy([]))).toEqual({
+      ok: true,
+      port: 3000,
+      fallbackFrom: null,
+    });
+  });
+
+  test("default/config terpakai → pindah ke port kosong berikutnya", async () => {
+    expect(
+      await choosePort("127.0.0.1", { port: 3000, source: "default" }, busy([3000, 3001])),
+    ).toEqual({
+      ok: true,
+      port: 3002,
+      fallbackFrom: 3000,
+    });
+    expect(
+      await choosePort("127.0.0.1", { port: 4000, source: "config" }, busy([4000])),
+    ).toMatchObject({
+      ok: true,
+      port: 4001,
+    });
+  });
+
+  test("port eksplisit terpakai → error, tanpa fallback", async () => {
+    const res = await choosePort("127.0.0.1", { port: 3000, source: "flag" }, busy([3000]));
+    expect(res.ok).toBe(false);
+    if (!res.ok) expect(res.error).toContain("--port");
+  });
+
+  test("portIsFree mendeteksi port yang sedang dipakai", async () => {
+    const s = Bun.serve({ hostname: "127.0.0.1", port: 0, fetch: () => new Response() });
+    try {
+      expect(await portIsFree("127.0.0.1", s.port as number)).toBe(false);
+    } finally {
+      s.stop(true);
+    }
+  });
+});
+
+describe("config port", () => {
+  let dir = "";
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  test("saveConfigPort menyimpan port & mempertahankan key lain", () => {
+    dir = mkdtempSync(path.join(tmpdir(), "kcg-port-"));
+    const file = path.join(dir, "config.json");
+    writeFileSync(file, JSON.stringify({ sandboxRoot: dir, extra: true }));
+
+    expect(saveConfigPort(file, 4321).ok).toBe(true);
+    expect(JSON.parse(readFileSync(file, "utf8"))).toEqual({
+      sandboxRoot: dir,
+      extra: true,
+      port: 4321,
+    });
+
+    const cfg = resolveConfig(file);
+    expect(cfg.ok && cfg.data.port).toBe(4321);
+  });
+
+  test("port tidak valid di config ditolak", () => {
+    dir = mkdtempSync(path.join(tmpdir(), "kcg-port-"));
+    const file = path.join(dir, "config.json");
+    writeFileSync(file, JSON.stringify({ sandboxRoot: dir, port: "abc" }));
+    expect(resolveConfig(file).ok).toBe(false);
+  });
+});

package/src/cli/args.ts

@@ -2,13 +2,32 @@
  * Parser argumen CLI kcgcode (tanpa dependency eksternal).
  */
 
+import { c } from "./theme";
+
 export interface CliArgs {
-  command: "start" | "init" | "reset-lock" | "help" | "version" | "invalid";
+  command:
+    | "start"
+    | "stop"
+    | "status"
+    | "logs"
+    | "init"
+    | "reset-lock"
+    | "help"
+    | "version"
+    | "invalid";
   port?: number;
   host?: string;
   /** Path berkas konfigurasi (override KCG_CONFIG_PATH). */
   config?: string;
   open: boolean;
+  /** Izinkan OS sleep (matikan keep-awake). */
+  allowSleep?: boolean;
+  /** Jalankan di background (lepas dari terminal). */
+  detach?: boolean;
+  /** `logs`: ikuti log baru. */
+  follow?: boolean;
+  /** `logs`: jumlah baris terakhir. */
+  lines?: number;
   /** Argumen tak dikenal / pesan error. */
   error?: string;
 }
@@ -17,20 +36,31 @@ const HELP_TEXT = `kcgcode — control CLI AI agents from your phone
 
 USAGE
   kcgcode [start] [options]
+  kcgcode start -d [options]
+  kcgcode stop | status | logs [-f]
   kcgcode init [options]
   kcgcode help | --help | -h
   kcgcode version | --version | -v
 
 COMMANDS
-  start (default)   Run server + terminal dashboard
+  start (default)   Run server + terminal dashboard; if it already runs
+                    in background, open its dashboard instead
+  stop              Stop the background server
+  status            Show background server status
+  logs              Show background server log (-f to follow)
   init              Create kcg-code.config.json & local sandbox folder
   reset-lock        Remove the app lock (forgot PIN/password) & sign out all devices
 
 OPTIONS
-  -p, --port <n>    HTTP port (default 3000 / env KCG_PORT)
+  -p, --port <n>    HTTP port (default: config "port" or 3000; a busy
+                    default is swapped for the next free port)
   -H, --host <h>    Bind host (default 127.0.0.1 / env KCG_HOST)
   -c, --config <f>  Config path (default ~/.kcgcode/config.json)
+  -d, --detach      Run in background (keeps running after terminal closes)
   --open            Open the web dashboard in a browser after start
+  -f, --follow      logs: keep printing new lines
+  -n, --lines <n>   logs: number of lines to show (default 50)
+  --allow-sleep     Let the OS sleep while running (default: keep awake)
   -h, --help        Show help
   -v, --version     Show version
 
@@ -39,16 +69,28 @@ ENV
   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
 
 EXAMPLES
   kcgcode
   kcgcode init
   kcgcode start --port 4000 --open
+  kcgcode start -d && kcgcode logs -f
   kcgcode init --config ~/.kcgcode/config.json
 `;
 
+/** Help berwarna: heading cyan, flag/command hijau, deskripsi redup. */
 export function helpText(): string {
-  return HELP_TEXT;
+  return HELP_TEXT.split("\n")
+    .map((line, i) => {
+      if (i === 0) return c.cyanBright(line);
+      if (/^[A-Z]+$/.test(line)) return c.cyanBright(line);
+      const m = line.match(/^(\s{2})(\S.*?)(\s{2,})(\S.*)$/);
+      if (m) return `${m[1]}${c.green(m[2] as string)}${m[3]}${c.dim(m[4] as string)}`;
+      if (/^\s+kcgcode/.test(line)) return c.white(line);
+      return line;
+    })
+    .join("\n");
 }
 
 export function parseArgs(argv: string[]): CliArgs {
@@ -63,8 +105,8 @@ export function parseArgs(argv: string[]): CliArgs {
   } else if (first === "reset-lock") {
     args.command = "reset-lock";
     rest.shift();
-  } else if (first === "start") {
-    args.command = "start";
+  } else if (first === "start" || first === "stop" || first === "status" || first === "logs") {
+    args.command = first;
     rest.shift();
   } else if (first === "help") {
     args.command = "help";
@@ -88,6 +130,27 @@ export function parseArgs(argv: string[]): CliArgs {
       args.open = true;
       continue;
     }
+    if (a === "-d" || a === "--detach") {
+      args.detach = true;
+      continue;
+    }
+    if (a === "-f" || a === "--follow") {
+      args.follow = true;
+      continue;
+    }
+    if (a === "-n" || a === "--lines") {
+      const raw = rest[++i];
+      const n = Number(raw);
+      if (raw === undefined || !Number.isInteger(n) || n <= 0) {
+        return { ...args, command: "invalid", error: `Invalid value for ${a}` };
+      }
+      args.lines = n;
+      continue;
+    }
+    if (a === "--allow-sleep") {
+      args.allowSleep = true;
+      continue;
+    }
     if (a === "-p" || a === "--port") {
       const raw = rest[++i];
       if (raw === undefined)