@polderlabs/bizar 4.5.2 → 4.7.1

package/bizar-dash/tests/backup-store.test.mjs

@@ -0,0 +1,300 @@
+/**
+ * tests/backup-store.test.mjs
+ *
+ * v4.8.0 — Tests for the backup-store module.
+ */
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  mkdirSync,
+  rmSync,
+  writeFileSync,
+  existsSync,
+  readFileSync,
+  readdirSync,
+} from 'node:fs';
+
+const BACKUP_STORE = await import('../src/server/backup-store.mjs').then((m) => m);
+
+describe('backup-store', () => {
+  let backupRoot;
+  let configDir;
+  let opencodeDir;
+  let memoryDir;
+
+  beforeEach(() => {
+    const id = `bizar-backup-test-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    backupRoot = join(tmpdir(), id, 'backups');
+    configDir = join(tmpdir(), id, 'config', 'bizar');
+    opencodeDir = join(tmpdir(), id, 'config', 'opencode');
+    memoryDir = join(tmpdir(), id, 'local', 'share', 'bizar', 'memory');
+
+    mkdirSync(configDir, { recursive: true });
+    mkdirSync(opencodeDir, { recursive: true });
+    mkdirSync(memoryDir, { recursive: true });
+    mkdirSync(backupRoot, { recursive: true });
+
+    // Create some test files
+    writeFileSync(join(configDir, 'settings.json'), JSON.stringify({ theme: { mode: 'dark' } }), { mode: 0o600 });
+    writeFileSync(join(opencodeDir, 'opencode.json'), JSON.stringify({ models: [] }), { mode: 0o600 });
+    writeFileSync(join(memoryDir, 'test.md'), '# Test memory', { mode: 0o600 });
+  });
+
+  afterEach(() => {
+    try { rmSync(backupRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+    try { rmSync(join(tmpdir(), `bizar-backup-test-${Date.now()}-${Math.random().toString(36).slice(2)}`), { recursive: true, force: true }); } catch { /* ignore */ }
+  });
+
+  // ── createBackup ─────────────────────────────────────────────────────────────
+
+  describe('createBackup', () => {
+    it('creates a timestamped backup directory', async () => {
+      const result = await BACKUP_STORE.createBackup({ outDir: backupRoot });
+      assert.strictEqual(result.ok, true);
+      assert.ok(result.path.includes('bizar-'));
+      assert.ok(existsSync(result.path));
+    });
+
+    it('writes a manifest.json with version, createdAt, and paths', async () => {
+      const result = await BACKUP_STORE.createBackup({ outDir: backupRoot });
+      const manifestPath = join(result.path, 'manifest.json');
+      assert.ok(existsSync(manifestPath));
+      const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+      assert.ok(manifest.version);
+      assert.ok(manifest.createdAt);
+      assert.ok(Array.isArray(manifest.paths));
+    });
+
+    it('copies existing files to the backup', async () => {
+      const result = await BACKUP_STORE.createBackup({ outDir: backupRoot });
+      const configBackup = join(result.path, 'config');
+      assert.ok(existsSync(configBackup));
+      const settingsBackup = join(configBackup, 'settings.json');
+      assert.ok(existsSync(settingsBackup));
+    });
+
+    it('skips non-existent optional paths', async () => {
+      const result = await BACKUP_STORE.createBackup({ outDir: backupRoot });
+      const manifestPath = join(result.path, 'manifest.json');
+      const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+      // Optional paths that don't exist should be in skipped list
+      assert.ok(manifest.skipped);
+    });
+
+    it('respects custom label in name and manifest', async () => {
+      const result = await BACKUP_STORE.createBackup({ outDir: backupRoot, label: 'test-label' });
+      assert.ok(result.path.includes('test-label'));
+      const manifest = JSON.parse(readFileSync(join(result.path, 'manifest.json'), 'utf8'));
+      assert.strictEqual(manifest.label, 'test-label');
+    });
+
+    it('returns sizeBytes and durationMs', async () => {
+      const result = await BACKUP_STORE.createBackup({ outDir: backupRoot });
+      assert.ok(typeof result.sizeBytes === 'number');
+      assert.ok(result.sizeBytes >= 0);
+      assert.ok(typeof result.durationMs === 'number');
+      assert.ok(result.durationMs >= 0);
+    });
+  });
+
+  // ── listBackups ──────────────────────────────────────────────────────────────
+
+  describe('listBackups', () => {
+    it('returns empty array when no backups exist', async () => {
+      const emptyDir = join(tmpdir(), `bizar-empty-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+      mkdirSync(emptyDir, { recursive: true });
+      try {
+        const backups = await BACKUP_STORE.listBackups({ inDir: emptyDir });
+        assert.strictEqual(backups.length, 0);
+      } finally {
+        rmSync(emptyDir, { recursive: true, force: true });
+      }
+    });
+
+    it('returns all backups sorted newest-first', async () => {
+      await BACKUP_STORE.createBackup({ outDir: backupRoot });
+      await BACKUP_STORE.createBackup({ outDir: backupRoot, label: 'second' });
+      const backups = await BACKUP_STORE.listBackups({ inDir: backupRoot });
+      assert.strictEqual(backups.length, 2);
+      assert.strictEqual(backups[0].manifest?.label, 'second');
+      assert.strictEqual(backups[1].manifest?.label, null);
+    });
+
+    it('includes createdAt, sizeBytes, sizeFormatted, and manifest', async () => {
+      await BACKUP_STORE.createBackup({ outDir: backupRoot });
+      const backups = await BACKUP_STORE.listBackups({ inDir: backupRoot });
+      assert.ok(backups[0].createdAt);
+      assert.ok(typeof backups[0].sizeBytes === 'number');
+      assert.ok(typeof backups[0].sizeFormatted === 'string');
+      assert.ok(backups[0].manifest);
+    });
+  });
+
+  // ── restoreBackup (dryRun) ───────────────────────────────────────────────────
+
+  describe('restoreBackup (dryRun)', () => {
+    it('does not modify any files when dryRun is true', async () => {
+      const result = await BACKUP_STORE.createBackup({ outDir: backupRoot });
+      const settingsFile = join(configDir, 'settings.json');
+      const originalContent = readFileSync(settingsFile, 'utf8');
+      // Modify the settings file
+      writeFileSync(settingsFile, JSON.stringify({ theme: { mode: 'light' } }), { mode: 0o600 });
+      const restoreResult = await BACKUP_STORE.restoreBackup({
+        backupPath: result.path,
+        dryRun: true,
+        conflictStrategy: 'overwrite',
+      });
+      assert.strictEqual(restoreResult.ok, true);
+      // File should still have the modified content
+      assert.strictEqual(readFileSync(settingsFile, 'utf8'), JSON.stringify({ theme: { mode: 'light' } }));
+    });
+
+    it('reports what would be restored in dryRun mode', async () => {
+      const result = await BACKUP_STORE.createBackup({ outDir: backupRoot });
+      const restoreResult = await BACKUP_STORE.restoreBackup({
+        backupPath: result.path,
+        dryRun: true,
+        conflictStrategy: 'merge',
+      });
+      assert.ok(restoreResult.restored.length > 0);
+    });
+  });
+
+  // ── restoreBackup (overwrite) ────────────────────────────────────────────────
+
+  describe('restoreBackup (overwrite)', () => {
+    it('reports overwritten entries when conflictStrategy is overwrite (dryRun)', async () => {
+      const result = await BACKUP_STORE.createBackup({ outDir: backupRoot });
+      // dryRun=true means no actual overwrite happens, but we can verify
+      // the restored list includes the backed-up entries
+      const restoreResult = await BACKUP_STORE.restoreBackup({
+        backupPath: result.path,
+        dryRun: true,
+        conflictStrategy: 'overwrite',
+      });
+      assert.strictEqual(restoreResult.ok, true);
+      // In dryRun mode, entries that would be overwritten are listed in restored
+      assert.ok(restoreResult.restored.length > 0);
+    });
+
+    it('overwrites a manually-created backup correctly', async () => {
+      // Create a manual backup structure with project-state label (which is in PROJECT_BACKUP_PATHS)
+      const testBackupDir = join(backupRoot, 'bizar-test-overwrite-manual');
+      const testProjectRoot = join(tmpdir(), `backup-overwrite-test-${Date.now()}`);
+      mkdirSync(testBackupDir, { recursive: true });
+      mkdirSync(testProjectRoot, { recursive: true });
+      mkdirSync(join(testBackupDir, 'project-state'), { recursive: true });
+
+      // Write original content to backup
+      const originalContent = { theme: { mode: 'dark' } };
+      writeFileSync(join(testBackupDir, 'project-state', 'state.json'), JSON.stringify(originalContent), { mode: 0o600 });
+      // Use new manifest format with {label, src} objects
+      writeFileSync(
+        join(testBackupDir, 'manifest.json'),
+        JSON.stringify({
+          version: '1.0.0',
+          createdAt: new Date().toISOString(),
+          paths: [{ label: 'project-state', src: '.bizar/' }],
+        }),
+        { mode: 0o600 },
+      );
+
+      // Restore with overwrite — project-state is in PROJECT_BACKUP_PATHS, so it will restore
+      const restoreResult = await BACKUP_STORE.restoreBackup({
+        backupPath: testBackupDir,
+        dryRun: false,
+        conflictStrategy: 'overwrite',
+        projectRoot: testProjectRoot,
+      });
+      // The entry should be restored (it's in PROJECT_BACKUP_PATHS)
+      assert.ok(restoreResult.ok);
+
+      // Cleanup
+      rmSync(testProjectRoot, { recursive: true, force: true });
+    });
+  });
+
+  // ── verifyBackup ─────────────────────────────────────────────────────────────
+
+  describe('verifyBackup', () => {
+    it('returns ok=true for a valid backup', async () => {
+      const result = await BACKUP_STORE.createBackup({ outDir: backupRoot });
+      const verifyResult = await BACKUP_STORE.verifyBackup({ backupPath: result.path });
+      assert.strictEqual(verifyResult.ok, true);
+      assert.strictEqual(verifyResult.issues.length, 0);
+    });
+
+    it('returns ok=false when manifest is missing', async () => {
+      const backupDir = join(backupRoot, 'bizar-test-no-manifest');
+      mkdirSync(backupDir, { recursive: true });
+      writeFileSync(join(backupDir, 'somefile.txt'), 'test', { mode: 0o600 });
+      const verifyResult = await BACKUP_STORE.verifyBackup({ backupPath: backupDir });
+      assert.strictEqual(verifyResult.ok, false);
+      assert.ok(verifyResult.issues.length > 0);
+    });
+
+    it('detects missing backup entries', async () => {
+      const result = await BACKUP_STORE.createBackup({ outDir: backupRoot });
+      // Remove a backed-up directory
+      rmSync(join(result.path, 'config'), { recursive: true, force: true });
+      const verifyResult = await BACKUP_STORE.verifyBackup({ backupPath: result.path });
+      assert.strictEqual(verifyResult.ok, false);
+      assert.ok(verifyResult.issues.some((i) => i.includes('config')));
+    });
+
+    it('returns ok=false when backup directory does not exist', async () => {
+      const verifyResult = await BACKUP_STORE.verifyBackup({
+        backupPath: join(tmpdir(), 'nonexistent-backup-path'),
+      });
+      assert.strictEqual(verifyResult.ok, false);
+    });
+  });
+
+  // ── deleteBackup ─────────────────────────────────────────────────────────────
+
+  describe('deleteBackup', () => {
+    it('removes the backup directory', async () => {
+      const result = await BACKUP_STORE.createBackup({ outDir: backupRoot });
+      assert.ok(existsSync(result.path));
+      const deleteResult = await BACKUP_STORE.deleteBackup({ backupPath: result.path });
+      assert.strictEqual(deleteResult.ok, true);
+      assert.ok(!existsSync(result.path));
+    });
+
+    it('returns ok=false when backup does not exist', async () => {
+      const deleteResult = await BACKUP_STORE.deleteBackup({
+        backupPath: join(tmpdir(), 'nonexistent-backup-path'),
+      });
+      assert.strictEqual(deleteResult.ok, false);
+      assert.ok(deleteResult.error);
+    });
+  });
+
+  // ── getManifest ──────────────────────────────────────────────────────────────
+
+  describe('getManifest', () => {
+    it('returns manifest when backup exists', async () => {
+      const result = await BACKUP_STORE.createBackup({ outDir: backupRoot });
+      const manifestResult = await BACKUP_STORE.getManifest({ backupPath: result.path });
+      assert.strictEqual(manifestResult.ok, true);
+      assert.ok(manifestResult.manifest);
+      assert.ok(manifestResult.manifest.version);
+    });
+
+    it('returns ok=false when manifest is missing', async () => {
+      const backupDir = join(backupRoot, 'bizar-no-manifest');
+      mkdirSync(backupDir, { recursive: true });
+      const manifestResult = await BACKUP_STORE.getManifest({ backupPath: backupDir });
+      assert.strictEqual(manifestResult.ok, false);
+    });
+
+    it('returns ok=false when backup does not exist', async () => {
+      const manifestResult = await BACKUP_STORE.getManifest({
+        backupPath: join(tmpdir(), 'nonexistent'),
+      });
+      assert.strictEqual(manifestResult.ok, false);
+    });
+  });
+});

package/bizar-dash/tests/cli-bugfixes.test.mjs

@@ -20,7 +20,7 @@ const REPO = join(process.cwd());
 describe('B1 — parseWithModsFlag', () => {
   it('exits with code 2 when --with-mods is the last arg', async () => {
     // Import fresh each time to avoid module-level side effects
-    const { parseWithModsFlag } = await import('../../cli/bin.mjs');
+    const { parseWithModsFlag } = await import('../../cli/commands/install.mjs');
     let exitCode = null;
     const origExit = process.exit;
     // Mock process.exit to capture the code without terminating the test
@@ -36,7 +36,7 @@ describe('B1 — parseWithModsFlag', () => {
   });
 
   it('exits with code 2 when next arg is another flag', async () => {
-    const { parseWithModsFlag } = await import('../../cli/bin.mjs');
+    const { parseWithModsFlag } = await import('../../cli/commands/install.mjs');
     let exitCode = null;
     const origExit = process.exit;
     try {
@@ -51,7 +51,7 @@ describe('B1 — parseWithModsFlag', () => {
   });
 
   it('returns null when --with-mods is not present', async () => {
-    const { parseWithModsFlag } = await import('../../cli/bin.mjs');
+    const { parseWithModsFlag } = await import('../../cli/commands/install.mjs');
     let exitCode = null;
     const origExit = process.exit;
     try {
@@ -65,7 +65,7 @@ describe('B1 — parseWithModsFlag', () => {
   });
 
   it('returns array of mod ids when value is provided', async () => {
-    const { parseWithModsFlag } = await import('../../cli/bin.mjs');
+    const { parseWithModsFlag } = await import('../../cli/commands/install.mjs');
     let exitCode = null;
     const origExit = process.exit;
     try {

package/bizar-dash/tests/cli-error-visibility.test.mjs

@@ -0,0 +1,153 @@
+/**
+ * bizar-dash/tests/cli-error-visibility.test.mjs
+ *
+ * v4.7.1 — CLI silent error visibility fixes.
+ *
+ * Verifies:
+ *   1. importCommand() failure produces a visible error message
+ *   2. `bizar help` shows help text (not "Unknown command")
+ *   3. `bizar --help` shows help text
+ *   4. `bizar` (no command) shows help text
+ *
+ * Run with: node --test bizar-dash/tests/cli-error-visibility.test.mjs
+ */
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// __dirname = .../BizarHarness/bizar-dash/tests  →  .../BizarHarness/cli
+const CLI_ROOT = resolve(__dirname, '..', '..', 'cli');
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Run the CLI as a subprocess and capture stdout + stderr.
+ * Uses spawnSync for reliable synchronous capture.
+ * Returns { code, stdout, stderr }.
+ */
+function runBizar(args, env = {}) {
+  const binPath = resolve(CLI_ROOT, 'bin.mjs');
+  const result = spawnSync('node', [binPath, ...args], {
+    env: { ...process.env, BIZAR_SKIP_INSTALL: '1', ...env },
+    timeout: 10000,
+    encoding: 'utf8',
+  });
+  return {
+    code: result.status,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+  };
+}
+
+// ── importCommand() failure ───────────────────────────────────────────────────
+
+describe('importCommand() failure produces visible error', () => {
+  test('non-existent command prints "Unknown command", not silent exit', () => {
+    const { code, stdout, stderr } = runBizar(['this-command-does-not-exist-xyz']);
+    const combined = stdout + stderr;
+    // Should exit with error code
+    assert.notStrictEqual(code, 0, `should exit non-zero, got ${code}`);
+    // Should NOT be silent
+    assert.ok(combined.length > 0, `should produce output, not silent. stdout=${stdout.length}, stderr=${stderr.length}`);
+    // Should mention the unknown command
+    assert.ok(
+      combined.includes('Unknown command') || combined.includes('this-command-does-not-exist-xyz'),
+      `output should mention Unknown command or the command name, got: ${combined.slice(0, 200)}`,
+    );
+  });
+
+  test('broken command module logs error to stderr (not silent)', () => {
+    // The bin.mjs importCommand catch now logs to console.error.
+    // We verify stderr is non-empty when a command fails to load.
+    const { stderr } = runBizar(['this-command-does-not-exist-xyz']);
+    assert.ok(stderr.length > 0, `stderr should not be empty when command fails. stderr=${JSON.stringify(stderr.slice(0, 100))}`);
+  });
+});
+
+// ── `bizar help` alias ─────────────────────────────────────────────────────────
+
+describe('`bizar help` alias', () => {
+  test('`bizar help` shows help text, not "Unknown command"', () => {
+    const { code, stdout, stderr } = runBizar(['help']);
+    const combined = stdout + stderr;
+    assert.strictEqual(code, 0, `should exit with 0, got ${code}. stderr: ${stderr.slice(0, 300)}`);
+    assert.ok(
+      combined.includes('Usage:') && combined.includes('bizar'),
+      `should show help usage, got: ${combined.slice(0, 300)}`,
+    );
+    assert.ok(
+      !combined.includes('Unknown command'),
+      `should NOT say "Unknown command", got: ${combined.slice(0, 300)}`,
+    );
+  });
+});
+
+// ── `bizar --help` ─────────────────────────────────────────────────────────────
+
+describe('`bizar --help`', () => {
+  test('`bizar --help` shows help text', () => {
+    const { code, stdout, stderr } = runBizar(['--help']);
+    const combined = stdout + stderr;
+    assert.strictEqual(code, 0, `should exit with 0, got ${code}. stderr: ${stderr.slice(0, 300)}`);
+    assert.ok(
+      combined.includes('Usage:') && combined.includes('bizar'),
+      `should show help usage, got: ${combined.slice(0, 300)}`,
+    );
+  });
+
+  test('`bizar -h` shows help text', () => {
+    const { code, stdout, stderr } = runBizar(['-h']);
+    const combined = stdout + stderr;
+    assert.strictEqual(code, 0, `should exit with 0, got ${code}. stderr: ${stderr.slice(0, 300)}`);
+    assert.ok(
+      combined.includes('Usage:') && combined.includes('bizar'),
+      `should show help usage, got: ${combined.slice(0, 300)}`,
+    );
+  });
+});
+
+// ── `bizar` (no command) ───────────────────────────────────────────────────────
+
+describe('`bizar` with no command', () => {
+  test('`bizar` with no args shows help text', () => {
+    const { code, stdout, stderr } = runBizar([]);
+    const combined = stdout + stderr;
+    assert.strictEqual(code, 0, `should exit with 0, got ${code}. stderr: ${stderr.slice(0, 300)}`);
+    assert.ok(
+      combined.includes('Usage:') && combined.includes('bizar'),
+      `should show help usage, got: ${combined.slice(0, 300)}`,
+    );
+    assert.ok(
+      !combined.includes('Unknown command'),
+      `should NOT say "Unknown command", got: ${combined.slice(0, 300)}`,
+    );
+  });
+});
+
+// ── Defensive null checks on import ───────────────────────────────────────────
+
+describe('command module null-check produces user-visible error', () => {
+  test('bin.mjs has null checks after importCommand in all case branches', async () => {
+    const binSrc = await import('fs').then((fs) =>
+      fs.promises.readFile(resolve(CLI_ROOT, 'bin.mjs'), 'utf8'),
+    );
+    // Count `if (!mod)` checks that follow `importCommand`
+    const nullCheckCount = (binSrc.match(/if \(!mod\)/g) || []).length;
+    // We have 9 case groups that call importCommand: install/update, service, dash,
+    // minimax, headroom, mod, artifact, memory, usage, and util (utility commands)
+    assert.ok(
+      nullCheckCount >= 9,
+      `Expected at least 9 null checks after importCommand, found ${nullCheckCount}`,
+    );
+    // Also verify each has a user-visible error message
+    const errorMsgCount = (binSrc.match(/Could not load .+ command module/g) || []).length;
+    assert.ok(
+      errorMsgCount >= 9,
+      `Expected at least 9 user-visible error messages for failed loads, found ${errorMsgCount}`,
+    );
+  });
+});

package/bizar-dash/tests/cli-refactor.test.mjs

@@ -0,0 +1,184 @@
+/**
+ * bizar-dash/tests/cli-refactor.test.mjs
+ *
+ * v4.6 — CLI refactor tests.
+ *
+ * Verifies:
+ *   1. cli/bin.mjs imports from cli/commands/*.mjs correctly
+ *   2. Each command module exports a `run` function
+ *   3. cli/utils.mjs exports `which()` and `bizarConfigDir()`
+ *   4. cli/artifact-cli.mjs, cli/artifact-server.mjs, cli/artifact-render.mjs
+ *      exist and export the right things
+ *   5. cli/artifact.mjs is a backward-compatible re-export shell
+ */
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readdirSync } from 'node:fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CLI_ROOT = resolve(__dirname, '..', '..', 'cli');
+const COMMANDS_DIR = resolve(CLI_ROOT, 'commands');
+
+// ── utils.mjs ────────────────────────────────────────────────────────────────
+
+describe('cli/utils.mjs exports', () => {
+  test('exports which()', async () => {
+    const { which } = await import(`${CLI_ROOT}/utils.mjs`);
+    assert.equal(typeof which, 'function');
+  });
+
+  test('exports whichPath()', async () => {
+    const { whichPath } = await import(`${CLI_ROOT}/utils.mjs`);
+    assert.equal(typeof whichPath, 'function');
+  });
+
+  test('exports bizarConfigDir()', async () => {
+    const { bizarConfigDir } = await import(`${CLI_ROOT}/utils.mjs`);
+    assert.equal(typeof bizarConfigDir, 'function');
+  });
+
+  test('bizarConfigDir() returns a non-empty string', async () => {
+    const { bizarConfigDir } = await import(`${CLI_ROOT}/utils.mjs`);
+    const dir = bizarConfigDir();
+    assert.equal(typeof dir, 'string');
+    assert.ok(dir.length > 0);
+    assert.ok(dir.includes('bizar'));
+  });
+
+  test('which() returns boolean', async () => {
+    const { which } = await import(`${CLI_ROOT}/utils.mjs`);
+    const result = which('node');
+    assert.equal(typeof result, 'boolean');
+  });
+
+  test('which() returns false for nonexistent command', async () => {
+    const { which } = await import(`${CLI_ROOT}/utils.mjs`);
+    const result = which('this-command-does-not-exist-xyz');
+    assert.equal(result, false);
+  });
+
+  test('whichPath() returns null for nonexistent command', async () => {
+    const { whichPath } = await import(`${CLI_ROOT}/utils.mjs`);
+    const result = whichPath('this-command-does-not-exist-xyz');
+    assert.equal(result, null);
+  });
+});
+
+// ── Command modules ────────────────────────────────────────────────────────────
+
+const COMMAND_FILES = [
+  'install',
+  'service',
+  'dash',
+  'minimax',
+  'headroom',
+  'mod',
+  'artifact',
+  'memory',
+  'usage',
+  'util',
+];
+
+describe('cli/commands/*.mjs exports', () => {
+  for (const name of COMMAND_FILES) {
+    test(`${name}.mjs exports run()`, async () => {
+      const mod = await import(`${COMMANDS_DIR}/${name}.mjs`);
+      assert.equal(typeof mod.run, 'function', `${name}.mjs should export run()`);
+    });
+
+    // Note: calling run() directly would execute the command (network calls, etc.)
+    // which is not appropriate in a module structure test. The run() signature
+    // is validated via TypeScript / node --check instead.
+  }
+});
+
+// ── Artifact split ────────────────────────────────────────────────────────────
+
+describe('artifact module split', () => {
+  test('artifact-cli.mjs exists and exports runArtifact', async () => {
+    const mod = await import(`${CLI_ROOT}/artifact-cli.mjs`);
+    assert.equal(typeof mod.runArtifact, 'function');
+    assert.equal(typeof mod.default, 'function');
+  });
+
+  test('artifact-cli.mjs exports showHelp', async () => {
+    const mod = await import(`${CLI_ROOT}/artifact-cli.mjs`);
+    assert.equal(typeof mod.showHelp, 'function');
+  });
+
+  test('artifact-cli.mjs exports regenerateHtml', async () => {
+    const mod = await import(`${CLI_ROOT}/artifact-cli.mjs`);
+    assert.equal(typeof mod.regenerateHtml, 'function');
+  });
+
+  test('artifact-server.mjs exists and exports startServer', async () => {
+    const mod = await import(`${CLI_ROOT}/artifact-server.mjs`);
+    assert.equal(typeof mod.startServer, 'function');
+  });
+
+  test('artifact-render.mjs exports CANVAS_SCHEMA_VERSION', async () => {
+    const mod = await import(`${CLI_ROOT}/artifact-render.mjs`);
+    assert.equal(mod.CANVAS_SCHEMA_VERSION, 2);
+  });
+
+  test('artifact-render.mjs exports canvas helpers', async () => {
+    const mod = await import(`${CLI_ROOT}/artifact-render.mjs`);
+    assert.equal(typeof mod.emptyCanvas, 'function');
+    assert.equal(typeof mod.readCanvasFile, 'function');
+    assert.equal(typeof mod.writeCanvasFile, 'function');
+    assert.equal(typeof mod.loadOrMigrateCanvas, 'function');
+    assert.equal(typeof mod.canvasToMarkdown, 'function');
+  });
+
+  test('artifact-render.mjs exports ID generators', async () => {
+    const mod = await import(`${CLI_ROOT}/artifact-render.mjs`);
+    assert.equal(typeof mod.makeElementId, 'function');
+    assert.equal(typeof mod.makeConnectionId, 'function');
+    assert.equal(typeof mod.makeCommentId, 'function');
+    assert.equal(typeof mod.makeReplyId, 'function');
+  });
+
+  test('artifact-render.mjs exports HTML renderers', async () => {
+    const mod = await import(`${CLI_ROOT}/artifact-render.mjs`);
+    assert.equal(typeof mod.renderElementHTML, 'function');
+    assert.equal(typeof mod.renderConnectionHTML, 'function');
+    assert.equal(typeof mod.renderCommentPinHTML, 'function');
+    assert.equal(typeof mod.escapeHtml, 'function');
+    assert.equal(typeof mod.formatDate, 'function');
+  });
+
+  test('artifact.mjs is a re-export shell (backward compat)', async () => {
+    const mod = await import(`${CLI_ROOT}/artifact.mjs`);
+    // Should re-export runArtifact
+    assert.equal(typeof mod.runArtifact, 'function');
+    // Should re-export runPlan as alias for runArtifact (backward compat)
+    assert.equal(typeof mod.runPlan, 'function');
+    // Should re-export startServer
+    assert.equal(typeof mod.startServer, 'function');
+    // Should re-export canvas helpers
+    assert.equal(typeof mod.emptyCanvas, 'function');
+    assert.equal(typeof mod.canvasToMarkdown, 'function');
+    // Should re-export render helpers
+    assert.equal(typeof mod.renderElementHTML, 'function');
+    assert.equal(typeof mod.escapeHtml, 'function');
+    // Should re-export regenerateHtml
+    assert.equal(typeof mod.regenerateHtml, 'function');
+  });
+});
+
+// ── bin.mjs structure ─────────────────────────────────────────────────────────
+
+describe('cli/bin.mjs structure', () => {
+  test('bin.mjs is a valid ESM module', async () => {
+    // Just verify it can be parsed as ESM — don't run main()
+    const { readFileSync } = await import('node:fs');
+    const src = readFileSync(`${CLI_ROOT}/bin.mjs`, 'utf8');
+    assert.ok(src.includes('#!/usr/bin/env node'));
+    assert.ok(src.includes('export'));
+    assert.ok(src.includes('import'));
+  });
+});
+
+console.log('  cli-refactor.test.mjs loaded — run with: node --test bizar-dash/tests/cli-refactor.test.mjs');