@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/cli/lib/commands/update.js

@@ -0,0 +1,147 @@
+// `kabmo update` — replace this install with the latest version on npm.
+//
+// The installation mechanics live in the shared update engine so the CLI and
+// the console's "Update" button do the same thing; this command owns the
+// terminal presentation and restarts the instances still serving the previous
+// build (the ones the CLI started — a server running from source is left to its
+// own launcher).
+
+import { color, configure, error, log, ok, warn, printJson, isJson, isQuiet } from '@/cli/lib/output.js';
+import { listLiveInstances } from '@/cli/lib/runtime.js';
+import { stopInstance } from '@/cli/lib/stop-instance.js';
+import { restartAuthWarning, restartServeOptions, selectRestartTargets } from '@/cli/lib/restart-scope.js';
+import { STOP_TIMEOUT_MS } from '@/cli/lib/process-lifecycle.js';
+import { run as runServe } from '@/cli/lib/commands/serve.js';
+import { skipRestartNote } from '@/server/lib/lifecycle/restart';
+import { isCliManaged } from '@/server/lib/lifecycle/launch-mode';
+import { resolveInstallContext, resolveKabmoVersion, updateKabmo } from '@/server/lib/updates/install';
+import { releaseTagUrl } from '@/server/lib/updates/release-url';
+
+/**
+ * Live instances to restart after an update. The selection rule lives in
+ * `restart-scope.js` so it is testable without a live server; the doc comment
+ * there explains why ownership — not port order — decides.
+ */
+async function liveInstances(options) {
+  return selectRestartTargets(await listLiveInstances(), Boolean(options?.all));
+}
+
+/**
+ * The context a replacement is spawned from.
+ *
+ * After a RENAME the installed package is not the one this command runs out of
+ * (`bun add -g @kabmo-labs/kabmo` leaves the pre-rename package untouched on
+ * disk), so restarting from `ctx.pkgRoot` relaunches the build the update just
+ * replaced — measured: the console came back as the OLD version after a
+ * successful move to the new one. The installed copy's own root wins whenever
+ * the update reported one.
+ */
+export function restartCtx(ctx, installed) {
+  if (!installed || typeof installed.root !== 'string' || installed.root.length === 0) return ctx;
+  return { ...ctx, pkgRoot: installed.root, bin: installed.bin ?? ctx.bin };
+}
+
+async function restartInstances(options, ctx) {
+  const restarted = [];
+  const skipped = [];
+  const failed = [];
+  for (const entry of await liveInstances(options)) {
+    if (!isCliManaged(entry.launchMode)) {
+      skipped.push({ port: entry.port, pid: entry.pid, launchMode: entry.launchMode });
+      log(`Skipping Kabmo on port ${entry.port}: ${skipRestartNote(entry.launchMode)}.`);
+      continue;
+    }
+
+    log(`Restarting Kabmo on port ${entry.port} (pid ${entry.pid})...`);
+    // The stop decides whether a start can happen: a server still holding the
+    // port would make the spawn fail on the port guard, which reads as the
+    // restart's own failure. Name the real cause instead.
+    const gone = await stopInstance(entry, { timeoutMs: STOP_TIMEOUT_MS });
+    if (!gone) {
+      warn(`Kabmo on port ${entry.port} (pid ${entry.pid}) is still running — it was not restarted.`);
+      failed.push({ port: entry.port, pid: entry.pid });
+      continue;
+    }
+    const authWarning = restartAuthWarning(entry, options?.handoverPayload);
+    if (authWarning) warn(authWarning);
+    await runServe(restartServeOptions(entry, options), ctx);
+    restarted.push(entry.port);
+  }
+  return { restarted, skipped, failed };
+}
+
+async function runCheck(pkgRoot, json) {
+  const info = await resolveKabmoVersion(pkgRoot);
+  const context = resolveInstallContext(pkgRoot);
+
+  if (json) {
+    printJson({
+      current: info.current,
+      latest: info.latest,
+      updateAvailable: info.updateAvailable,
+      installed: true,
+      method: context.method,
+      reason: context.reason,
+      error: info.error,
+      releaseUrl: info.latest ? releaseTagUrl(info.latest) : null,
+    });
+  } else {
+    log(`Current version: ${info.current ?? 'unknown'}`);
+    if (info.updateAvailable) {
+      log(color.yellow(`New version available: ${info.latest}`));
+    } else if (!info.error) {
+      ok('Already up to date');
+    }
+    if (info.error) warn(info.error);
+  }
+
+  if (info.error) process.exitCode = 1;
+}
+
+export async function run(options, ctx) {
+  const json = isJson();
+  const quiet = isQuiet();
+  const pkgRoot = ctx?.pkgRoot ?? process.cwd();
+  const force = Boolean(options?.force);
+  const shouldRestart = options?.restart !== false;
+  const onStage = quiet || json ? undefined : (label) => process.stdout.write(`${color.dim(`\u203a ${label}...`)}\n`);
+  const onLine = quiet || json ? undefined : (chunk) => process.stdout.write(chunk);
+
+  if (options?.check) {
+    return runCheck(pkgRoot, json);
+  }
+
+  const result = await updateKabmo({ force, pkgRoot, onStage, onLine });
+
+  if (json) {
+    // Restarting prints through the serve command; silence it so stdout stays
+    // one JSON document.
+    if (result.success && result.updated && shouldRestart) configure({ json: false, quiet: true });
+    const { restarted, skipped, failed } = result.success && result.updated && shouldRestart
+      ? await restartInstances(options, restartCtx(ctx, result.installed))
+      : { restarted: [], skipped: [], failed: [] };
+    printJson({ ...result, restarted, skipped, failed });
+    if (!result.success || failed.length > 0) process.exitCode = 1;
+    return;
+  }
+
+  if (!result.success) {
+    (result.manual ? warn : error)(result.message);
+    process.exitCode = 1;
+    return;
+  }
+
+  ok(result.message);
+  if (!result.updated) return;
+
+  if (!shouldRestart) {
+    log('Restart the server to apply it: `kabmo restart`.');
+    return;
+  }
+
+  const { restarted, skipped, failed } = await restartInstances(options, restartCtx(ctx, result.installed));
+  if (restarted.length === 0 && skipped.length === 0) {
+    log('No running instance to restart.');
+  }
+  if (failed.length > 0) process.exitCode = 1;
+}

package/src/cli/lib/commands/update.test.js

@@ -0,0 +1,36 @@
+// The context `kabmo update` restarts from.
+//
+// Pinned because getting it wrong is silent and expensive: after a RENAME the
+// installed package is a different directory from the one this command runs
+// out of, and restarting from `ctx.pkgRoot` relaunches the build the update
+// just replaced. Measured on the 4.23.1 → 0.0.1 move: the console came back as
+// the old version while the update reported success.
+
+import { describe, expect, test } from 'bun:test';
+
+import { restartCtx } from '@/cli/lib/commands/update.js';
+
+const ctx = { cwd: '/work', pkgRoot: '/global/node_modules/ompchamber', version: '4.23.1', bin: 'ompchamber' };
+
+describe('restartCtx', () => {
+  test('spawns the replacement from the copy the update installed', () => {
+    const installed = {
+      root: '/global/node_modules/@kabmo-labs/kabmo',
+      packageName: '@kabmo-labs/kabmo',
+      bin: 'kabmo',
+      cli: '/global/node_modules/@kabmo-labs/kabmo/src/cli/kabmo.js',
+    };
+    expect(restartCtx(ctx, installed)).toEqual({
+      ...ctx,
+      pkgRoot: '/global/node_modules/@kabmo-labs/kabmo',
+      bin: 'kabmo',
+    });
+  });
+
+  test('keeps this command\u2019s own root when the update reported none', () => {
+    // A checkout, or a run whose install could not be read: the copy that was
+    // updated IS this one, so nothing moves.
+    expect(restartCtx(ctx, null)).toBe(ctx);
+    expect(restartCtx(ctx, { root: '' })).toBe(ctx);
+  });
+});

package/src/cli/lib/output.js

@@ -0,0 +1,143 @@
+const state = {
+  json: false,
+  quiet: false,
+};
+
+/**
+ * Store module-level output flags for the current process.
+ */
+export function configure({ json = false, quiet = false } = {}) {
+  state.json = Boolean(json);
+  state.quiet = Boolean(quiet);
+}
+
+export function isQuiet() {
+  return state.quiet;
+}
+
+export function isJson() {
+  return state.json;
+}
+
+function colorsEnabled() {
+  return Bun.enableANSIColors;
+}
+
+function paint(open, close, text) {
+  const value = String(text);
+  if (!colorsEnabled()) {
+    return value;
+  }
+  return `\u001b[${open}m${value}\u001b[${close}m`;
+}
+
+/**
+ * ANSI helpers. Every entry is `(text) => string` and degrades to a plain
+ * pass-through when Bun reports ANSI colors unsupported (non-TTY stdout,
+ * NO_COLOR set, or FORCE_COLOR=0).
+ */
+export const color = {
+  red: (text) => paint(31, 39, text),
+  green: (text) => paint(32, 39, text),
+  yellow: (text) => paint(33, 39, text),
+  dim: (text) => paint(2, 22, text),
+  bold: (text) => paint(1, 22, text),
+};
+
+/**
+ * Write a line to stdout unless quiet mode is active.
+ */
+export function log(message) {
+  if (state.quiet) {
+    return;
+  }
+  process.stdout.write(`${message}\n`);
+}
+
+/**
+ * Write a success line (green check prefix) to stdout unless quiet.
+ */
+export function ok(message) {
+  if (state.quiet) {
+    return;
+  }
+  process.stdout.write(`${color.green('\u2713')} ${message}\n`);
+}
+
+/**
+ * Write a warning line to stderr. Never suppressed.
+ */
+export function warn(message) {
+  process.stderr.write(`${message}\n`);
+}
+
+/**
+ * Write an error line to stderr. Never suppressed.
+ */
+export function error(message) {
+  process.stderr.write(`${message}\n`);
+}
+
+/**
+ * Write a pretty-printed JSON document to stdout.
+ */
+export function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+/**
+ * Report a fatal error and terminate with the given exit code.
+ */
+export function fail(message, code = 1) {
+  error(message);
+  process.exit(code);
+}
+
+/**
+ * Render a simple padded plain-text table for human output.
+ *
+ * Widths are measured with `Bun.stringWidth`, not `String.length`: `.length`
+ * counts UTF-16 code units, so a CJK session title or an emoji reported a width
+ * it does not render at and the whole table misaligned (verified: a 5-column
+ * overcount on a Japanese title). `stringWidth` also ignores ANSI escapes, so a
+ * coloured cell does not pad against its own escape bytes.
+ */
+export function formatTable(rows, headers = []) {
+  const body = Array.isArray(rows) ? rows.map((row) => (Array.isArray(row) ? row : [row])) : [];
+  const head = Array.isArray(headers) ? headers : [];
+  const columns = Math.max(head.length, ...body.map((row) => row.length), 0);
+
+  if (columns === 0) {
+    return '';
+  }
+
+  const cellText = (row, i) => (row[i] === undefined || row[i] === null ? '' : String(row[i]));
+  const widths = [];
+  for (let i = 0; i < columns; i += 1) {
+    let width = head[i] === undefined ? 0 : Bun.stringWidth(String(head[i]));
+    for (const row of body) {
+      const cellWidth = Bun.stringWidth(cellText(row, i));
+      if (cellWidth > width) width = cellWidth;
+    }
+    widths[i] = width;
+  }
+
+  const renderRow = (row) =>
+    widths
+      .map((width, i) => {
+        const cell = cellText(row, i);
+        return cell + ' '.repeat(Math.max(0, width - Bun.stringWidth(cell)));
+      })
+      .join('  ')
+      .trimEnd();
+
+  const lines = [];
+  if (head.length > 0) {
+    lines.push(renderRow(head));
+    lines.push(widths.map((width) => '-'.repeat(width)).join('  '));
+  }
+  for (const row of body) {
+    lines.push(renderRow(row));
+  }
+  return lines.join('\n');
+}

package/src/cli/lib/path-utils.js

@@ -0,0 +1,99 @@
+// Minimal path helpers for the CLI — Bun has no path builtin (Bun.path is
+// undefined), and the CLI only needs POSIX-style join/resolve/dirname on
+// absolute native paths.
+//
+// Every helper speaks BOTH separators, because the CLI runs on Windows. A path
+// there arrives as `C:\Users\...\kabmo\src\cli` (import.meta.dir, argv, an
+// env override), and a resolver that recognized only a leading `/` treated it
+// as RELATIVE: it prefixed the cwd and `resolvePath(import.meta.dir, '..', '..')`
+// answered `C:\/C:\/C:\Users\...\src\cli/../..`, so the package root and every
+// path derived from it pointed nowhere — `kabmo serve` reported "This
+// install is incomplete" for a tarball that ships `dist/client`. Verified
+// against the published install.
+
+import { homedir } from 'node:os';
+
+/** `C:\x` / `C:/x` — a Windows drive-rooted path. */
+const WINDOWS_DRIVE = /^[A-Za-z]:[\\/]/;
+/** `\\server\share` — a Windows UNC path (also spelled `//server/share`). */
+const WINDOWS_UNC = /^[\\/]{2}[^\\/]/;
+
+/**
+ * Whether a path is absolute.
+ *
+ * Both platforms' spellings are recognized on either platform: the CLI's paths
+ * come from the OS (a Windows path IS absolute on Windows) and from user input,
+ * and an absolute argument must discard what precedes it exactly as `/tmp/x`
+ * does — otherwise `kabmo plugin new C:\proj` scaffolds into `<cwd>/C:\proj`.
+ */
+export function isAbsolutePath(value) {
+  if (typeof value !== 'string' || value.length === 0) return false;
+  return value.startsWith('/') || WINDOWS_DRIVE.test(value) || WINDOWS_UNC.test(value);
+}
+
+/** Forward-slash spelling: the form every helper here does its string work in. */
+function toPosix(value) {
+  return value.replace(/\\/g, '/');
+}
+
+/** Collapse duplicate separators without mangling a UNC prefix (`//server`). */
+function collapseSlashes(value) {
+  const unc = value.startsWith('//');
+  const collapsed = value.replace(/\/{2,}/g, '/');
+  return unc ? `/${collapsed}` : collapsed;
+}
+
+/** Join path segments with the platform separator without duplicated separators. */
+export function joinPath(...segments) {
+  let joined = '';
+  for (const segment of segments) {
+    if (!segment) continue;
+    const part = toPosix(segment);
+    if (!joined) {
+      joined = part;
+    } else if (joined.endsWith('/') || part.startsWith('/')) {
+      joined = `${joined.replace(/\/+$/, '')}/${part.replace(/^\/+/, '')}`;
+    } else {
+      joined = `${joined}/${part}`;
+    }
+  }
+  return joined;
+}
+
+/**
+ * Resolve a path to an absolute normalized path.
+ *
+ * Node's `path.resolve` semantics on the two points that matter here:
+ *
+ * - An ABSOLUTE segment discards everything before it. `joinPath` deliberately
+ *   strips a leading slash (it is used to build a path FROM a root), so
+ *   `joinPath(cwd, '/tmp/x')` yields `<cwd>/tmp/x` — a silent relocation of an
+ *   absolute argument. Verified on the CLI: `kabmo plugin new /tmp/x`
+ *   scaffolded into `<cwd>/tmp/x`. On Windows the same rule applies to a
+ *   drive-rooted or UNC argument.
+ * - A `.` segment means "here", so it contributes nothing. Without this,
+ *   `resolvePath(cwd, '.')` answered `<cwd>/.` — a path that works but is not
+ *   the string a caller compares against.
+ */
+export function resolvePath(...segments) {
+  let lastAbsolute = -1;
+  for (let i = 0; i < segments.length; i += 1) {
+    if (isAbsolutePath(segments[i])) lastAbsolute = i;
+  }
+  const parts = (lastAbsolute === -1 ? [process.cwd(), ...segments] : segments.slice(lastAbsolute))
+    .filter((segment) => typeof segment === 'string' && segment.length > 0 && segment !== '.')
+    .map(toPosix);
+  const joined = (parts.length > 0 && isAbsolutePath(parts[0]) ? parts : [toPosix(process.cwd()), ...parts]).join('/');
+  return collapseSlashes(joined).replace(/(.+)\/$/, '$1');
+}
+
+/**
+ * Current user home directory. Uses `os.homedir()` rather than `Bun.env.HOME`
+ * because the env var is absent when the CLI runs without a shell (cron,
+ * launchd, GUI launcher) — there it would yield '' and make every derived data
+ * path relative to the cwd, so `stop`/`status` would look in the wrong place.
+ * `os.homedir()` falls back to getpwuid on POSIX and USERPROFILE on Windows.
+ */
+export function homeDir() {
+  return homedir();
+}

package/src/cli/lib/path-utils.test.js

@@ -0,0 +1,184 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The CLI's own path helpers, on both platforms' path spellings.
+ *
+ * These are not cosmetic: `kabmo.js` derives the package root from
+ * `import.meta.dir`, and every entry the CLI runs — the built server, the dev
+ * entry, the build script, the login-entry argv — hangs off that root. A
+ * resolver that recognizes only a leading `/` treats a Windows path as
+ * relative, prefixes the cwd twice and answers a path that exists nowhere:
+ * measured against the published tarball, `kabmo serve` reported "This
+ * install is incomplete" for an install that ships `dist/client`.
+ *
+ * The Windows cases therefore assert on the SHAPE of the answer (an absolute
+ * path, the cwd not re-prefixed, a drive letter appearing once) rather than on
+ * `fs.existsSync` — the suite runs on macOS, so the cwd is stubbed for them.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { homedir } from 'node:os';
+
+import { homeDir, isAbsolutePath, joinPath, resolvePath } from '@/cli/lib/path-utils.js';
+import { isWindows } from '@/test-support/platform';
+
+/**
+ * Run `fn` with `process.cwd()` answering `value`.
+ *
+ * The only way to pin a Windows resolution without a Windows host: the helpers
+ * read the cwd through that one call, and every branch under test is decided by
+ * the SEGMENTS, so a stubbed cwd exercises the real code path.
+ */
+function withCwd(value, fn) {
+  const original = process.cwd;
+  Object.defineProperty(process, 'cwd', { value: () => value, configurable: true });
+  try {
+    return fn();
+  } finally {
+    Object.defineProperty(process, 'cwd', { value: original, configurable: true });
+  }
+}
+
+describe('homeDir', () => {
+  // The CLI must resolve the same data directory as the server (which uses
+  // os.homedir()). Reading Bun.env.HOME yields '' without a shell (cron,
+  // launchd, GUI launcher), which silently made every derived path relative to
+  // the cwd — `stop`/`status` then missed the running instance.
+  test('is absolute even when HOME is absent from the environment', () => {
+    const saved = Bun.env.HOME;
+    try {
+      delete Bun.env.HOME;
+      expect(homeDir()).toBe(homedir());
+      // The invariant is ABSOLUTENESS, not a leading `/`: a Windows home is
+      // `C:\Users\x`, which is absolute and not `/`-rooted. Asserting the
+      // portable predicate keeps the case meaningful on both platforms.
+      expect(isAbsolutePath(homeDir())).toBe(true);
+    } finally {
+      if (saved !== undefined) Bun.env.HOME = saved;
+    }
+  });
+
+  test('agrees with os.homedir()', () => {
+    expect(homeDir()).toBe(homedir());
+  });
+});
+
+describe('isAbsolutePath', () => {
+  test('recognizes both platforms’ spellings', () => {
+    expect(isAbsolutePath('/tmp/x')).toBe(true);
+    expect(isAbsolutePath('C:\\Users\\x')).toBe(true);
+    expect(isAbsolutePath('C:/Users/x')).toBe(true);
+    expect(isAbsolutePath('\\\\server\\share')).toBe(true);
+    expect(isAbsolutePath('//server/share')).toBe(true);
+  });
+
+  test('rejects relative spellings, including a bare drive', () => {
+    expect(isAbsolutePath('rel/dir')).toBe(false);
+    expect(isAbsolutePath('..')).toBe(false);
+    expect(isAbsolutePath('')).toBe(false);
+    expect(isAbsolutePath(undefined)).toBe(false);
+    // `C:` with no separator is drive-RELATIVE on Windows, not absolute.
+    expect(isAbsolutePath('C:')).toBe(false);
+  });
+});
+
+describe('joinPath', () => {
+  test('keeps a single separator between segments', () => {
+    expect(joinPath('/a', 'b', 'c')).toBe('/a/b/c');
+    expect(joinPath('/a/', '/b')).toBe('/a/b');
+    expect(joinPath('/a//', '//b')).toBe('/a/b');
+  });
+
+  test('skips empty segments', () => {
+    expect(joinPath('/a', '', 'b')).toBe('/a/b');
+  });
+
+  test('normalizes Windows separators so a joined path is comparable', () => {
+    expect(joinPath('C:\\a', 'b', 'c')).toBe('C:/a/b/c');
+    expect(joinPath('C:\\Users\\x\\kabmo', 'dist', 'client', 'index.js'))
+      .toBe('C:/Users/x/kabmo/dist/client/index.js');
+  });
+});
+
+describe('resolvePath', () => {
+  test('returns an absolute path for an absolute input', () => {
+    expect(resolvePath('/tmp/x')).toBe('/tmp/x');
+    expect(resolvePath('/tmp/x/')).toBe('/tmp/x');
+  });
+
+  test('resolves relative input against the cwd', () => {
+    expect(resolvePath('rel/dir')).toBe(joinPath(process.cwd(), 'rel/dir'));
+  });
+
+  test('a `.` segment contributes nothing', () => {
+    // `resolvePath` normalises separators to `/` (that is what makes a joined
+    // path comparable across platforms), so the expectation normalises the cwd
+    // the same way — on Windows `process.cwd()` is `D:\\a\\b` and the answer is
+    // `D:/a/b`, which is the same path, not a different one.
+    expect(resolvePath(process.cwd(), '.')).toBe(process.cwd().replace(/\\/g, '/'));
+  });
+
+  test('an absolute segment discards everything before it', () => {
+    expect(resolvePath('/cwd/here', '/tmp/x')).toBe('/tmp/x');
+    expect(resolvePath('/cwd/here', 'rel')).toBe('/cwd/here/rel');
+  });
+
+  test('the data dir derived from homeDir is always absolute', () => {
+    const saved = Bun.env.HOME;
+    try {
+      delete Bun.env.HOME;
+      if (!isWindows) expect(joinPath(homeDir(), '.kabmo').startsWith('/')).toBe(true);
+      // The claim in the name is absoluteness, and that holds on both
+      // platforms — `C:/Users/x/.kabmo` is as absolute as `/Users/x/…`.
+      expect(isAbsolutePath(joinPath(homeDir(), '.kabmo'))).toBe(true);
+    } finally {
+      if (saved !== undefined) Bun.env.HOME = saved;
+    }
+  });
+
+  // The issue #5 regression. `kabmo.js` calls exactly this shape with
+  // `import.meta.dir`, which on Windows is a drive-rooted backslash path.
+  describe('on Windows', () => {
+    const WIN_DIR = 'C:\\Users\\Administrator\\.bun\\install\\global\\node_modules\\kabmo\\src\\cli';
+
+    test('the package root keeps one drive letter and is not cwd-prefixed', () => {
+      const pkgRoot = withCwd('C:\\', () => resolvePath(WIN_DIR, '..', '..'));
+      // The bug answered `C:\/C:\/C:\Users\...\src\cli/../..`.
+      expect(pkgRoot.startsWith('C:/')).toBe(true);
+      expect(pkgRoot.indexOf('C:', 1)).toBe(-1);
+      expect(pkgRoot).not.toContain('C:\\');
+      expect(pkgRoot).toBe('C:/Users/Administrator/.bun/install/global/node_modules/kabmo/src/cli/../..');
+    });
+
+    test('every path derived from the package root stays inside it', () => {
+      const pkgRoot = withCwd('C:\\', () => resolvePath(WIN_DIR, '..', '..'));
+      expect(joinPath(pkgRoot, 'dist', 'client', 'index.js'))
+        .toBe('C:/Users/Administrator/.bun/install/global/node_modules/kabmo/src/cli/../../dist/client/index.js');
+      expect(joinPath(pkgRoot, 'scripts', 'build-client.ts')).toContain('/kabmo/src/cli/../../scripts/');
+    });
+
+    test('a drive-rooted segment is absolute, so it discards the cwd', () => {
+      expect(withCwd('C:\\proj', () => resolvePath('C:\\other'))).toBe('C:/other');
+      expect(withCwd('C:\\proj', () => resolvePath('C:\\proj', 'sub'))).toBe('C:/proj/sub');
+    });
+
+    test('a relative segment still resolves against a Windows cwd', () => {
+      expect(withCwd('C:\\proj', () => resolvePath('sub'))).toBe('C:/proj/sub');
+      expect(withCwd('C:\\proj', () => resolvePath('.'))).toBe('C:/proj');
+    });
+
+    test('a UNC path keeps its double-slash prefix', () => {
+      expect(withCwd('C:\\', () => resolvePath('\\\\server\\share', 'dir'))).toBe('//server/share/dir');
+      expect(withCwd('C:\\', () => resolvePath('//server/share/'))).toBe('//server/share');
+    });
+
+    test('an absolute POSIX path is still absolute there', () => {
+      // A git-bash style argument on Windows: absolute, so it must not be
+      // relocated under the cwd.
+      expect(withCwd('C:\\proj', () => resolvePath('/tmp/x'))).toBe('/tmp/x');
+    });
+  });
+});

package/src/cli/lib/paths.js

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import { getDataDir, getRunDir } from '@/server/lib/lifecycle/paths';
+import { joinPath } from '@/cli/lib/path-utils.js';
+
+/**
+ * CLI-side paths.
+ *
+ * The data directory and the per-port run directory are owned by
+ * `src/server/lib/lifecycle/paths` — the server writes its instance record
+ * there, and the CLI must read the same file. Only the log location is
+ * CLI-specific: the CLI redirects the daemon's stdout into it, so the server
+ * never needs to know where the logs live.
+ */
+
+/**
+ * Directory holding per-instance log files.
+ */
+export function getLogsDir() {
+  const dir = joinPath(getDataDir(), 'logs');
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * Log file for the running instance bound to `port`.
+ */
+export function getLogFilePath(port) {
+  return joinPath(getLogsDir(), `kabmo-${port}.log`);
+}
+
+/**
+ * Ensure the full data directory tree exists and return every path.
+ */
+export function ensureDataDirs() {
+  return {
+    dataDir: getDataDir(),
+    runDir: getRunDir(),
+    logsDir: getLogsDir(),
+  };
+}