kadi-deploy 0.19.0

package/src/commands/lock.ts

@@ -0,0 +1,571 @@
+/**
+ * Deployment Lock File Management (v3 — multi-instance)
+ *
+ * Handles reading, writing, and deleting the `.kadi-deploy.lock` file
+ * that tracks the state of active deployments. The lock file supports
+ * multiple simultaneous deployments keyed by `{profile}:{instanceId}`,
+ * enabling scenarios like deploying the same profile to multiple brokers,
+ * multiple Akash providers, or having both local and Akash deployments active.
+ *
+ * The lock file is updated after each successful deployment and cleaned
+ * up after a successful teardown. It is deleted entirely when the last
+ * deployment is removed.
+ *
+ * @module commands/lock
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+// ─────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────
+
+/** Lock file schema version — bump when the shape changes */
+export const LOCK_VERSION = 3;
+
+/** Standard lock file name (lives in the project root next to agent.json) */
+export const LOCK_FILENAME = '.kadi-deploy.lock';
+
+/**
+ * Local deployment state persisted to disk
+ */
+export interface LocalDeploymentLock {
+  composePath: string;
+  engine: 'docker' | 'podman';
+  network: string;
+  services: string[];
+  containers: Record<string, string>;
+}
+
+/**
+ * Akash deployment state persisted to disk
+ */
+export interface AkashDeploymentLock {
+  dseq: number;
+  owner: string;
+  provider: string;
+  providerUri: string;
+  network: 'mainnet' | 'testnet';
+  gseq: number;
+  oseq: number;
+}
+
+/**
+ * A single deployment entry inside the lock file.
+ * Each entry is keyed by `{profile}:{instanceId}` in the `deployments` map.
+ */
+export interface DeploymentLock {
+  /** Unique deployment instance ID (e.g. "a3f7") */
+  instanceId: string;
+  target: 'local' | 'akash';
+  profile: string;
+  deployedAt: string;
+  /** Optional human-readable label (e.g. "broker-us-east", "staging") */
+  label?: string;
+
+  /** Present when target === 'local' */
+  local?: LocalDeploymentLock;
+  /** Present when target === 'akash' */
+  akash?: AkashDeploymentLock;
+}
+
+/**
+ * The top-level lock file shape written to `.kadi-deploy.lock` (v3).
+ *
+ * ```json
+ * {
+ *   "version": 3,
+ *   "deployments": {
+ *     "local:a3f7": { "instanceId": "a3f7", "target": "local", "profile": "local", ... },
+ *     "akash:b9e2": { "instanceId": "b9e2", "target": "akash", "profile": "akash", ... }
+ *   }
+ * }
+ * ```
+ */
+export interface LockFile {
+  version: number;
+  deployments: Record<string, DeploymentLock>;
+}
+
+// ─────────────────────────────────────────────────────────
+// v1 / v2 compat types (for migration)
+// ─────────────────────────────────────────────────────────
+
+/** Shape of the v1 lock file (single deployment, version on the entry) */
+interface V1LockFile {
+  version: number;
+  target: 'local' | 'akash';
+  profile: string;
+  deployedAt: string;
+  local?: LocalDeploymentLock;
+  akash?: AkashDeploymentLock;
+}
+
+/** Shape of a v2 deployment entry (no instanceId) */
+interface V2DeploymentEntry {
+  target: 'local' | 'akash';
+  profile: string;
+  deployedAt: string;
+  local?: LocalDeploymentLock;
+  akash?: AkashDeploymentLock;
+}
+
+/** Shape of the v2 lock file (keyed by profile name, no instanceId) */
+interface V2LockFile {
+  version: number;
+  deployments: Record<string, V2DeploymentEntry>;
+}
+
+// ─────────────────────────────────────────────────────────
+// Instance ID & key utilities
+// ─────────────────────────────────────────────────────────
+
+/**
+ * Generate a short random instance ID (4 hex characters).
+ * 65,536 possible values — more than enough for per-project tracking.
+ */
+export function generateInstanceId(): string {
+  return crypto.randomBytes(2).toString('hex');
+}
+
+/**
+ * Build a composite deployment key: `{profile}:{instanceId}`.
+ */
+export function deploymentKey(profile: string, instanceId: string): string {
+  return `${profile}:${instanceId}`;
+}
+
+/**
+ * Parse a composite deployment key back into its parts.
+ */
+export function parseDeploymentKey(key: string): { profile: string; instanceId: string } {
+  const idx = key.lastIndexOf(':');
+  if (idx === -1) {
+    return { profile: key, instanceId: '' };
+  }
+  return { profile: key.slice(0, idx), instanceId: key.slice(idx + 1) };
+}
+
+// ─────────────────────────────────────────────────────────
+// Lock file operations
+// ─────────────────────────────────────────────────────────
+
+/**
+ * Build the absolute path to the lock file for a given project root.
+ */
+export function lockFilePath(projectRoot: string): string {
+  return path.join(projectRoot, LOCK_FILENAME);
+}
+
+/**
+ * Migrate a v1 lock file (single deployment) to the v3 format.
+ */
+export function migrateV1toV3(v1: V1LockFile): LockFile {
+  const instanceId = generateInstanceId();
+  const entry: DeploymentLock = {
+    instanceId,
+    target: v1.target,
+    profile: v1.profile,
+    deployedAt: v1.deployedAt,
+  };
+
+  if (v1.local) entry.local = v1.local;
+  if (v1.akash) entry.akash = v1.akash;
+
+  return {
+    version: LOCK_VERSION,
+    deployments: {
+      [deploymentKey(v1.profile, instanceId)]: entry,
+    },
+  };
+}
+
+/**
+ * Migrate a v2 lock file (keyed by profile name, no instanceId) to v3 format.
+ */
+export function migrateV2toV3(v2: V2LockFile): LockFile {
+  const v3: LockFile = { version: LOCK_VERSION, deployments: {} };
+
+  for (const [profileName, oldEntry] of Object.entries(v2.deployments)) {
+    const instanceId = generateInstanceId();
+    const key = deploymentKey(profileName, instanceId);
+    v3.deployments[key] = {
+      instanceId,
+      target: oldEntry.target,
+      profile: oldEntry.profile,
+      deployedAt: oldEntry.deployedAt,
+      ...(oldEntry.local ? { local: oldEntry.local } : {}),
+      ...(oldEntry.akash ? { akash: oldEntry.akash } : {}),
+    };
+  }
+
+  return v3;
+}
+
+/**
+ * @deprecated Use migrateV1toV3 instead. Kept for backward compatibility.
+ */
+export function migrateV1toV2(v1: V1LockFile): LockFile {
+  return migrateV1toV3(v1);
+}
+
+/**
+ * Detect whether a lock file's entries have instanceId fields (v3) or not (v2).
+ */
+function isV3Format(data: { deployments: Record<string, any> }): boolean {
+  const entries = Object.values(data.deployments);
+  if (entries.length === 0) return true; // empty is fine as v3
+  return entries.every((entry) => typeof entry.instanceId === 'string' && entry.instanceId.length > 0);
+}
+
+/**
+ * Validate that a deployment entry has the expected sections.
+ */
+function validateEntry(entry: DeploymentLock, filePath: string): void {
+  if (!entry.target || !entry.profile) {
+    throw new Error(
+      `Invalid deployment entry in ${filePath}: missing required fields (target, profile)`
+    );
+  }
+
+  if (entry.target === 'local' && !entry.local) {
+    throw new Error(
+      `Invalid deployment entry "${entry.profile}" in ${filePath}: target is "local" but "local" section is missing`
+    );
+  }
+
+  if (entry.target === 'akash' && !entry.akash) {
+    throw new Error(
+      `Invalid deployment entry "${entry.profile}" in ${filePath}: target is "akash" but "akash" section is missing`
+    );
+  }
+}
+
+/**
+ * Read the deployment lock file from disk.
+ *
+ * Transparently migrates v1 and v2 lock files to v3 format on read
+ * (the file on disk is NOT rewritten — migration is in-memory only).
+ *
+ * @param projectRoot - Absolute path to the project directory
+ * @returns The parsed v3 lock data, or `null` if the file does not exist
+ * @throws If the file exists but cannot be parsed or is invalid
+ */
+export async function readLockFile(
+  projectRoot: string
+): Promise<LockFile | null> {
+  const filePath = lockFilePath(projectRoot);
+
+  try {
+    const raw = await fs.readFile(filePath, 'utf-8');
+    const data = JSON.parse(raw);
+
+    // Detect v1 format: has `target` at the top level
+    if (data.version === 1 || (data.target && !data.deployments)) {
+      const v3 = migrateV1toV3(data as V1LockFile);
+      for (const entry of Object.values(v3.deployments)) {
+        validateEntry(entry, filePath);
+      }
+      return v3;
+    }
+
+    // Detect v2 format: has deployments but entries lack instanceId
+    if (data.version === 2 || (data.deployments && !isV3Format(data))) {
+      const v3 = migrateV2toV3(data as V2LockFile);
+      for (const entry of Object.values(v3.deployments)) {
+        validateEntry(entry, filePath);
+      }
+      return v3;
+    }
+
+    // v3 format
+    const lockFile = data as LockFile;
+
+    if (!lockFile.version || !lockFile.deployments) {
+      throw new Error(
+        `Invalid lock file at ${filePath}: missing required fields (version, deployments)`
+      );
+    }
+
+    for (const entry of Object.values(lockFile.deployments)) {
+      validateEntry(entry, filePath);
+    }
+
+    return lockFile;
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      return null;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Write or update the lock file on disk.
+ *
+ * This is merge-based: it reads any existing lock file, assigns a unique
+ * instanceId if not already set, inserts the entry keyed by
+ * `{profile}:{instanceId}`, and writes the whole thing back.
+ *
+ * @param projectRoot - Absolute path to the project directory
+ * @param lock - The deployment entry to add or update
+ * @returns The instanceId of the written deployment
+ */
+export async function writeLockFile(
+  projectRoot: string,
+  lock: DeploymentLock
+): Promise<string> {
+  const filePath = lockFilePath(projectRoot);
+
+  // Read existing (may be null or v1/v2 — readLockFile handles both)
+  const existing = await readLockFile(projectRoot);
+
+  const lockFile: LockFile = existing ?? {
+    version: LOCK_VERSION,
+    deployments: {},
+  };
+
+  // Ensure version is current
+  lockFile.version = LOCK_VERSION;
+
+  // Generate a collision-free instance ID if not already set
+  let instanceId = lock.instanceId;
+  if (!instanceId) {
+    do {
+      instanceId = generateInstanceId();
+    } while (deploymentKey(lock.profile, instanceId) in lockFile.deployments);
+    lock.instanceId = instanceId;
+  }
+
+  // Add/update this deployment's entry using composite key
+  const key = deploymentKey(lock.profile, instanceId);
+  lockFile.deployments[key] = lock;
+
+  const json = JSON.stringify(lockFile, null, 2) + '\n';
+  await fs.writeFile(filePath, json, 'utf-8');
+
+  return instanceId;
+}
+
+/**
+ * Remove a single deployment entry from the lock file by profile and instanceId.
+ *
+ * If the last entry is removed, the file is deleted entirely.
+ *
+ * @returns `true` if the entry was found and removed, `false` otherwise
+ */
+export async function removeDeployment(
+  projectRoot: string,
+  profile: string,
+  instanceId?: string
+): Promise<boolean> {
+  const lockFile = await readLockFile(projectRoot);
+  if (!lockFile) return false;
+
+  let keyToRemove: string | undefined;
+
+  if (instanceId) {
+    // Direct lookup with composite key
+    keyToRemove = deploymentKey(profile, instanceId);
+  } else {
+    // Backward compat: find the first (or only) entry matching this profile.
+    // This supports callers that only pass a profile name.
+    const matching = Object.entries(lockFile.deployments)
+      .filter(([_, entry]) => entry.profile === profile);
+
+    if (matching.length === 1) {
+      keyToRemove = matching[0][0];
+    } else if (matching.length === 0) {
+      return false;
+    } else {
+      // Multiple instances from same profile — caller must specify instanceId
+      // For backward compat, remove the first one found
+      keyToRemove = matching[0][0];
+    }
+  }
+
+  if (!keyToRemove || !(keyToRemove in lockFile.deployments)) return false;
+
+  delete lockFile.deployments[keyToRemove];
+
+  // If no deployments left, delete the entire file
+  if (Object.keys(lockFile.deployments).length === 0) {
+    return deleteLockFile(projectRoot);
+  }
+
+  // Write back the remaining deployments
+  const filePath = lockFilePath(projectRoot);
+  const json = JSON.stringify(lockFile, null, 2) + '\n';
+  await fs.writeFile(filePath, json, 'utf-8');
+  return true;
+}
+
+/**
+ * Get a single deployment entry by instance ID.
+ *
+ * @returns The deployment entry, or `null` if not found
+ */
+export async function getDeploymentByInstance(
+  projectRoot: string,
+  instanceId: string
+): Promise<DeploymentLock | null> {
+  const lockFile = await readLockFile(projectRoot);
+  if (!lockFile) return null;
+  const entry = Object.values(lockFile.deployments)
+    .find((d) => d.instanceId === instanceId);
+  return entry ?? null;
+}
+
+/**
+ * Get a single deployment entry by profile name.
+ *
+ * If multiple instances exist for the same profile, returns the first one found.
+ *
+ * @returns The deployment entry, or `null` if not found
+ */
+export async function getDeployment(
+  projectRoot: string,
+  profile: string
+): Promise<DeploymentLock | null> {
+  const lockFile = await readLockFile(projectRoot);
+  if (!lockFile) return null;
+
+  // Check composite key first (backward compat for tests passing full key)
+  if (lockFile.deployments[profile]) {
+    return lockFile.deployments[profile];
+  }
+
+  // Search by profile field
+  const entry = Object.values(lockFile.deployments)
+    .find((d) => d.profile === profile);
+  return entry ?? null;
+}
+
+/**
+ * Get all deployment entries for a given profile name.
+ *
+ * @returns Array of [compositeKey, entry] tuples
+ */
+export async function getDeploymentsByProfile(
+  projectRoot: string,
+  profile: string
+): Promise<Array<[string, DeploymentLock]>> {
+  const lockFile = await readLockFile(projectRoot);
+  if (!lockFile) return [];
+  return Object.entries(lockFile.deployments)
+    .filter(([_, entry]) => entry.profile === profile);
+}
+
+/**
+ * List all active deployment entries.
+ *
+ * @returns Array of [compositeKey, entry] tuples, or empty if no lock file
+ */
+export async function listDeployments(
+  projectRoot: string
+): Promise<Array<[string, DeploymentLock]>> {
+  const lockFile = await readLockFile(projectRoot);
+  if (!lockFile) return [];
+  return Object.entries(lockFile.deployments);
+}
+
+/**
+ * Delete the deployment lock file entirely.
+ *
+ * @param projectRoot - Absolute path to the project directory
+ * @returns `true` if the file was deleted, `false` if it did not exist
+ */
+export async function deleteLockFile(projectRoot: string): Promise<boolean> {
+  const filePath = lockFilePath(projectRoot);
+
+  try {
+    await fs.unlink(filePath);
+    return true;
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      return false;
+    }
+    throw err;
+  }
+}
+
+// ─────────────────────────────────────────────────────────
+// Lock builders — convenience functions to create lock data
+// from deployment results
+// ─────────────────────────────────────────────────────────
+
+/**
+ * Build a DeploymentLock from local deployment result data.
+ *
+ * @param profileName - The profile name used
+ * @param data - LocalDeploymentData from deploy-ability
+ * @param label - Optional human-readable label for this deployment instance
+ */
+export function buildLocalLock(
+  profileName: string,
+  data: {
+    engine: string;
+    network: string;
+    services: readonly string[];
+    containers: Record<string, string>;
+    composePath: string;
+    deployedAt: Date;
+  },
+  label?: string
+): DeploymentLock {
+  return {
+    instanceId: '', // assigned by writeLockFile
+    target: 'local',
+    profile: profileName,
+    deployedAt: data.deployedAt.toISOString(),
+    ...(label ? { label } : {}),
+    local: {
+      composePath: data.composePath,
+      engine: data.engine as 'docker' | 'podman',
+      network: data.network,
+      services: [...data.services],
+      containers: data.containers,
+    },
+  };
+}
+
+/**
+ * Build a DeploymentLock from Akash deployment result data.
+ *
+ * @param profileName - The profile name used
+ * @param data - AkashDeploymentData from deploy-ability
+ * @param label - Optional human-readable label for this deployment instance
+ */
+export function buildAkashLock(
+  profileName: string,
+  data: {
+    dseq: number;
+    owner: string;
+    provider: string;
+    providerUri: string;
+    network: string;
+    gseq: number;
+    oseq: number;
+    deployedAt: Date;
+  },
+  label?: string
+): DeploymentLock {
+  return {
+    instanceId: '', // assigned by writeLockFile
+    target: 'akash',
+    profile: profileName,
+    deployedAt: data.deployedAt.toISOString(),
+    ...(label ? { label } : {}),
+    akash: {
+      dseq: data.dseq,
+      owner: data.owner,
+      provider: data.provider,
+      providerUri: data.providerUri,
+      network: data.network as 'mainnet' | 'testnet',
+      gseq: data.gseq,
+      oseq: data.oseq,
+    },
+  };
+}