feat: orchestration harness, selective install, observer improvements

tests/lib/install-config.test.js

@@ -0,0 +1,117 @@
+/**
+ * Tests for scripts/lib/install/config.js
+ */
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const {
+  loadInstallConfig,
+  resolveInstallConfigPath,
+} = require('../../scripts/lib/install/config');
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  \u2713 ${name}`);
+    return true;
+  } catch (error) {
+    console.log(`  \u2717 ${name}`);
+    console.log(`    Error: ${error.message}`);
+    return false;
+  }
+}
+
+function createTempDir(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+function cleanup(dirPath) {
+  fs.rmSync(dirPath, { recursive: true, force: true });
+}
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(value, null, 2));
+}
+
+function runTests() {
+  console.log('\n=== Testing install/config.js ===\n');
+
+  let passed = 0;
+  let failed = 0;
+
+  if (test('resolves relative config paths from the provided cwd', () => {
+    const cwd = '/workspace/app';
+    const resolved = resolveInstallConfigPath('configs/ecc-install.json', { cwd });
+    assert.strictEqual(resolved, path.join(cwd, 'configs', 'ecc-install.json'));
+  })) passed++; else failed++;
+
+  if (test('loads and normalizes a valid install config', () => {
+    const cwd = createTempDir('install-config-');
+
+    try {
+      const configPath = path.join(cwd, 'ecc-install.json');
+      writeJson(configPath, {
+        version: 1,
+        target: 'cursor',
+        profile: 'developer',
+        modules: ['platform-configs', 'platform-configs'],
+        include: ['lang:typescript', 'framework:nextjs', 'lang:typescript'],
+        exclude: ['capability:media'],
+        options: {
+          includeExamples: false,
+        },
+      });
+
+      const config = loadInstallConfig('ecc-install.json', { cwd });
+      assert.strictEqual(config.path, configPath);
+      assert.strictEqual(config.target, 'cursor');
+      assert.strictEqual(config.profileId, 'developer');
+      assert.deepStrictEqual(config.moduleIds, ['platform-configs']);
+      assert.deepStrictEqual(config.includeComponentIds, ['lang:typescript', 'framework:nextjs']);
+      assert.deepStrictEqual(config.excludeComponentIds, ['capability:media']);
+      assert.deepStrictEqual(config.options, { includeExamples: false });
+    } finally {
+      cleanup(cwd);
+    }
+  })) passed++; else failed++;
+
+  if (test('rejects invalid config schema values', () => {
+    const cwd = createTempDir('install-config-');
+
+    try {
+      writeJson(path.join(cwd, 'ecc-install.json'), {
+        version: 2,
+        target: 'ghost-target',
+      });
+
+      assert.throws(
+        () => loadInstallConfig('ecc-install.json', { cwd }),
+        /Invalid install config/
+      );
+    } finally {
+      cleanup(cwd);
+    }
+  })) passed++; else failed++;
+
+  if (test('fails when the install config does not exist', () => {
+    const cwd = createTempDir('install-config-');
+
+    try {
+      assert.throws(
+        () => loadInstallConfig('ecc-install.json', { cwd }),
+        /Install config not found/
+      );
+    } finally {
+      cleanup(cwd);
+    }
+  })) passed++; else failed++;
+
+  console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+runTests();

tests/lib/install-lifecycle.test.js

@@ -0,0 +1,357 @@
+/**
+ * Tests for scripts/lib/install-lifecycle.js
+ */
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const {
+  buildDoctorReport,
+  discoverInstalledStates,
+} = require('../../scripts/lib/install-lifecycle');
+const {
+  createInstallState,
+  writeInstallState,
+} = require('../../scripts/lib/install-state');
+
+const REPO_ROOT = path.join(__dirname, '..', '..');
+const CURRENT_PACKAGE_VERSION = JSON.parse(
+  fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8')
+).version;
+const CURRENT_MANIFEST_VERSION = JSON.parse(
+  fs.readFileSync(path.join(REPO_ROOT, 'manifests', 'install-modules.json'), 'utf8')
+).version;
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  \u2713 ${name}`);
+    return true;
+  } catch (error) {
+    console.log(`  \u2717 ${name}`);
+    console.log(`    Error: ${error.message}`);
+    return false;
+  }
+}
+
+function createTempDir(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+function cleanup(dirPath) {
+  fs.rmSync(dirPath, { recursive: true, force: true });
+}
+
+function writeState(filePath, options) {
+  const state = createInstallState(options);
+  writeInstallState(filePath, state);
+  return state;
+}
+
+function runTests() {
+  console.log('\n=== Testing install-lifecycle.js ===\n');
+
+  let passed = 0;
+  let failed = 0;
+
+  if (test('discovers installed states for multiple targets in the current context', () => {
+    const homeDir = createTempDir('install-lifecycle-home-');
+    const projectRoot = createTempDir('install-lifecycle-project-');
+
+    try {
+      const claudeStatePath = path.join(homeDir, '.claude', 'ecc', 'install-state.json');
+      const cursorStatePath = path.join(projectRoot, '.cursor', 'ecc-install-state.json');
+
+      writeState(claudeStatePath, {
+        adapter: { id: 'claude-home', target: 'claude', kind: 'home' },
+        targetRoot: path.join(homeDir, '.claude'),
+        installStatePath: claudeStatePath,
+        request: {
+          profile: null,
+          modules: [],
+          legacyLanguages: ['typescript'],
+          legacyMode: true,
+        },
+        resolution: {
+          selectedModules: ['legacy-claude-rules'],
+          skippedModules: [],
+        },
+        operations: [],
+        source: {
+          repoVersion: CURRENT_PACKAGE_VERSION,
+          repoCommit: 'abc123',
+          manifestVersion: CURRENT_MANIFEST_VERSION,
+        },
+      });
+
+      writeState(cursorStatePath, {
+        adapter: { id: 'cursor-project', target: 'cursor', kind: 'project' },
+        targetRoot: path.join(projectRoot, '.cursor'),
+        installStatePath: cursorStatePath,
+        request: {
+          profile: 'core',
+          modules: [],
+          legacyLanguages: [],
+          legacyMode: false,
+        },
+        resolution: {
+          selectedModules: ['rules-core', 'platform-configs'],
+          skippedModules: [],
+        },
+        operations: [],
+        source: {
+          repoVersion: CURRENT_PACKAGE_VERSION,
+          repoCommit: 'def456',
+          manifestVersion: CURRENT_MANIFEST_VERSION,
+        },
+      });
+
+      const records = discoverInstalledStates({
+        homeDir,
+        projectRoot,
+        targets: ['claude', 'cursor'],
+      });
+
+      assert.strictEqual(records.length, 2);
+      assert.strictEqual(records[0].exists, true);
+      assert.strictEqual(records[1].exists, true);
+      assert.strictEqual(records[0].state.target.id, 'claude-home');
+      assert.strictEqual(records[1].state.target.id, 'cursor-project');
+    } finally {
+      cleanup(homeDir);
+      cleanup(projectRoot);
+    }
+  })) passed++; else failed++;
+
+  if (test('doctor reports missing managed files as an error', () => {
+    const homeDir = createTempDir('install-lifecycle-home-');
+    const projectRoot = createTempDir('install-lifecycle-project-');
+
+    try {
+      const targetRoot = path.join(projectRoot, '.cursor');
+      const statePath = path.join(targetRoot, 'ecc-install-state.json');
+      fs.mkdirSync(targetRoot, { recursive: true });
+
+      writeState(statePath, {
+        adapter: { id: 'cursor-project', target: 'cursor', kind: 'project' },
+        targetRoot,
+        installStatePath: statePath,
+        request: {
+          profile: null,
+          modules: ['platform-configs'],
+          legacyLanguages: [],
+          legacyMode: false,
+        },
+        resolution: {
+          selectedModules: ['platform-configs'],
+          skippedModules: [],
+        },
+        operations: [
+          {
+            kind: 'copy-file',
+            moduleId: 'platform-configs',
+            sourceRelativePath: '.cursor/hooks.json',
+            destinationPath: path.join(targetRoot, 'hooks.json'),
+            strategy: 'sync-root-children',
+            ownership: 'managed',
+            scaffoldOnly: false,
+          },
+        ],
+        source: {
+          repoVersion: CURRENT_PACKAGE_VERSION,
+          repoCommit: 'abc123',
+          manifestVersion: CURRENT_MANIFEST_VERSION,
+        },
+      });
+
+      const report = buildDoctorReport({
+        repoRoot: REPO_ROOT,
+        homeDir,
+        projectRoot,
+        targets: ['cursor'],
+      });
+
+      assert.strictEqual(report.results.length, 1);
+      assert.strictEqual(report.results[0].status, 'error');
+      assert.ok(report.results[0].issues.some(issue => issue.code === 'missing-managed-files'));
+    } finally {
+      cleanup(homeDir);
+      cleanup(projectRoot);
+    }
+  })) passed++; else failed++;
+
+  if (test('doctor reports a healthy legacy install when managed files are present', () => {
+    const homeDir = createTempDir('install-lifecycle-home-');
+    const projectRoot = createTempDir('install-lifecycle-project-');
+
+    try {
+      const targetRoot = path.join(homeDir, '.claude');
+      const statePath = path.join(targetRoot, 'ecc', 'install-state.json');
+      const managedFile = path.join(targetRoot, 'rules', 'common', 'coding-style.md');
+      const sourceContent = fs.readFileSync(path.join(REPO_ROOT, 'rules', 'common', 'coding-style.md'), 'utf8');
+      fs.mkdirSync(path.dirname(managedFile), { recursive: true });
+      fs.writeFileSync(managedFile, sourceContent);
+
+      writeState(statePath, {
+        adapter: { id: 'claude-home', target: 'claude', kind: 'home' },
+        targetRoot,
+        installStatePath: statePath,
+        request: {
+          profile: null,
+          modules: [],
+          legacyLanguages: ['typescript'],
+          legacyMode: true,
+        },
+        resolution: {
+          selectedModules: ['legacy-claude-rules'],
+          skippedModules: [],
+        },
+        operations: [
+          {
+            kind: 'copy-file',
+            moduleId: 'legacy-claude-rules',
+            sourceRelativePath: 'rules/common/coding-style.md',
+            destinationPath: managedFile,
+            strategy: 'preserve-relative-path',
+            ownership: 'managed',
+            scaffoldOnly: false,
+          },
+        ],
+        source: {
+          repoVersion: CURRENT_PACKAGE_VERSION,
+          repoCommit: 'abc123',
+          manifestVersion: CURRENT_MANIFEST_VERSION,
+        },
+      });
+
+      const report = buildDoctorReport({
+        repoRoot: REPO_ROOT,
+        homeDir,
+        projectRoot,
+        targets: ['claude'],
+      });
+
+      assert.strictEqual(report.results.length, 1);
+      assert.strictEqual(report.results[0].status, 'ok');
+      assert.strictEqual(report.results[0].issues.length, 0);
+    } finally {
+      cleanup(homeDir);
+      cleanup(projectRoot);
+    }
+  })) passed++; else failed++;
+
+  if (test('doctor reports drifted managed files as a warning', () => {
+    const homeDir = createTempDir('install-lifecycle-home-');
+    const projectRoot = createTempDir('install-lifecycle-project-');
+
+    try {
+      const targetRoot = path.join(projectRoot, '.cursor');
+      const statePath = path.join(targetRoot, 'ecc-install-state.json');
+      const sourcePath = path.join(REPO_ROOT, '.cursor', 'hooks.json');
+      const destinationPath = path.join(targetRoot, 'hooks.json');
+      fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+      fs.writeFileSync(destinationPath, '{"drifted":true}\n');
+
+      writeState(statePath, {
+        adapter: { id: 'cursor-project', target: 'cursor', kind: 'project' },
+        targetRoot,
+        installStatePath: statePath,
+        request: {
+          profile: null,
+          modules: ['platform-configs'],
+          legacyLanguages: [],
+          legacyMode: false,
+        },
+        resolution: {
+          selectedModules: ['platform-configs'],
+          skippedModules: [],
+        },
+        operations: [
+          {
+            kind: 'copy-file',
+            moduleId: 'platform-configs',
+            sourcePath,
+            sourceRelativePath: '.cursor/hooks.json',
+            destinationPath,
+            strategy: 'sync-root-children',
+            ownership: 'managed',
+            scaffoldOnly: false,
+          },
+        ],
+        source: {
+          repoVersion: CURRENT_PACKAGE_VERSION,
+          repoCommit: 'abc123',
+          manifestVersion: CURRENT_MANIFEST_VERSION,
+        },
+      });
+
+      const report = buildDoctorReport({
+        repoRoot: REPO_ROOT,
+        homeDir,
+        projectRoot,
+        targets: ['cursor'],
+      });
+
+      assert.strictEqual(report.results.length, 1);
+      assert.strictEqual(report.results[0].status, 'warning');
+      assert.ok(report.results[0].issues.some(issue => issue.code === 'drifted-managed-files'));
+    } finally {
+      cleanup(homeDir);
+      cleanup(projectRoot);
+    }
+  })) passed++; else failed++;
+
+  if (test('doctor reports manifest resolution drift for non-legacy installs', () => {
+    const homeDir = createTempDir('install-lifecycle-home-');
+    const projectRoot = createTempDir('install-lifecycle-project-');
+
+    try {
+      const targetRoot = path.join(projectRoot, '.cursor');
+      const statePath = path.join(targetRoot, 'ecc-install-state.json');
+      fs.mkdirSync(targetRoot, { recursive: true });
+
+      writeState(statePath, {
+        adapter: { id: 'cursor-project', target: 'cursor', kind: 'project' },
+        targetRoot,
+        installStatePath: statePath,
+        request: {
+          profile: 'core',
+          modules: [],
+          legacyLanguages: [],
+          legacyMode: false,
+        },
+        resolution: {
+          selectedModules: ['rules-core'],
+          skippedModules: [],
+        },
+        operations: [],
+        source: {
+          repoVersion: CURRENT_PACKAGE_VERSION,
+          repoCommit: 'abc123',
+          manifestVersion: CURRENT_MANIFEST_VERSION,
+        },
+      });
+
+      const report = buildDoctorReport({
+        repoRoot: REPO_ROOT,
+        homeDir,
+        projectRoot,
+        targets: ['cursor'],
+      });
+
+      assert.strictEqual(report.results.length, 1);
+      assert.strictEqual(report.results[0].status, 'warning');
+      assert.ok(report.results[0].issues.some(issue => issue.code === 'resolution-drift'));
+    } finally {
+      cleanup(homeDir);
+      cleanup(projectRoot);
+    }
+  })) passed++; else failed++;
+
+  console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+runTests();

tests/lib/install-manifests.test.js

@@ -0,0 +1,196 @@
+/**
+ * Tests for scripts/lib/install-manifests.js
+ */
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const {
+  loadInstallManifests,
+  listInstallComponents,
+  listInstallModules,
+  listInstallProfiles,
+  resolveInstallPlan,
+} = require('../../scripts/lib/install-manifests');
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  \u2713 ${name}`);
+    return true;
+  } catch (error) {
+    console.log(`  \u2717 ${name}`);
+    console.log(`    Error: ${error.message}`);
+    return false;
+  }
+}
+
+function createTestRepo() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'install-manifests-'));
+  fs.mkdirSync(path.join(root, 'manifests'), { recursive: true });
+  return root;
+}
+
+function cleanupTestRepo(root) {
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(value, null, 2));
+}
+
+function runTests() {
+  console.log('\n=== Testing install-manifests.js ===\n');
+
+  let passed = 0;
+  let failed = 0;
+
+  if (test('loads real project install manifests', () => {
+    const manifests = loadInstallManifests();
+    assert.ok(manifests.modules.length >= 1, 'Should load modules');
+    assert.ok(Object.keys(manifests.profiles).length >= 1, 'Should load profiles');
+    assert.ok(manifests.components.length >= 1, 'Should load components');
+  })) passed++; else failed++;
+
+  if (test('lists install profiles from the real project', () => {
+    const profiles = listInstallProfiles();
+    assert.ok(profiles.some(profile => profile.id === 'core'), 'Should include core profile');
+    assert.ok(profiles.some(profile => profile.id === 'full'), 'Should include full profile');
+  })) passed++; else failed++;
+
+  if (test('lists install modules from the real project', () => {
+    const modules = listInstallModules();
+    assert.ok(modules.some(module => module.id === 'rules-core'), 'Should include rules-core');
+    assert.ok(modules.some(module => module.id === 'orchestration'), 'Should include orchestration');
+  })) passed++; else failed++;
+
+  if (test('lists install components from the real project', () => {
+    const components = listInstallComponents();
+    assert.ok(components.some(component => component.id === 'lang:typescript'),
+      'Should include lang:typescript');
+    assert.ok(components.some(component => component.id === 'capability:security'),
+      'Should include capability:security');
+  })) passed++; else failed++;
+
+  if (test('resolves a real project profile with target-specific skips', () => {
+    const projectRoot = '/workspace/app';
+    const plan = resolveInstallPlan({ profileId: 'developer', target: 'cursor', projectRoot });
+    assert.ok(plan.selectedModuleIds.includes('rules-core'), 'Should keep rules-core');
+    assert.ok(plan.selectedModuleIds.includes('commands-core'), 'Should keep commands-core');
+    assert.ok(!plan.selectedModuleIds.includes('orchestration'),
+      'Should not select unsupported orchestration module for cursor');
+    assert.ok(plan.skippedModuleIds.includes('orchestration'),
+      'Should report unsupported orchestration module as skipped');
+    assert.strictEqual(plan.targetAdapterId, 'cursor-project');
+    assert.strictEqual(plan.targetRoot, path.join(projectRoot, '.cursor'));
+    assert.strictEqual(plan.installStatePath, path.join(projectRoot, '.cursor', 'ecc-install-state.json'));
+    assert.ok(plan.operations.length > 0, 'Should include scaffold operations');
+    assert.ok(
+      plan.operations.some(operation => (
+        operation.sourceRelativePath === '.cursor'
+        && operation.strategy === 'sync-root-children'
+      )),
+      'Should flatten the native cursor root'
+    );
+  })) passed++; else failed++;
+
+  if (test('resolves explicit modules with dependency expansion', () => {
+    const plan = resolveInstallPlan({ moduleIds: ['security'] });
+    assert.ok(plan.selectedModuleIds.includes('security'), 'Should include requested module');
+    assert.ok(plan.selectedModuleIds.includes('workflow-quality'),
+      'Should include transitive dependency');
+    assert.ok(plan.selectedModuleIds.includes('platform-configs'),
+      'Should include nested dependency');
+  })) passed++; else failed++;
+
+  if (test('resolves included and excluded user-facing components', () => {
+    const plan = resolveInstallPlan({
+      profileId: 'core',
+      includeComponentIds: ['capability:security'],
+      excludeComponentIds: ['capability:orchestration'],
+      target: 'claude',
+    });
+
+    assert.deepStrictEqual(plan.includedComponentIds, ['capability:security']);
+    assert.deepStrictEqual(plan.excludedComponentIds, ['capability:orchestration']);
+    assert.ok(plan.selectedModuleIds.includes('security'), 'Should include modules from selected components');
+    assert.ok(!plan.selectedModuleIds.includes('orchestration'), 'Should exclude modules from excluded components');
+    assert.ok(plan.excludedModuleIds.includes('orchestration'),
+      'Should report modules removed by excluded components');
+  })) passed++; else failed++;
+
+  if (test('fails when a selected component depends on an excluded component module', () => {
+    assert.throws(
+      () => resolveInstallPlan({
+        includeComponentIds: ['capability:social'],
+        excludeComponentIds: ['capability:content'],
+      }),
+      /depends on excluded module business-content/
+    );
+  })) passed++; else failed++;
+
+  if (test('throws on unknown install profile', () => {
+    assert.throws(
+      () => resolveInstallPlan({ profileId: 'ghost-profile' }),
+      /Unknown install profile/
+    );
+  })) passed++; else failed++;
+
+  if (test('throws on unknown install target', () => {
+    assert.throws(
+      () => resolveInstallPlan({ profileId: 'core', target: 'not-a-target' }),
+      /Unknown install target/
+    );
+  })) passed++; else failed++;
+
+  if (test('throws when a dependency does not support the requested target', () => {
+    const repoRoot = createTestRepo();
+    writeJson(path.join(repoRoot, 'manifests', 'install-modules.json'), {
+      version: 1,
+      modules: [
+        {
+          id: 'parent',
+          kind: 'skills',
+          description: 'Parent',
+          paths: ['parent'],
+          targets: ['claude'],
+          dependencies: ['child'],
+          defaultInstall: false,
+          cost: 'light',
+          stability: 'stable'
+        },
+        {
+          id: 'child',
+          kind: 'skills',
+          description: 'Child',
+          paths: ['child'],
+          targets: ['cursor'],
+          dependencies: [],
+          defaultInstall: false,
+          cost: 'light',
+          stability: 'stable'
+        }
+      ]
+    });
+    writeJson(path.join(repoRoot, 'manifests', 'install-profiles.json'), {
+      version: 1,
+      profiles: {
+        core: { description: 'Core', modules: ['parent'] }
+      }
+    });
+
+    assert.throws(
+      () => resolveInstallPlan({ repoRoot, profileId: 'core', target: 'claude' }),
+      /does not support target claude/
+    );
+    cleanupTestRepo(repoRoot);
+  })) passed++; else failed++;
+
+  console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+runTests();

tests/lib/install-request.test.js

@@ -0,0 +1,147 @@
+/**
+ * Tests for scripts/lib/install/request.js
+ */
+
+const assert = require('assert');
+
+const {
+  normalizeInstallRequest,
+  parseInstallArgs,
+} = require('../../scripts/lib/install/request');
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  \u2713 ${name}`);
+    return true;
+  } catch (error) {
+    console.log(`  \u2717 ${name}`);
+    console.log(`    Error: ${error.message}`);
+    return false;
+  }
+}
+
+function runTests() {
+  console.log('\n=== Testing install/request.js ===\n');
+
+  let passed = 0;
+  let failed = 0;
+
+  if (test('parses manifest-mode CLI arguments', () => {
+    const parsed = parseInstallArgs([
+      'node',
+      'scripts/install-apply.js',
+      '--target', 'cursor',
+      '--profile', 'developer',
+      '--with', 'lang:typescript',
+      '--without', 'capability:media',
+      '--config', 'ecc-install.json',
+      '--dry-run',
+      '--json'
+    ]);
+
+    assert.strictEqual(parsed.target, 'cursor');
+    assert.strictEqual(parsed.profileId, 'developer');
+    assert.strictEqual(parsed.configPath, 'ecc-install.json');
+    assert.deepStrictEqual(parsed.includeComponentIds, ['lang:typescript']);
+    assert.deepStrictEqual(parsed.excludeComponentIds, ['capability:media']);
+    assert.strictEqual(parsed.dryRun, true);
+    assert.strictEqual(parsed.json, true);
+    assert.deepStrictEqual(parsed.languages, []);
+  })) passed++; else failed++;
+
+  if (test('normalizes legacy language installs into a canonical request', () => {
+    const request = normalizeInstallRequest({
+      target: 'claude',
+      profileId: null,
+      moduleIds: [],
+      languages: ['typescript', 'python']
+    });
+
+    assert.strictEqual(request.mode, 'legacy');
+    assert.strictEqual(request.target, 'claude');
+    assert.deepStrictEqual(request.languages, ['typescript', 'python']);
+    assert.deepStrictEqual(request.moduleIds, []);
+    assert.strictEqual(request.profileId, null);
+  })) passed++; else failed++;
+
+  if (test('normalizes manifest installs into a canonical request', () => {
+    const request = normalizeInstallRequest({
+      target: 'cursor',
+      profileId: 'developer',
+      moduleIds: [],
+      includeComponentIds: ['lang:typescript'],
+      excludeComponentIds: ['capability:media'],
+      languages: []
+    });
+
+    assert.strictEqual(request.mode, 'manifest');
+    assert.strictEqual(request.target, 'cursor');
+    assert.strictEqual(request.profileId, 'developer');
+    assert.deepStrictEqual(request.includeComponentIds, ['lang:typescript']);
+    assert.deepStrictEqual(request.excludeComponentIds, ['capability:media']);
+    assert.deepStrictEqual(request.languages, []);
+  })) passed++; else failed++;
+
+  if (test('merges config-backed component selections with CLI overrides', () => {
+    const request = normalizeInstallRequest({
+      target: 'cursor',
+      profileId: null,
+      moduleIds: ['platform-configs'],
+      includeComponentIds: ['framework:nextjs'],
+      excludeComponentIds: ['capability:media'],
+      languages: [],
+      configPath: '/workspace/app/ecc-install.json',
+      config: {
+        path: '/workspace/app/ecc-install.json',
+        target: 'claude',
+        profileId: 'developer',
+        moduleIds: ['workflow-quality'],
+        includeComponentIds: ['lang:typescript'],
+        excludeComponentIds: ['capability:orchestration'],
+      },
+    });
+
+    assert.strictEqual(request.mode, 'manifest');
+    assert.strictEqual(request.target, 'cursor');
+    assert.strictEqual(request.profileId, 'developer');
+    assert.deepStrictEqual(request.moduleIds, ['workflow-quality', 'platform-configs']);
+    assert.deepStrictEqual(request.includeComponentIds, ['lang:typescript', 'framework:nextjs']);
+    assert.deepStrictEqual(request.excludeComponentIds, ['capability:orchestration', 'capability:media']);
+    assert.strictEqual(request.configPath, '/workspace/app/ecc-install.json');
+  })) passed++; else failed++;
+
+  if (test('rejects mixing legacy languages with manifest flags', () => {
+    assert.throws(
+      () => normalizeInstallRequest({
+        target: 'claude',
+        profileId: 'core',
+        moduleIds: [],
+        includeComponentIds: [],
+        excludeComponentIds: [],
+        languages: ['typescript']
+      }),
+      /cannot be combined/
+    );
+  })) passed++; else failed++;
+
+  if (test('rejects empty install requests when not asking for help', () => {
+    assert.throws(
+      () => normalizeInstallRequest({
+        target: 'claude',
+        profileId: null,
+        moduleIds: [],
+        includeComponentIds: [],
+        excludeComponentIds: [],
+        languages: [],
+        help: false
+      }),
+      /No install profile, module IDs, included components, or legacy languages/
+    );
+  })) passed++; else failed++;
+
+  console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+runTests();

tests/lib/install-state.test.js

@@ -0,0 +1,139 @@
+/**
+ * Tests for scripts/lib/install-state.js
+ */
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const {
+  createInstallState,
+  readInstallState,
+  writeInstallState,
+} = require('../../scripts/lib/install-state');
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  \u2713 ${name}`);
+    return true;
+  } catch (error) {
+    console.log(`  \u2717 ${name}`);
+    console.log(`    Error: ${error.message}`);
+    return false;
+  }
+}
+
+function createTestDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'install-state-'));
+}
+
+function cleanupTestDir(dirPath) {
+  fs.rmSync(dirPath, { recursive: true, force: true });
+}
+
+function runTests() {
+  console.log('\n=== Testing install-state.js ===\n');
+
+  let passed = 0;
+  let failed = 0;
+
+  if (test('creates a valid install-state payload', () => {
+    const state = createInstallState({
+      adapter: { id: 'cursor-project' },
+      targetRoot: '/repo/.cursor',
+      installStatePath: '/repo/.cursor/ecc-install-state.json',
+      request: {
+        profile: 'developer',
+        modules: ['orchestration'],
+        legacyLanguages: ['typescript'],
+        legacyMode: true,
+      },
+      resolution: {
+        selectedModules: ['rules-core', 'orchestration'],
+        skippedModules: [],
+      },
+      operations: [
+        {
+          kind: 'copy-path',
+          moduleId: 'rules-core',
+          sourceRelativePath: 'rules',
+          destinationPath: '/repo/.cursor/rules',
+          strategy: 'preserve-relative-path',
+          ownership: 'managed',
+          scaffoldOnly: true,
+        },
+      ],
+      source: {
+        repoVersion: '1.9.0',
+        repoCommit: 'abc123',
+        manifestVersion: 1,
+      },
+      installedAt: '2026-03-13T00:00:00Z',
+    });
+
+    assert.strictEqual(state.schemaVersion, 'ecc.install.v1');
+    assert.strictEqual(state.target.id, 'cursor-project');
+    assert.strictEqual(state.request.profile, 'developer');
+    assert.strictEqual(state.operations.length, 1);
+  })) passed++; else failed++;
+
+  if (test('writes and reads install-state from disk', () => {
+    const testDir = createTestDir();
+    const statePath = path.join(testDir, 'ecc-install-state.json');
+
+    try {
+      const state = createInstallState({
+        adapter: { id: 'claude-home' },
+        targetRoot: path.join(testDir, '.claude'),
+        installStatePath: statePath,
+        request: {
+          profile: 'core',
+          modules: [],
+          legacyLanguages: [],
+          legacyMode: false,
+        },
+        resolution: {
+          selectedModules: ['rules-core'],
+          skippedModules: [],
+        },
+        operations: [],
+        source: {
+          repoVersion: '1.9.0',
+          repoCommit: 'abc123',
+          manifestVersion: 1,
+        },
+      });
+
+      writeInstallState(statePath, state);
+      const loaded = readInstallState(statePath);
+
+      assert.strictEqual(loaded.target.id, 'claude-home');
+      assert.strictEqual(loaded.request.profile, 'core');
+      assert.deepStrictEqual(loaded.resolution.selectedModules, ['rules-core']);
+    } finally {
+      cleanupTestDir(testDir);
+    }
+  })) passed++; else failed++;
+
+  if (test('rejects invalid install-state payloads on read', () => {
+    const testDir = createTestDir();
+    const statePath = path.join(testDir, 'ecc-install-state.json');
+
+    try {
+      fs.writeFileSync(statePath, JSON.stringify({ schemaVersion: 'ecc.install.v1' }, null, 2));
+      assert.throws(
+        () => readInstallState(statePath),
+        /Invalid install-state/
+      );
+    } finally {
+      cleanupTestDir(testDir);
+    }
+  })) passed++; else failed++;
+
+  console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+runTests();

tests/lib/install-targets.test.js

@@ -0,0 +1,110 @@
+/**
+ * Tests for scripts/lib/install-targets/registry.js
+ */
+
+const assert = require('assert');
+const path = require('path');
+
+const {
+  getInstallTargetAdapter,
+  listInstallTargetAdapters,
+  planInstallTargetScaffold,
+} = require('../../scripts/lib/install-targets/registry');
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  \u2713 ${name}`);
+    return true;
+  } catch (error) {
+    console.log(`  \u2717 ${name}`);
+    console.log(`    Error: ${error.message}`);
+    return false;
+  }
+}
+
+function runTests() {
+  console.log('\n=== Testing install-target adapters ===\n');
+
+  let passed = 0;
+  let failed = 0;
+
+  if (test('lists supported target adapters', () => {
+    const adapters = listInstallTargetAdapters();
+    const targets = adapters.map(adapter => adapter.target);
+    assert.ok(targets.includes('claude'), 'Should include claude target');
+    assert.ok(targets.includes('cursor'), 'Should include cursor target');
+    assert.ok(targets.includes('antigravity'), 'Should include antigravity target');
+    assert.ok(targets.includes('codex'), 'Should include codex target');
+    assert.ok(targets.includes('opencode'), 'Should include opencode target');
+  })) passed++; else failed++;
+
+  if (test('resolves cursor adapter root and install-state path from project root', () => {
+    const adapter = getInstallTargetAdapter('cursor');
+    const projectRoot = '/workspace/app';
+    const root = adapter.resolveRoot({ projectRoot });
+    const statePath = adapter.getInstallStatePath({ projectRoot });
+
+    assert.strictEqual(root, path.join(projectRoot, '.cursor'));
+    assert.strictEqual(statePath, path.join(projectRoot, '.cursor', 'ecc-install-state.json'));
+  })) passed++; else failed++;
+
+  if (test('resolves claude adapter root and install-state path from home dir', () => {
+    const adapter = getInstallTargetAdapter('claude');
+    const homeDir = '/Users/example';
+    const root = adapter.resolveRoot({ homeDir, repoRoot: '/repo/ecc' });
+    const statePath = adapter.getInstallStatePath({ homeDir, repoRoot: '/repo/ecc' });
+
+    assert.strictEqual(root, path.join(homeDir, '.claude'));
+    assert.strictEqual(statePath, path.join(homeDir, '.claude', 'ecc', 'install-state.json'));
+  })) passed++; else failed++;
+
+  if (test('plans scaffold operations and flattens native target roots', () => {
+    const repoRoot = '/repo/ecc';
+    const projectRoot = '/workspace/app';
+    const modules = [
+      {
+        id: 'platform-configs',
+        paths: ['.cursor', 'mcp-configs'],
+      },
+      {
+        id: 'rules-core',
+        paths: ['rules'],
+      },
+    ];
+
+    const plan = planInstallTargetScaffold({
+      target: 'cursor',
+      repoRoot,
+      projectRoot,
+      modules,
+    });
+
+    assert.strictEqual(plan.adapter.id, 'cursor-project');
+    assert.strictEqual(plan.targetRoot, path.join(projectRoot, '.cursor'));
+    assert.strictEqual(plan.installStatePath, path.join(projectRoot, '.cursor', 'ecc-install-state.json'));
+
+    const flattened = plan.operations.find(operation => operation.sourceRelativePath === '.cursor');
+    const preserved = plan.operations.find(operation => operation.sourceRelativePath === 'rules');
+
+    assert.ok(flattened, 'Should include .cursor scaffold operation');
+    assert.strictEqual(flattened.strategy, 'sync-root-children');
+    assert.strictEqual(flattened.destinationPath, path.join(projectRoot, '.cursor'));
+
+    assert.ok(preserved, 'Should include rules scaffold operation');
+    assert.strictEqual(preserved.strategy, 'preserve-relative-path');
+    assert.strictEqual(preserved.destinationPath, path.join(projectRoot, '.cursor', 'rules'));
+  })) passed++; else failed++;
+
+  if (test('throws on unknown target adapter', () => {
+    assert.throws(
+      () => getInstallTargetAdapter('ghost-target'),
+      /Unknown install target adapter/
+    );
+  })) passed++; else failed++;
+
+  console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+runTests();

tests/lib/orchestration-session.test.js

@@ -7,6 +7,7 @@ const path = require('path');
 
 const {
   buildSessionSnapshot,
+  listTmuxPanes,
   loadWorkerSnapshots,
   parseWorkerHandoff,
   parseWorkerStatus,
@@ -186,6 +187,16 @@ test('buildSessionSnapshot merges tmux panes with worker metadata', () => {
   }
 });
 
+test('listTmuxPanes returns an empty array when tmux is unavailable', () => {
+  const panes = listTmuxPanes('workflow-visual-proof', {
+    spawnSyncImpl: () => ({
+      error: Object.assign(new Error('tmux not found'), { code: 'ENOENT' })
+    })
+  });
+
+  assert.deepStrictEqual(panes, []);
+});
+
 test('resolveSnapshotTarget handles plan files and direct session names', () => {
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-orch-target-'));
   const repoRoot = path.join(tempRoot, 'repo');

tests/lib/session-adapters.test.js

@@ -0,0 +1,214 @@
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { createClaudeHistoryAdapter } = require('../../scripts/lib/session-adapters/claude-history');
+const { createDmuxTmuxAdapter } = require('../../scripts/lib/session-adapters/dmux-tmux');
+const { createAdapterRegistry } = require('../../scripts/lib/session-adapters/registry');
+
+console.log('=== Testing session-adapters ===\n');
+
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  ✓ ${name}`);
+    passed += 1;
+  } catch (error) {
+    console.log(`  ✗ ${name}: ${error.message}`);
+    failed += 1;
+  }
+}
+
+function withHome(homeDir, fn) {
+  const previousHome = process.env.HOME;
+  process.env.HOME = homeDir;
+
+  try {
+    fn();
+  } finally {
+    if (typeof previousHome === 'string') {
+      process.env.HOME = previousHome;
+    } else {
+      delete process.env.HOME;
+    }
+  }
+}
+
+test('dmux adapter normalizes orchestration snapshots into canonical form', () => {
+  const adapter = createDmuxTmuxAdapter({
+    collectSessionSnapshotImpl: () => ({
+      sessionName: 'workflow-visual-proof',
+      coordinationDir: '/tmp/.claude/orchestration/workflow-visual-proof',
+      repoRoot: '/tmp/repo',
+      targetType: 'plan',
+      sessionActive: true,
+      paneCount: 1,
+      workerCount: 1,
+      workerStates: { running: 1 },
+      panes: [{
+        paneId: '%95',
+        windowIndex: 1,
+        paneIndex: 0,
+        title: 'seed-check',
+        currentCommand: 'codex',
+        currentPath: '/tmp/worktree',
+        active: false,
+        dead: false,
+        pid: 1234
+      }],
+      workers: [{
+        workerSlug: 'seed-check',
+        workerDir: '/tmp/.claude/orchestration/workflow-visual-proof/seed-check',
+        status: {
+          state: 'running',
+          updated: '2026-03-13T00:00:00Z',
+          branch: 'feature/seed-check',
+          worktree: '/tmp/worktree',
+          taskFile: '/tmp/task.md',
+          handoffFile: '/tmp/handoff.md'
+        },
+        task: {
+          objective: 'Inspect seeded files.',
+          seedPaths: ['scripts/orchestrate-worktrees.js']
+        },
+        handoff: {
+          summary: ['Pending'],
+          validation: [],
+          remainingRisks: ['No screenshot yet']
+        },
+        files: {
+          status: '/tmp/status.md',
+          task: '/tmp/task.md',
+          handoff: '/tmp/handoff.md'
+        },
+        pane: {
+          paneId: '%95',
+          title: 'seed-check'
+        }
+      }]
+    })
+  });
+
+  const snapshot = adapter.open('workflow-visual-proof').getSnapshot();
+
+  assert.strictEqual(snapshot.schemaVersion, 'ecc.session.v1');
+  assert.strictEqual(snapshot.adapterId, 'dmux-tmux');
+  assert.strictEqual(snapshot.session.id, 'workflow-visual-proof');
+  assert.strictEqual(snapshot.session.kind, 'orchestrated');
+  assert.strictEqual(snapshot.session.sourceTarget.type, 'session');
+  assert.strictEqual(snapshot.aggregates.workerCount, 1);
+  assert.strictEqual(snapshot.workers[0].runtime.kind, 'tmux-pane');
+  assert.strictEqual(snapshot.workers[0].outputs.remainingRisks[0], 'No screenshot yet');
+});
+
+test('claude-history adapter loads the latest recorded session', () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-session-adapter-home-'));
+  const sessionsDir = path.join(homeDir, '.claude', 'sessions');
+  fs.mkdirSync(sessionsDir, { recursive: true });
+
+  const sessionPath = path.join(sessionsDir, '2026-03-13-a1b2c3d4-session.tmp');
+  fs.writeFileSync(sessionPath, [
+    '# Session Review',
+    '',
+    '**Date:** 2026-03-13',
+    '**Started:** 09:00',
+    '**Last Updated:** 11:30',
+    '**Project:** everything-claude-code',
+    '**Branch:** feat/session-adapter',
+    '**Worktree:** /tmp/ecc-worktree',
+    '',
+    '### Completed',
+    '- [x] Build snapshot prototype',
+    '',
+    '### In Progress',
+    '- [ ] Add CLI wrapper',
+    '',
+    '### Notes for Next Session',
+    'Need a second adapter.',
+    '',
+    '### Context to Load',
+    '```',
+    'scripts/lib/orchestration-session.js',
+    '```'
+  ].join('\n'));
+
+  try {
+    withHome(homeDir, () => {
+      const adapter = createClaudeHistoryAdapter();
+      const snapshot = adapter.open('claude:latest').getSnapshot();
+
+      assert.strictEqual(snapshot.schemaVersion, 'ecc.session.v1');
+      assert.strictEqual(snapshot.adapterId, 'claude-history');
+      assert.strictEqual(snapshot.session.kind, 'history');
+      assert.strictEqual(snapshot.session.state, 'recorded');
+      assert.strictEqual(snapshot.workers.length, 1);
+      assert.strictEqual(snapshot.workers[0].branch, 'feat/session-adapter');
+      assert.strictEqual(snapshot.workers[0].worktree, '/tmp/ecc-worktree');
+      assert.strictEqual(snapshot.workers[0].runtime.kind, 'claude-session');
+      assert.strictEqual(snapshot.workers[0].artifacts.sessionFile, sessionPath);
+      assert.ok(snapshot.workers[0].outputs.summary.includes('Build snapshot prototype'));
+    });
+  } finally {
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  }
+});
+
+test('adapter registry routes plan files to dmux and explicit claude targets to history', () => {
+  const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-session-registry-repo-'));
+  const planPath = path.join(repoRoot, 'workflow.json');
+  fs.writeFileSync(planPath, JSON.stringify({
+    sessionName: 'workflow-visual-proof',
+    repoRoot,
+    coordinationRoot: path.join(repoRoot, '.claude', 'orchestration')
+  }));
+
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-session-registry-home-'));
+  const sessionsDir = path.join(homeDir, '.claude', 'sessions');
+  fs.mkdirSync(sessionsDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(sessionsDir, '2026-03-13-z9y8x7w6-session.tmp'),
+    '# History Session\n\n**Branch:** feat/history\n'
+  );
+
+  try {
+    withHome(homeDir, () => {
+      const registry = createAdapterRegistry({
+        adapters: [
+          createDmuxTmuxAdapter({
+            collectSessionSnapshotImpl: () => ({
+              sessionName: 'workflow-visual-proof',
+              coordinationDir: path.join(repoRoot, '.claude', 'orchestration', 'workflow-visual-proof'),
+              repoRoot,
+              targetType: 'plan',
+              sessionActive: false,
+              paneCount: 0,
+              workerCount: 0,
+              workerStates: {},
+              panes: [],
+              workers: []
+            })
+          }),
+          createClaudeHistoryAdapter()
+        ]
+      });
+
+      const dmuxSnapshot = registry.open(planPath, { cwd: repoRoot }).getSnapshot();
+      const claudeSnapshot = registry.open('claude:latest', { cwd: repoRoot }).getSnapshot();
+
+      assert.strictEqual(dmuxSnapshot.adapterId, 'dmux-tmux');
+      assert.strictEqual(claudeSnapshot.adapterId, 'claude-history');
+    });
+  } finally {
+    fs.rmSync(repoRoot, { recursive: true, force: true });
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  }
+});
+
+console.log(`\n=== Results: ${passed} passed, ${failed} failed ===`);
+if (failed > 0) process.exit(1);