kadi-deploy 0.19.0

package/tests/lock.test.ts

@@ -0,0 +1,1148 @@
+/**
+ * Deployment Lock File Tests (v3 — multi-instance)
+ *
+ * Tests for the `.kadi-deploy.lock` file management:
+ * - writeLockFile / readLockFile round-trip (v3 format)
+ * - Multi-instance per profile behavior
+ * - removeDeployment / getDeployment / getDeploymentByInstance / getDeploymentsByProfile / listDeployments
+ * - v1 → v3 migration
+ * - v2 → v3 migration
+ * - buildLocalLock / buildAkashLock convenience builders
+ * - instanceId generation and collision avoidance
+ * - Validation of malformed lock files
+ * - Missing file handling
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+import {
+  LOCK_VERSION,
+  LOCK_FILENAME,
+  lockFilePath,
+  writeLockFile,
+  readLockFile,
+  deleteLockFile,
+  removeDeployment,
+  getDeployment,
+  getDeploymentByInstance,
+  getDeploymentsByProfile,
+  listDeployments,
+  migrateV1toV2,
+  migrateV1toV3,
+  migrateV2toV3,
+  generateInstanceId,
+  deploymentKey,
+  parseDeploymentKey,
+  buildLocalLock,
+  buildAkashLock,
+  type DeploymentLock,
+  type LockFile,
+  type LocalDeploymentLock,
+  type AkashDeploymentLock,
+} from '../src/commands/lock.js';
+
+// ─────────────────────────────────────────────────────────
+// Fixtures
+// ─────────────────────────────────────────────────────────
+
+const LOCAL_ENTRY: DeploymentLock = {
+  instanceId: 'a1b2',
+  target: 'local',
+  profile: 'dev',
+  deployedAt: '2026-02-25T12:00:00.000Z',
+  local: {
+    composePath: '/tmp/test-project/docker-compose.yml',
+    engine: 'docker',
+    network: 'kadi-net',
+    services: ['web', 'api'],
+    containers: { web: 'abc123', api: 'def456' },
+  },
+};
+
+const AKASH_ENTRY: DeploymentLock = {
+  instanceId: 'c3d4',
+  target: 'akash',
+  profile: 'production',
+  deployedAt: '2026-02-25T12:00:00.000Z',
+  akash: {
+    dseq: 12345678,
+    owner: 'akash1abc123def456',
+    provider: 'akash1provider789',
+    providerUri: 'https://provider.example.com',
+    network: 'mainnet',
+    gseq: 1,
+    oseq: 1,
+  },
+};
+
+// ─────────────────────────────────────────────────────────
+// Test helpers
+// ─────────────────────────────────────────────────────────
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'kadi-deploy-lock-test-'));
+});
+
+afterEach(async () => {
+  try {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  } catch {
+    // ignore cleanup errors
+  }
+});
+
+// ─────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────
+
+describe('constants', () => {
+  it('LOCK_VERSION is 3', () => {
+    expect(LOCK_VERSION).toBe(3);
+  });
+
+  it('LOCK_FILENAME is .kadi-deploy.lock', () => {
+    expect(LOCK_FILENAME).toBe('.kadi-deploy.lock');
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// lockFilePath
+// ─────────────────────────────────────────────────────────
+
+describe('lockFilePath', () => {
+  it('returns the correct path', () => {
+    expect(lockFilePath('/my/project')).toBe(
+      path.join('/my/project', LOCK_FILENAME)
+    );
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// writeLockFile + readLockFile round-trip (v2)
+// ─────────────────────────────────────────────────────────
+
+describe('writeLockFile + readLockFile', () => {
+  it('round-trips a local deployment entry', async () => {
+    await writeLockFile(tmpDir, LOCAL_ENTRY);
+    const lockFile = await readLockFile(tmpDir);
+
+    expect(lockFile).not.toBeNull();
+    expect(lockFile!.version).toBe(LOCK_VERSION);
+
+    const entries = Object.values(lockFile!.deployments);
+    expect(entries).toHaveLength(1);
+
+    const entry = entries[0];
+    expect(entry.target).toBe('local');
+    expect(entry.profile).toBe('dev');
+    expect(entry.instanceId).toBe('a1b2');
+    expect(entry.local).toBeDefined();
+    expect(entry.local!.engine).toBe('docker');
+    expect(entry.local!.services).toEqual(['web', 'api']);
+    expect(entry.local!.containers).toEqual({ web: 'abc123', api: 'def456' });
+    expect(entry.local!.composePath).toBe('/tmp/test-project/docker-compose.yml');
+    expect(entry.local!.network).toBe('kadi-net');
+  });
+
+  it('round-trips an Akash deployment entry', async () => {
+    await writeLockFile(tmpDir, AKASH_ENTRY);
+    const lockFile = await readLockFile(tmpDir);
+
+    expect(lockFile).not.toBeNull();
+    expect(lockFile!.version).toBe(LOCK_VERSION);
+
+    const entries = Object.values(lockFile!.deployments);
+    expect(entries).toHaveLength(1);
+
+    const entry = entries[0];
+    expect(entry.target).toBe('akash');
+    expect(entry.profile).toBe('production');
+    expect(entry.instanceId).toBe('c3d4');
+    expect(entry.akash).toBeDefined();
+    expect(entry.akash!.dseq).toBe(12345678);
+    expect(entry.akash!.owner).toBe('akash1abc123def456');
+    expect(entry.akash!.provider).toBe('akash1provider789');
+    expect(entry.akash!.providerUri).toBe('https://provider.example.com');
+    expect(entry.akash!.network).toBe('mainnet');
+    expect(entry.akash!.gseq).toBe(1);
+    expect(entry.akash!.oseq).toBe(1);
+  });
+
+  it('preserves deployedAt as ISO string', async () => {
+    await writeLockFile(tmpDir, AKASH_ENTRY);
+    const lockFile = await readLockFile(tmpDir);
+    const entry = Object.values(lockFile!.deployments)[0];
+    expect(entry.deployedAt).toBe('2026-02-25T12:00:00.000Z');
+  });
+
+  it('writes valid JSON with trailing newline', async () => {
+    await writeLockFile(tmpDir, LOCAL_ENTRY);
+    const raw = await fs.readFile(lockFilePath(tmpDir), 'utf-8');
+    expect(raw.endsWith('\n')).toBe(true);
+    expect(() => JSON.parse(raw)).not.toThrow();
+  });
+
+  it('writes v3 format with version and deployments map', async () => {
+    await writeLockFile(tmpDir, LOCAL_ENTRY);
+    const raw = await fs.readFile(lockFilePath(tmpDir), 'utf-8');
+    const data = JSON.parse(raw);
+    expect(data.version).toBe(3);
+    expect(data.deployments).toBeDefined();
+    expect(typeof data.deployments).toBe('object');
+  });
+
+  it('uses composite key {profile}:{instanceId}', async () => {
+    await writeLockFile(tmpDir, LOCAL_ENTRY);
+    const raw = await fs.readFile(lockFilePath(tmpDir), 'utf-8');
+    const data = JSON.parse(raw);
+    const keys = Object.keys(data.deployments);
+    expect(keys).toEqual(['dev:a1b2']);
+  });
+
+  it('returns instanceId from writeLockFile', async () => {
+    const instanceId = await writeLockFile(tmpDir, LOCAL_ENTRY);
+    expect(instanceId).toBe('a1b2');
+  });
+
+  it('generates instanceId when not provided', async () => {
+    const entry: DeploymentLock = {
+      instanceId: '', // empty — should be auto-generated
+      target: 'local',
+      profile: 'test',
+      deployedAt: '2026-02-25T12:00:00.000Z',
+      local: LOCAL_ENTRY.local,
+    };
+    const instanceId = await writeLockFile(tmpDir, entry);
+    expect(instanceId).toHaveLength(4);
+    expect(/^[0-9a-f]{4}$/.test(instanceId)).toBe(true);
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// Multi-deployment merge behavior
+// ─────────────────────────────────────────────────────────
+
+describe('multi-deployment merge', () => {
+  it('merges multiple deployments into the same lock file', async () => {
+    await writeLockFile(tmpDir, LOCAL_ENTRY);
+    await writeLockFile(tmpDir, AKASH_ENTRY);
+
+    const lockFile = await readLockFile(tmpDir);
+    expect(lockFile).not.toBeNull();
+
+    const entries = Object.values(lockFile!.deployments);
+    expect(entries).toHaveLength(2);
+
+    const profiles = entries.map(e => e.profile).sort();
+    expect(profiles).toEqual(['dev', 'production']);
+  });
+
+  it('does NOT overwrite same profile — creates a new instance', async () => {
+    await writeLockFile(tmpDir, LOCAL_ENTRY);
+
+    const updated: DeploymentLock = {
+      instanceId: 'e5f6',
+      target: 'local',
+      profile: 'dev',
+      deployedAt: '2026-03-01T00:00:00.000Z',
+      local: LOCAL_ENTRY.local,
+    };
+    await writeLockFile(tmpDir, updated);
+
+    const lockFile = await readLockFile(tmpDir);
+    const entries = Object.values(lockFile!.deployments);
+    expect(entries).toHaveLength(2);
+
+    const instanceIds = entries.map(e => e.instanceId).sort();
+    expect(instanceIds).toEqual(['a1b2', 'e5f6']);
+  });
+
+  it('supports three simultaneous deployments', async () => {
+    await writeLockFile(tmpDir, LOCAL_ENTRY);
+    await writeLockFile(tmpDir, AKASH_ENTRY);
+
+    const staging: DeploymentLock = {
+      instanceId: 'f7f8',
+      target: 'akash',
+      profile: 'staging',
+      deployedAt: '2026-02-25T15:00:00.000Z',
+      akash: { ...AKASH_ENTRY.akash!, dseq: 99999 },
+    };
+    await writeLockFile(tmpDir, staging);
+
+    const lockFile = await readLockFile(tmpDir);
+    const entries = Object.values(lockFile!.deployments);
+    expect(entries).toHaveLength(3);
+  });
+
+  it('allows multiple instances of the same profile', async () => {
+    // Deploy "local" profile twice with different instanceIds
+    const instance1: DeploymentLock = {
+      instanceId: 'aa11',
+      target: 'local',
+      profile: 'local',
+      deployedAt: '2026-03-01T10:00:00.000Z',
+      local: LOCAL_ENTRY.local,
+    };
+    const instance2: DeploymentLock = {
+      instanceId: 'bb22',
+      target: 'local',
+      profile: 'local',
+      deployedAt: '2026-03-01T11:00:00.000Z',
+      local: { ...LOCAL_ENTRY.local!, network: 'kadi-net-2' },
+    };
+
+    await writeLockFile(tmpDir, instance1);
+    await writeLockFile(tmpDir, instance2);
+
+    const lockFile = await readLockFile(tmpDir);
+    expect(Object.keys(lockFile!.deployments).sort()).toEqual(['local:aa11', 'local:bb22']);
+
+    // Both entries should exist with different data
+    const entries = Object.values(lockFile!.deployments);
+    expect(entries).toHaveLength(2);
+    expect(entries[0].profile).toBe('local');
+    expect(entries[1].profile).toBe('local');
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// readLockFile — edge cases
+// ─────────────────────────────────────────────────────────
+
+describe('readLockFile edge cases', () => {
+  it('returns null when file does not exist', async () => {
+    const result = await readLockFile(tmpDir);
+    expect(result).toBeNull();
+  });
+
+  it('throws on invalid JSON', async () => {
+    await fs.writeFile(lockFilePath(tmpDir), 'not json!', 'utf-8');
+    await expect(readLockFile(tmpDir)).rejects.toThrow();
+  });
+
+  it('throws when v3 is missing version', async () => {
+    await fs.writeFile(
+      lockFilePath(tmpDir),
+      JSON.stringify({ deployments: {} }),
+      'utf-8'
+    );
+    await expect(readLockFile(tmpDir)).rejects.toThrow(/missing required fields/);
+  });
+
+  it('throws when v3 is missing deployments', async () => {
+    await fs.writeFile(
+      lockFilePath(tmpDir),
+      JSON.stringify({ version: 3 }),
+      'utf-8'
+    );
+    await expect(readLockFile(tmpDir)).rejects.toThrow(/missing required fields/);
+  });
+
+  it('throws when entry target=local but local section missing', async () => {
+    const data: LockFile = {
+      version: 3,
+      deployments: {
+        'dev:ab12': { instanceId: 'ab12', target: 'local', profile: 'dev', deployedAt: new Date().toISOString() },
+      },
+    };
+    await fs.writeFile(lockFilePath(tmpDir), JSON.stringify(data), 'utf-8');
+    await expect(readLockFile(tmpDir)).rejects.toThrow(/"local" section is missing/);
+  });
+
+  it('throws when entry target=akash but akash section missing', async () => {
+    const data: LockFile = {
+      version: 3,
+      deployments: {
+        'prod:cd34': { instanceId: 'cd34', target: 'akash', profile: 'prod', deployedAt: new Date().toISOString() },
+      },
+    };
+    await fs.writeFile(lockFilePath(tmpDir), JSON.stringify(data), 'utf-8');
+    await expect(readLockFile(tmpDir)).rejects.toThrow(/"akash" section is missing/);
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// v1 → v2 migration
+// ─────────────────────────────────────────────────────────
+
+describe('v1 → v3 migration', () => {
+  it('migrateV1toV3 converts a v1 local lock', () => {
+    const v1 = {
+      version: 1,
+      target: 'local' as const,
+      profile: 'dev',
+      deployedAt: '2026-01-01T00:00:00.000Z',
+      local: LOCAL_ENTRY.local,
+    };
+
+    const v3 = migrateV1toV3(v1);
+    expect(v3.version).toBe(LOCK_VERSION);
+
+    const entries = Object.values(v3.deployments);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].target).toBe('local');
+    expect(entries[0].profile).toBe('dev');
+    expect(entries[0].instanceId).toHaveLength(4);
+    expect(entries[0].local).toEqual(LOCAL_ENTRY.local);
+  });
+
+  it('migrateV1toV3 converts a v1 Akash lock', () => {
+    const v1 = {
+      version: 1,
+      target: 'akash' as const,
+      profile: 'production',
+      deployedAt: '2026-01-01T00:00:00.000Z',
+      akash: AKASH_ENTRY.akash,
+    };
+
+    const v3 = migrateV1toV3(v1);
+    expect(v3.version).toBe(LOCK_VERSION);
+
+    const entries = Object.values(v3.deployments);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].target).toBe('akash');
+    expect(entries[0].profile).toBe('production');
+    expect(entries[0].instanceId).toHaveLength(4);
+    expect(entries[0].akash).toEqual(AKASH_ENTRY.akash);
+  });
+
+  it('migrateV1toV2 is a backward-compat alias for migrateV1toV3', () => {
+    const v1 = {
+      version: 1,
+      target: 'local' as const,
+      profile: 'dev',
+      deployedAt: '2026-01-01T00:00:00.000Z',
+      local: LOCAL_ENTRY.local,
+    };
+
+    const result = migrateV1toV2(v1);
+    expect(result.version).toBe(LOCK_VERSION);
+    const entries = Object.values(result.deployments);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].instanceId).toHaveLength(4);
+  });
+
+  it('readLockFile transparently reads v1 files as v3', async () => {
+    // Write a raw v1-format lock file
+    const v1 = {
+      version: 1,
+      target: 'local',
+      profile: 'dev',
+      deployedAt: '2026-01-15T08:00:00.000Z',
+      local: LOCAL_ENTRY.local,
+    };
+    await fs.writeFile(lockFilePath(tmpDir), JSON.stringify(v1, null, 2), 'utf-8');
+
+    const lockFile = await readLockFile(tmpDir);
+    expect(lockFile).not.toBeNull();
+    expect(lockFile!.version).toBe(LOCK_VERSION);
+
+    const entries = Object.values(lockFile!.deployments);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].target).toBe('local');
+    expect(entries[0].profile).toBe('dev');
+    expect(entries[0].instanceId).toHaveLength(4);
+  });
+
+  it('readLockFile validates v1 entries during migration', async () => {
+    const v1 = {
+      version: 1,
+      target: 'local',
+      profile: 'dev',
+      deployedAt: '2026-01-15T08:00:00.000Z',
+      // missing local section
+    };
+    await fs.writeFile(lockFilePath(tmpDir), JSON.stringify(v1), 'utf-8');
+    await expect(readLockFile(tmpDir)).rejects.toThrow(/"local" section is missing/);
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// v2 → v3 migration
+// ─────────────────────────────────────────────────────────
+
+describe('v2 → v3 migration', () => {
+  it('migrates v2 lock file entries and assigns instanceIds', async () => {
+    // Write a raw v2-format lock file (keyed by profile name, no instanceId)
+    const v2 = {
+      version: 2,
+      deployments: {
+        dev: {
+          target: 'local',
+          profile: 'dev',
+          deployedAt: '2026-02-25T12:00:00.000Z',
+          local: LOCAL_ENTRY.local,
+        },
+        production: {
+          target: 'akash',
+          profile: 'production',
+          deployedAt: '2026-02-25T12:00:00.000Z',
+          akash: AKASH_ENTRY.akash,
+        },
+      },
+    };
+    await fs.writeFile(lockFilePath(tmpDir), JSON.stringify(v2, null, 2), 'utf-8');
+
+    const lockFile = await readLockFile(tmpDir);
+    expect(lockFile).not.toBeNull();
+    expect(lockFile!.version).toBe(LOCK_VERSION);
+
+    const entries = Object.values(lockFile!.deployments);
+    expect(entries).toHaveLength(2);
+
+    // Each entry should have a generated instanceId
+    for (const entry of entries) {
+      expect(entry.instanceId).toHaveLength(4);
+      expect(/^[0-9a-f]{4}$/.test(entry.instanceId)).toBe(true);
+    }
+
+    // Keys should be composite
+    const keys = Object.keys(lockFile!.deployments);
+    for (const key of keys) {
+      expect(key).toContain(':');
+    }
+  });
+
+  it('preserves deployment data during v2 → v3 migration', async () => {
+    const v2 = {
+      version: 2,
+      deployments: {
+        production: {
+          target: 'akash',
+          profile: 'production',
+          deployedAt: '2026-02-25T12:00:00.000Z',
+          akash: AKASH_ENTRY.akash,
+        },
+      },
+    };
+    await fs.writeFile(lockFilePath(tmpDir), JSON.stringify(v2, null, 2), 'utf-8');
+
+    const lockFile = await readLockFile(tmpDir);
+    const entry = Object.values(lockFile!.deployments)[0];
+    expect(entry.akash!.dseq).toBe(12345678);
+    expect(entry.akash!.owner).toBe('akash1abc123def456');
+    expect(entry.profile).toBe('production');
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// removeDeployment
+// ─────────────────────────────────────────────────────────
+
+describe('removeDeployment', () => {
+  it('removes a deployment by profile+instanceId and keeps others', async () => {
+    const id1 = await writeLockFile(tmpDir, LOCAL_ENTRY);
+    const id2 = await writeLockFile(tmpDir, AKASH_ENTRY);
+
+    const removed = await removeDeployment(tmpDir, 'dev', id1);
+    expect(removed).toBe(true);
+
+    const lockFile = await readLockFile(tmpDir);
+    expect(lockFile).not.toBeNull();
+    const remaining = Object.values(lockFile!.deployments);
+    expect(remaining).toHaveLength(1);
+    expect(remaining[0].profile).toBe('production');
+    expect(remaining[0].instanceId).toBe(id2);
+  });
+
+  it('removes by profile alone when only one instance exists', async () => {
+    await writeLockFile(tmpDir, LOCAL_ENTRY);
+    await writeLockFile(tmpDir, AKASH_ENTRY);
+
+    const removed = await removeDeployment(tmpDir, 'dev');
+    expect(removed).toBe(true);
+
+    const lockFile = await readLockFile(tmpDir);
+    expect(lockFile).not.toBeNull();
+    const remaining = Object.values(lockFile!.deployments);
+    expect(remaining).toHaveLength(1);
+    expect(remaining[0].profile).toBe('production');
+  });
+
+  it('deletes the lock file when last deployment is removed', async () => {
+    const id1 = await writeLockFile(tmpDir, LOCAL_ENTRY);
+
+    const removed = await removeDeployment(tmpDir, 'dev', id1);
+    expect(removed).toBe(true);
+
+    const lockFile = await readLockFile(tmpDir);
+    expect(lockFile).toBeNull();
+
+    // File should not exist on disk
+    const exists = await fs.stat(lockFilePath(tmpDir)).then(() => true).catch(() => false);
+    expect(exists).toBe(false);
+  });
+
+  it('returns false for a non-existent profile', async () => {
+    await writeLockFile(tmpDir, LOCAL_ENTRY);
+    const removed = await removeDeployment(tmpDir, 'nonexistent');
+    expect(removed).toBe(false);
+  });
+
+  it('returns false when no lock file exists', async () => {
+    const removed = await removeDeployment(tmpDir, 'anything');
+    expect(removed).toBe(false);
+  });
+
+  it('removes correct instance when multiple instances share a profile', async () => {
+    const id1 = await writeLockFile(tmpDir, { ...LOCAL_ENTRY, instanceId: '' });
+    const id2 = await writeLockFile(tmpDir, { ...LOCAL_ENTRY, instanceId: '' });
+    expect(id1).not.toBe(id2);
+
+    const removed = await removeDeployment(tmpDir, 'dev', id1);
+    expect(removed).toBe(true);
+
+    const lockFile = await readLockFile(tmpDir);
+    const remaining = Object.values(lockFile!.deployments);
+    expect(remaining).toHaveLength(1);
+    expect(remaining[0].instanceId).toBe(id2);
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// getDeployment / getDeploymentByInstance / getDeploymentsByProfile
+// ─────────────────────────────────────────────────────────
+
+describe('getDeployment', () => {
+  it('returns a deployment by profile name', async () => {
+    await writeLockFile(tmpDir, LOCAL_ENTRY);
+    await writeLockFile(tmpDir, AKASH_ENTRY);
+
+    const entry = await getDeployment(tmpDir, 'dev');
+    expect(entry).not.toBeNull();
+    expect(entry!.target).toBe('local');
+    expect(entry!.profile).toBe('dev');
+    expect(entry!.instanceId).toHaveLength(4);
+  });
+
+  it('returns null for non-existent profile', async () => {
+    await writeLockFile(tmpDir, LOCAL_ENTRY);
+    const entry = await getDeployment(tmpDir, 'nonexistent');
+    expect(entry).toBeNull();
+  });
+
+  it('returns null when no lock file exists', async () => {
+    const entry = await getDeployment(tmpDir, 'dev');
+    expect(entry).toBeNull();
+  });
+});
+
+describe('getDeploymentByInstance', () => {
+  it('returns a deployment by instanceId', async () => {
+    const id = await writeLockFile(tmpDir, LOCAL_ENTRY);
+    const entry = await getDeploymentByInstance(tmpDir, id);
+    expect(entry).not.toBeNull();
+    expect(entry!.instanceId).toBe(id);
+    expect(entry!.profile).toBe('dev');
+  });
+
+  it('returns null for non-existent instanceId', async () => {
+    await writeLockFile(tmpDir, LOCAL_ENTRY);
+    const entry = await getDeploymentByInstance(tmpDir, 'ffff');
+    expect(entry).toBeNull();
+  });
+
+  it('returns null when no lock file exists', async () => {
+    const entry = await getDeploymentByInstance(tmpDir, 'abcd');
+    expect(entry).toBeNull();
+  });
+});
+
+describe('getDeploymentsByProfile', () => {
+  it('returns all instances for a given profile', async () => {
+    const id1 = await writeLockFile(tmpDir, { ...LOCAL_ENTRY, instanceId: '' });
+    const id2 = await writeLockFile(tmpDir, { ...LOCAL_ENTRY, instanceId: '' });
+    await writeLockFile(tmpDir, AKASH_ENTRY);
+
+    const results = await getDeploymentsByProfile(tmpDir, 'dev');
+    expect(results).toHaveLength(2);
+    const ids = results.map(([_, e]) => e.instanceId).sort();
+    expect(ids).toContain(id1);
+    expect(ids).toContain(id2);
+  });
+
+  it('returns empty array for non-existent profile', async () => {
+    await writeLockFile(tmpDir, LOCAL_ENTRY);
+    const results = await getDeploymentsByProfile(tmpDir, 'nonexistent');
+    expect(results).toEqual([]);
+  });
+
+  it('returns empty array when no lock file exists', async () => {
+    const results = await getDeploymentsByProfile(tmpDir, 'dev');
+    expect(results).toEqual([]);
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// listDeployments
+// ─────────────────────────────────────────────────────────
+
+describe('listDeployments', () => {
+  it('lists all active deployments as tuples with composite keys', async () => {
+    const id1 = await writeLockFile(tmpDir, LOCAL_ENTRY);
+    const id2 = await writeLockFile(tmpDir, AKASH_ENTRY);
+
+    const list = await listDeployments(tmpDir);
+    expect(list).toHaveLength(2);
+
+    const keys = list.map(([key]) => key).sort();
+    expect(keys).toEqual([`dev:${id1}`, `production:${id2}`].sort());
+  });
+
+  it('returns empty array when no lock file exists', async () => {
+    const list = await listDeployments(tmpDir);
+    expect(list).toEqual([]);
+  });
+
+  it('returns single entry for one deployment', async () => {
+    const id = await writeLockFile(tmpDir, LOCAL_ENTRY);
+    const list = await listDeployments(tmpDir);
+    expect(list).toHaveLength(1);
+    expect(list[0][0]).toBe(`dev:${id}`);
+    expect(list[0][1].target).toBe('local');
+    expect(list[0][1].instanceId).toBe(id);
+  });
+
+  it('lists multiple instances of the same profile', async () => {
+    const id1 = await writeLockFile(tmpDir, { ...LOCAL_ENTRY, instanceId: '' });
+    const id2 = await writeLockFile(tmpDir, { ...LOCAL_ENTRY, instanceId: '' });
+
+    const list = await listDeployments(tmpDir);
+    expect(list).toHaveLength(2);
+    const ids = list.map(([_, e]) => e.instanceId).sort();
+    expect(ids).toContain(id1);
+    expect(ids).toContain(id2);
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// deleteLockFile
+// ─────────────────────────────────────────────────────────
+
+describe('deleteLockFile', () => {
+  it('deletes existing lock file and returns true', async () => {
+    await writeLockFile(tmpDir, LOCAL_ENTRY);
+
+    const exists = await fs.stat(lockFilePath(tmpDir)).then(() => true).catch(() => false);
+    expect(exists).toBe(true);
+
+    const deleted = await deleteLockFile(tmpDir);
+    expect(deleted).toBe(true);
+
+    const existsAfter = await fs.stat(lockFilePath(tmpDir)).then(() => true).catch(() => false);
+    expect(existsAfter).toBe(false);
+  });
+
+  it('returns false when file does not exist', async () => {
+    const deleted = await deleteLockFile(tmpDir);
+    expect(deleted).toBe(false);
+  });
+
+  it('is idempotent', async () => {
+    await writeLockFile(tmpDir, LOCAL_ENTRY);
+    expect(await deleteLockFile(tmpDir)).toBe(true);
+    expect(await deleteLockFile(tmpDir)).toBe(false);
+  });
+
+  it('removes the file so readLockFile returns null', async () => {
+    await writeLockFile(tmpDir, AKASH_ENTRY);
+    expect(await readLockFile(tmpDir)).not.toBeNull();
+
+    await deleteLockFile(tmpDir);
+    expect(await readLockFile(tmpDir)).toBeNull();
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// buildLocalLock
+// ─────────────────────────────────────────────────────────
+
+describe('buildLocalLock', () => {
+  it('builds a valid local lock from deployment data', () => {
+    const lock = buildLocalLock('dev', {
+      engine: 'docker',
+      network: 'kadi-net',
+      services: ['web', 'api'],
+      containers: { web: 'abc', api: 'def' },
+      composePath: '/project/docker-compose.yml',
+      deployedAt: new Date('2026-02-25T12:00:00Z'),
+    });
+
+    expect(lock.target).toBe('local');
+    expect(lock.profile).toBe('dev');
+    expect(lock.instanceId).toBe(''); // assigned by writeLockFile
+    expect(lock.deployedAt).toBe('2026-02-25T12:00:00.000Z');
+    expect(lock.local).toBeDefined();
+    expect(lock.local!.composePath).toBe('/project/docker-compose.yml');
+    expect(lock.local!.engine).toBe('docker');
+    expect(lock.local!.services).toEqual(['web', 'api']);
+    expect(lock.akash).toBeUndefined();
+  });
+
+  it('does not include a version field on the entry', () => {
+    const lock = buildLocalLock('dev', {
+      engine: 'docker',
+      network: 'kadi-net',
+      services: ['app'],
+      containers: { app: '123' },
+      composePath: '/project/compose.yml',
+      deployedAt: new Date(),
+    });
+
+    expect('version' in lock).toBe(false);
+  });
+
+  it('supports podman engine', () => {
+    const lock = buildLocalLock('test', {
+      engine: 'podman',
+      network: 'kadi-net',
+      services: ['app'],
+      containers: { app: '123' },
+      composePath: '/project/docker-compose.yml',
+      deployedAt: new Date(),
+    });
+
+    expect(lock.local!.engine).toBe('podman');
+  });
+
+  it('converts deployedAt Date to ISO string', () => {
+    const now = new Date();
+    const lock = buildLocalLock('test', {
+      engine: 'docker',
+      network: 'test-net',
+      services: ['app'],
+      containers: { app: '123' },
+      composePath: '/project/compose.yml',
+      deployedAt: now,
+    });
+
+    expect(lock.deployedAt).toBe(now.toISOString());
+  });
+
+  it('includes label when provided', () => {
+    const lock = buildLocalLock('dev', {
+      engine: 'docker',
+      network: 'kadi-net',
+      services: ['app'],
+      containers: { app: '123' },
+      composePath: '/project/compose.yml',
+      deployedAt: new Date(),
+    }, 'broker-east');
+
+    expect(lock.label).toBe('broker-east');
+  });
+
+  it('omits label when not provided', () => {
+    const lock = buildLocalLock('dev', {
+      engine: 'docker',
+      network: 'kadi-net',
+      services: ['app'],
+      containers: { app: '123' },
+      composePath: '/project/compose.yml',
+      deployedAt: new Date(),
+    });
+
+    expect(lock.label).toBeUndefined();
+  });
+
+  it('writeLockFile assigns instanceId to a buildLocalLock result', async () => {
+    const lock = buildLocalLock('dev', {
+      engine: 'docker',
+      network: 'kadi-net',
+      services: ['svc'],
+      containers: { svc: '123' },
+      composePath: '/project/compose.yml',
+      deployedAt: new Date(),
+    });
+
+    expect(lock.instanceId).toBe('');
+    const id = await writeLockFile(tmpDir, lock);
+    expect(id).toHaveLength(4);
+    expect(lock.instanceId).toBe(id);
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// buildAkashLock
+// ─────────────────────────────────────────────────────────
+
+describe('buildAkashLock', () => {
+  it('builds a valid Akash lock from deployment data', () => {
+    const lock = buildAkashLock('production', {
+      dseq: 99999,
+      owner: 'akash1owner',
+      provider: 'akash1prov',
+      providerUri: 'https://prov.example.com',
+      network: 'mainnet',
+      gseq: 1,
+      oseq: 1,
+      deployedAt: new Date('2026-02-25T14:30:00Z'),
+    });
+
+    expect(lock.target).toBe('akash');
+    expect(lock.profile).toBe('production');
+    expect(lock.instanceId).toBe(''); // assigned by writeLockFile
+    expect(lock.deployedAt).toBe('2026-02-25T14:30:00.000Z');
+    expect(lock.akash).toBeDefined();
+    expect(lock.akash!.dseq).toBe(99999);
+    expect(lock.akash!.owner).toBe('akash1owner');
+    expect(lock.akash!.network).toBe('mainnet');
+    expect(lock.local).toBeUndefined();
+  });
+
+  it('does not include a version field on the entry', () => {
+    const lock = buildAkashLock('prod', {
+      dseq: 42,
+      owner: 'akash1owner',
+      provider: 'akash1prov',
+      providerUri: 'https://uri.com',
+      network: 'mainnet',
+      gseq: 1,
+      oseq: 1,
+      deployedAt: new Date(),
+    });
+
+    expect('version' in lock).toBe(false);
+  });
+
+  it('supports testnet network', () => {
+    const lock = buildAkashLock('staging', {
+      dseq: 11111,
+      owner: 'akash1test',
+      provider: 'akash1testprov',
+      providerUri: 'https://testprov.example.com',
+      network: 'testnet',
+      gseq: 1,
+      oseq: 1,
+      deployedAt: new Date(),
+    });
+
+    expect(lock.akash!.network).toBe('testnet');
+  });
+
+  it('preserves all deployment identifiers', () => {
+    const lock = buildAkashLock('prod', {
+      dseq: 42,
+      owner: 'akash1owner',
+      provider: 'akash1prov',
+      providerUri: 'https://uri.com',
+      network: 'mainnet',
+      gseq: 3,
+      oseq: 5,
+      deployedAt: new Date(),
+    });
+
+    expect(lock.akash!.gseq).toBe(3);
+    expect(lock.akash!.oseq).toBe(5);
+    expect(lock.akash!.providerUri).toBe('https://uri.com');
+  });
+
+  it('includes label when provided', () => {
+    const lock = buildAkashLock('production', {
+      dseq: 42,
+      owner: 'akash1owner',
+      provider: 'akash1prov',
+      providerUri: 'https://uri.com',
+      network: 'mainnet',
+      gseq: 1,
+      oseq: 1,
+      deployedAt: new Date(),
+    }, 'primary-gpu');
+
+    expect(lock.label).toBe('primary-gpu');
+  });
+
+  it('omits label when not provided', () => {
+    const lock = buildAkashLock('production', {
+      dseq: 42,
+      owner: 'akash1owner',
+      provider: 'akash1prov',
+      providerUri: 'https://uri.com',
+      network: 'mainnet',
+      gseq: 1,
+      oseq: 1,
+      deployedAt: new Date(),
+    });
+
+    expect(lock.label).toBeUndefined();
+  });
+
+  it('writeLockFile assigns instanceId to a buildAkashLock result', async () => {
+    const lock = buildAkashLock('production', {
+      dseq: 42,
+      owner: 'akash1owner',
+      provider: 'akash1prov',
+      providerUri: 'https://uri.com',
+      network: 'mainnet',
+      gseq: 1,
+      oseq: 1,
+      deployedAt: new Date(),
+    });
+
+    expect(lock.instanceId).toBe('');
+    const id = await writeLockFile(tmpDir, lock);
+    expect(id).toHaveLength(4);
+    expect(lock.instanceId).toBe(id);
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// Full lifecycle: write → read → remove → delete
+// ─────────────────────────────────────────────────────────
+
+describe('full lock lifecycle', () => {
+  it('write multiple → remove one → verify remainder → remove last → null', async () => {
+    // Write two deployments
+    const id1 = await writeLockFile(tmpDir, LOCAL_ENTRY);
+    const id2 = await writeLockFile(tmpDir, AKASH_ENTRY);
+
+    let lockFile = await readLockFile(tmpDir);
+    const profiles = Object.values(lockFile!.deployments).map(e => e.profile).sort();
+    expect(profiles).toEqual(['dev', 'production']);
+
+    // Remove one by profile+instanceId
+    await removeDeployment(tmpDir, 'dev', id1);
+    lockFile = await readLockFile(tmpDir);
+    const remaining = Object.values(lockFile!.deployments);
+    expect(remaining).toHaveLength(1);
+    expect(remaining[0].profile).toBe('production');
+
+    // Remove last — file should be deleted
+    await removeDeployment(tmpDir, 'production', id2);
+    lockFile = await readLockFile(tmpDir);
+    expect(lockFile).toBeNull();
+  });
+
+  it('buildLocalLock → writeLockFile → getDeployment round-trip', async () => {
+    const lock = buildLocalLock('test-profile', {
+      engine: 'podman',
+      network: 'test-net',
+      services: ['svc1', 'svc2', 'svc3'],
+      containers: { svc1: 'c1', svc2: 'c2', svc3: 'c3' },
+      composePath: path.join(tmpDir, 'docker-compose.yml'),
+      deployedAt: new Date('2026-01-01T00:00:00Z'),
+    });
+
+    const id = await writeLockFile(tmpDir, lock);
+    const entry = await getDeployment(tmpDir, 'test-profile');
+    expect(entry).not.toBeNull();
+    expect(entry!.instanceId).toBe(id);
+    expect(entry!.target).toBe('local');
+    expect(entry!.profile).toBe('test-profile');
+    expect(entry!.local!.engine).toBe('podman');
+  });
+
+  it('buildAkashLock → writeLockFile → getDeployment round-trip', async () => {
+    const lock = buildAkashLock('staging', {
+      dseq: 777,
+      owner: 'akash1abc',
+      provider: 'akash1xyz',
+      providerUri: 'https://example.com',
+      network: 'testnet',
+      gseq: 2,
+      oseq: 3,
+      deployedAt: new Date('2026-06-15T10:30:00Z'),
+    });
+
+    const id = await writeLockFile(tmpDir, lock);
+    const entry = await getDeployment(tmpDir, 'staging');
+    expect(entry).not.toBeNull();
+    expect(entry!.instanceId).toBe(id);
+    expect(entry!.target).toBe('akash');
+    expect(entry!.akash!.dseq).toBe(777);
+  });
+
+  it('multiple instances of same profile coexist', async () => {
+    const lock1 = buildLocalLock('dev', {
+      engine: 'docker',
+      network: 'net-1',
+      services: ['svc'],
+      containers: { svc: 'c1' },
+      composePath: '/project/compose.yml',
+      deployedAt: new Date(),
+    });
+    const lock2 = buildLocalLock('dev', {
+      engine: 'docker',
+      network: 'net-2',
+      services: ['svc'],
+      containers: { svc: 'c2' },
+      composePath: '/project/compose.yml',
+      deployedAt: new Date(),
+    });
+
+    const id1 = await writeLockFile(tmpDir, lock1);
+    const id2 = await writeLockFile(tmpDir, lock2);
+    expect(id1).not.toBe(id2);
+
+    const all = await getDeploymentsByProfile(tmpDir, 'dev');
+    expect(all).toHaveLength(2);
+
+    const list = await listDeployments(tmpDir);
+    expect(list).toHaveLength(2);
+
+    // Each can be retrieved by instance
+    const e1 = await getDeploymentByInstance(tmpDir, id1);
+    const e2 = await getDeploymentByInstance(tmpDir, id2);
+    expect(e1!.local!.network).toBe('net-1');
+    expect(e2!.local!.network).toBe('net-2');
+  });
+
+  it('labels are preserved through write → read cycle', async () => {
+    const lock = buildLocalLock('dev', {
+      engine: 'docker',
+      network: 'kadi-net',
+      services: ['svc'],
+      containers: { svc: 'c1' },
+      composePath: '/project/compose.yml',
+      deployedAt: new Date(),
+    }, 'broker-west');
+
+    const id = await writeLockFile(tmpDir, lock);
+    const entry = await getDeploymentByInstance(tmpDir, id);
+    expect(entry!.label).toBe('broker-west');
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// Utility functions: generateInstanceId, deploymentKey, parseDeploymentKey
+// ─────────────────────────────────────────────────────────
+
+describe('generateInstanceId', () => {
+  it('returns a 4-char hex string', () => {
+    const id = generateInstanceId();
+    expect(id).toHaveLength(4);
+    expect(/^[0-9a-f]{4}$/.test(id)).toBe(true);
+  });
+
+  it('generates unique IDs on successive calls', () => {
+    const ids = new Set(Array.from({ length: 20 }, () => generateInstanceId()));
+    // With 65536 possible values, 20 should almost certainly be unique
+    expect(ids.size).toBe(20);
+  });
+});
+
+describe('deploymentKey', () => {
+  it('creates a composite key', () => {
+    expect(deploymentKey('dev', 'ab12')).toBe('dev:ab12');
+  });
+});
+
+describe('parseDeploymentKey', () => {
+  it('parses a composite key into profile and instanceId', () => {
+    const parsed = parseDeploymentKey('dev:ab12');
+    expect(parsed.profile).toBe('dev');
+    expect(parsed.instanceId).toBe('ab12');
+  });
+
+  it('handles profiles with colons', () => {
+    const parsed = parseDeploymentKey('my:complex:profile:ab12');
+    expect(parsed.profile).toBe('my:complex:profile');
+    expect(parsed.instanceId).toBe('ab12');
+  });
+});