@jamaynor/hal-config 1.0.2 → 1.1.1

package/index.d.ts

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

package/lib/config.d.ts

@@ -0,0 +1,111 @@
+import type {
+  HalCommunicationAccountEntry,
+  HalRuntimeContext,
+  HalVaultAreas,
+} from './types.js';
+
+export interface ResolveWorkspaceOptions {
+  workspace?: string;
+  envPrefix?: string;
+  fallback?: string | null;
+}
+
+export interface RuntimeContextOptions {
+  callingAgentRuntimePath?: string | null;
+}
+
+export interface SkillRuntimeData {
+  [key: string]: unknown;
+}
+
+export interface SkillInstallData {
+  binary?: string | string[];
+  [key: string]: unknown;
+}
+
+export interface SkillEntry {
+  enabled?: boolean;
+  homeAgent?: string | null;
+  runtime?: SkillRuntimeData;
+  install?: SkillInstallData;
+  [key: string]: unknown;
+}
+
+export interface HalSystemConfig {
+  skills?: Record<string, SkillEntry>;
+  'hal-obsidian-vaults'?: Array<Record<string, unknown>>;
+  'hal-communication-accounts'?: HalCommunicationAccountEntry[];
+  'hal-timezone'?: string;
+  'hal-work-hours'?: { start: string; end: string } | null;
+  [key: string]: unknown;
+}
+
+export interface VaultDirectoryPaths {
+  vaultPath: string | null;
+  projectsPath: string | null;
+  dailyNotesPath: string | null;
+  emailPath: string | null;
+  meetingsPath: string | null;
+  peoplePath: string | null;
+}
+
+export interface HalSkillConfigApi {
+  normalizeSkillName(skillScope: string): string;
+  adminRoot(skillName: string): string;
+  configDir(skillName: string): string;
+  logDir(skillName: string): string;
+  configPath(skillName: string): string;
+  read(skillScope: string): Record<string, unknown>;
+  getSetting(skillScope: string, key: string): unknown;
+  write(skillScope: string, data: Record<string, unknown>): void;
+  merge(skillScope: string, patch: Record<string, unknown>): Record<string, unknown>;
+  setSetting(skillScope: string, key: string, value: unknown): Record<string, unknown>;
+}
+
+export declare function load(configDir?: string): HalSystemConfig;
+export declare function reload(): HalSystemConfig;
+export declare function raw(): HalSystemConfig;
+export declare function configDir(): string;
+
+export declare function openclawSharedWorkspaceRoot(): string;
+export declare function openclawConfigFilePath(): string;
+export declare function halSystemConfigDir(): string;
+export declare function halSystemConfigFilePath(): string;
+export declare function halSkillAdminRoot(skillName: string): string;
+export declare function halSkillConfigDir(skillName: string): string;
+export declare function halSkillLogDir(skillName: string): string;
+
+export declare const halSkillConfig: HalSkillConfigApi;
+export declare function skillConfigPath(name: string): string;
+export declare function skillConfigDir(name: string): string;
+
+export declare function vaults(): Array<Record<string, unknown>>;
+export declare function vaultFolders(vaultName: string): HalVaultAreas;
+export declare function vaultDirectoryPaths(vaultName: string): VaultDirectoryPaths;
+export declare function accounts(provider?: string): HalCommunicationAccountEntry[];
+export declare function timezone(): string | null;
+export declare function workHours(): { start: string; end: string } | null;
+
+export declare function getSetting(scopeOrKey: string, key?: string): unknown;
+export declare const GetSetting: typeof getSetting;
+
+export declare function skill(name: string): SkillEntry | null;
+export declare function isEnabled(name: string): boolean;
+export declare function skillWorkspace(name: string): string | null;
+export declare function skillBinaries(name: string): string[];
+export declare function homeAgent(name: string): string | null;
+export declare function isInstalled(name: string): boolean;
+export declare function isInstalledAsync(name: string): Promise<boolean>;
+
+export declare function getRuntimeContext(opts?: RuntimeContextOptions): HalRuntimeContext | { general: HalRuntimeContext['general'] };
+
+export declare function register(name: string, runtimeData: Record<string, unknown>): void;
+export declare function upsertCommunicationAccount(account: HalCommunicationAccountEntry): void;
+export declare function deleteCommunicationAccount(label: string): boolean;
+export declare function writeSkillConfig(name: string, data: Record<string, unknown>): void;
+export declare function writeSharedSettings(settings: Record<string, unknown>): void;
+
+export declare function resolveWorkspace(opts?: ResolveWorkspaceOptions): string;
+export declare function getSkillConfig(skillName: string, workspace: string): Record<string, unknown>;
+export declare const loadSkillConfig: typeof getSkillConfig;
+export declare function saveSkillConfig(skillName: string, workspace: string, data: Record<string, unknown>): void;

package/lib/config.js

@@ -1,11 +1,37 @@
 // =============================================================================
-// hal-shared-config — Shared configuration loader for HAL OpenClaw skills
+// hal-config/lib/config
 //
-// 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).
+// SRP (Single Responsibility)
+// - Load + cache `hal-system-config.json` and provide a single, stable API for
+//   HAL/OpenClaw skills to read shared settings (vaults, accounts, timezone,
+//   work hours), resolve workspaces, and locate per-skill config/log directories.
 //
-// Skills use this instead of each maintaining their own system-config reader.
+// Public Interface
+// config
+// ├── Loading / cache
+// │   ├── load(configDir?)
+// │   ├── reload()
+// │   └── configDir()
+// ├── Runtime context (primary read API)
+// │   ├── getRuntimeContext(opts?)                   -> HalRuntimeContext
+// │   │   opts.callingAgentRuntimePath?: string|null
+// │   │   - If null/unresolved, returns only `general` (no `callingAgent`)
+// │   └── HalRuntimeContext
+// │       ├── general
+// │       └── callingAgent?                          (optional)
+// │           └── skills[*].agentHasAccess           (resolved from homeAgent + caller)
+// ├── Installation checks
+// │   ├── isInstalled(skillName)
+// │   └── isInstalledAsync(skillName)
+// ├── Per-skill config I/O (skill-owned files; separate from hal-system-config.json)
+// │   ├── getSkillConfig(skillName, workspace)
+// │   └── saveSkillConfig(skillName, workspace, data)
+// └── Init-wizard writes (mutate hal-system-config.json)
+//     ├── register(name, runtimeData)
+//     ├── upsertCommunicationAccount(account)
+//     ├── deleteCommunicationAccount(label)
+//     ├── writeSkillConfig(name, data)
+//     └── writeSharedSettings(settings)
 // =============================================================================
 
 import fs from 'node:fs';
@@ -474,6 +500,190 @@ export function isInstalledAsync(name) {
   return _isBinaryOnPathAsync(bins[0]);
 }
 
+function _canWriteDir(dirPath) {
+  try {
+    if (!dirPath) return false;
+    fs.accessSync(dirPath, fs.constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function _deriveAgentIdFromRuntimePath(runtimePath) {
+  const normalized = path.resolve(String(runtimePath || '').trim());
+  if (!normalized) return null;
+  const id = path.basename(normalized);
+  return id || null;
+}
+
+function _vaultDirectoryName(vaultPath) {
+  const p = String(vaultPath || '').trim();
+  if (!p) return '';
+  const normalized = p.replace(/[\\/]+$/, '');
+  const useWin = normalized.includes('\\') || /^[a-zA-Z]:\\/.test(normalized);
+  return useWin ? path.win32.basename(normalized) : path.posix.basename(normalized);
+}
+
+function _resolveMasterVault(vaultEntries) {
+  const masters = vaultEntries.filter(v => v.role === 'master');
+  if (masters.length === 0) return null;
+  if (masters.length > 1) {
+    throw new Error('ERROR: Multiple master vaults configured in hal-obsidian-vaults.');
+  }
+  const m = masters[0];
+  return {
+    name: m.name,
+    label: m.label,
+    absolutePath: m.absolutePath,
+    directoryName: m.directoryName,
+  };
+}
+
+/**
+ * Build a normalized runtime context for HAL/OpenClaw consumers.
+ *
+ * @param {{ callingAgentRuntimePath?: string|null }} [opts]
+ * @returns {{ general: object, callingAgent?: object }}
+ */
+export function getRuntimeContext(opts) {
+  _ensure();
+  const o = opts || {};
+
+  const openClawRoot = '/data/openclaw';
+  const openClawAgentRoot = '/data/agents';
+  const openClawConfigFile = path.join(openClawRoot, 'openclaw.json');
+  const openClawSharedAgentWorkspace = openclawSharedWorkspaceRoot();
+  const halRoot = halSystemConfigDir();
+  const halSystemConfigFile = halSystemConfigFilePath();
+
+  const rawVaults = vaults();
+  const vaultEntries = rawVaults.map(v => {
+    const name = String(v?.name || '').trim();
+    const label = String(v?.label || name).trim();
+    const absolutePath = String(v?.path || '').trim();
+    const role = String(v?.role || v?.vaultType || 'standard').trim().toLowerCase() === 'master'
+      ? 'master'
+      : 'standard';
+    const folderNames = vaultFolders(name);
+    return {
+      name,
+      label,
+      role,
+      absolutePath,
+      directoryName: _vaultDirectoryName(absolutePath),
+      knownAreas: {
+        projectsPath: _joinVaultSubpath(absolutePath, folderNames.projectsFolder),
+        dailyNotesPath: _joinVaultSubpath(absolutePath, folderNames.dailyNotesFolder),
+        emailPath: _joinVaultSubpath(absolutePath, folderNames.emailFolder),
+        meetingsPath: _joinVaultSubpath(absolutePath, folderNames.meetingsFolder),
+        peoplePath: _joinVaultSubpath(absolutePath, folderNames.peopleFolder),
+      },
+    };
+  });
+
+  const skillMap = _cache.skills || {};
+  const skills = {};
+  for (const [skillName, skillData] of Object.entries(skillMap)) {
+    const bins = (() => {
+      const bin = skillData?.install?.binary;
+      if (!bin) return [];
+      return Array.isArray(bin) ? bin : [bin];
+    })();
+    skills[skillName] = {
+      enabled: skillData?.enabled !== false,
+      homeAgent: skillData?.homeAgent || null,
+      binaries: bins,
+      configPath: skillConfigPath(skillName),
+      configDir: skillConfigDir(skillName),
+    };
+  }
+
+  const general = {
+    openClawPaths: {
+      openClawRoot,
+      openClawAgentRoot,
+      openClawConfigFile,
+      openClawSharedAgentWorkspace,
+    },
+    halPaths: {
+      halRoot,
+      halSystemConfigDir: halRoot,
+      halSystemConfigFile,
+    },
+    masterTemplates: {
+      masterUserPath: path.join(openClawSharedAgentWorkspace, 'USER.md'),
+      masterSafetyPath: path.join(openClawSharedAgentWorkspace, 'SAFETY.md'),
+    },
+    vaults: vaultEntries,
+    masterVault: _resolveMasterVault(vaultEntries),
+    communicationAccounts: _cache['hal-communication-accounts'] || [],
+    settings: {
+      timezone: _cache['hal-timezone'] || null,
+      workHours: _cache['hal-work-hours'] || null,
+    },
+    skills,
+  };
+
+  const runtimePathRaw = (o.callingAgentRuntimePath ?? process.env.HAL_AGENT_WORKSPACE ?? '').toString().trim();
+  if (!runtimePathRaw) return { general };
+
+  const runtimePath = path.resolve(runtimePathRaw);
+  const agentId = _deriveAgentIdFromRuntimePath(runtimePath);
+
+  const skillPathsBySkill = {};
+  const accessBySkill = {};
+  const agentSkillState = {};
+  for (const [skillName, skillData] of Object.entries(skills)) {
+    const sharedConfigDir = halSkillConfigDir(skillName);
+    const sharedLogDir = halSkillLogDir(skillName);
+    const agentWorkingDir = path.join(runtimePath, 'hal', skillName);
+    skillPathsBySkill[skillName] = {
+      skillName,
+      sharedConfigDir,
+      sharedLogDir,
+      agentWorkingDir,
+      agentStateDir: path.join(agentWorkingDir, 'state'),
+      agentCacheDir: path.join(agentWorkingDir, 'cache'),
+      agentTmpDir: path.join(agentWorkingDir, 'tmp'),
+      agentSweepDir: path.join(agentWorkingDir, 'sweep'),
+    };
+    const hasAccess = !skillData.homeAgent || (agentId && skillData.homeAgent === agentId);
+    accessBySkill[skillName] = !!hasAccess;
+    agentSkillState[skillName] = { agentHasAccess: !!hasAccess };
+  }
+
+  const callingAgent = {
+    id: agentId,
+    workspacePath: runtimePath,
+    identityFiles: {
+      soul: path.join(runtimePath, 'SOUL.md'),
+      agents: path.join(runtimePath, 'AGENTS.md'),
+      identity: path.join(runtimePath, 'IDENTITY.md'),
+      heartbeat: path.join(runtimePath, 'HEARTBEAT.md'),
+      tools: path.join(runtimePath, 'TOOLS.md'),
+      user: path.join(runtimePath, 'USER.md'),
+      safety: path.join(runtimePath, 'SAFETY.md'),
+    },
+    stores: {
+      memoryDir: path.join(runtimePath, 'memory'),
+      knowledgeDir: path.join(runtimePath, 'knowledge'),
+      skillsDir: path.join(runtimePath, 'skills'),
+    },
+    skillPaths: {
+      bySkill: skillPathsBySkill,
+    },
+    skills: agentSkillState,
+    capabilities: {
+      canWriteAgentWorkspace: _canWriteDir(runtimePath),
+      canWriteSharedWorkspace: _canWriteDir(openClawSharedAgentWorkspace),
+      isHomeAgentForSkill: accessBySkill,
+    },
+  };
+
+  return { general, callingAgent };
+}
+
 // ---------------------------------------------------------------------------
 // Binary helpers
 // ---------------------------------------------------------------------------
@@ -521,25 +731,51 @@ export function register(name, runtimeData) {
 }
 
 /**
- * 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
+ * Upsert a single communication account by label.
+ *
+ * @param {import('./types').HalCommunicationAccountEntry} account
  */
-export function writeAccounts(newAccounts) {
+export function upsertCommunicationAccount(account) {
   _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);
-    }
+  if (!account || typeof account !== 'object') {
+    throw new Error('ERROR: upsertCommunicationAccount requires an account object.');
+  }
+  if (!account.label || typeof account.label !== 'string') {
+    throw new Error('ERROR: upsertCommunicationAccount requires account.label (string).');
   }
+  if (!account.provider || typeof account.provider !== 'string') {
+    throw new Error('ERROR: upsertCommunicationAccount requires account.provider (string).');
+  }
+
+  const existing = _cache['hal-communication-accounts'] || [];
+  const idx = existing.findIndex(e => e.label === account.label);
+  if (idx >= 0) existing[idx] = account;
+  else existing.push(account);
+
   _cache['hal-communication-accounts'] = existing;
   _flush();
 }
 
+/**
+ * Delete a communication account by label.
+ *
+ * @param {string} label
+ * @returns {boolean} true when an entry was removed
+ */
+export function deleteCommunicationAccount(label) {
+  _ensure();
+  if (!label || typeof label !== 'string') {
+    throw new Error('ERROR: deleteCommunicationAccount requires label (string).');
+  }
+
+  const existing = _cache['hal-communication-accounts'] || [];
+  const before = existing.length;
+  _cache['hal-communication-accounts'] = existing.filter(e => e?.label !== label);
+  const removed = _cache['hal-communication-accounts'].length < before;
+  if (removed) _flush();
+  return removed;
+}
+
 /**
  * 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.
@@ -623,7 +859,7 @@ export function resolveWorkspace(opts) {
  * @param {string} workspace
  * @returns {object}
  */
-export function loadSkillConfig(skillName, workspace) {
+export function getSkillConfig(skillName, workspace) {
   const filePath = path.join(workspace, 'hal', 'config', `${skillName}.json`);
   try {
     return JSON.parse(fs.readFileSync(filePath, 'utf8'));
@@ -633,6 +869,9 @@ export function loadSkillConfig(skillName, workspace) {
   }
 }
 
+// Backward compatibility alias; prefer getSkillConfig().
+export const loadSkillConfig = getSkillConfig;
+
 /**
  * Deep-merge source into target. Plain objects are merged recursively.
  * Arrays are replaced atomically. Non-object values overwrite.

package/lib/types.d.ts

@@ -0,0 +1,218 @@
+/**
+ * =============================================================================
+ * hal-config/lib/types
+ *
+ * SRP (Single Responsibility)
+ * - Define the shared TypeScript contracts for HAL/OpenClaw runtime context:
+ *   global platform state plus calling-agent state used by skills at runtime.
+ *
+ * Interface Tree
+HalRuntimeContext
+├── general: HalGeneralState
+│   ├── openClawPaths
+│   │   ├── openClawRoot
+│   │   ├── openClawAgentRoot
+│   │   ├── openClawConfigFile
+│   │   └── openClawSharedAgentWorkspace
+│   ├── halPaths
+│   │   ├── halRoot
+│   │   ├── halSystemConfigDir
+│   │   └── halSystemConfigFile
+│   ├── masterTemplates
+│   │   ├── masterUserPath      (e.g. {openClawSharedAgentWorkspace}/USER.md)
+│   │   └── masterSafetyPath    (e.g. {openClawSharedAgentWorkspace}/SAFETY.md)
+│   ├── vaults: HalVaultEntry[]
+│   │   └── HalVaultEntry
+│   │       ├── name
+│   │       ├── label
+│   │       ├── role (master|standard)
+│   │       ├── absolutePath
+│   │       ├── directoryName
+│   │       └── knownAreas
+│   │           ├── projectsPath
+│   │           ├── dailyNotesPath
+│   │           ├── emailPath
+│   │           ├── meetingsPath
+│   │           └── peoplePath
+│   ├── masterVault
+│   │   ├── name
+│   │   ├── label
+│   │   ├── absolutePath
+│   │   └── directoryName
+│   ├── communicationAccounts: HalCommunicationAccountEntry[]
+│   │   └── HalCommunicationAccountEntry
+│   │       ├── label
+│   │       ├── provider
+│   │       ├── email?
+│   │       └── scopes?
+│   ├── settings
+│   │   ├── timezone
+│   │   └── workHours
+│   │       ├── start
+│   │       └── end
+│   └── skills: Record<string, HalSkillRuntimeEntry>
+│       └── HalSkillRuntimeEntry
+│           ├── enabled
+│           ├── homeAgent
+│           ├── binaries[]
+│           ├── configPath
+│           └── configDir
+└── callingAgent: HalCallingAgentState
+    ├── id
+    ├── workspacePath
+    ├── identityFiles
+    │   ├── soul
+    │   ├── agents
+    │   ├── identity
+    │   ├── heartbeat
+    │   ├── tools
+    │   ├── user
+    │   └── safety
+    ├── stores
+    │   ├── memoryDir
+    │   ├── knowledgeDir
+    │   └── skillsDir
+    ├── skillPaths
+    │   └── bySkill: Record<string, HalSkillPathSet>
+    │       └── HalSkillPathSet
+    │           ├── skillName
+    │           ├── sharedConfigDir
+    │           ├── sharedLogDir
+    │           ├── agentWorkingDir
+    │           ├── agentStateDir
+    │           ├── agentCacheDir
+    │           ├── agentTmpDir
+    │           └── agentSweepDir
+    └── capabilities
+        ├── canWriteAgentWorkspace
+        ├── canWriteSharedWorkspace
+        └── isHomeAgentForSkill: Record<string, boolean>
+ * =============================================================================
+ */
+export type VaultRole = 'master' | 'standard';
+
+export interface HalVaultAreas {
+  projectsFolder: string;
+  dailyNotesFolder: string;
+  emailFolder: string;
+  meetingsFolder: string;
+  peopleFolder: string;
+}
+
+export interface HalVaultResolvedAreas {
+  projectsPath: string;
+  dailyNotesPath: string;
+  emailPath: string;
+  meetingsPath: string;
+  peoplePath: string;
+}
+
+export interface HalVaultEntry {
+  name: string;
+  label: string;
+  role: VaultRole;
+  absolutePath: string;
+  directoryName: string;
+  knownAreas: HalVaultResolvedAreas;
+}
+
+export interface HalMasterVaultRef {
+  name: string;
+  label: string;
+  absolutePath: string;
+  directoryName: string;
+}
+
+export interface HalCommunicationAccountEntry {
+  label: string;
+  provider: string;
+  email?: string;
+  scopes?: string[];
+  [key: string]: unknown;
+}
+
+export interface HalSkillRuntimeEntry {
+  enabled: boolean;
+  homeAgent: string | null;
+  binaries: string[];
+  configPath: string;
+  configDir: string;
+}
+
+export interface HalSkillPathSet {
+  skillName: string;
+  sharedConfigDir: string;
+  sharedLogDir: string;
+  agentWorkingDir: string;
+  agentStateDir: string;
+  agentCacheDir: string;
+  agentTmpDir: string;
+  agentSweepDir: string;
+}
+
+export interface HalGeneralState {
+  openClawPaths: {
+    openClawRoot: string;
+    openClawAgentRoot: string;
+    openClawConfigFile: string;
+    openClawSharedAgentWorkspace: string;
+  };
+
+  halPaths: {
+    halRoot: string;
+    halSystemConfigDir: string;
+    halSystemConfigFile: string;
+  };
+
+  masterTemplates: {
+    masterUserPath: string;
+    masterSafetyPath: string;
+  };
+
+  vaults: HalVaultEntry[];
+  masterVault: HalMasterVaultRef | null;
+  communicationAccounts: HalCommunicationAccountEntry[];
+
+  settings: {
+    timezone: string | null;
+    workHours: { start: string; end: string } | null;
+  };
+
+  skills: Record<string, HalSkillRuntimeEntry>;
+}
+
+export interface HalCallingAgentState {
+  id: string | null;
+  workspacePath: string | null;
+
+  identityFiles: {
+    soul: string | null;
+    agents: string | null;
+    identity: string | null;
+    heartbeat: string | null;
+    tools: string | null;
+    user: string | null;
+    safety: string | null;
+  };
+
+  stores: {
+    memoryDir: string | null;
+    knowledgeDir: string | null;
+    skillsDir: string | null;
+  };
+
+  skillPaths: {
+    bySkill: Record<string, HalSkillPathSet>;
+  };
+
+  capabilities: {
+    canWriteAgentWorkspace: boolean;
+    canWriteSharedWorkspace: boolean;
+    isHomeAgentForSkill: Record<string, boolean>;
+  };
+}
+
+export interface HalRuntimeContext {
+  general: HalGeneralState;
+  callingAgent: HalCallingAgentState;
+}

package/package.json

@@ -1,16 +1,35 @@
 {
   "name": "@jamaynor/hal-config",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "Shared configuration loader for HAL OpenClaw skills — reads system-config.json, provides skill discovery, and runtime registration",
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "test-utils.js",
+    "test-utils.d.ts",
+    "lib/",
+    "security/",
+    "package.json"
+  ],
   "publishConfig": {
     "access": "public"
   },
   "exports": {
-    ".": "./index.js",
-    "./test-utils": "./test-utils.js",
-    "./security": "./security/index.js"
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./test-utils": {
+      "types": "./test-utils.d.ts",
+      "default": "./test-utils.js"
+    },
+    "./security": {
+      "types": "./security/index.d.ts",
+      "default": "./security/index.js"
+    }
   },
   "scripts": {
     "test": "node --test test/test.js test/test-utils.test.js test/config-io.test.js test/security.test.js"