fix(miner): harden laptop-mode doctor checks (#2329)

Author: 9876543210-tc-0123456789

packages/gittensory-miner/README.md

@@ -48,7 +48,8 @@ gittensory-miner doctor
 
 `init` bootstraps the local config directory and the SQLite-backed `run-state.sqlite3` file. Path
 resolution mirrors the package's other local stores: `GITTENSORY_MINER_CONFIG_DIR`, then
-`XDG_CONFIG_HOME`, then `~/.config/gittensory-miner/`.
+`XDG_CONFIG_HOME`, then `~/.config/gittensory-miner/`. If you need the SQLite file elsewhere, set
+`GITTENSORY_MINER_RUN_STATE_DB`; that overrides the DB path only, not the config-dir chain.
 
 ## Commands
 
@@ -61,8 +62,8 @@ gittensory-miner init
 gittensory-miner doctor
 ```
 
-`doctor` always reports Docker as informational only. Laptop mode never requires Docker, Redis, or
-Postgres to initialize.
+`doctor` always reports Docker as informational only and times out quickly if `docker --version`
+hangs. Laptop mode never requires Docker, Redis, or Postgres to initialize.
 
 ## Version check
 

packages/gittensory-miner/lib/laptop-mode.js

@@ -1,9 +1,12 @@
 import { spawnSync } from "node:child_process";
 import { accessSync, constants, existsSync } from "node:fs";
-import { dirname } from "node:path";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import { initRunStateStore, resolveRunStateDbPath } from "./run-state.js";
 
+const dockerProbeTimeoutMs = 1500;
+
 function errorDetail(error) {
   return error instanceof Error && error.message ? error.message : "unknown_error";
 }
@@ -13,7 +16,15 @@ export function resolveLaptopModeStateDbPath(env = process.env) {
 }
 
 export function resolveLaptopModeConfigDir(env = process.env) {
-  return dirname(resolveLaptopModeStateDbPath(env));
+  const explicitConfigDir = typeof env.GITTENSORY_MINER_CONFIG_DIR === "string"
+    ? env.GITTENSORY_MINER_CONFIG_DIR.trim()
+    : "";
+  if (explicitConfigDir) return explicitConfigDir;
+
+  const configHome = typeof env.XDG_CONFIG_HOME === "string" && env.XDG_CONFIG_HOME.trim()
+    ? env.XDG_CONFIG_HOME.trim()
+    : join(homedir(), ".config");
+  return join(configHome, "gittensory-miner");
 }
 
 /**
@@ -41,10 +52,29 @@ export function initLaptopMode(input = {}) {
   }
 }
 
+function nearestExistingAncestor(path) {
+  let candidate = dirname(path);
+  while (!existsSync(candidate)) {
+    const parent = dirname(candidate);
+    if (parent === candidate) return null;
+    candidate = parent;
+  }
+  return candidate;
+}
+
 function inspectWritablePath(path) {
   const exists = existsSync(path);
   if (!exists) {
-    return { path, exists: false, writable: false, error: null };
+    const ancestor = nearestExistingAncestor(path);
+    if (!ancestor) {
+      return { path, exists: false, writable: false, error: "missing_parent_directory" };
+    }
+    try {
+      accessSync(ancestor, constants.W_OK | constants.X_OK);
+      return { path, exists: false, writable: true, error: null };
+    } catch (error) {
+      return { path, exists: false, writable: false, error: errorDetail(error) };
+    }
   }
   try {
     accessSync(path, constants.W_OK);
@@ -96,12 +126,19 @@ function probeDocker(spawn = spawnSync) {
     result = spawn("docker", ["--version"], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
+      timeout: dockerProbeTimeoutMs,
     });
   } catch (error) {
     return { available: false, detail: errorDetail(error) };
   }
 
   if (result.error) {
+    if (result.error.code === "ETIMEDOUT") {
+      return {
+        available: false,
+        detail: `docker --version timed out after ${dockerProbeTimeoutMs}ms`,
+      };
+    }
     return {
       available: false,
       detail: result.error.code === "ENOENT" ? "docker not found on PATH" : errorDetail(result.error),

test/unit/miner-laptop-mode.test.ts

@@ -38,6 +38,21 @@ describe("gittensory-miner laptop mode bootstrap (#2329)", () => {
     expect(resolveLaptopModeStateDbPath({})).toMatch(/\/\.config\/gittensory-miner\/run-state\.sqlite3$/);
   });
 
+  it("keeps the laptop-mode config dir on the config chain even when the run-state DB path is overridden", () => {
+    const env = {
+      GITTENSORY_MINER_RUN_STATE_DB: "/custom/state.sqlite3",
+      GITTENSORY_MINER_CONFIG_DIR: "/custom/config",
+      XDG_CONFIG_HOME: "/xdg",
+    };
+
+    expect(resolveLaptopModeConfigDir(env)).toBe("/custom/config");
+    expect(resolveLaptopModeStateDbPath(env)).toBe("/custom/state.sqlite3");
+    expect(resolveLaptopModeConfigDir({
+      GITTENSORY_MINER_RUN_STATE_DB: "/custom/state.sqlite3",
+      XDG_CONFIG_HOME: "/xdg",
+    })).toBe("/xdg/gittensory-miner");
+  });
+
   it("initializes the config dir and SQLite run-state store on a fresh laptop-mode boot", () => {
     const configDir = join(tempRoot(), "config");
     const result = initLaptopMode({ env: { GITTENSORY_MINER_CONFIG_DIR: configDir } });
@@ -111,9 +126,8 @@ describe("gittensory-miner laptop mode bootstrap (#2329)", () => {
     expect(formatLaptopDoctor(report)).toContain("miner_run_state ready");
   });
 
-  it("doctor handles missing Docker and a missing state DB gracefully", () => {
+  it("doctor treats a fresh, creatable config dir as writable and handles missing Docker gracefully", () => {
     const configDir = join(tempRoot(), "config");
-    mkdirSync(configDir, { recursive: true });
 
     const report = inspectLaptopMode({
       env: { GITTENSORY_MINER_CONFIG_DIR: configDir },
@@ -125,10 +139,16 @@ describe("gittensory-miner laptop mode bootstrap (#2329)", () => {
       })) as never,
     });
 
+    expect(report.configDir).toMatchObject({
+      path: configDir,
+      exists: false,
+      writable: true,
+      error: null,
+    });
     expect(report.stateDb).toMatchObject({
       path: join(configDir, "run-state.sqlite3"),
       exists: false,
-      writable: false,
+      writable: true,
       sqliteReady: false,
       schemaReady: false,
       schemaError: null,
@@ -137,6 +157,25 @@ describe("gittensory-miner laptop mode bootstrap (#2329)", () => {
     expect(formatLaptopDoctor(report)).toContain("Docker: unavailable (docker not found on PATH; informational only)");
   });
 
+  it("doctor treats a timed-out Docker probe as informational only", () => {
+    const configDir = join(tempRoot(), "config");
+    initLaptopMode({ env: { GITTENSORY_MINER_CONFIG_DIR: configDir } });
+
+    const report = inspectLaptopMode({
+      env: { GITTENSORY_MINER_CONFIG_DIR: configDir },
+      spawnSyncFn: vi.fn(() => ({
+        status: null,
+        stdout: "",
+        stderr: "",
+        error: Object.assign(new Error("spawn docker ETIMEDOUT"), { code: "ETIMEDOUT" }),
+      })) as never,
+    });
+
+    expect(report.docker.available).toBe(false);
+    expect(report.docker.detail).toContain("timed out");
+    expect(formatLaptopDoctor(report)).toContain("informational only");
+  });
+
   it("doctor surfaces an invalid existing SQLite file with the schema error detail in the human output", () => {
     const configDir = join(tempRoot(), "config");
     mkdirSync(configDir, { recursive: true });