kcg-code 0.0.0-stage → 0.2.0

package/src/hooks/useMention.ts

@@ -0,0 +1,236 @@
+/**
+ * Deteksi & penyelesaian referensi `@file` pada input composer (meniru
+ * perilaku `@` di opencode TUI).
+ *
+ * Logika murni yang dapat diuji tanpa DOM:
+ * - `activeMention(text, caret)`: token `@query` yang sedang diketik pada
+ *   posisi kursor (bila ada), beserta rentang [start, end) di string input.
+ * - `applyMention(text, range, path)`: ganti token `@query` dengan teks
+ *   `@path` saat satu saran dipilih.
+ *
+ * Hook `useFileMention` mengelola state dropdown + fetch `/files?q=`
+ * dengan debounce 150 ms; server mencari via index milik opencode.
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export interface ActiveMention {
+  /** Teks query setelah `@` (tanpa simbol `@`). */
+  query: string;
+  /** Posisi awal token (indeks karakter `@`). */
+  start: number;
+  /** Posisi akhir token (satu melewati karakter terakhir query). */
+  end: number;
+}
+
+/** Apakah karakter dipisah kata (token `@` berhenti di sini). */
+function isBoundary(ch: string | undefined): boolean {
+  if (ch === undefined) return true;
+  return /[\s]/.test(ch) || "()[]{}<>,'\"`".includes(ch);
+}
+
+/**
+ * Token `@query` aktif pada posisi kursor — hanya bila kursor berada di
+ * dalam/di akhir token dan token tersebut dimulai dengan `@` yang berdiri
+ * sendiri (bukan bagian dari kata lain, mis. email).
+ */
+export function activeMention(text: string, caret: number): ActiveMention | null {
+  if (caret < 0 || caret > text.length) return null;
+  // Cari `@` terakhir sebelum kursor tanpa spasi di antaranya.
+  let at = -1;
+  for (let i = caret - 1; i >= 0; i--) {
+    const ch = text[i];
+    if (ch === "@") {
+      at = i;
+      break;
+    }
+    if (isBoundary(ch)) return null;
+  }
+  if (at < 0) return null;
+  // `@` harus berdiri sendiri (awal teks atau dipisah karakter non-kata).
+  const before = text[at - 1];
+  if (before !== undefined && !isBoundary(before)) return null;
+  const query = text.slice(at + 1, caret);
+  // Query tak boleh memuat pemisah kata (kursor sudah dijaga di atas, tapi
+  // token yang tersisa bisa saja panjang — batasi agar fetch masuk akal).
+  if (query.length > 200) return null;
+  return { query, start: at, end: caret };
+}
+
+/** Ganti token `@query` pada rentang `range` dengan `@<path>`. */
+export function applyMention(text: string, range: ActiveMention, path: string): string {
+  const replacement = `@${path}`;
+  const after = text[range.end];
+  // Beri spasi penutup bila karakter setelah token bukan pemisah.
+  const suffix = after !== undefined && !isBoundary(after) ? " " : "";
+  return text.slice(0, range.start) + replacement + suffix + text.slice(range.end);
+}
+
+export interface UseFileMentionResult {
+  /** Saran file yang sedang tampil (kosong = dropdown tertutup). */
+  suggestions: string[];
+  /** Indeks saran yang disorot (navigasi panah). */
+  highlighted: number;
+  /** Range token `@` aktif saat ini; null bila tidak ada. */
+  mention: ActiveMention | null;
+  loading: boolean;
+  error: string | null;
+  /** Dipanggil dari onChange textarea. */
+  onInputChange(text: string, caret: number): void;
+  /** Pilih saran pada indeks tertentu -> hasil teks baru via `applyMention`. */
+  pick(index: number): string | null;
+  /** Navigasi keyboard; return true bila event ditangani (blok default). */
+  handleKeyDown(e: { key: string; preventDefault(): void }): boolean;
+  /**
+   * Pasang callback yang dipanggil saat saran dipilih via keyboard
+   * (Enter/Tab) — menerima teks input baru hasil substitusi `@path`.
+   */
+  setOnPick(cb: (next: string) => void): void;
+  /** Tutup dropdown (mis. saat blur). */
+  close(): void;
+}
+
+export interface UseFileMentionOptions {
+  /** Endpoint pencarian file, mis. `/api/sessions/:id/files`. */
+  endpoint: string;
+  /** Jeda debounce fetch (default 150 ms). */
+  debounceMs?: number;
+  /** Batas saran yang ditampilkan. */
+  limit?: number;
+}
+
+type FetchFn = (path: string) => Promise<Response>;
+
+export function useFileMention(
+  opts: UseFileMentionOptions,
+  fetchFn: FetchFn = (p) => fetch(p),
+): UseFileMentionResult {
+  const { endpoint, debounceMs = 150, limit = 8 } = opts;
+  const [mention, setMention] = useState<ActiveMention | null>(null);
+  const [suggestions, setSuggestions] = useState<string[]>([]);
+  const [highlighted, setHighlighted] = useState(0);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const lastTextRef = useRef("");
+  const lastCaretRef = useRef(0);
+
+  const close = useCallback(() => {
+    setSuggestions([]);
+    setMention(null);
+    setHighlighted(0);
+    setError(null);
+  }, []);
+
+  /** Pasang callback pilihan keyboard (dipanggil sekali dari efek pemanggil). */
+  const setOnPick = useCallback((cb: (next: string) => void) => {
+    onPickRef.current = cb;
+  }, []);
+
+  // Fetch saran (debounced) setiap mention berubah. fetchFn/endpoint tidak
+  // masuk dependency (stabil dari pemanggil; efek cukup pada perubahan token).
+  // biome-ignore lint/correctness/useExhaustiveDependencies: dependensi eksternal sengaja dipatok
+  useEffect(() => {
+    if (!mention) return;
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+      setLoading(true);
+      setError(null);
+      fetchFn(`${endpoint}?q=${encodeURIComponent(mention.query)}`)
+        .then(async (res) => {
+          if (!res.ok) throw new Error(`HTTP ${res.status}`);
+          const body = (await res.json()) as { files?: unknown };
+          const files = Array.isArray(body.files)
+            ? body.files.filter((f): f is string => typeof f === "string")
+            : [];
+          setSuggestions(files.slice(0, limit));
+          setHighlighted(0);
+        })
+        .catch((e) => {
+          if ((e as Error).name === "AbortError") return;
+          setError("Failed to search files");
+          setSuggestions([]);
+        })
+        .finally(() => {
+          if (!controller.signal.aborted) setLoading(false);
+        });
+    }, debounceMs);
+    return () => {
+      clearTimeout(timer);
+      controller.abort();
+    };
+  }, [mention?.start, mention?.query]);
+
+  const onInputChange = useCallback(
+    (text: string, caret: number) => {
+      lastTextRef.current = text;
+      lastCaretRef.current = caret;
+      const m = activeMention(text, caret);
+      if (m) {
+        setMention(m);
+      } else {
+        close();
+      }
+    },
+    [close],
+  );
+
+  const pick = useCallback(
+    (index: number): string | null => {
+      if (!mention || suggestions[index] === undefined) return null;
+      const next = applyMention(lastTextRef.current, mention, suggestions[index] as string);
+      close();
+      return next;
+    },
+    [mention, suggestions, close],
+  );
+
+  /**
+   * Ref ke callback pemanggil: hasil `pick` (teks baru) disetel ke state
+   * input lewat sini — hook tidak memegang state textarea.
+   */
+  const onPickRef = useRef<((next: string) => void) | null>(null);
+
+  const handleKeyDown = useCallback(
+    (e: { key: string; preventDefault(): void }): boolean => {
+      if (!mention || suggestions.length === 0) return false;
+      if (e.key === "ArrowDown") {
+        e.preventDefault();
+        setHighlighted((h) => (h + 1) % suggestions.length);
+        return true;
+      }
+      if (e.key === "ArrowUp") {
+        e.preventDefault();
+        setHighlighted((h) => (h - 1 + suggestions.length) % suggestions.length);
+        return true;
+      }
+      if (e.key === "Enter" || e.key === "Tab") {
+        e.preventDefault();
+        const next = pick(highlighted);
+        // Teruskan teks baru ke pemanggil — tanpa ini hasil pilihan keyboard
+        // terbuang (bug: Enter tidak menyisipkan file).
+        if (next !== null) onPickRef.current?.(next);
+        return next !== null;
+      }
+      if (e.key === "Escape") {
+        e.preventDefault();
+        close();
+        return true;
+      }
+      return false;
+    },
+    [mention, suggestions, highlighted, pick, close],
+  );
+
+  return {
+    suggestions,
+    highlighted,
+    mention,
+    loading,
+    error,
+    onInputChange,
+    pick,
+    handleKeyDown,
+    setOnPick,
+    close,
+  };
+}

package/src/hooks/useProjects.ts

@@ -0,0 +1,88 @@
+/**
+ * Engine homepage (`ProjectsPage`): daftar Project + ringkasan per Project.
+ *
+ * `GET /api/projects` + `GET /api/sessions` dimuat bersamaan, lalu
+ * ringkasan & pencarian dihitung `lib/project-overview.ts` (murni, teruji).
+ * Komponen halaman tinggal merender hasilnya.
+ */
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { ApiError, apiFetch } from "@/lib/api";
+import {
+  buildProjectOverviews,
+  filterProjectOverviews,
+  type ProjectOverview,
+  totalRunningSessions,
+} from "@/lib/project-overview";
+import type { Project, Session } from "@/types";
+
+/** Ambang jumlah Project sebelum kolom pencarian ditampilkan. */
+const SEARCH_THRESHOLD = 5;
+
+export interface UseProjectsResult {
+  overviews: ProjectOverview[];
+  loading: boolean;
+  loadError: string | null;
+  refresh: () => Promise<void>;
+  /** Hasil pencarian (nama/path) dari `overviews`. */
+  visible: ProjectOverview[];
+  running: number;
+  showSearch: boolean;
+  /** Dialog pembuatan Project baru. */
+  dialogOpen: boolean;
+  setDialogOpen: (open: boolean) => void;
+  query: string;
+  setQuery: (query: string) => void;
+}
+
+export function useProjects(): UseProjectsResult {
+  const [overviews, setOverviews] = useState<ProjectOverview[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  const [dialogOpen, setDialogOpen] = useState(false);
+  const [query, setQuery] = useState("");
+
+  const refresh = useCallback(async () => {
+    setLoading(true);
+    setLoadError(null);
+    try {
+      // Session dimuat bersamaan supaya tiap baris bisa menampilkan status &
+      // target "Lanjutkan" tanpa request tambahan per Project.
+      const [projectsRes, sessionsRes] = await Promise.all([
+        apiFetch("/api/projects"),
+        apiFetch("/api/sessions"),
+      ]);
+      const [{ projects }, { sessions }] = (await Promise.all([
+        projectsRes.json(),
+        sessionsRes.json(),
+      ])) as [{ projects: Project[] }, { sessions: Session[] }];
+      setOverviews(buildProjectOverviews(projects, sessions));
+    } catch (e) {
+      setOverviews([]);
+      setLoadError(e instanceof ApiError ? e.message : "Failed to load projects");
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  const visible = useMemo(() => filterProjectOverviews(overviews, query), [overviews, query]);
+  const running = totalRunningSessions(overviews);
+  const showSearch = overviews.length >= SEARCH_THRESHOLD;
+
+  return {
+    overviews,
+    loading,
+    loadError,
+    refresh,
+    visible,
+    running,
+    showSearch,
+    dialogOpen,
+    setDialogOpen,
+    query,
+    setQuery,
+  };
+}

package/src/hooks/useResyncOnReconnect.ts

@@ -0,0 +1,28 @@
+/**
+ * `useResyncOnReconnect` — muat ulang data setelah koneksi WebSocket
+ * TERSAMBUNG ULANG (bukan saat koneksi pertama).
+ *
+ * Broadcast (status, hapus, data berubah) yang terjadi selama koneksi putus
+ * tidak dikirim ulang oleh server, jadi daftar di layar bisa basi. Begitu
+ * status kembali `connected` setelah sebelumnya pernah terhubung, `resync`
+ * dipanggil sekali untuk menutup celah itu.
+ */
+import { useEffect, useRef } from "react";
+import type { WsConnectionStatus } from "@/hooks/useWebSocket";
+
+export function useResyncOnReconnect(status: WsConnectionStatus, resync: () => unknown): void {
+  const wasConnected = useRef(false);
+  const lost = useRef(false);
+  const resyncRef = useRef(resync);
+  resyncRef.current = resync;
+
+  useEffect(() => {
+    if (status === "connected") {
+      if (wasConnected.current && lost.current) void resyncRef.current();
+      wasConnected.current = true;
+      lost.current = false;
+    } else if (wasConnected.current) {
+      lost.current = true;
+    }
+  }, [status]);
+}

package/src/hooks/useRouter.ts

@@ -0,0 +1,92 @@
+/**
+ * Router URL tipis untuk shell SPA KCG Code (tanpa dependency).
+ *
+ * - Server (`src/server/app.ts`) menyajikan shell SPA hanya untuk rute halaman
+ *   yang terdaftar di `src/index.ts` (`spaPaths`), sehingga tiap halaman punya
+ *   URL sendiri; `components/layout/AppShell.tsx` memetakan
+ *   `location.pathname` -> view via `parseRoute()` di `lib/routes.ts`.
+ * - `navigate()` memakai History API (`pushState`) + registry listener;
+ *   `useRouter()` berlangganan event `popstate` (tombol back/forward browser)
+ *   dan registry tersebut (navigasi dari dalam aplikasi).
+ * - `navigate(path, { transition })` membungkus perubahan dalam View
+ *   Transitions API (bila didukung & pengguna tidak memilih reduced motion):
+ *   DOM baru dirender sinkron (`flushSync`) di dalam callback sehingga browser
+ *   bisa me-morph elemen bernama `view-transition-name` yang sama antar
+ *   halaman. Tanpa dukungan -> navigasi biasa, tanpa animasi.
+ */
+
+import { useCallback, useEffect, useState } from "react";
+import { flushSync } from "react-dom";
+
+const ROUTE_CHANGE_EVENT = "kcg-code-route-change";
+
+/** Listener perubahan route hasil `navigate()` (popstate ditangani terpisah). */
+const listeners = new Set<() => void>();
+
+export interface NavigateOptions {
+  /**
+   * Nama jenis transisi (mis. "to-session"). Dipasang sebagai atribut
+   * `data-vt` di `<html>` selama animasi berjalan agar CSS bisa memilih
+   * animasi yang sesuai.
+   */
+  transition?: string;
+}
+
+function commit(path: string): void {
+  window.history.pushState({}, "", path);
+  window.dispatchEvent(new Event(ROUTE_CHANGE_EVENT));
+  for (const listener of listeners) listener();
+}
+
+function canAnimate(): boolean {
+  return (
+    typeof document.startViewTransition === "function" &&
+    !window.matchMedia("(prefers-reduced-motion: reduce)").matches
+  );
+}
+
+/**
+ * Navigasi SPA: ubah URL tanpa reload halaman, lalu beri tahu subscriber
+ * `useRouter()`. Tidak melakukan apa-apa bila History API tidak tersedia.
+ */
+export function navigate(path: string, options: NavigateOptions = {}): void {
+  if (typeof window === "undefined" || typeof window.history === "undefined") return;
+  const { transition } = options;
+  if (!transition || !canAnimate()) {
+    commit(path);
+    return;
+  }
+  const root = document.documentElement;
+  root.dataset.vt = transition;
+  const vt = document.startViewTransition(() => {
+    // Render halaman tujuan secara sinkron agar snapshot "sesudah" lengkap.
+    flushSync(() => commit(path));
+  });
+  void vt.finished.finally(() => {
+    if (root.dataset.vt === transition) delete root.dataset.vt;
+  });
+}
+
+/**
+ * Hook: pathname saat ini, diperbarui saat navigasi SPA (`navigate()`) maupun
+ * tombol back/forward browser (`popstate`).
+ */
+export function useRouter(): { pathname: string; navigate: typeof navigate } {
+  const [pathname, setPathname] = useState(() => window.location.pathname);
+
+  useEffect(() => {
+    const sync = () => setPathname(window.location.pathname);
+    window.addEventListener("popstate", sync);
+    window.addEventListener(ROUTE_CHANGE_EVENT, sync);
+    listeners.add(sync);
+    return () => {
+      window.removeEventListener("popstate", sync);
+      window.removeEventListener(ROUTE_CHANGE_EVENT, sync);
+      listeners.delete(sync);
+    };
+  }, []);
+
+  const go = useCallback((path: string, options?: NavigateOptions) => navigate(path, options), []);
+
+  return { pathname, navigate: go };
+}