@jamaynor/hal-config 1.0.2 → 1.1.1

package/security/index.d.ts

@@ -0,0 +1,33 @@
+export interface ValidateResult {
+  allowed: boolean;
+  reason?: string;
+}
+
+export interface SanitizeResult {
+  cleaned: string;
+  stats: Record<string, unknown>;
+}
+
+export interface SecurityApi {
+  sanitize: {
+    text(text: string, opts?: Record<string, unknown>): SanitizeResult;
+  };
+  redact: {
+    secrets(text: string): string;
+    pii(text: string, config: Record<string, unknown>): string;
+    all(text: string, config: Record<string, unknown>): string;
+  };
+  validate: {
+    path(filePath: string, allowedDirs: string[]): ValidateResult;
+    url(url: string, resolver?: unknown): Promise<ValidateResult>;
+    filename(name: string): ValidateResult;
+  };
+  governor: {
+    create(opts?: Record<string, unknown>): unknown;
+    GovernorError: new (...args: unknown[]) => Error;
+    DEFAULTS: Record<string, unknown>;
+  };
+}
+
+declare const security: SecurityApi;
+export default security;

package/test-utils.d.ts

@@ -0,0 +1,30 @@
+export declare function makeTmpDir(prefix?: string): string;
+export declare function makeTmpDirAsync(prefix?: string): Promise<string>;
+export declare function cleanup(dir: string): void;
+export declare function cleanupAsync(dir: string): Promise<void>;
+
+export declare function scaffold(
+  baseDir: string,
+  opts?: {
+    dirs?: string[];
+    files?: Record<string, string | object>;
+  }
+): void;
+
+export declare function captureLog(): { lines: string[]; restore: () => void };
+export declare function captureStderr(): { lines: string[]; restore: () => void };
+export declare function captureWarn(): { lines: string[]; restore: () => void };
+export declare function captureOutput(): {
+  stdout: string[];
+  stderr: string[];
+  raw: unknown[];
+  restore: () => void;
+};
+
+export declare function silent<T>(fn: () => T): T;
+export declare function withCapturedLog<T>(fn: () => T): string[] | Promise<string[]>;
+export declare function writeJson(filePath: string, data: unknown): void;
+export declare function mockProcessExit(): {
+  readonly code: number | undefined;
+  restore: () => void;
+};

package/CLAUDE.md

@@ -1,84 +0,0 @@
-# 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/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
-}
-

package/test/config-io.test.js

@@ -1,326 +0,0 @@
-/**
- * config-io.test
- *
- * Responsibility: Tests for resolveWorkspace, loadSkillConfig, and
- * saveSkillConfig added in M-2.5/2.6.
- */
-
-import { describe, it, beforeEach, afterEach } from 'node:test';
-import assert from 'node:assert/strict';
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { dirname } from 'node:path';
-
-import { makeTmpDir, writeJson, cleanup } from '../test-utils.js';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-// Fresh dynamic import for each test to reset module-level cache
-async function freshImport() {
-  const modPath = path.resolve(__dirname, '../lib/config.js');
-  const url = `file:///${modPath.replace(/\\/g, '/')}?t=${Date.now()}`;
-  return import(url);
-}
-
-// ============================================================================
-// resolveWorkspace
-// ============================================================================
-
-describe('resolveWorkspace()', () => {
-  let hal;
-
-  beforeEach(async () => {
-    hal = await freshImport();
-  });
-
-  it('returns explicit opts.workspace when provided', () => {
-    const result = hal.resolveWorkspace({ workspace: '/explicit/path' });
-    assert.equal(result, path.resolve('/explicit/path'));
-  });
-
-  it('explicit opts.workspace takes precedence over all env vars', () => {
-    const origSkill = process.env.HAL_TEST_SKILL_MASTER_WORKSPACE;
-    const origAgent = process.env.HAL_AGENT_WORKSPACE;
-    process.env.HAL_TEST_SKILL_MASTER_WORKSPACE = '/skill/env/path';
-    process.env.HAL_AGENT_WORKSPACE = '/agent/env/path';
-    try {
-      const result = hal.resolveWorkspace({
-        workspace: '/explicit/wins',
-        envPrefix: 'TEST_SKILL',
-        fallback: '/fallback/path',
-      });
-      assert.equal(result, path.resolve('/explicit/wins'));
-    } finally {
-      if (origSkill === undefined) delete process.env.HAL_TEST_SKILL_MASTER_WORKSPACE;
-      else process.env.HAL_TEST_SKILL_MASTER_WORKSPACE = origSkill;
-      if (origAgent === undefined) delete process.env.HAL_AGENT_WORKSPACE;
-      else process.env.HAL_AGENT_WORKSPACE = origAgent;
-    }
-  });
-
-  it('reads HAL_{envPrefix}_MASTER_WORKSPACE when envPrefix is set', () => {
-    const key = 'HAL_TEST_SKILL_MASTER_WORKSPACE';
-    const orig = process.env[key];
-    process.env[key] = '/from/skill/env';
-    try {
-      const result = hal.resolveWorkspace({ envPrefix: 'TEST_SKILL' });
-      assert.equal(result, path.resolve('/from/skill/env'));
-    } finally {
-      if (orig === undefined) delete process.env[key];
-      else process.env[key] = orig;
-    }
-  });
-
-  it('falls through to HAL_AGENT_WORKSPACE when skill-specific env var is unset', () => {
-    const skillKey = 'HAL_PLAN_DAY_MASTER_WORKSPACE';
-    const agentKey = 'HAL_AGENT_WORKSPACE';
-    const origSkill = process.env[skillKey];
-    const origAgent = process.env[agentKey];
-    delete process.env[skillKey];
-    process.env[agentKey] = '/from/agent/env';
-    try {
-      const result = hal.resolveWorkspace({ envPrefix: 'PLAN_DAY' });
-      assert.equal(result, path.resolve('/from/agent/env'));
-    } finally {
-      if (origSkill === undefined) delete process.env[skillKey];
-      else process.env[skillKey] = origSkill;
-      if (origAgent === undefined) delete process.env[agentKey];
-      else process.env[agentKey] = origAgent;
-    }
-  });
-
-  it('falls through to opts.fallback when no env vars are set', () => {
-    const skillKey = 'HAL_TEST_SKILL_MASTER_WORKSPACE';
-    const agentKey = 'HAL_AGENT_WORKSPACE';
-    const origSkill = process.env[skillKey];
-    const origAgent = process.env[agentKey];
-    delete process.env[skillKey];
-    delete process.env[agentKey];
-    try {
-      const result = hal.resolveWorkspace({
-        envPrefix: 'TEST_SKILL',
-        fallback: '/my/fallback',
-      });
-      assert.equal(result, path.resolve('/my/fallback'));
-    } finally {
-      if (origSkill === undefined) delete process.env[skillKey];
-      else process.env[skillKey] = origSkill;
-      if (origAgent === undefined) delete process.env[agentKey];
-      else process.env[agentKey] = origAgent;
-    }
-  });
-
-  it('falls through to process.cwd() when nothing is configured', () => {
-    const skillKey = 'HAL_NOTHING_MASTER_WORKSPACE';
-    const agentKey = 'HAL_AGENT_WORKSPACE';
-    const origSkill = process.env[skillKey];
-    const origAgent = process.env[agentKey];
-    delete process.env[skillKey];
-    delete process.env[agentKey];
-    try {
-      const result = hal.resolveWorkspace({ envPrefix: 'NOTHING' });
-      assert.equal(result, path.resolve(process.cwd()));
-    } finally {
-      if (origSkill === undefined) delete process.env[skillKey];
-      else process.env[skillKey] = origSkill;
-      if (origAgent === undefined) delete process.env[agentKey];
-      else process.env[agentKey] = origAgent;
-    }
-  });
-
-  it('returns cwd when opts is empty', () => {
-    const agentKey = 'HAL_AGENT_WORKSPACE';
-    const origAgent = process.env[agentKey];
-    delete process.env[agentKey];
-    try {
-      const result = hal.resolveWorkspace({});
-      assert.equal(result, path.resolve(process.cwd()));
-    } finally {
-      if (origAgent === undefined) delete process.env[agentKey];
-      else process.env[agentKey] = origAgent;
-    }
-  });
-
-  it('returns cwd when opts is omitted', () => {
-    const agentKey = 'HAL_AGENT_WORKSPACE';
-    const origAgent = process.env[agentKey];
-    delete process.env[agentKey];
-    try {
-      const result = hal.resolveWorkspace();
-      assert.equal(result, path.resolve(process.cwd()));
-    } finally {
-      if (origAgent === undefined) delete process.env[agentKey];
-      else process.env[agentKey] = origAgent;
-    }
-  });
-
-  it('all returned paths are absolute', () => {
-    const result = hal.resolveWorkspace({ workspace: 'relative/path' });
-    assert.ok(path.isAbsolute(result), `Expected absolute path, got: ${result}`);
-  });
-
-  it('env var path is resolved to absolute', () => {
-    const key = 'HAL_AGENT_WORKSPACE';
-    const orig = process.env[key];
-    process.env[key] = 'relative/agent/path';
-    try {
-      const result = hal.resolveWorkspace({});
-      assert.ok(path.isAbsolute(result), `Expected absolute path, got: ${result}`);
-    } finally {
-      if (orig === undefined) delete process.env[key];
-      else process.env[key] = orig;
-    }
-  });
-});
-
-// ============================================================================
-// loadSkillConfig
-// ============================================================================
-
-describe('loadSkillConfig()', () => {
-  let hal;
-  let tmpDir;
-
-  beforeEach(async () => {
-    hal = await freshImport();
-    tmpDir = makeTmpDir('hsc-load-');
-  });
-
-  afterEach(() => {
-    cleanup(tmpDir);
-  });
-
-  it('returns {} for a missing config file', () => {
-    const result = hal.loadSkillConfig('no-such-skill', tmpDir);
-    assert.deepStrictEqual(result, {});
-  });
-
-  it('returns parsed JSON for an existing config file', () => {
-    const configPath = path.join(tmpDir, 'hal', 'config', 'my-skill.json');
-    writeJson(configPath, { version: '1.0', key: 'value' });
-    const result = hal.loadSkillConfig('my-skill', tmpDir);
-    assert.equal(result.version, '1.0');
-    assert.equal(result.key, 'value');
-  });
-
-  it('reads from {workspace}/hal/config/{skillName}.json', () => {
-    const expected = { configured: true, count: 42 };
-    const configPath = path.join(tmpDir, 'hal', 'config', 'test-skill.json');
-    writeJson(configPath, expected);
-    const result = hal.loadSkillConfig('test-skill', tmpDir);
-    assert.deepStrictEqual(result, expected);
-  });
-
-  it('throws SyntaxError on corrupt JSON', () => {
-    const configDir = path.join(tmpDir, 'hal', 'config');
-    fs.mkdirSync(configDir, { recursive: true });
-    fs.writeFileSync(path.join(configDir, 'bad-skill.json'), '{not valid json', 'utf8');
-    assert.throws(
-      () => hal.loadSkillConfig('bad-skill', tmpDir),
-      { name: 'SyntaxError' }
-    );
-  });
-});
-
-// ============================================================================
-// saveSkillConfig
-// ============================================================================
-
-describe('saveSkillConfig()', () => {
-  let hal;
-  let tmpDir;
-
-  beforeEach(async () => {
-    hal = await freshImport();
-    tmpDir = makeTmpDir('hsc-save-');
-  });
-
-  afterEach(() => {
-    cleanup(tmpDir);
-  });
-
-  it('creates the file and parent directories on first write', () => {
-    hal.saveSkillConfig('new-skill', tmpDir, { initialized: true });
-    const filePath = path.join(tmpDir, 'hal', 'config', 'new-skill.json');
-    assert.ok(fs.existsSync(filePath), 'config file must be created');
-    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
-    assert.equal(parsed.initialized, true);
-  });
-
-  it('deep merge: new top-level keys are added, existing keys preserved', () => {
-    const configPath = path.join(tmpDir, 'hal', 'config', 'test-skill.json');
-    writeJson(configPath, { existing: 'keep-me', count: 1 });
-
-    hal.saveSkillConfig('test-skill', tmpDir, { newKey: 'added' });
-
-    const result = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-    assert.equal(result.existing, 'keep-me');
-    assert.equal(result.count, 1);
-    assert.equal(result.newKey, 'added');
-  });
-
-  it('deep merge: overwritten top-level keys are replaced', () => {
-    const configPath = path.join(tmpDir, 'hal', 'config', 'test-skill.json');
-    writeJson(configPath, { key: 'old-value', other: 'unchanged' });
-
-    hal.saveSkillConfig('test-skill', tmpDir, { key: 'new-value' });
-
-    const result = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-    assert.equal(result.key, 'new-value');
-    assert.equal(result.other, 'unchanged');
-  });
-
-  it('deep merge: nested objects are merged recursively', () => {
-    const configPath = path.join(tmpDir, 'hal', 'config', 'test-skill.json');
-    writeJson(configPath, {
-      governor: {
-        callers: ['agent-a', 'agent-b'],
-        spendWarnThreshold: 5,
-      },
-    });
-
-    hal.saveSkillConfig('test-skill', tmpDir, {
-      governor: { spendWarnThreshold: 10 },
-    });
-
-    const result = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-    // Existing nested key preserved
-    assert.deepStrictEqual(result.governor.callers, ['agent-a', 'agent-b']);
-    // Nested key updated
-    assert.equal(result.governor.spendWarnThreshold, 10);
-  });
-
-  it('deep merge: arrays are replaced atomically', () => {
-    const configPath = path.join(tmpDir, 'hal', 'config', 'test-skill.json');
-    writeJson(configPath, { tags: ['alpha', 'beta', 'gamma'] });
-
-    hal.saveSkillConfig('test-skill', tmpDir, { tags: ['delta'] });
-
-    const result = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-    assert.deepStrictEqual(result.tags, ['delta']);
-  });
-
-  it('writes valid JSON with 2-space indentation', () => {
-    hal.saveSkillConfig('indent-skill', tmpDir, { a: 1, b: { c: 2 } });
-    const filePath = path.join(tmpDir, 'hal', 'config', 'indent-skill.json');
-    const raw = fs.readFileSync(filePath, 'utf8');
-    // 2-space indent: second line should start with two spaces
-    const lines = raw.split('\n');
-    assert.ok(lines.length > 1, 'should be multi-line JSON');
-    assert.ok(lines[1].startsWith('  '), `second line should start with 2 spaces: "${lines[1]}"`);
-  });
-
-  it('written file ends with a trailing newline', () => {
-    hal.saveSkillConfig('newline-skill', tmpDir, { x: true });
-    const filePath = path.join(tmpDir, 'hal', 'config', 'newline-skill.json');
-    const raw = fs.readFileSync(filePath, 'utf8');
-    assert.ok(raw.endsWith('\n'), 'file must end with a newline character');
-  });
-
-  it('always writes to {workspace}/hal/config/{skillName}.json', () => {
-    hal.saveSkillConfig('location-check', tmpDir, { ok: true });
-    const expected = path.join(tmpDir, 'hal', 'config', 'location-check.json');
-    assert.ok(fs.existsSync(expected), `file must be at ${expected}`);
-  });
-});