@jamaynor/hal-config 1.0.1

package/lib/config.js

@@ -0,0 +1,675 @@
+// =============================================================================
+// hal-shared-config — Shared configuration loader for HAL OpenClaw skills
+//
+// Reads system-config.json once, caches for the process lifetime, and exposes
+// accessors for shared data (vaults, accounts, timezone, etc.) and skill
+// discovery (enabled, installed, workspace, binaries).
+//
+// Skills use this instead of each maintaining their own system-config reader.
+// =============================================================================
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync, execFile } from 'node:child_process';
+
+// ---------------------------------------------------------------------------
+// Module-level cache — one system-config.json per process
+// ---------------------------------------------------------------------------
+let _cache = null;
+let _configDir = null;
+
+// ---------------------------------------------------------------------------
+// Loading
+// ---------------------------------------------------------------------------
+
+/**
+ * Read and cache hal-system-config.json. Call explicitly to set a custom configDir,
+ * or let it auto-load on first accessor call.
+ *
+ * @param {string} [configDir] — directory containing hal-system-config.json.
+ *   Defaults to HAL_SYSTEM_CONFIG env var, then /data/openclaw/hal.
+ * @returns {object} The parsed config object.
+ */
+export function load(configDir) {
+  _configDir = configDir || process.env.HAL_SYSTEM_CONFIG || '/data/openclaw/hal';
+  const filePath = path.join(_configDir, 'hal-system-config.json');
+  try {
+    _cache = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      _cache = {};
+    } else {
+      throw err;
+    }
+  }
+  return _cache;
+}
+
+/**
+ * Bust the cache and re-read from disk.
+ */
+export function reload() {
+  _cache = null;
+  return load(_configDir);
+}
+
+/** Ensure config is loaded (auto-load on first access). */
+function _ensure() {
+  if (!_cache) load();
+}
+
+/**
+ * Return the full parsed config object.
+ */
+export function raw() {
+  _ensure();
+  return _cache;
+}
+
+/**
+ * Return the resolved config directory path.
+ */
+export function configDir() {
+  _ensure();
+  return _configDir;
+}
+
+// ---------------------------------------------------------------------------
+// Deterministic filesystem locations (OpenClaw + HAL)
+// ---------------------------------------------------------------------------
+
+export function openclawSharedWorkspaceRoot() {
+  return '/data/openclaw/workspace';
+}
+
+export function openclawConfigFilePath() {
+  return '/data/openclaw/openclaw.json';
+}
+
+export function halSystemConfigDir() {
+  // Matches load() defaulting behavior (dir containing hal-system-config.json)
+  return process.env.HAL_SYSTEM_CONFIG || '/data/openclaw/hal';
+}
+
+export function halSystemConfigFilePath() {
+  return path.join(halSystemConfigDir(), 'hal-system-config.json');
+}
+
+export function halSkillAdminRoot(skillName) {
+  const root = process.env.HAL_SKILL_ADMIN_ROOT?.trim() || '/data/openclaw/hal';
+  return path.join(root, String(skillName || '').trim());
+}
+
+export function halSkillConfigDir(skillName) {
+  return path.join(halSkillAdminRoot(skillName), 'config');
+}
+
+export function halSkillLogDir(skillName) {
+  return path.join(halSkillAdminRoot(skillName), 'log');
+}
+
+// ---------------------------------------------------------------------------
+// halSkillConfig (independent per-skill config files under HAL skill admin root)
+// ---------------------------------------------------------------------------
+
+function _deepMergeSkillConfig(target, source) {
+  for (const key of Object.keys(source || {})) {
+    const srcVal = source[key];
+    const tgtVal = target[key];
+    const srcIsPlain = typeof srcVal === 'object' && srcVal !== null && !Array.isArray(srcVal);
+    const tgtIsPlain = typeof tgtVal === 'object' && tgtVal !== null && !Array.isArray(tgtVal);
+    if (srcIsPlain && tgtIsPlain) {
+      _deepMergeSkillConfig(tgtVal, srcVal);
+    } else {
+      target[key] = srcVal;
+    }
+  }
+  return target;
+}
+
+function _readJsonOrEmpty(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return {};
+    throw err;
+  }
+}
+
+function _writeJsonAtomic(filePath, payload) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  fs.writeFileSync(tempPath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+  fs.renameSync(tempPath, filePath);
+}
+
+export const halSkillConfig = {
+  normalizeSkillName: _normalizeSkillName,
+  adminRoot: halSkillAdminRoot,
+  configDir: halSkillConfigDir,
+  logDir: halSkillLogDir,
+  configPath: skillConfigPath,
+
+  read(skillScope) {
+    const name = _normalizeSkillName(skillScope);
+    const fp = skillConfigPath(name);
+    return _readJsonOrEmpty(fp);
+  },
+
+  getSetting(skillScope, key) {
+    const name = _normalizeSkillName(skillScope);
+    const cfg = this.read(name);
+    const k = String(key);
+    return Object.prototype.hasOwnProperty.call(cfg, k) ? cfg[k] : undefined;
+  },
+
+  write(skillScope, data) {
+    const name = _normalizeSkillName(skillScope);
+    const fp = skillConfigPath(name);
+    _writeJsonAtomic(fp, data || {});
+  },
+
+  merge(skillScope, patch) {
+    const name = _normalizeSkillName(skillScope);
+    const fp = skillConfigPath(name);
+    const existing = _readJsonOrEmpty(fp);
+    const merged = _deepMergeSkillConfig(existing, patch || {});
+    _writeJsonAtomic(fp, merged);
+    return merged;
+  },
+
+  setSetting(skillScope, key, value) {
+    return this.merge(skillScope, { [String(key)]: value });
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Shared data accessors
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the hal-obsidian-vaults array (raw — consumers transform as needed).
+ * @returns {Array<{name: string, path: string, label: string, [key: string]: any}>}
+ */
+export function vaults() {
+  _ensure();
+  return _cache['hal-obsidian-vaults'] || [];
+}
+
+function _vaultByName(name) {
+  const n = String(name || '').trim();
+  if (!n) return null;
+  const v = vaults().find(x => x && x.name === n);
+  return v || null;
+}
+
+const DEFAULT_VAULT_FOLDERS = {
+  projectsFolder:   '1-Projects',
+  dailyNotesFolder: 'areas/daily-notes',
+  emailFolder:      'areas/email',
+  meetingsFolder:   'areas/meetings',
+  peopleFolder:     'areas/people',
+};
+
+/**
+ * Return configured vault folder names (subpaths) for a given vault.
+ * These come from the `hal-obsidian-vaults` entries in hal-system-config.json.
+ *
+ * @param {string} vaultName
+ * @returns {{
+ *   projectsFolder: string,
+ *   dailyNotesFolder: string,
+ *   emailFolder: string,
+ *   meetingsFolder: string,
+ *   peopleFolder: string,
+ * }}
+ */
+export function vaultFolders(vaultName) {
+  _ensure();
+  const v = _vaultByName(vaultName);
+  const get = (key, fallback) => {
+    if (!v) return fallback;
+    const val = v[key];
+    return (typeof val === 'string' && val.trim()) ? val.trim() : fallback;
+  };
+  return {
+    projectsFolder:   get('projects-folder', DEFAULT_VAULT_FOLDERS.projectsFolder),
+    dailyNotesFolder: get('daily-notes-folder', DEFAULT_VAULT_FOLDERS.dailyNotesFolder),
+    emailFolder:      get('email-folder', DEFAULT_VAULT_FOLDERS.emailFolder),
+    meetingsFolder:   get('meetings-folder', DEFAULT_VAULT_FOLDERS.meetingsFolder),
+    peopleFolder:     get('people-folder', DEFAULT_VAULT_FOLDERS.peopleFolder),
+  };
+}
+
+function _joinVaultSubpath(base, sub) {
+  const b = String(base || '');
+  const s = String(sub || '');
+  if (!b) return s;
+  // Config paths are usually POSIX (/vaults/...). Keep POSIX joining unless
+  // the base looks like a Windows path.
+  const useWin = b.includes('\\') || /^[a-zA-Z]:\\/.test(b);
+  const joiner = useWin ? path.win32.join : path.posix.join;
+  return joiner(b, s);
+}
+
+/**
+ * Return resolved full paths for vault directories (vault root + configured folder).
+ *
+ * @param {string} vaultName
+ * @returns {{
+ *   vaultPath: string|null,
+ *   projectsPath: string|null,
+ *   dailyNotesPath: string|null,
+ *   emailPath: string|null,
+ *   meetingsPath: string|null,
+ *   peoplePath: string|null,
+ * }}
+ */
+export function vaultDirectoryPaths(vaultName) {
+  _ensure();
+  const v = _vaultByName(vaultName);
+  if (!v || !v.path) {
+    return {
+      vaultPath: null,
+      projectsPath: null,
+      dailyNotesPath: null,
+      emailPath: null,
+      meetingsPath: null,
+      peoplePath: null,
+    };
+  }
+  const folders = vaultFolders(vaultName);
+  return {
+    vaultPath: v.path,
+    projectsPath: _joinVaultSubpath(v.path, folders.projectsFolder),
+    dailyNotesPath: _joinVaultSubpath(v.path, folders.dailyNotesFolder),
+    emailPath: _joinVaultSubpath(v.path, folders.emailFolder),
+    meetingsPath: _joinVaultSubpath(v.path, folders.meetingsFolder),
+    peoplePath: _joinVaultSubpath(v.path, folders.peopleFolder),
+  };
+}
+
+/**
+ * Return communication accounts, optionally filtered by provider.
+ * @param {string} [provider] — e.g. 'google', 'ms365', 'imap'
+ * @returns {Array<{label: string, provider: string, email: string, scopes: string[]}>}
+ */
+export function accounts(provider) {
+  _ensure();
+  const all = _cache['hal-communication-accounts'] || [];
+  if (!provider) return all;
+  return all.filter(a => a.provider === provider);
+}
+
+/**
+ * Return the configured timezone string.
+ * @returns {string|null}
+ */
+export function timezone() {
+  _ensure();
+  return _cache['hal-timezone'] || null;
+}
+
+/**
+ * Return work hours config.
+ * @returns {{start: string, end: string}|null}
+ */
+export function workHours() {
+  _ensure();
+  return _cache['hal-work-hours'] || null;
+}
+
+// ---------------------------------------------------------------------------
+// Settings accessors (deterministic callers)
+// ---------------------------------------------------------------------------
+
+function _normalizeSkillName(name) {
+  const n = String(name || '').trim();
+  if (!n) return n;
+  if (n.startsWith('hal-')) return n.slice('hal-'.length);
+  if (n.startsWith('openclaw-skill-')) return n.slice('openclaw-skill-'.length);
+  return n;
+}
+
+/**
+ * Deterministic settings getter.
+ *
+ * Usage:
+ *   getSetting('system-emails')                       -> reads top-level key from hal-system-config.json
+ *   getSetting('hal-email-triage', 'gog_client_id')   -> reads from the skill's independent config file
+ *
+ * Skill config path (deterministic):
+ *   {HAL_SKILL_ADMIN_ROOT or /data/openclaw/hal}/{skillName}/config/{skillName}.json
+ *
+ * Returns undefined when not found.
+ */
+export function getSetting(scopeOrKey, key) {
+  _ensure();
+
+  // Global setting: getSetting('system-emails')
+  if (key === undefined) {
+    return _cache ? _cache[String(scopeOrKey)] : undefined;
+  }
+
+  // Skill setting: getSetting('hal-email-triage', 'gog_client_id')
+  const skillName = _normalizeSkillName(scopeOrKey);
+  const settingKey = String(key);
+  const filePath = skillConfigPath(skillName);
+
+  let cfg;
+  try {
+    cfg = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return undefined;
+    throw err;
+  }
+
+  if (!cfg || typeof cfg !== 'object') return undefined;
+  return Object.prototype.hasOwnProperty.call(cfg, settingKey)
+    ? cfg[settingKey]
+    : undefined;
+}
+
+// Alias for callers that prefer PascalCase.
+export const GetSetting = getSetting;
+
+// ---------------------------------------------------------------------------
+// Skill accessors
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the full config block for a skill, or null if not configured.
+ * @param {string} name — skill name (e.g. 'project-manager')
+ * @returns {object|null}
+ */
+export function skill(name) {
+  _ensure();
+  const skills = _cache.skills || {};
+  return skills[name] || null;
+}
+
+/**
+ * Check if a skill is enabled (exists in config and enabled !== false).
+ */
+export function isEnabled(name) {
+  const s = skill(name);
+  return s ? s.enabled !== false : false;
+}
+
+/**
+ * Return the runtime.workspace path for a skill, or null.
+ */
+export function skillWorkspace(name) {
+  const s = skill(name);
+  return s && s.runtime ? s.runtime.workspace || null : null;
+}
+
+/**
+ * Return the binary name(s) for a skill as an array.
+ * @returns {string[]}
+ */
+export function skillBinaries(name) {
+  const s = skill(name);
+  if (!s || !s.install) return [];
+  const bin = s.install.binary;
+  if (!bin) return [];
+  return Array.isArray(bin) ? bin : [bin];
+}
+
+/**
+ * Return the homeAgent for a skill, or null if not set.
+ * When null, the skill is homed in the primary (first) agent.
+ * @param {string} name — skill name
+ * @returns {string|null}
+ */
+export function homeAgent(name) {
+  const s = skill(name);
+  return s ? s.homeAgent || null : null;
+}
+
+/**
+ * Resolve the path to a skill's config file in the HAL skill admin root.
+ *
+ * Canonical convention:
+ *   /data/openclaw/hal/{skillName}/config/{skillName}.json
+ *
+ * Override the root via HAL_SKILL_ADMIN_ROOT.
+ *
+ * @param {string} name — skill name (e.g. 'project-manager')
+ * @returns {string} absolute path to the skill's config file
+ */
+export function skillConfigPath(name) {
+  _ensure();
+  const skillName = String(name || '').trim();
+  return path.join(halSkillConfigDir(skillName), `${skillName}.json`);
+}
+
+/**
+ * Resolve the config directory for a skill under the HAL skill admin root.
+ * @param {string} name — skill name
+ * @returns {string} absolute path to the hal/config directory
+ */
+export function skillConfigDir(name) {
+  return path.dirname(skillConfigPath(name));
+}
+
+/**
+ * Synchronous check: is a skill enabled AND is its primary binary on PATH?
+ */
+export function isInstalled(name) {
+  if (!isEnabled(name)) return false;
+  const bins = skillBinaries(name);
+  if (bins.length === 0) return false;
+  return _isBinaryOnPath(bins[0]);
+}
+
+/**
+ * Async check: is a skill enabled AND is its primary binary on PATH?
+ * @returns {Promise<boolean>}
+ */
+export function isInstalledAsync(name) {
+  if (!isEnabled(name)) return Promise.resolve(false);
+  const bins = skillBinaries(name);
+  if (bins.length === 0) return Promise.resolve(false);
+  return _isBinaryOnPathAsync(bins[0]);
+}
+
+// ---------------------------------------------------------------------------
+// Binary helpers
+// ---------------------------------------------------------------------------
+
+function _isBinaryOnPath(binary) {
+  try {
+    const result = spawnSync(binary, ['--version'], {
+      timeout: 3000,
+      stdio: 'ignore',
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+function _isBinaryOnPathAsync(binary) {
+  return new Promise(resolve => {
+    try {
+      execFile(binary, ['--version'], { timeout: 5000 }, err => {
+        resolve(!err);
+      });
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Registration — write data back to system-config.json
+// ---------------------------------------------------------------------------
+
+/**
+ * Merge runtime data into a skill's runtime block and flush to disk.
+ * @param {string} name — skill name
+ * @param {object} runtimeData — key/value pairs to merge into skills[name].runtime
+ */
+export function register(name, runtimeData) {
+  _ensure();
+  if (!_cache.skills) _cache.skills = {};
+  if (!_cache.skills[name]) _cache.skills[name] = {};
+  if (!_cache.skills[name].runtime) _cache.skills[name].runtime = {};
+  Object.assign(_cache.skills[name].runtime, runtimeData);
+  _flush();
+}
+
+/**
+ * Merge communication accounts by label (upsert — match by label, replace or
+ * append). Never deletes entries whose label isn't in newAccounts.
+ * @param {Array} newAccounts — accounts to upsert
+ */
+export function writeAccounts(newAccounts) {
+  _ensure();
+  const existing = _cache['hal-communication-accounts'] || [];
+  for (const acc of newAccounts) {
+    const idx = existing.findIndex(e => e.label === acc.label);
+    if (idx >= 0) {
+      existing[idx] = acc;
+    } else {
+      existing.push(acc);
+    }
+  }
+  _cache['hal-communication-accounts'] = existing;
+  _flush();
+}
+
+/**
+ * Merge key/value pairs into a skill's config block (not runtime — top level
+ * of the skill entry). Used by init wizards to store skill-specific settings.
+ * @param {string} name — skill name
+ * @param {object} data — key/value pairs to merge
+ */
+export function writeSkillConfig(name, data) {
+  _ensure();
+  if (!_cache.skills) _cache.skills = {};
+  if (!_cache.skills[name]) _cache.skills[name] = {};
+  Object.assign(_cache.skills[name], data);
+  _flush();
+}
+
+/**
+ * Write shared top-level settings (e.g. hal-timezone, hal-work-hours).
+ * Merges into the config root — does not touch skills or other nested objects.
+ * @param {object} settings — key/value pairs for top-level config keys
+ */
+export function writeSharedSettings(settings) {
+  _ensure();
+  for (const [key, val] of Object.entries(settings)) {
+    _cache[key] = val;
+  }
+  _flush();
+}
+
+/**
+ * Flush the in-memory config to disk.
+ */
+function _flush() {
+  const dir = _configDir || process.env.HAL_SYSTEM_CONFIG || '/data/openclaw/hal';
+  fs.mkdirSync(dir, { recursive: true });
+  const filePath = path.join(dir, 'hal-system-config.json');
+  fs.writeFileSync(filePath, JSON.stringify(_cache, null, 2) + '\n', 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// Workspace resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the workspace path for a skill using a priority chain:
+ *   1. opts.workspace (explicit CLI flag)
+ *   2. HAL_{opts.envPrefix}_MASTER_WORKSPACE (skill-specific env var)
+ *   3. HAL_AGENT_WORKSPACE (agent-level env var)
+ *   4. opts.fallback (skill-specific default)
+ *   5. process.cwd()
+ *
+ * @param {{ workspace?: string, envPrefix?: string, fallback?: string }} [opts]
+ * @returns {string} Resolved absolute path.
+ */
+export function resolveWorkspace(opts) {
+  const o = opts || {};
+
+  if (o.workspace) return path.resolve(o.workspace);
+
+  if (o.envPrefix) {
+    const skillEnv = process.env[`HAL_${o.envPrefix}_MASTER_WORKSPACE`];
+    if (skillEnv) return path.resolve(skillEnv);
+  }
+
+  const agentEnv = process.env.HAL_AGENT_WORKSPACE;
+  if (agentEnv) return path.resolve(agentEnv);
+
+  if (o.fallback) return path.resolve(o.fallback);
+
+  return path.resolve(process.cwd());
+}
+
+// ---------------------------------------------------------------------------
+// Skill config file I/O
+// ---------------------------------------------------------------------------
+
+/**
+ * Read a skill's config file from {workspace}/hal/config/{skillName}.json.
+ * Returns {} when the file does not exist. Throws on corrupt JSON or
+ * permission errors.
+ *
+ * @param {string} skillName
+ * @param {string} workspace
+ * @returns {object}
+ */
+export function loadSkillConfig(skillName, workspace) {
+  const filePath = path.join(workspace, 'hal', 'config', `${skillName}.json`);
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') return {};
+    throw err;
+  }
+}
+
+/**
+ * Deep-merge source into target. Plain objects are merged recursively.
+ * Arrays are replaced atomically. Non-object values overwrite.
+ *
+ * @param {object} target
+ * @param {object} source
+ * @returns {object} The mutated target.
+ */
+function _deepMerge(target, source) {
+  for (const key of Object.keys(source)) {
+    const srcVal = source[key];
+    const tgtVal = target[key];
+    const srcIsPlain = typeof srcVal === 'object' && srcVal !== null && !Array.isArray(srcVal);
+    const tgtIsPlain = typeof tgtVal === 'object' && tgtVal !== null && !Array.isArray(tgtVal);
+
+    if (srcIsPlain && tgtIsPlain) {
+      _deepMerge(tgtVal, srcVal);
+    } else {
+      target[key] = srcVal;
+    }
+  }
+  return target;
+}
+
+/**
+ * Deep-merge data into the existing skill config at
+ * {workspace}/hal/config/{skillName}.json and write to disk.
+ * Creates parent directories as needed.
+ *
+ * @param {string} skillName
+ * @param {string} workspace
+ * @param {object} data
+ */
+export function saveSkillConfig(skillName, workspace, data) {
+  const existing = loadSkillConfig(skillName, workspace);
+  const merged = _deepMerge(existing, data);
+  const filePath = path.join(workspace, 'hal', 'config', `${skillName}.json`);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@jamaynor/hal-config",
+  "version": "1.0.1",
+  "description": "Shared configuration loader for HAL OpenClaw skills — reads system-config.json, provides skill discovery, and runtime registration",
+  "type": "module",
+  "main": "index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./test-utils": "./test-utils.js",
+    "./security": "./security/index.js"
+  },
+  "scripts": {
+    "test": "node --test test/test.js test/test-utils.test.js test/config-io.test.js test/security.test.js"
+  },
+  "keywords": ["openclaw", "hal", "config"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  }
+}