@jamaynor/hal-config 1.0.2 → 1.1.0

package/CLAUDE.md

@@ -52,7 +52,8 @@ halConfig.halSkillConfig.setSetting(skillNameOrScope, key, value) // merge singl
 
 // 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.upsertCommunicationAccount(account) // Upsert one communication account by label
+halConfig.deleteCommunicationAccount(label)   // Delete one communication account by label
 halConfig.writeSkillConfig(name, data)     // Merge into skills[name]
 halConfig.writeSharedSettings(settings)    // Write top-level keys (hal-timezone, etc.)
 ```

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,6 +1,6 @@
 {
   "name": "@jamaynor/hal-config",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Shared configuration loader for HAL OpenClaw skills — reads system-config.json, provides skill discovery, and runtime registration",
   "type": "module",
   "main": "index.js",

package/test/test.js

@@ -495,12 +495,12 @@ describe('hal-shared-config', () => {
     });
   });
 
-  describe('writeAccounts()', () => {
-    it('appends new accounts', () => {
+  describe('upsertCommunicationAccount()', () => {
+    it('appends new account', () => {
       hal.load(tmpDir);
-      hal.writeAccounts([
-        { label: 'imap@example.com', provider: 'imap', email: 'imap@example.com' },
-      ]);
+      hal.upsertCommunicationAccount(
+        { label: 'imap@example.com', provider: 'imap', email: 'imap@example.com' }
+      );
 
       const ondisk = readConfig(tmpDir);
       assert.equal(ondisk['hal-communication-accounts'].length, 3);
@@ -508,10 +508,10 @@ describe('hal-shared-config', () => {
 
     it('replaces existing account by label', () => {
       hal.load(tmpDir);
-      hal.writeAccounts([
+      hal.upsertCommunicationAccount(
         { label: 'me@gmail.com', provider: 'google', email: 'me@gmail.com',
-          scopes: ['email'] },
-      ]);
+          scopes: ['email'] }
+      );
 
       const ondisk = readConfig(tmpDir);
       assert.equal(ondisk['hal-communication-accounts'].length, 2);
@@ -522,9 +522,9 @@ describe('hal-shared-config', () => {
 
     it('does not remove unmentioned accounts', () => {
       hal.load(tmpDir);
-      hal.writeAccounts([
-        { label: 'new@example.com', provider: 'imap', email: 'new@example.com' },
-      ]);
+      hal.upsertCommunicationAccount(
+        { label: 'new@example.com', provider: 'imap', email: 'new@example.com' }
+      );
 
       const ondisk = readConfig(tmpDir);
       const labels = ondisk['hal-communication-accounts'].map(a => a.label);
@@ -534,6 +534,23 @@ describe('hal-shared-config', () => {
     });
   });
 
+  describe('deleteCommunicationAccount()', () => {
+    it('deletes an existing account by label', () => {
+      hal.load(tmpDir);
+      const removed = hal.deleteCommunicationAccount('me@gmail.com');
+      assert.equal(removed, true);
+      const ondisk = readConfig(tmpDir);
+      const labels = ondisk['hal-communication-accounts'].map(a => a.label);
+      assert.ok(!labels.includes('me@gmail.com'));
+    });
+
+    it('returns false when label does not exist', () => {
+      hal.load(tmpDir);
+      const removed = hal.deleteCommunicationAccount('missing@example.com');
+      assert.equal(removed, false);
+    });
+  });
+
   describe('writeSkillConfig()', () => {
     it('merges into skill block', () => {
       hal.load(tmpDir);

package/publish.ps1

@@ -1,30 +0,0 @@
-$ErrorActionPreference = 'Stop'
-
-Write-Host "Publishing @jamaynor/hal-config from this directory..."
-
-# Prompt for token without echoing it to the console.
-$secure = Read-Host -Prompt "Paste npm automation token (input hidden)" -AsSecureString
-$token  = [Runtime.InteropServices.Marshal]::PtrToStringAuto(
-  [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure)
-)
-
-if (-not $token -or -not $token.Trim()) {
-  throw "No token provided."
-}
-
-try {
-  $env:NPM_TOKEN = $token.Trim()
-
-  Write-Host ""
-  Write-Host "npm whoami:"
-  npm whoami
-
-  Write-Host ""
-  Write-Host "npm publish:"
-  npm publish
-} finally {
-  Remove-Item Env:NPM_TOKEN -ErrorAction SilentlyContinue
-  # Reduce lifetime of plaintext token in memory.
-  $token = $null
-}
-