feat: add home-scoped config loading

Author: DonPrus

README.md

@@ -66,3 +66,13 @@ This keeps the architecture modular, simpler to reason about, and easier to evol
 - `nulltickets + nullboiler + nullclaw`: full multi-agent orchestration with durable task source.
 
 See additional integration docs in [`docs/`](./docs).
+
+## Config Location
+
+- Default config path: `~/.nullboiler/config.json`
+- Override instance home with `NULLBOILER_HOME=/path/to/dir`
+- Override config file directly with `--config /path/to/config.json`
+
+When `NULLBOILER_HOME` is set, `nullboiler` reads `config.json` from that directory and
+resolves relative paths like `db`, `strategies_dir`, `tracker.workflows_dir`, and
+`tracker.workspace.root` relative to that config file.

src/config.zig

@@ -1,4 +1,8 @@
 const std = @import("std");
+const builtin = @import("builtin");
+
+pub const home_env_var = "NULLBOILER_HOME";
+pub const home_dir_name = ".nullboiler";
 
 pub const WorkerConfig = struct {
     id: []const u8,
@@ -78,6 +82,27 @@ pub const Config = struct {
     tracker: ?TrackerConfig = null,
 };
 
+pub fn resolveConfigPath(allocator: std.mem.Allocator, override_path: ?[]const u8) ![]const u8 {
+    if (override_path) |path| return allocator.dupe(u8, path);
+
+    const home_dir = try resolveHomeDir(allocator);
+    defer allocator.free(home_dir);
+    return std.fs.path.join(allocator, &.{ home_dir, "config.json" });
+}
+
+pub fn resolveHomeDir(allocator: std.mem.Allocator) ![]const u8 {
+    if (std.process.getEnvVarOwned(allocator, home_env_var)) |env_home| {
+        return env_home;
+    } else |err| switch (err) {
+        error.EnvironmentVariableNotFound => {},
+        else => return err,
+    }
+
+    const home = try getHomeDirOwned(allocator);
+    defer allocator.free(home);
+    return std.fs.path.join(allocator, &.{ home, home_dir_name });
+}
+
 /// Load configuration from a JSON file. If the file does not exist,
 /// return a default Config.
 pub fn loadFromFile(allocator: std.mem.Allocator, path: []const u8) !Config {
@@ -116,6 +141,18 @@ fn resolveRelativePath(allocator: std.mem.Allocator, config_path: []const u8, va
     return std.fs.path.resolve(allocator, &.{ base_dir, value });
 }
 
+fn getHomeDirOwned(allocator: std.mem.Allocator) ![]u8 {
+    return std.process.getEnvVarOwned(allocator, "HOME") catch |err| switch (err) {
+        error.EnvironmentVariableNotFound => {
+            if (builtin.os.tag == .windows) {
+                return std.process.getEnvVarOwned(allocator, "USERPROFILE") catch error.HomeNotSet;
+            }
+            return error.HomeNotSet;
+        },
+        else => return err,
+    };
+}
+
 // ── Tests ──────────────────────────────────────────────────────────────
 
 test "default config" {
@@ -215,7 +252,7 @@ test "SubprocessDefaults has base_port and health_check_retries" {
     try std.testing.expectEqualStrings("Continue working on this task. Your previous context is preserved.", sd.continuation_prompt);
 }
 
-test "resolveRelativePaths anchors tracker compat and advanced paths to config directory" {
+test "resolveRelativePaths anchors tracker paths to config directory" {
     var tmp = std.testing.tmpDir(.{});
     defer tmp.cleanup();
 

src/from_json.zig

@@ -1,5 +1,6 @@
 const std = @import("std");
 const builtin = @import("builtin");
+const config_mod = @import("config.zig");
 
 pub fn run(allocator: std.mem.Allocator, args: []const []const u8) !void {
     if (args.len == 0) {
@@ -25,7 +26,11 @@ pub fn run(allocator: std.mem.Allocator, args: []const []const u8) !void {
     const port = getU16(obj, "port") orelse 8080;
     const api_token = getString(obj, "api_token");
     const db_path = getString(obj, "db_path") orelse "nullboiler.db";
-    const home = getString(obj, "home") orelse ".";
+    const home = resolveHome(allocator, getString(obj, "home")) catch |err| {
+        std.debug.print("error: failed to resolve home: {s}\n", .{@errorName(err)});
+        std.process.exit(1);
+    };
+    defer allocator.free(home);
     const tracker_enabled = getBoolish(obj, "tracker_enabled");
     const tracker_url = getString(obj, "tracker_url");
     const tracker_api_token = getString(obj, "tracker_api_token");
@@ -230,6 +235,11 @@ fn sanitizeFileComponent(allocator: std.mem.Allocator, value: []const u8) ![]con
     return out;
 }
 
+fn resolveHome(allocator: std.mem.Allocator, json_home: ?[]const u8) ![]const u8 {
+    if (json_home) |home| return allocator.dupe(u8, home);
+    return config_mod.resolveHomeDir(allocator);
+}
+
 test "run writes tracker config and workflow with advanced settings" {
     var tmp = std.testing.tmpDir(.{});
     defer tmp.cleanup();

src/main.zig

@@ -59,7 +59,7 @@ pub fn main() !void {
     var port_override: ?u16 = null;
     var db_override: ?[:0]const u8 = null;
     var token_override: ?[]const u8 = null;
-    var config_path: []const u8 = "config.json";
+    var config_path_override: ?[]const u8 = null;
 
     var i: usize = 0;
     while (i < all_args.len) : (i += 1) {
@@ -90,7 +90,7 @@ pub fn main() !void {
         } else if (std.mem.eql(u8, arg, "--config")) {
             i += 1;
             if (i < all_args.len) {
-                config_path = all_args[i];
+                config_path_override = all_args[i];
             }
         } else if (std.mem.eql(u8, arg, "--version")) {
             std.debug.print("nullboiler v{s}\n", .{version});
@@ -101,6 +101,10 @@ pub fn main() !void {
     // Load configuration
     var cfg_arena = std.heap.ArenaAllocator.init(allocator);
     defer cfg_arena.deinit();
+    const config_path = config.resolveConfigPath(cfg_arena.allocator(), config_path_override) catch |err| {
+        std.debug.print("failed to resolve config path: {}\n", .{err});
+        return;
+    };
     var cfg = config.loadFromFile(cfg_arena.allocator(), config_path) catch |err| {
         std.debug.print("failed to load config from {s}: {}\n", .{ config_path, err });
         return;
@@ -134,6 +138,11 @@ pub fn main() !void {
         std.debug.print("API auth: disabled\n", .{});
     }
 
+    ensureParentDirForFile(db_path) catch |err| {
+        std.debug.print("failed to create database directory for {s}: {}\n", .{ db_path, err });
+        return;
+    };
+
     var store = try Store.init(allocator, db_path);
     defer store.deinit();
     var metrics = metrics_mod.Metrics{};
@@ -396,6 +405,26 @@ pub fn main() !void {
     }
 }
 
+fn ensureParentDirForFile(path: []const u8) !void {
+    if (path.len == 0 or std.mem.eql(u8, path, ":memory:") or std.mem.startsWith(u8, path, "file:")) return;
+
+    const parent = std.fs.path.dirname(path) orelse return;
+    if (parent.len == 0) return;
+
+    if (std.fs.path.isAbsolute(parent)) {
+        std.fs.makeDirAbsolute(parent) catch |err| switch (err) {
+            error.PathAlreadyExists => {},
+            else => return err,
+        };
+        return;
+    }
+
+    std.fs.cwd().makePath(parent) catch |err| switch (err) {
+        error.PathAlreadyExists => {},
+        else => return err,
+    };
+}
+
 fn serializeTagsJson(allocator: std.mem.Allocator, tags: []const []const u8) ![]const u8 {
     return std.json.Stringify.valueAlloc(allocator, tags, .{});
 }