@jamaynor/hal-config 1.0.1

package/test/config-io.test.js

@@ -0,0 +1,326 @@
+/**
+ * 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}`);
+  });
+});