vibecarbon 0.1.0

package/src/lib/hetzner-dns.js

@@ -0,0 +1,377 @@
+/**
+ * Hetzner Cloud DNS Operations
+ *
+ * DNS management through the Hetzner Cloud API (api.hetzner.cloud/v1).
+ * Uses the same API token as server operations — no additional credentials needed.
+ *
+ * The Cloud API uses `/zones/{id}/rrsets` for record management (not `/records`).
+ * Updates are performed via delete + create (PUT on rrsets returns 422).
+ *
+ * API Documentation: https://docs.hetzner.cloud/
+ */
+
+import * as p from '@clack/prompts';
+import { fetchWithRetry } from './fetch-retry.js';
+import { HetznerProvider } from './providers/hetzner.js';
+
+const API_BASE = HetznerProvider.API_BASE;
+
+// Default TTL for HA records (low for fast failover propagation)
+const HA_TTL = 60;
+// Default TTL for standard records (low to prevent stale DNS between test runs)
+const DEFAULT_TTL = 60;
+
+// ============================================================================
+// HELPERS
+// ============================================================================
+
+/**
+ * Convert an FQDN to a zone-relative name for the Hetzner DNS API.
+ *
+ * Hetzner DNS records use names relative to the zone:
+ *   example.com       (zone: example.com)  → "@"
+ *   *.example.com     (zone: example.com)  → "*"
+ *   sub.example.com   (zone: example.com)  → "sub"
+ *   a.b.example.com   (zone: example.com)  → "a.b"
+ *
+ * @param {string} fqdn - Fully qualified domain name
+ * @param {string} zoneName - Zone name (e.g. "example.com")
+ * @returns {string} Zone-relative record name
+ */
+export function fqdnToRelative(fqdn, zoneName) {
+  // Strip trailing dots
+  const clean = fqdn.replace(/\.$/, '');
+  const zone = zoneName.replace(/\.$/, '');
+
+  if (clean === zone) return '@';
+  if (clean === `*.${zone}`) return '*';
+  if (clean.endsWith(`.${zone}`)) {
+    return clean.slice(0, -(zone.length + 1));
+  }
+  // If no match, return as-is (caller may have already passed a relative name)
+  return clean;
+}
+
+// ============================================================================
+// LOW-LEVEL API FUNCTIONS
+// ============================================================================
+
+/**
+ * Get all DNS zones in the Hetzner Cloud project.
+ *
+ * @param {string} apiToken - Hetzner Cloud API token
+ * @returns {Promise<Array>} Array of zone objects
+ */
+export async function getZones(apiToken) {
+  const zones = [];
+  let page = 1;
+
+  while (true) {
+    const response = await fetchWithRetry(`${API_BASE}/zones?page=${page}&per_page=50`, {
+      headers: { Authorization: `Bearer ${apiToken}` },
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new Error(`Hetzner DNS API error: ${error.error?.message || response.statusText}`);
+    }
+
+    const data = await response.json();
+    zones.push(...(data.zones || []));
+
+    if (!data.meta?.pagination?.next_page) break;
+    page = data.meta.pagination.next_page;
+  }
+
+  return zones;
+}
+
+/**
+ * Get a single DNS zone by ID.
+ *
+ * @param {string} apiToken - Hetzner Cloud API token
+ * @param {string} zoneId - Zone ID
+ * @returns {Promise<object>} Zone object (includes `name`)
+ */
+export async function getZone(apiToken, zoneId) {
+  const response = await fetchWithRetry(`${API_BASE}/zones/${zoneId}`, {
+    headers: { Authorization: `Bearer ${apiToken}` },
+  });
+
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({}));
+    throw new Error(`Hetzner DNS API error: ${error.error?.message || response.statusText}`);
+  }
+
+  const data = await response.json();
+  return data.zone;
+}
+
+/**
+ * List all rrsets (record sets) in a DNS zone.
+ *
+ * @param {string} apiToken - Hetzner Cloud API token
+ * @param {string} zoneId - Zone ID
+ * @returns {Promise<Array>} Array of rrset objects
+ */
+export async function getRrsets(apiToken, zoneId) {
+  const rrsets = [];
+  let page = 1;
+
+  while (true) {
+    const response = await fetchWithRetry(
+      `${API_BASE}/zones/${zoneId}/rrsets?page=${page}&per_page=100`,
+      {
+        headers: { Authorization: `Bearer ${apiToken}` },
+      },
+    );
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new Error(`Hetzner DNS API error: ${error.error?.message || response.statusText}`);
+    }
+
+    const data = await response.json();
+    rrsets.push(...(data.rrsets || []));
+
+    if (!data.meta?.pagination?.next_page) break;
+    page = data.meta.pagination.next_page;
+  }
+
+  return rrsets;
+}
+
+/**
+ * Create or update a DNS record.
+ *
+ * Uses the /rrsets endpoint. If a matching rrset (same type + name) exists,
+ * deletes it first then creates a new one (PUT is not supported on rrsets).
+ *
+ * @param {string} apiToken - Hetzner Cloud API token
+ * @param {string} zoneId - Zone ID
+ * @param {string} zoneName - Zone name (e.g. "example.com") for FQDN→relative conversion
+ * @param {object} config - Record config
+ * @param {string} config.type - Record type (A, AAAA, CNAME, etc.)
+ * @param {string} config.name - Record name (FQDN — converted to relative internally)
+ * @param {string} config.value - Record value (e.g. IP address)
+ * @param {number} [config.ttl] - TTL in seconds (default: 3600)
+ * @returns {Promise<object>} Created rrset object
+ */
+export async function createDNSRecord(apiToken, zoneId, zoneName, config) {
+  const { type, name, value, ttl = DEFAULT_TTL } = config;
+  const relativeName = fqdnToRelative(name, zoneName);
+
+  // Delete existing rrset if present (PUT is not supported, so we delete + create)
+  const existing = await getRrsets(apiToken, zoneId);
+  const match = existing.find((r) => r.type === type && r.name === relativeName);
+
+  if (match) {
+    const delResponse = await fetchWithRetry(
+      `${API_BASE}/zones/${zoneId}/rrsets/${relativeName}/${type}`,
+      {
+        method: 'DELETE',
+        headers: { Authorization: `Bearer ${apiToken}` },
+      },
+    );
+    if (!delResponse.ok) {
+      const error = await delResponse.json().catch(() => ({}));
+      throw new Error(
+        `Failed to remove existing DNS record: ${error.error?.message || delResponse.statusText}`,
+      );
+    }
+  }
+
+  // Create new rrset
+  const response = await fetchWithRetry(`${API_BASE}/zones/${zoneId}/rrsets`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${apiToken}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      name: relativeName,
+      type,
+      ttl,
+      records: [{ value }],
+    }),
+  });
+
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({}));
+    throw new Error(`Failed to create DNS record: ${error.error?.message || response.statusText}`);
+  }
+
+  const data = await response.json();
+  return data.rrset;
+}
+
+/**
+ * Delete a DNS rrset by FQDN and type — but only if every value in the
+ * rrset belongs to this caller's stack.
+ *
+ * Hetzner stores DNS records as rrsets (one row per name+type, with an
+ * array of values). The destroy path historically wiped the rrset
+ * unconditionally, which was fine for single-tenant zones but blasted
+ * shared zones when e2e scenarios reused the same root domain
+ * (the 2026-05-16 matrix saw compose-ha's destroy zero compose's
+ * `e1.carbonstack.dev` mid-verify).
+ *
+ * Ownership rule:
+ *   - If every value in the rrset is in `ownedIps`, DELETE the rrset.
+ *   - If any value is NOT owned, preserve the entire rrset (we don't
+ *     PATCH out individual records — Hetzner's API forces delete+recreate
+ *     anyway, and a stale recreate risks dropping the others' values).
+ *   - If `ownedIps` is empty, preserve (safer default when envConfig
+ *     has no IPs to verify against).
+ *
+ * @param {string} apiToken - Hetzner Cloud API token
+ * @param {string} zoneId - Zone ID
+ * @param {string} zoneName - Zone name for FQDN→relative conversion
+ * @param {string} name - Record name (FQDN)
+ * @param {string[]} ownedIps - IPs that belong to this caller's stack
+ * @param {string} [type='A'] - Record type
+ * @returns {Promise<{deleted: boolean, skipped: boolean, foundValues: string[], skippedTargets: string[]}>}
+ */
+export async function deleteDNSRecord(apiToken, zoneId, zoneName, name, ownedIps, type = 'A') {
+  const relativeName = fqdnToRelative(name, zoneName);
+
+  // Inspect the rrset before deleting. The list endpoint surfaces all
+  // values for a (name, type) tuple as a single rrset row.
+  const rrsets = await getRrsets(apiToken, zoneId);
+  const match = rrsets.find((r) => r.type === type && r.name === relativeName);
+
+  if (!match) {
+    return { deleted: false, skipped: false, foundValues: [], skippedTargets: [] };
+  }
+
+  const values = (match.records || []).map((r) => r.value);
+  const owned = new Set(ownedIps || []);
+  const unowned = values.filter((v) => !owned.has(v));
+
+  if (unowned.length > 0) {
+    // At least one value belongs to someone else — leave the whole rrset
+    // alone. Surfaces to the caller so they can log what was preserved.
+    return { deleted: false, skipped: true, foundValues: values, skippedTargets: unowned };
+  }
+
+  const response = await fetchWithRetry(
+    `${API_BASE}/zones/${zoneId}/rrsets/${relativeName}/${type}`,
+    {
+      method: 'DELETE',
+      headers: { Authorization: `Bearer ${apiToken}` },
+    },
+  );
+
+  return {
+    deleted: response.ok,
+    skipped: false,
+    foundValues: values,
+    skippedTargets: [],
+  };
+}
+
+// ============================================================================
+// HIGH-LEVEL SETUP FUNCTIONS
+// ============================================================================
+
+/**
+ * Set up Hetzner DNS for a simple single-server deployment.
+ * Creates root A and wildcard A records.
+ *
+ * @param {string} apiToken - Hetzner Cloud API token
+ * @param {string} zoneId - DNS zone ID
+ * @param {string} domain - Domain name (e.g. "app.example.com")
+ * @param {string} serverIp - Server IP address
+ * @param {object} [options] - Options
+ * @param {Function} [options.onProgress] - Progress callback (skips internal spinners)
+ * @returns {Promise<object>} Setup result
+ */
+export async function setupSimple(apiToken, zoneId, domain, serverIp, options = {}) {
+  const { onProgress } = options;
+  const s = onProgress ? null : p.spinner();
+
+  try {
+    s?.start(`Creating DNS records for ${domain}`);
+    onProgress?.(`Creating DNS records for ${domain}`);
+
+    // Fetch zone name for FQDN→relative conversion
+    const zone = await getZone(apiToken, zoneId);
+    const zoneName = zone.name;
+
+    // Root A record
+    await createDNSRecord(apiToken, zoneId, zoneName, {
+      type: 'A',
+      name: domain,
+      value: serverIp,
+      ttl: DEFAULT_TTL,
+    });
+
+    // Wildcard A record for subdomains (registry, api, etc.)
+    await createDNSRecord(apiToken, zoneId, zoneName, {
+      type: 'A',
+      name: `*.${domain}`,
+      value: serverIp,
+      ttl: DEFAULT_TTL,
+    });
+
+    s?.stop('DNS records created (root + wildcard)');
+    onProgress?.('DNS records created (root + wildcard)');
+
+    return { success: true, mode: 'simple' };
+  } catch (error) {
+    s?.stop(`Hetzner DNS setup failed: ${error.message}`);
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Set up Hetzner DNS for an HA deployment.
+ * Creates root A and wildcard A records pointing to the primary server,
+ * with a low TTL for fast failover propagation.
+ *
+ * Note: Hetzner DNS has no health checks or load balancers.
+ * Failover is triggered manually via `vibecarbon failover`.
+ *
+ * @param {string} apiToken - Hetzner Cloud API token
+ * @param {string} zoneId - DNS zone ID
+ * @param {string} domain - Domain name
+ * @param {Array} servers - Array of { name, ip } objects (primary first)
+ * @returns {Promise<object>} Setup result
+ */
+export async function setupHA(apiToken, zoneId, domain, servers) {
+  const s = p.spinner();
+
+  try {
+    // Fetch zone name for FQDN→relative conversion
+    const zone = await getZone(apiToken, zoneId);
+    const zoneName = zone.name;
+
+    // Root A record (low TTL for fast failover)
+    s.start(`Creating DNS record for ${domain}`);
+    await createDNSRecord(apiToken, zoneId, zoneName, {
+      type: 'A',
+      name: domain,
+      value: servers[0].ip,
+      ttl: HA_TTL,
+    });
+    s.stop('Primary DNS record created');
+
+    // Wildcard A record (low TTL for fast failover)
+    await createDNSRecord(apiToken, zoneId, zoneName, {
+      type: 'A',
+      name: `*.${domain}`,
+      value: servers[0].ip,
+      ttl: HA_TTL,
+    });
+
+    return {
+      success: true,
+      mode: 'dns',
+      primaryIp: servers[0].ip,
+      standbyIp: servers[1]?.ip,
+    };
+  } catch (error) {
+    s.stop(`Hetzner DNS setup failed: ${error.message}`);
+    return { success: false, error: error.message };
+  }
+}

package/src/lib/hetzner-guided-setup.js

@@ -0,0 +1,275 @@
+/**
+ * Hetzner Guided Setup - Interactive prompts for first-time setup
+ *
+ * This module provides improved DX for users setting up Hetzner credentials:
+ * 1. Creating a Hetzner API token
+ * 2. Creating S3 Object Storage credentials
+ *
+ * Features:
+ * - Clear visual guides with step-by-step instructions
+ * - Better validation and error messages
+ * - Lookup chain: env var → ~/.vibecarbon/credentials.json → interactive prompt
+ * - Single "Save keys for future deploys?" prompt applies to all credentials
+ */
+
+import * as p from '@clack/prompts';
+import { c } from './colors.js';
+import { loadCredentials, saveCredentials } from './config.js';
+
+/**
+ * Validate a Hetzner API token by making a lightweight API call.
+ * @param {string} token
+ * @returns {Promise<{ valid: boolean, error?: string }>}
+ */
+async function validateHetznerToken(token) {
+  try {
+    const res = await fetch('https://api.hetzner.cloud/v1/locations?per_page=1', {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (res.ok) return { valid: true };
+    if (res.status === 401) return { valid: false, error: 'Token is invalid or expired' };
+    return { valid: false, error: `Hetzner API returned status ${res.status}` };
+  } catch {
+    return { valid: true, unreachable: true };
+  }
+}
+
+/**
+ * Display improved visual guide for API token creation
+ */
+function displayApiTokenGuide(projectName) {
+  p.log.info('');
+  p.log.info(`${c.boldCyan('🔑 Hetzner API Token Setup')}`);
+  p.log.info('');
+  p.log.info(c.dim('─'.repeat(60)));
+  p.log.info('');
+  p.log.info(`${c.bold('1.')} Open: ${c.boldCyanUnderline('https://console.hetzner.cloud/')}`);
+  p.log.info(
+    `${c.dim('   └─')} Select ${c.info('+ New project')} and call it ${c.info(projectName || 'your-project')}`,
+  );
+  p.log.info('');
+  p.log.info(`${c.bold('2.')} In the sidebar: ${c.info('Security')}`);
+  p.log.info(`${c.dim('   └─')} Click the ${c.info('API tokens')} tab`);
+  p.log.info('');
+  p.log.info(`${c.bold('3.')} Click ${c.boldCyan('Generate API token')}`);
+  p.log.info(`${c.dim('   ├─')} Description: ${c.info(`"${projectName || 'vibecarbon'}-deploy"`)}`);
+  p.log.info(`${c.dim('   └─')} Permissions: ${c.info('Read & Write')} ${c.dim('(required)')}`);
+  p.log.info('');
+  p.log.info(`${c.bold('4.')} ${c.boldYellow('⚠️  Copy the token immediately')}`);
+  p.log.info(`${c.dim('   └─')} ${c.dim('It will only be shown once!')}`);
+  p.log.info('');
+  p.log.info(c.dim('─'.repeat(60)));
+  p.log.info('');
+}
+
+/**
+ * Display improved visual guide for S3 credentials creation
+ */
+function displayS3CredentialsGuide(projectName) {
+  p.log.info('');
+  p.log.info(`${c.boldCyan('🗄️  Hetzner Object Storage Setup')}`);
+  p.log.info('');
+  p.log.info(c.dim('─'.repeat(60)));
+  p.log.info('');
+  p.log.info(
+    `${c.bold('1.')} Click the ${c.info('S3 credentials')} tab ${c.dim('(you should already be on Security)')}`,
+  );
+  p.log.info('');
+  p.log.info(`${c.bold('2.')} Click ${c.boldCyan('Generate credentials')}`);
+  p.log.info(`${c.dim('   └─')} Description: ${c.info(`"${projectName || 'vibecarbon'}-s3"`)}`);
+
+  p.log.info('');
+  p.log.info(`${c.bold('3.')} ${c.boldYellow('⚠️  Copy BOTH credentials immediately:')}`);
+  p.log.info(`${c.dim('   ├─')} ${c.info('Access Key')} ${c.dim('(visible anytime)')}`);
+  p.log.info(`${c.dim('   └─')} ${c.info('Secret Key')} ${c.dim('(only shown once!)')}`);
+  p.log.info('');
+  p.log.info(c.dim('─'.repeat(60)));
+  p.log.info('');
+  p.note('Object Storage is required for database backups and file uploads', 'Why S3?');
+  p.log.info('');
+}
+
+// Session-level save preference: null = not asked yet, true/false = user's answer.
+// Once the user answers "Save keys for future deploys?" the decision applies to all
+// credentials prompted during this process.
+let _savePreference = null;
+
+/**
+ * Ask the user once whether to save credentials, then reuse the answer.
+ * @param {object} credentials - Credential object to merge-save
+ */
+export async function saveIfWanted(credentials) {
+  if (_savePreference === null) {
+    const shouldSave = await p.confirm({
+      message: 'Save keys for future deploys?',
+      initialValue: true,
+    });
+    _savePreference = shouldSave && !p.isCancel(shouldSave);
+  }
+
+  if (_savePreference) {
+    saveCredentials(credentials);
+    p.log.info(c.dim('Saved to ~/.vibecarbon/credentials.json'));
+  }
+}
+
+/**
+ * Reset the session-level save preference (for testing)
+ */
+export function resetSavePreference() {
+  _savePreference = null;
+}
+
+/**
+ * Get API token with improved visual guidance
+ * Lookup order: env var → credentials file → interactive prompt
+ *
+ * @param {string} [projectName] - Project name for display in guide
+ * @param {{ save?: boolean }} [options] - Options (save: offer to save, default true)
+ * @returns {Promise<string|null>}
+ */
+export async function getApiToken(projectName, options = {}) {
+  const { save = true } = options;
+
+  // 1. Check environment variable first
+  const envToken = process.env.HETZNER_API_TOKEN;
+  if (envToken) {
+    const check = await validateHetznerToken(envToken);
+    if (!check.valid) {
+      p.log.warn(`HETZNER_API_TOKEN environment variable is set but invalid: ${check.error}`);
+      // Fall through to credentials file / interactive prompt
+    } else {
+      if (check.unreachable) {
+        p.log.warn('Could not reach Hetzner API to verify token — proceeding with saved token');
+      }
+      p.log.info('✓ Using Hetzner API token from HETZNER_API_TOKEN environment variable');
+      return envToken;
+    }
+  }
+
+  // 2. Check credentials file
+  const creds = loadCredentials();
+  if (creds.hetzner?.apiToken) {
+    const check = await validateHetznerToken(creds.hetzner.apiToken);
+    if (!check.valid) {
+      p.log.warn(`Saved Hetzner API token is invalid: ${check.error}. Please enter a new one.`);
+      // Fall through to interactive prompt
+    } else {
+      if (check.unreachable) {
+        p.log.warn('Could not reach Hetzner API to verify token — proceeding with saved token');
+      }
+      p.log.info('✓ Using Hetzner API token from ~/.vibecarbon/credentials.json');
+      return creds.hetzner.apiToken;
+    }
+  }
+
+  // 3. Interactive prompt (with retry on invalid token)
+  displayApiTokenGuide(projectName);
+
+  let token;
+  while (true) {
+    token = await p.password({
+      message: 'Paste your Hetzner API token here',
+      validate: (v) => {
+        if (!v || v.length < 10) return 'API token is required';
+        if (v.length !== 64)
+          return 'Token should be 64 characters - please check you copied it correctly';
+        return undefined;
+      },
+    });
+
+    if (p.isCancel(token)) {
+      p.cancel('Operation cancelled.');
+      process.exit(0);
+    }
+
+    const s = p.spinner();
+    s.start('Verifying API token...');
+    const check = await validateHetznerToken(token);
+    if (check.valid) {
+      if (check.unreachable) {
+        s.stop('Could not reach Hetzner API — proceeding with unverified token');
+      } else {
+        s.stop('API token verified');
+      }
+      break;
+    }
+    s.stop(`Token invalid: ${check.error}`);
+    p.log.warn('Please try again with a valid token.');
+  }
+
+  if (save) {
+    await saveIfWanted({ hetzner: { apiToken: token } });
+  }
+
+  return token;
+}
+
+/**
+ * Get S3 credentials with improved visual guidance
+ * Lookup order: env vars → credentials file → interactive prompt
+ *
+ * @param {string} [projectName] - Project name for display in guide
+ * @param {{ save?: boolean, force?: boolean }} [options] - Options
+ *   save: offer to save credentials (default true)
+ *   force: skip env/file lookup and go straight to interactive prompt (default false)
+ * @returns {Promise<{accessKey: string, secretKey: string}|null>}
+ */
+export async function getS3Credentials(projectName, options = {}) {
+  const { save = true, force = false } = options;
+
+  if (!force) {
+    // 1. Check environment variables first
+    const envAccessKey = process.env.S3_ACCESS_KEY;
+    const envSecretKey = process.env.S3_SECRET_KEY;
+
+    if (envAccessKey && envSecretKey) {
+      p.log.info('✓ Using S3 credentials from environment variables');
+      return { accessKey: envAccessKey, secretKey: envSecretKey };
+    }
+
+    // 2. Check credentials file
+    const creds = loadCredentials();
+    if (creds.s3?.accessKey && creds.s3?.secretKey) {
+      p.log.info('✓ Using S3 credentials from ~/.vibecarbon/credentials.json');
+      return { accessKey: creds.s3.accessKey, secretKey: creds.s3.secretKey };
+    }
+  }
+
+  // 3. Interactive prompt
+  displayS3CredentialsGuide(projectName);
+
+  const accessKey = await p.text({
+    message: 'Paste your S3 Access Key here',
+    validate: (v) => {
+      if (!v || v.length < 10) return 'Access Key is required';
+      return undefined;
+    },
+  });
+
+  if (p.isCancel(accessKey)) {
+    p.cancel('Operation cancelled.');
+    process.exit(0);
+  }
+
+  const secretKey = await p.password({
+    message: 'Paste your S3 Secret Key here',
+    validate: (v) => {
+      if (!v || v.length < 10) return 'Secret Key is required';
+      return undefined;
+    },
+  });
+
+  if (p.isCancel(secretKey)) {
+    p.cancel('Operation cancelled.');
+    process.exit(0);
+  }
+
+  p.log.success('S3 credentials received!');
+
+  if (save) {
+    await saveIfWanted({ s3: { accessKey, secretKey } });
+  }
+
+  return { accessKey, secretKey };
+}

package/src/lib/host-keys.js

@@ -0,0 +1,37 @@
+import { chmodSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/**
+ * Absolute path to the per-environment known_hosts file for SSH strict-checking.
+ *
+ * NOTE: Permission enforcement below relies on POSIX modes and is a no-op on
+ * Windows. This CLI targets Linux/macOS developer machines and Linux servers.
+ *
+ * @param {string} env - environment name
+ * @param {string} [cwd=process.cwd()] - project root
+ * @returns {string}
+ */
+export function knownHostsPath(env, cwd = process.cwd()) {
+  return join(cwd, '.vibecarbon', `known_hosts_${env}`);
+}
+
+/**
+ * Overwrite the per-environment known_hosts file with the given host-key lines.
+ *
+ * Enforces `.vibecarbon/` mode 0o700 and file mode 0o600 unconditionally —
+ * `mkdirSync`/`writeFileSync` only apply `mode` on initial creation, so we
+ * follow each with `chmodSync` to guarantee the mode even when the target
+ * already exists (which it will on every re-pin after first deploy).
+ *
+ * @param {string} env
+ * @param {string[]} hostKeyLines - one host-key entry per element
+ * @param {string} [cwd=process.cwd()]
+ */
+export function pinHostKey(env, hostKeyLines, cwd = process.cwd()) {
+  const path = knownHostsPath(env, cwd);
+  const dir = dirname(path);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+  writeFileSync(path, `${hostKeyLines.join('\n')}\n`, { mode: 0o600 });
+  chmodSync(path, 0o600);
+}