@jamaynor/hal-config 1.0.1

package/CLAUDE.md

@@ -0,0 +1,84 @@
+# CLAUDE.md — @jamaynor/hal-config
+
+## Overview
+
+Shared configuration loader for HAL OpenClaw skills. Reads `hal-system-config.json` once, caches for the process lifetime, and provides accessors for shared data and skill discovery.
+
+Zero runtime dependencies. ESM (ES modules). Node >= 22.
+
+## API
+
+```js
+import halConfig from '@jamaynor/hal-config';
+
+// Loading
+halConfig.load(configDir?)         // Read hal-system-config.json (defaults to HAL_SYSTEM_CONFIG env)
+halConfig.reload()                 // Bust cache and re-read
+halConfig.raw()                    // Full config object
+halConfig.configDir()              // Resolved config directory path
+
+// Shared data
+halConfig.vaults()                 // hal-obsidian-vaults array (raw)
+halConfig.accounts(provider?)      // hal-communication-accounts, optionally filtered
+halConfig.timezone()               // string or null
+halConfig.workHours()              // { start, end } or null
+
+// Skill discovery
+halConfig.skill(name)              // Full skill config block or null
+halConfig.isEnabled(name)          // boolean — exists and enabled !== false
+halConfig.isInstalled(name)        // boolean — enabled + binary on PATH (sync)
+halConfig.isInstalledAsync(name)   // Promise<boolean> — async version
+halConfig.skillWorkspace(name)     // runtime.workspace or null
+halConfig.skillBinaries(name)      // string[] of binary names from install metadata
+halConfig.homeAgent(name)          // homeAgent string or null (null = primary agent)
+
+// Deterministic locations (no searching)
+halConfig.openclawSharedWorkspaceRoot()     // /data/openclaw/workspace
+halConfig.openclawConfigFilePath()          // /data/openclaw/openclaw.json
+halConfig.halSystemConfigDir()              // /data/openclaw/hal (or HAL_SYSTEM_CONFIG)
+halConfig.halSystemConfigFilePath()         // {halSystemConfigDir}/hal-system-config.json
+halConfig.halSkillAdminRoot(skillName)      // /data/openclaw/hal/{skillName} (or HAL_SKILL_ADMIN_ROOT)
+halConfig.halSkillConfigDir(skillName)      // /data/openclaw/hal/{skillName}/config
+halConfig.skillConfigPath(skillName)        // /data/openclaw/hal/{skillName}/config/{skillName}.json
+halConfig.skillConfigDir(skillName)         // /data/openclaw/hal/{skillName}/config
+halConfig.halSkillLogDir(skillName)         // /data/openclaw/hal/{skillName}/log
+
+// Per-skill config files (read/write)
+halConfig.halSkillConfig.read(skillNameOrScope)                  // {} if missing; throws on invalid JSON
+halConfig.halSkillConfig.getSetting(skillNameOrScope, key)       // returns value or undefined
+halConfig.halSkillConfig.write(skillNameOrScope, obj)            // overwrites entire {skill}.json (atomic)
+halConfig.halSkillConfig.merge(skillNameOrScope, patchObj)       // deep merge (objects merge, arrays replace) + write (atomic)
+halConfig.halSkillConfig.setSetting(skillNameOrScope, key, value) // merge single key + write (atomic)
+
+// Registration (for init wizards to write back)
+halConfig.register(name, data)     // Merge into skills[name].runtime
+halConfig.writeAccounts(accounts)  // Merge-by-label upsert into hal-communication-accounts
+halConfig.writeSkillConfig(name, data)     // Merge into skills[name]
+halConfig.writeSharedSettings(settings)    // Write top-level keys (hal-timezone, etc.)
+```
+
+## Config Location
+
+Resolved in order: `configDir` argument > `HAL_SYSTEM_CONFIG` env > `/data/openclaw/hal`
+
+File: `hal-system-config.json` (v2.0)
+
+## Error Handling
+
+- Missing file → returns `{}` (graceful). Skills that require the file (email-triage) enforce this at their wrapper level.
+- Corrupt JSON → throws `SyntaxError`
+- Auto-loads on first accessor call if `load()` not called explicitly
+
+## Testing
+
+```bash
+npm test
+```
+
+147 tests using `node:test`. Tests use temp directories with synthetic configs — no real system-config needed.
+
+## How Skills Use It
+
+Each skill adds `"hal-config": "file:../hal-config"` to its `package.json` dependencies. When `npm install -g` runs inside the container, npm resolves the `file:` path relative to the skill's source directory (`/repos/jamaynor/<skill>/`).
+
+Skills keep thin wrappers in `lib/config/system-config.js` that delegate to this package while preserving their existing function signatures.

package/index.js

@@ -0,0 +1,3 @@
+import * as config from './lib/config.js';
+export default config;
+export * from './lib/config.js';