From c4743573194ef615ceb05fc99639ea84f123efd2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ciar=C3=A1n=20Curley?= <ciaran.curley.11.11@gmail.com>
Date: Wed, 18 Feb 2026 13:46:34 +0000
Subject: [PATCH] stage 4 code review

---
 .gitignore                               |  1 +
 src/commands/shared.ts                   | 10 ++++-
 tests/cli.vault-root.integration.test.ts | 47 ++++++++++++++++++++++++
 3 files changed, 57 insertions(+), 1 deletion(-)
 create mode 100644 tests/cli.vault-root.integration.test.ts

diff --git a/.gitignore b/.gitignore
index 48daeef..cbb0aaf 100644
--- a/.gitignore
+++ b/.gitignore
@@ -34,3 +34,4 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 
 # Finder (MacOS) folder config
 .DS_Store
+.bun/install/cache
diff --git a/src/commands/shared.ts b/src/commands/shared.ts
index 0516cc4..4636e1d 100644
--- a/src/commands/shared.ts
+++ b/src/commands/shared.ts
@@ -81,7 +81,15 @@ export function getVaultRoot(options: Map<string, string | true>): string {
     return fromFlag;
   }
 
-  return `${process.env.HOME ?? ""}/obsidian/crabpot`;
+  const home = process.env.HOME;
+  if (!home) {
+    throw new CliError(
+      "VALIDATION_ERROR",
+      "Missing HOME; pass --vault-root <path> explicitly",
+    );
+  }
+
+  return `${home}/obsidian/crabpot`;
 }
 
 export async function parseJsonInput(value: string): Promise<Record<string, unknown>> {
diff --git a/tests/cli.vault-root.integration.test.ts b/tests/cli.vault-root.integration.test.ts
new file mode 100644
index 0000000..a5a72f3
--- /dev/null
+++ b/tests/cli.vault-root.integration.test.ts
@@ -0,0 +1,47 @@
+import { expect, test } from "bun:test";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const TEST_FILE_DIR = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(TEST_FILE_DIR, "..");
+const CLI_PATH = join(REPO_ROOT, "src", "cli.ts");
+
+type CliResult = {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+};
+
+function runCliWithoutHome(args: string[]): CliResult {
+  const proc = Bun.spawnSync({
+    cmd: ["bun", "run", CLI_PATH, ...args],
+    cwd: REPO_ROOT,
+    env: {
+      ...process.env,
+      HOME: "",
+    },
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  return {
+    exitCode: proc.exitCode,
+    stdout: new TextDecoder().decode(proc.stdout).trim(),
+    stderr: new TextDecoder().decode(proc.stderr).trim(),
+  };
+}
+
+function parseJsonOutput(stdout: string): any {
+  return JSON.parse(stdout);
+}
+
+test("missing HOME without --vault-root returns clear validation error", () => {
+  const result = runCliWithoutHome(["exists", "--job-spec-url", "https://example.com/jobs/123"]);
+
+  expect(result.exitCode).toBe(2);
+  const payload = parseJsonOutput(result.stdout);
+  expect(payload.ok).toBe(false);
+  expect(payload.error.code).toBe("VALIDATION_ERROR");
+  expect(payload.error.message.includes("--vault-root")).toBe(true);
+  expect(payload.error.message.includes("HOME")).toBe(true);
+});
-- 
knotmirror 0.0.1