kcg-code 0.0.0-stage → 0.1.0

package/src/server/services/opencode-server.ts

@@ -0,0 +1,319 @@
+/**
+ * OpenCode_Server — lifecycle proses `opencode serve` per Project.
+ *
+ * Satu instance `opencode serve` hanya dapat membuat Session di direktori
+ * kerja (cwd) tempat ia dijalankan (terverifikasi: `POST /session` tidak
+ * menerima field `directory`). Karena Project KCG Code bisa berbeda-beda
+ * direktori, setiap Project mendapat satu server sendiri yang di-spawn di
+ * `project.path` — menggantikan model "satu PTY per Session".
+ *
+ * - `--port 0` meminta port acak; port ditemukan dari baris log
+ *   "opencode server listening on http://127.0.0.1:<port>" di stderr.
+ * - stdout/stderr terus di-drain (buffer log bergulir) agar pipe tidak penuh
+ *   dan memblokir proses server yang berumur panjang.
+ * - `ensureServer` idempoten dan aman terhadap konkurensi (in-flight promise).
+ * - Exit callback hanya dipanggil bila instance yang keluar masih instance
+ *   aktif — instance pengganti tidak terpengaruh.
+ */
+
+import { existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { Result } from "../result";
+import type { OpenCodeClient, OpenCodeEvent } from "./opencode-client";
+import { createOpenCodeClient } from "./opencode-client";
+
+export interface OpenCodeServerHandle {
+  projectId: string;
+  baseUrl: string;
+  client: OpenCodeClient;
+}
+
+/** Kontrak proses minimal (di-mock pada test). */
+export interface ServerProcessLike {
+  kill(signal: "SIGTERM" | "SIGKILL"): void;
+  exited: Promise<number | null>;
+  /** Stream stderr (untuk menemukan port). */
+  stderr: ReadableStream<Uint8Array>;
+  /** Stream stdout (di-drain agar tidak penuh). */
+  stdout?: ReadableStream<Uint8Array>;
+  /** PID proses (untuk SIGKILL fallback). */
+  pid?: number;
+}
+
+export interface OpenCodeServerManagerOptions {
+  /** Spawn `opencode serve` (injectable untuk test). */
+  spawn?: (cwd: string) => ServerProcessLike;
+  /** Factory client (injectable untuk test). */
+  clientFactory?: (baseUrl: string) => OpenCodeClient;
+  /** Batas waktu menunggu port tercetak di stderr (ms). */
+  portTimeoutMs?: number;
+  /** Batas waktu menunggu health (ms). */
+  readyTimeoutMs?: number;
+  /** Hook event SSE dari tiap server (diteruskan ke Session_Manager). */
+  onEvent?: (projectId: string, ev: OpenCodeEvent) => void;
+}
+
+export interface OpenCodeServerManager {
+  ensureServer(projectId: string, projectPath: string): Promise<Result<OpenCodeServerHandle>>;
+  getServer(projectId: string): OpenCodeServerHandle | undefined;
+  /**
+   * Pastikan server hidup; bila file config opencode berubah sejak spawn
+   * terakhir, server di-restart agar `/config/providers` (daftar model)
+   * dan `/agent` ikut terbaca ulang — `opencode serve` tidak hot-reload.
+   */
+  ensureFreshServer(projectId: string, projectPath: string): Promise<Result<OpenCodeServerHandle>>;
+  stopServer(projectId: string): Promise<void>;
+  stopAll(): Promise<void>;
+  /** Daftarkan hook saat server keluar tak terduga. */
+  onServerExit(cb: (projectId: string) => void): void;
+}
+
+interface ServerInstance {
+  handle: OpenCodeServerHandle;
+  proc: ServerProcessLike;
+  exiting: boolean;
+  /** Fingerprint config opencode saat server di-spawn (deteksi perubahan). */
+  configFingerprint: string;
+}
+
+/**
+ * Path file config opencode yang memengaruhi provider/model/agent:
+ * project (`opencode.json`/`opencode.jsonc`) + global user config.
+ */
+export function opencodeConfigPaths(projectPath: string): string[] {
+  const home = homedir();
+  return [
+    join(projectPath, "opencode.json"),
+    join(projectPath, "opencode.jsonc"),
+    join(home, ".config", "opencode", "opencode.json"),
+    join(home, ".config", "opencode", "opencode.jsonc"),
+    join(home, ".opencode", "opencode.json"),
+    join(home, ".opencode", "opencode.jsonc"),
+  ];
+}
+
+/**
+ * Fingerprint config: path:mtimeMs untuk tiap file yang ada. Bila nilainya
+ * berbeda dari saat spawn, config dianggap berubah dan server perlu restart.
+ */
+export function configFingerprint(projectPath: string): string {
+  const parts: string[] = [];
+  for (const p of opencodeConfigPaths(projectPath)) {
+    try {
+      if (existsSync(p)) parts.push(`${p}:${statSync(p).mtimeMs}`);
+    } catch {
+      /* file hilang / tidak readable — lewati */
+    }
+  }
+  return parts.join("|");
+}
+
+const DEFAULT_SPAWN: (cwd: string) => ServerProcessLike = (cwd) => {
+  const proc = Bun.spawn(["opencode", "serve", "--port", "0", "--hostname", "127.0.0.1"], {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  return {
+    kill: (signal) => proc.kill(signal as NodeJS.Signals),
+    exited: proc.exited.then((code) => code),
+    stderr: proc.stderr,
+    stdout: proc.stdout,
+    pid: proc.pid,
+  };
+};
+
+/** Ekstrak port dari baris log stderr "listening on http://host:port". */
+export function parseListeningPort(line: string): number | null {
+  const m = line.match(/listening on http:\/\/[^:]+:(\d+)/);
+  return m ? Number(m[1]) : null;
+}
+
+/** Poll `GET /global/health` hingga siap atau timeout. */
+export async function waitHealth(client: OpenCodeClient, timeoutMs: number): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await client.health()) return true;
+    await Bun.sleep(300);
+  }
+  return false;
+}
+
+export function createOpenCodeServerManager(
+  opts: OpenCodeServerManagerOptions = {},
+): OpenCodeServerManager {
+  const spawn = opts.spawn ?? DEFAULT_SPAWN;
+  const clientFactory = opts.clientFactory ?? createOpenCodeClient;
+  const portTimeoutMs = opts.portTimeoutMs ?? 30000;
+  const readyTimeoutMs = opts.readyTimeoutMs ?? 60000;
+  const onEvent = opts.onEvent;
+  const instances = new Map<string, ServerInstance>();
+  /** In-flight ensure agar dua panggilan paralel tidak men-spawn dua server. */
+  const pending = new Map<string, Promise<Result<OpenCodeServerHandle>>>();
+  const exitCbs = new Set<(projectId: string) => void>();
+
+  function ensureServer(
+    projectId: string,
+    projectPath: string,
+  ): Promise<Result<OpenCodeServerHandle>> {
+    const existing = instances.get(projectId);
+    if (existing && !existing.exiting) {
+      return Promise.resolve({ ok: true, data: existing.handle });
+    }
+    const inflight = pending.get(projectId);
+    if (inflight) return inflight;
+    const p = startServer(projectId, projectPath).finally(() => pending.delete(projectId));
+    pending.set(projectId, p);
+    return p;
+  }
+
+  /**
+   * Seperti `ensureServer`, tapi restart dulu bila fingerprint config
+   * berubah. Restart adalah stop + ensure (in-flight aman terhadap
+   * dua panggilan paralel lewat map `pending`).
+   */
+  async function ensureFreshServer(
+    projectId: string,
+    projectPath: string,
+  ): Promise<Result<OpenCodeServerHandle>> {
+    const existing = instances.get(projectId);
+    if (existing && !existing.exiting) {
+      if (existing.configFingerprint === configFingerprint(projectPath)) {
+        return { ok: true, data: existing.handle };
+      }
+      await stopServer(projectId);
+    }
+    return ensureServer(projectId, projectPath);
+  }
+
+  async function startServer(
+    projectId: string,
+    projectPath: string,
+  ): Promise<Result<OpenCodeServerHandle>> {
+    let proc: ServerProcessLike;
+    try {
+      proc = spawn(projectPath);
+    } catch (e) {
+      return { ok: false, error: `SERVER_START_FAILED: ${(e as Error).message}` };
+    }
+
+    // ---- Drain stdout/stderr berkelanjutan + deteksi port dari stderr ----
+    let serverLog = "";
+    let port: number | null = null;
+    let portResolved = false;
+    let resolvePort: (p: number | null) => void = () => {};
+    const portPromise = new Promise<number | null>((res) => {
+      resolvePort = res;
+    });
+    const resolveOnce = (p: number | null): void => {
+      if (!portResolved) {
+        portResolved = true;
+        resolvePort(p);
+      }
+    };
+
+    const drain = (stream: ReadableStream<Uint8Array>): void => {
+      const decoder = new TextDecoder();
+      void (async () => {
+        const reader = stream.getReader();
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) {
+            resolveOnce(port);
+            return;
+          }
+          const text = decoder.decode(value, { stream: true });
+          serverLog = (serverLog + text).slice(-16000);
+          if (port === null) {
+            const found = parseListeningPort(text);
+            if (found !== null) {
+              port = found;
+              resolveOnce(found);
+            }
+          }
+        }
+      })();
+    };
+    drain(proc.stderr);
+    if (proc.stdout) drain(proc.stdout);
+
+    const found = await Promise.race([
+      portPromise,
+      Bun.sleep(portTimeoutMs).then(() => {
+        resolveOnce(port);
+        return port;
+      }),
+    ]);
+    if (found === null) {
+      proc.kill("SIGKILL");
+      return {
+        ok: false,
+        error: `SERVER_START_FAILED: port tidak ditemukan. Log:\n${serverLog.slice(-800)}`,
+      };
+    }
+
+    const baseUrl = `http://127.0.0.1:${found}`;
+    const client = clientFactory(baseUrl);
+    if (!(await waitHealth(client, readyTimeoutMs))) {
+      proc.kill("SIGKILL");
+      return { ok: false, error: "SERVER_START_FAILED: health check gagal" };
+    }
+
+    const handle: OpenCodeServerHandle = { projectId, baseUrl, client };
+    const instance: ServerInstance = {
+      handle,
+      proc,
+      exiting: false,
+      configFingerprint: configFingerprint(projectPath),
+    };
+    instances.set(projectId, instance);
+
+    if (onEvent) {
+      client.subscribeEvents((ev) => onEvent(projectId, ev));
+    }
+
+    // Server mati tak terduga: hanya bila instance ini masih yang aktif.
+    void proc.exited.then(() => {
+      if (instance.exiting) return;
+      if (instances.get(projectId) !== instance) return; // sudah diganti — abaikan
+      instances.delete(projectId);
+      for (const cb of exitCbs) cb(projectId);
+    });
+
+    return { ok: true, data: handle };
+  }
+
+  async function stopServer(projectId: string): Promise<void> {
+    const instance = instances.get(projectId);
+    if (!instance) return;
+    instance.exiting = true;
+    instances.delete(projectId);
+    instance.proc.kill("SIGTERM");
+    await Promise.race([instance.proc.exited, Bun.sleep(3000)]);
+    if (instance.proc.pid !== undefined) {
+      try {
+        Bun.spawnSync(["kill", "-9", String(instance.proc.pid)]);
+      } catch {
+        /* best effort */
+      }
+    } else {
+      instance.proc.kill("SIGKILL");
+    }
+  }
+
+  async function stopAll(): Promise<void> {
+    await Promise.all([...instances.keys()].map((id) => stopServer(id)));
+  }
+
+  return {
+    ensureServer,
+    ensureFreshServer,
+    getServer: (projectId) => instances.get(projectId)?.handle,
+    stopServer,
+    stopAll,
+    onServerExit: (cb) => {
+      exitCbs.add(cb);
+    },
+  };
+}

package/src/server/services/opencode-sse.ts

@@ -0,0 +1,82 @@
+/**
+ * Event SSE server headless opencode — parsing & langganan.
+ *
+ * Dipisah dari `opencode-client.ts`:
+ * - `parseSseFrame` mengambil baris `data:` dari satu frame SSE.
+ * - `normalizeEvent` meratakan payload `{ id, type, properties }` menjadi
+ *   `{ type, id, ...properties }` agar konsumen mudah membaca `requestID`,
+ *   `sessionID`, `permission`, `questions`, dst.
+ * - `subscribeOpenCodeEvents` menjalankan loop baca `GET /event` dengan
+ *   reconnect otomatis; mengembalikan fungsi untuk berhenti.
+ */
+import type { OpenCodeEvent } from "./opencode-client";
+
+/** Parsing satu frame SSE: baris `data:` (dan `event:` bila ada). */
+export function parseSseFrame(frame: string): string | null {
+  const dataLine = frame.split("\n").find((l) => l.startsWith("data:"));
+  if (!dataLine) return null;
+  return dataLine.slice(5).trim();
+}
+
+/** Normalisasi payload event SSE `{ id, type, properties }` -> event datar. */
+export function normalizeEvent(payload: unknown): OpenCodeEvent | null {
+  if (typeof payload !== "object" || payload === null) return null;
+  const raw = payload as Record<string, unknown>;
+  if (typeof raw.type !== "string") return null;
+  const props =
+    typeof raw.properties === "object" && raw.properties !== null
+      ? (raw.properties as Record<string, unknown>)
+      : {};
+  return { type: raw.type, ...(raw.id !== undefined ? { id: String(raw.id) } : {}), ...props };
+}
+
+/**
+ * Buka langganan event SSE (`GET /event`) dan panggil `cb` untuk setiap
+ * event. Bila koneksi putus/error, coba lagi setelah jeda 1 detik. Fungsi
+ * yang dikembalikan menghentikan langganan (membatalkan reader aktif).
+ */
+export function subscribeOpenCodeEvents(
+  baseUrl: string,
+  cb: (ev: OpenCodeEvent) => void,
+): () => void {
+  let cancelled = false;
+  let reader: ReadableStreamDefaultReader<Uint8Array> | null = null;
+  void (async () => {
+    while (!cancelled) {
+      try {
+        const res = await fetch(`${baseUrl}/event`);
+        if (!res.ok || !res.body) {
+          await Bun.sleep(1000);
+          continue;
+        }
+        reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buf = "";
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done || cancelled) break;
+          buf += decoder.decode(value, { stream: true });
+          const frames = buf.split("\n\n");
+          buf = frames.pop() ?? "";
+          for (const frame of frames) {
+            const data = parseSseFrame(frame);
+            if (data === null) continue;
+            try {
+              const ev = normalizeEvent(JSON.parse(data));
+              if (ev) cb(ev);
+            } catch {
+              /* frame tidak valid — abaikan */
+            }
+          }
+        }
+      } catch {
+        /* koneksi SSE terputus — coba lagi setelah jeda */
+      }
+      if (!cancelled) await Bun.sleep(1000);
+    }
+  })();
+  return () => {
+    cancelled = true;
+    reader?.cancel().catch(() => {});
+  };
+}

package/src/server/services/project-manager.ts

@@ -0,0 +1,147 @@
+/**
+ * Project_Manager & Folder_Browser.
+ * Sesuai `design.md` — `project-manager.ts`.
+ *
+ * `listDirectory` dan `createProject` selalu memvalidasi path lewat
+ * `sandbox.ts` sebelum operasi filesystem apa pun, dan memakai `db.ts`
+ * untuk persistensi.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readdirSync } from "node:fs";
+import type { SessionStore } from "../../db";
+import type { Project } from "../../types";
+import type { Result, SimpleResult } from "../result";
+import { resolveWithinSandbox } from "./sandbox";
+
+export interface ProjectManager {
+  listDirectory(relativePath: string): Result<{ entries: string[] }>;
+  createProject(name: string, relativePath: string): Result<Project>;
+  listProjects(): Project[];
+  getProject(projectId: string): Result<Project>;
+  /**
+   * Simpan custom instruction Project. Teks di-trim; kosong -> `null`
+   * (hapus). Menolak teks di atas `MAX_PROJECT_INSTRUCTIONS_LENGTH`.
+   */
+  updateInstructions(projectId: string, instructions: string): Result<Project>;
+  /**
+   * Hapus registrasi Project dari Session_Store. Direktori kerja di
+   * filesystem TIDAK disentuh — Project hanyalah pendaftaran sebuah folder,
+   * jadi menghapusnya tidak boleh menghapus kode/pekerjaan pengguna.
+   * Menolak bila masih ada Session miliknya (`PROJECT_HAS_SESSIONS`).
+   */
+  deleteProject(projectId: string): SimpleResult;
+  /** Sandbox_Root aktif (path absolut). */
+  getSandboxRoot(): string;
+  /**
+   * Ganti Sandbox_Root saat berjalan (Settings -> Workspace). Pemanggil
+   * WAJIB sudah memvalidasi root lewat `workspace.ts`; dari titik ini semua
+   * operasi (listing, create) memakai root baru.
+   */
+  setSandboxRoot(root: string): void;
+}
+
+/** Batas panjang custom instruction Project (karakter). */
+export const MAX_PROJECT_INSTRUCTIONS_LENGTH = 20_000;
+
+/** Peta hasil validasi sandbox -> pesan error publik. */
+function sandboxError(reason: string): string {
+  return reason === "outside_sandbox" ? "PATH_OUTSIDE_SANDBOX" : "INVALID_PATH_CHARS";
+}
+
+/**
+ * Membuat instance Project_Manager terikat pada `store`. Sandbox_Root
+ * awal dari config; bisa diganti lewat `setSandboxRoot` tanpa restart.
+ */
+export function createProjectManager(initialRoot: string, store: SessionStore): ProjectManager {
+  let sandboxRoot = initialRoot;
+  function listDirectory(relativePath: string): Result<{ entries: string[] }> {
+    const res = resolveWithinSandbox(sandboxRoot, relativePath);
+    if (!res.ok) return { ok: false, error: sandboxError(res.reason) };
+
+    const realPath = res.realPath;
+    let dirents: import("node:fs").Dirent[];
+    try {
+      dirents = readdirSync(realPath, { withFileTypes: true });
+    } catch {
+      return { ok: false, error: "PATH_NOT_FOUND" };
+    }
+
+    // Hanya sub-direktori (Requirement 10.2). Symlink tidak diikuti sehingga
+    // entri dari luar sandbox tidak pernah bocor ke hasil listing.
+    const entries = dirents
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name)
+      .sort();
+    return { ok: true, data: { entries } };
+  }
+
+  function createProject(name: string, relativePath: string): Result<Project> {
+    const trimmed = name.trim();
+    if (!trimmed) return { ok: false, error: "NAME_REQUIRED" };
+
+    const byName = store.getProjectByName(trimmed);
+    if (byName.ok) return { ok: false, error: "NAME_TAKEN" };
+
+    const res = resolveWithinSandbox(sandboxRoot, relativePath);
+    if (!res.ok) return { ok: false, error: sandboxError(res.reason) };
+    const realPath = res.realPath;
+
+    const byPath = store.getProjectByPath(realPath);
+    if (byPath.ok) return { ok: false, error: "PATH_TAKEN" };
+
+    try {
+      mkdirSync(realPath, { recursive: true });
+    } catch {
+      return { ok: false, error: "MKDIR_FAILED" };
+    }
+
+    const project: Project = {
+      id: randomUUID(),
+      name: trimmed,
+      path: realPath,
+      createdAt: Date.now(),
+      instructions: null,
+    };
+    const inserted = store.insertProject(project);
+    if (!inserted.ok) return inserted;
+    return { ok: true, data: project };
+  }
+
+  function listProjects(): Project[] {
+    return store.listProjects();
+  }
+
+  function getProject(projectId: string): Result<Project> {
+    return store.getProjectById(projectId);
+  }
+
+  function updateInstructions(projectId: string, instructions: string): Result<Project> {
+    const trimmed = instructions.trim();
+    if (trimmed.length > MAX_PROJECT_INSTRUCTIONS_LENGTH) {
+      return { ok: false, error: "INSTRUCTIONS_TOO_LONG" };
+    }
+    return store.updateProjectInstructions(projectId, trimmed === "" ? null : trimmed);
+  }
+
+  /**
+   * Hapus pendaftaran Project. Direktori kerjanya dibiarkan utuh: Project
+   * adalah referensi ke sebuah folder Sandbox, bukan pemiliknya — menghapus
+   * folder berisi kode pengguna jauh melampaui maksud aksi ini.
+   */
+  function deleteProject(projectId: string): SimpleResult {
+    return store.deleteProject(projectId);
+  }
+
+  return {
+    listDirectory,
+    createProject,
+    listProjects,
+    getProject,
+    updateInstructions,
+    deleteProject,
+    getSandboxRoot: () => sandboxRoot,
+    setSandboxRoot: (root: string) => {
+      sandboxRoot = root;
+    },
+  };
+}

package/src/server/services/sandbox.ts

@@ -0,0 +1,83 @@
+/**
+ * Validator Sandbox_Root — `resolveWithinSandbox`.
+ * Sesuai `design.md` — `sandbox.ts`.
+ *
+ * Langkah validasi:
+ * 1. Tolak segmen path yang berisi `..` sebelum resolusi apa pun.
+ * 2. Validasi karakter terlarang OS pada tiap segmen nama direktori.
+ * 3. Resolve path (mengikuti symlink) lalu pastikan hasil berada di dalam
+ *    `sandboxRoot` (startsWith `rootReal + sep` atau sama persis).
+ *
+ * Path yang belum ada di filesystem (mis. saat `createProject` akan mkdir)
+ * tetap diperbolehkan selama seluruh segmen valid dan ancestor terdalam yang
+ * sudah ada berada di dalam sandbox.
+ */
+import { existsSync, realpathSync } from "node:fs";
+import path from "node:path";
+
+export type SandboxReason = "outside_sandbox" | "invalid_chars";
+
+export type SandboxResult = { ok: true; realPath: string } | { ok: false; reason: SandboxReason };
+
+/** Karakter terlarang untuk nama direktori sesuai OS server. */
+const FORBIDDEN_CHARS = process.platform === "win32" ? /[<>:"|?*\0/\\]/ : /[\0]/;
+
+function isWithin(rootReal: string, p: string): boolean {
+  return p === rootReal || p.startsWith(rootReal + path.sep);
+}
+
+function splitSegments(userPath: string): string[] {
+  return userPath.split(/[\\/]/).filter((s) => s.length > 0 && s !== ".");
+}
+
+/**
+ * Memvalidasi dan me-resolve `userPath` terhadap `sandboxRoot`.
+ * Mengembalikan path absolut hasil resolusi bila valid.
+ */
+export function resolveWithinSandbox(sandboxRoot: string, userPath: string): SandboxResult {
+  let rootReal: string;
+  try {
+    rootReal = realpathSync(sandboxRoot);
+  } catch {
+    return { ok: false, reason: "outside_sandbox" };
+  }
+
+  const segments = splitSegments(userPath);
+
+  // 1. Tolak ".." sebelum resolusi apa pun
+  // 2. Validasi karakter terlarang OS
+  for (const seg of segments) {
+    if (seg === "..") return { ok: false, reason: "outside_sandbox" };
+    if (FORBIDDEN_CHARS.test(seg)) return { ok: false, reason: "invalid_chars" };
+  }
+
+  // 3. Gabungkan + resolve, mengikuti symlink.
+  //    Path absolut dipakai langsung (bukan digabung) sehingga path absolut di
+  //    luar sandbox pasti tertolak oleh pemeriksaan kontainmen.
+  const candidate = path.isAbsolute(userPath)
+    ? path.normalize(userPath)
+    : path.join(rootReal, ...segments);
+
+  // Cari ancestor terdalam yang sudah ada di filesystem agar `realpath`
+  // (yang mengikuti symlink) dapat dijalankan meski path tujuan belum dibuat.
+  let existing = candidate;
+  const tail: string[] = [];
+  while (!existsSync(existing)) {
+    const parent = path.dirname(existing);
+    if (parent === existing) return { ok: false, reason: "outside_sandbox" };
+    tail.unshift(path.basename(existing));
+    existing = parent;
+  }
+
+  let realExisting: string;
+  try {
+    realExisting = realpathSync(existing);
+  } catch {
+    return { ok: false, reason: "outside_sandbox" };
+  }
+
+  if (!isWithin(rootReal, realExisting)) return { ok: false, reason: "outside_sandbox" };
+
+  const realPath = tail.length === 0 ? realExisting : path.join(realExisting, ...tail);
+  return { ok: true, realPath };
+}