@take-out/scripts 0.0.79 → 0.0.81

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@take-out/scripts",
-  "version": "0.0.79",
+  "version": "0.0.81",
   "type": "module",
   "main": "./src/run.ts",
   "sideEffects": false,
@@ -28,10 +28,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@take-out/helpers": "0.0.76"
+    "@take-out/helpers": "0.0.79"
   },
   "peerDependencies": {
-    "vxrn": "*"
+    "vxrn": "^1.4.15"
   },
   "peerDependenciesMeta": {
     "vxrn": {
@@ -39,6 +39,6 @@
     }
   },
   "devDependencies": {
-    "vxrn": "1.4.10-1770207233041"
+    "vxrn": "1.4.15"
   }
 }

package/src/helpers/github-tail.ts

@@ -0,0 +1,249 @@
+/**
+ * tail github actions ci logs for the latest run
+ */
+
+import { execSync, spawn } from 'node:child_process'
+
+export interface GithubTailOptions {
+  /** workflow name to look for (default: 'CI') */
+  workflowName?: string
+  /** job name to tail (default: 'build-test-and-deploy') */
+  jobName?: string
+  /** only show failed step logs */
+  showOnlyFailed?: boolean
+  /** force watch mode even for completed jobs */
+  forceWatch?: boolean
+}
+
+function getFailedStepLogs(jobId: string, stepName: string): string {
+  try {
+    const logs = execSync(
+      `gh run view --job ${jobId} --log 2>/dev/null | grep -A 100 -B 20 "${stepName}"`,
+      {
+        encoding: 'utf-8',
+        shell: '/bin/bash',
+        maxBuffer: 10 * 1024 * 1024,
+      }
+    )
+    return logs
+  } catch {
+    try {
+      const logs = execSync(`gh run view --job ${jobId} --log-failed 2>/dev/null`, {
+        encoding: 'utf-8',
+        maxBuffer: 10 * 1024 * 1024,
+      })
+      return logs
+    } catch {
+      return ''
+    }
+  }
+}
+
+async function watchJob(
+  runId: string,
+  jobId: string,
+  jobName: string,
+  showOnlyFailed: boolean
+) {
+  try {
+    const jobsJson = execSync(`gh run view ${runId} --json jobs`, {
+      encoding: 'utf-8',
+    })
+    const { jobs } = JSON.parse(jobsJson)
+    const job = jobs.find((j: any) => j.name === jobName)
+
+    if (job && job.status === 'completed') {
+      console.info(`\nJob already completed with conclusion: ${job.conclusion}\n`)
+
+      if (job.conclusion === 'failure') {
+        const failedSteps =
+          job.steps?.filter((s: any) => s.conclusion === 'failure') || []
+        if (failedSteps.length > 0) {
+          console.info(`❌ Failed step: ${failedSteps[0].name}\n`)
+          console.info('🔍 Showing failure details...\n')
+          console.info('─'.repeat(80))
+
+          const failureLogs = getFailedStepLogs(jobId, failedSteps[0].name)
+          if (failureLogs) {
+            console.info(failureLogs)
+          } else {
+            execSync(`gh run view --job ${jobId} --log-failed`, {
+              stdio: 'inherit',
+            })
+          }
+        } else {
+          execSync(`gh run view --job ${jobId} --log-failed`, {
+            stdio: 'inherit',
+          })
+        }
+      } else {
+        if (!showOnlyFailed) {
+          execSync(`gh run view --job ${jobId} --log`, {
+            stdio: 'inherit',
+          })
+        }
+      }
+
+      process.exit(job.conclusion === 'success' ? 0 : 1)
+    }
+  } catch {
+    // continue to watch mode
+  }
+
+  console.info('\n📡 Watching CI logs...\n')
+  console.info('─'.repeat(80))
+
+  const watchProcess = spawn('gh', ['run', 'watch', runId, '--exit-status'], {
+    stdio: 'inherit',
+  })
+
+  watchProcess.on('exit', async (code) => {
+    if (code !== 0) {
+      console.info('\n❌ CI failed! Getting detailed logs...\n')
+      console.info('─'.repeat(80))
+
+      try {
+        const jobsJson = execSync(`gh run view ${runId} --json jobs`, {
+          encoding: 'utf-8',
+        })
+        const { jobs } = JSON.parse(jobsJson)
+        const job = jobs.find((j: any) => j.name === jobName)
+
+        if (job) {
+          const failedSteps =
+            job.steps?.filter((s: any) => s.conclusion === 'failure') || []
+          if (failedSteps.length > 0) {
+            console.info(
+              `Failed steps: ${failedSteps.map((s: any) => s.name).join(', ')}\n`
+            )
+
+            for (const step of failedSteps) {
+              console.info(`\n━━━ Logs for failed step: ${step.name} ━━━\n`)
+              const stepLogs = getFailedStepLogs(jobId, step.name)
+              if (stepLogs) {
+                console.info(stepLogs)
+              }
+            }
+          }
+        }
+
+        console.info('\n━━━ Summary of all failed steps ━━━\n')
+        execSync(`gh run view --job ${jobId} --log-failed`, {
+          stdio: 'inherit',
+        })
+      } catch {
+        console.error('Could not retrieve detailed failure logs')
+      }
+    }
+
+    process.exit(code || 0)
+  })
+
+  process.on('SIGINT', () => {
+    watchProcess.kill()
+    process.exit(0)
+  })
+}
+
+export async function githubTail(options: GithubTailOptions = {}) {
+  const {
+    workflowName = 'CI',
+    jobName = 'build-test-and-deploy',
+    showOnlyFailed = false,
+    forceWatch = false,
+  } = options
+
+  try {
+    let latestCommit = execSync('git rev-parse HEAD', { encoding: 'utf-8' }).trim()
+    let shortCommit = latestCommit.substring(0, 7)
+
+    console.info(`Fetching CI logs for commit: ${shortCommit}`)
+
+    let runsJson = execSync(
+      `gh run list --commit ${latestCommit} --json databaseId,name,status,conclusion --limit 5`,
+      { encoding: 'utf-8' }
+    )
+    let runs = JSON.parse(runsJson)
+    let ciRun = runs.find((r: any) => r.name === workflowName)
+
+    if (!ciRun) {
+      console.info('No CI run found for local commit, checking remote...')
+
+      latestCommit = execSync('git rev-parse origin/main', { encoding: 'utf-8' }).trim()
+      shortCommit = latestCommit.substring(0, 7)
+
+      console.info(`Fetching CI logs for remote commit: ${shortCommit}`)
+
+      runsJson = execSync(
+        `gh run list --commit ${latestCommit} --json databaseId,name,status,conclusion --limit 5`,
+        { encoding: 'utf-8' }
+      )
+      runs = JSON.parse(runsJson)
+      ciRun = runs.find((r: any) => r.name === workflowName)
+
+      if (!ciRun) {
+        console.info('No CI run for remote HEAD, getting latest CI run...')
+        runsJson = execSync(
+          `gh run list --workflow=${workflowName} --json databaseId,name,status,conclusion,headSha --limit 1`,
+          { encoding: 'utf-8' }
+        )
+        runs = JSON.parse(runsJson)
+        ciRun = runs[0]
+
+        if (ciRun) {
+          shortCommit = ciRun.headSha?.substring(0, 7) || 'unknown'
+          console.info(`Using latest CI run for commit: ${shortCommit}`)
+        }
+      }
+    }
+
+    if (!ciRun) {
+      console.error('No CI runs found')
+      process.exit(1)
+    }
+
+    console.info(`CI Run: ${ciRun.status} (${ciRun.conclusion || 'in progress'})`)
+
+    const jobsJson = execSync(`gh run view ${ciRun.databaseId} --json jobs`, {
+      encoding: 'utf-8',
+    })
+    const { jobs } = JSON.parse(jobsJson)
+    const buildJob = jobs.find((j: any) => j.name === jobName)
+
+    if (!buildJob) {
+      console.error(`No ${jobName} job found`)
+      process.exit(1)
+    }
+
+    console.info(
+      `\nJob: ${buildJob.name} - ${buildJob.status} (${buildJob.conclusion || 'in progress'})`
+    )
+    console.info('─'.repeat(80))
+
+    if (buildJob.status === 'completed' && !forceWatch) {
+      const logFlag =
+        showOnlyFailed || buildJob.conclusion === 'failure' ? '--log-failed' : '--log'
+
+      if (buildJob.conclusion === 'failure') {
+        console.info('\n❌ Job failed! Showing failed steps...\n')
+      } else if (showOnlyFailed) {
+        console.info('\n🔍 Showing only failed steps...\n')
+      }
+
+      execSync(`gh run view --job ${buildJob.databaseId} ${logFlag}`, {
+        stdio: 'inherit',
+      })
+
+      process.exit(buildJob.conclusion === 'success' ? 0 : 1)
+    } else {
+      await watchJob(ciRun.databaseId, buildJob.databaseId, jobName, showOnlyFailed)
+    }
+  } catch (error: any) {
+    if (error.status === 1 && error.stdout?.includes('No jobs in progress')) {
+      console.info('Job completed. Run again to see full logs.')
+    } else {
+      console.error('Error fetching CI logs:', error.message)
+      process.exit(1)
+    }
+  }
+}

package/src/helpers/multipass.ts

@@ -0,0 +1,174 @@
+import { writeFileSync } from 'node:fs'
+
+import { sleep } from '@take-out/helpers'
+
+import { run } from './run'
+
+export interface MultipassConfig {
+  vmName: string
+  sshKeyPath: string
+}
+
+export function createMultipassConfig(
+  name: string,
+  sshKeyPath?: string
+): MultipassConfig {
+  return {
+    vmName: name,
+    sshKeyPath: sshKeyPath || `${process.env.HOME}/.ssh/${name}`,
+  }
+}
+
+export async function checkMultipass(): Promise<void> {
+  try {
+    await run('multipass --version', { silent: true })
+    console.info('✅ multipass installed')
+  } catch {
+    throw new Error('multipass not found - install: brew install multipass')
+  }
+}
+
+export async function getVMIP(config: MultipassConfig): Promise<string | null> {
+  try {
+    const { stdout } = await run(`multipass info ${config.vmName} --format json`, {
+      silent: true,
+      captureOutput: true,
+    })
+    const data = JSON.parse(stdout)
+    return data.info[config.vmName]?.ipv4?.[0] || null
+  } catch {
+    return null
+  }
+}
+
+export async function vmExists(config: MultipassConfig): Promise<boolean> {
+  try {
+    const { stdout } = await run('multipass list', { silent: true, captureOutput: true })
+    return stdout.includes(config.vmName)
+  } catch {
+    return false
+  }
+}
+
+export async function createVM(config: MultipassConfig): Promise<void> {
+  console.info('\n🖥️  creating multipass vm...\n')
+
+  if (await vmExists(config)) {
+    console.info(`✅ vm '${config.vmName}' already exists`)
+    return
+  }
+
+  const cloudInit = `#cloud-config
+package_update: true
+package_upgrade: true
+packages:
+  - curl
+`
+
+  const cloudInitPath = `${process.cwd()}/.cloud-init.yml`
+  writeFileSync(cloudInitPath, cloudInit)
+
+  try {
+    await run(
+      `multipass launch --name ${config.vmName} --cpus 4 --memory 4G --disk 20G --cloud-init ${cloudInitPath}`
+    )
+  } finally {
+    await run(`rm -f ${cloudInitPath}`, { silent: true })
+  }
+
+  console.info('\n⏳ waiting for vm to be ready...')
+
+  let attempts = 0
+  while (attempts < 30) {
+    try {
+      const { stdout } = await run(`multipass info ${config.vmName} --format json`, {
+        silent: true,
+        captureOutput: true,
+      })
+      const data = JSON.parse(stdout)
+      if (data.info[config.vmName]?.state === 'Running') {
+        break
+      }
+    } catch {
+      // vm not ready yet
+    }
+    await sleep(2000)
+    attempts++
+  }
+
+  // wait for cloud-init
+  console.info('waiting for cloud-init to complete...')
+  await sleep(10000)
+
+  try {
+    await run(`multipass exec ${config.vmName} -- timeout 300 cloud-init status --wait`)
+    console.info('✅ cloud-init complete')
+  } catch {
+    console.info('⚠️  cloud-init status check timed out, continuing...')
+  }
+
+  console.info('✅ vm ready')
+}
+
+export async function setupVMSSH(config: MultipassConfig): Promise<void> {
+  console.info('\n🔑 setting up ssh...\n')
+
+  try {
+    await run(`test -f ${config.sshKeyPath}`, { silent: true })
+    console.info('✅ ssh key exists')
+  } catch {
+    console.info('generating ssh key...')
+    await run(`ssh-keygen -t rsa -b 4096 -f ${config.sshKeyPath} -N ""`, { silent: true })
+    console.info('✅ ssh key generated')
+  }
+
+  const { stdout: pubKey } = await run(`cat ${config.sshKeyPath}.pub`, {
+    silent: true,
+    captureOutput: true,
+  })
+  await run(
+    `multipass exec ${config.vmName} -- sh -c 'mkdir -p ~/.ssh && echo "${pubKey.trim()}" >> ~/.ssh/authorized_keys'`
+  )
+  console.info('✅ ssh key configured')
+}
+
+export async function setupPortForward(
+  config: MultipassConfig,
+  ports: { local: number; containerName: string; containerPort: number }[]
+): Promise<void> {
+  console.info('\n🌐 setting up port forwarding...\n')
+
+  const ip = await getVMIP(config)
+  if (!ip) {
+    console.error('❌ could not get vm ip')
+    return
+  }
+
+  const forwards: string[] = []
+  for (const { local, containerName, containerPort } of ports) {
+    const { stdout: containerIP } = await run(
+      `multipass exec ${config.vmName} -- sudo docker inspect $(multipass exec ${config.vmName} -- sudo docker ps -q -f name=${containerName}) -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}'`,
+      { silent: true, captureOutput: true }
+    )
+    console.info(`${containerName} container: ${containerIP.trim()}:${containerPort}`)
+    forwards.push(`-L ${local}:${containerIP.trim()}:${containerPort}`)
+  }
+
+  // kill any existing port forwards
+  try {
+    await run(`pkill -f "ssh.*${config.vmName}"`, { silent: true })
+  } catch {
+    // ignore if none found
+  }
+
+  for (const { local, containerName, containerPort } of ports) {
+    console.info(`forwarding localhost:${local} -> ${containerName}:${containerPort}`)
+  }
+
+  await run(
+    `ssh -i ${config.sshKeyPath} -o StrictHostKeyChecking=no -f -N ${forwards.join(' ')} ubuntu@${ip}`,
+    { silent: true }
+  )
+
+  console.info('✅ port forwarding active')
+}

package/src/helpers/parse-env-file.ts

@@ -0,0 +1,71 @@
+/**
+ * parse a .env file, handling multi-line quoted values (PEM keys etc)
+ */
+export function parseEnvFile(
+  content: string,
+  options?: { allowedKeys?: string[] }
+): Record<string, string> {
+  const result: Record<string, string> = {}
+  const lines = content.split('\n')
+  let currentKey: string | null = null
+  let currentValue: string[] = []
+  let inMultiline = false
+
+  const save = () => {
+    if (!currentKey) return
+    if (options?.allowedKeys && !options.allowedKeys.includes(currentKey)) {
+      currentKey = null
+      currentValue = []
+      inMultiline = false
+      return
+    }
+    let value = currentValue.join('\n')
+    // remove surrounding quotes
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1)
+    }
+    value = value.replace(/\\"/g, '"')
+    result[currentKey] = value
+    currentKey = null
+    currentValue = []
+    inMultiline = false
+  }
+
+  for (const line of lines) {
+    if (inMultiline) {
+      currentValue.push(line)
+      if (line.trim().endsWith('"') || line.trim().endsWith("'")) {
+        save()
+      }
+      continue
+    }
+
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+
+    const match = trimmed.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/)
+    if (match && match[1]) {
+      if (currentKey) save()
+
+      currentKey = match[1]
+      const valueStart = match[2] || ''
+
+      if (
+        (valueStart.startsWith('"') && !valueStart.endsWith('"')) ||
+        (valueStart.startsWith("'") && !valueStart.endsWith("'"))
+      ) {
+        inMultiline = true
+        currentValue = [valueStart]
+      } else {
+        currentValue = [valueStart]
+        save()
+      }
+    }
+  }
+  if (currentKey) save()
+
+  return result
+}

package/src/helpers/process-compose-env.ts

@@ -0,0 +1,44 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+
+// collapse multi-line values (like PEM keys) to single line for yaml compatibility
+function yamlSafe(value: string): string {
+  if (value.includes('\n')) {
+    return value.replace(/\n/g, '\\n')
+  }
+  return value
+}
+
+/**
+ * processes docker-compose file, replacing ${VAR:-default} with actual env values.
+ * handles multi-line values (PEM keys etc) by escaping newlines for yaml.
+ */
+export function processComposeEnv(
+  composeFile: string,
+  outputFile: string,
+  envVars: Record<string, string | undefined>
+): void {
+  let content = readFileSync(composeFile, 'utf-8')
+
+  // replace all ${VAR:-default} patterns with actual env values
+  content = content.replace(
+    /\$\{([A-Z_][A-Z0-9_]*):-([^}]*)\}/g,
+    (_match, varName, defaultValue) => {
+      const value = envVars[varName]
+      if (value) {
+        console.info(
+          `  ${varName}: ${value.slice(0, 50)}${value.length > 50 ? '...' : ''}`
+        )
+      }
+      return value ? yamlSafe(value) : defaultValue
+    }
+  )
+
+  // replace standalone ${VAR} patterns
+  content = content.replace(/\$\{([A-Z_][A-Z0-9_]*)\}/g, (_match, varName) => {
+    const value = envVars[varName]
+    return value ? yamlSafe(value) : _match
+  })
+
+  writeFileSync(outputFile, content)
+  console.info(`✅ processed compose file: ${outputFile}`)
+}

package/src/helpers/ssh.ts

@@ -0,0 +1,23 @@
+import { run } from './run'
+
+export async function checkSSHKey(sshKeyPath: string): Promise<void> {
+  try {
+    await run(`test -f ${sshKeyPath}`, { silent: true })
+    console.info('✅ ssh key exists')
+  } catch {
+    throw new Error(`ssh key not found: ${sshKeyPath}`)
+  }
+}
+
+export async function testSSHConnection(host: string, sshKey: string): Promise<void> {
+  console.info('\n🔑 testing ssh connection...\n')
+
+  try {
+    await run(
+      `ssh -i ${sshKey} -o StrictHostKeyChecking=no -o ConnectTimeout=5 ${host} "echo 'SSH connection successful'"`
+    )
+    console.info('✅ ssh connection verified')
+  } catch {
+    throw new Error(`cannot connect to ${host} - check ssh key: ${sshKey}`)
+  }
+}

package/src/helpers/uncloud-deploy.ts

@@ -0,0 +1,140 @@
+/**
+ * generic uncloud deployment helpers for ci/cd
+ */
+
+import { existsSync } from 'node:fs'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+import { time } from '@take-out/helpers'
+
+import { run } from './run'
+
+export async function checkUncloudConfigured(): Promise<boolean> {
+  return Boolean(process.env.DEPLOY_HOST && process.env.DEPLOY_DB)
+}
+
+export async function verifyDatabaseConfig(): Promise<{
+  valid: boolean
+  errors: string[]
+}> {
+  const errors: string[] = []
+
+  const deployDb = process.env.DEPLOY_DB
+  const upstreamDb = process.env.ZERO_UPSTREAM_DB
+  const cvrDb = process.env.ZERO_CVR_DB
+  const changeDb = process.env.ZERO_CHANGE_DB
+
+  if (!deployDb) errors.push('DEPLOY_DB is not set')
+  if (!upstreamDb) errors.push('ZERO_UPSTREAM_DB is not set')
+  if (!cvrDb) errors.push('ZERO_CVR_DB is not set')
+  if (!changeDb) errors.push('ZERO_CHANGE_DB is not set')
+
+  if (errors.length > 0) {
+    return { valid: false, errors }
+  }
+
+  const getHost = (url: string): string | null => {
+    try {
+      const match = url.match(/@([^:/]+)/)
+      return match?.[1] || null
+    } catch {
+      return null
+    }
+  }
+
+  const deployHost = getHost(deployDb!)
+  const upstreamHost = getHost(upstreamDb!)
+  const cvrHost = getHost(cvrDb!)
+  const changeHost = getHost(changeDb!)
+
+  if (deployHost && upstreamHost && deployHost !== upstreamHost) {
+    errors.push(
+      `ZERO_UPSTREAM_DB host (${upstreamHost}) does not match DEPLOY_DB host (${deployHost})`
+    )
+  }
+  if (deployHost && cvrHost && deployHost !== cvrHost) {
+    errors.push(
+      `ZERO_CVR_DB host (${cvrHost}) does not match DEPLOY_DB host (${deployHost})`
+    )
+  }
+  if (deployHost && changeHost && deployHost !== changeHost) {
+    errors.push(
+      `ZERO_CHANGE_DB host (${changeHost}) does not match DEPLOY_DB host (${deployHost})`
+    )
+  }
+
+  return { valid: errors.length === 0, errors }
+}
+
+export async function installUncloudCLI(version = '0.16.0') {
+  console.info('🔧 checking uncloud cli...')
+  try {
+    await run('uc --version', { silent: true, timeout: time.ms.seconds(5) })
+    console.info('  uncloud cli already installed')
+  } catch {
+    console.info(`  installing uncloud cli v${version}...`)
+    await run(
+      `curl -fsS https://get.uncloud.run/install.sh | sh -s -- --version ${version}`,
+      { timeout: time.ms.seconds(30) }
+    )
+    console.info('  ✓ uncloud cli installed')
+  }
+}
+
+export async function setupSSHKey() {
+  if (!process.env.DEPLOY_SSH_KEY) {
+    return
+  }
+
+  const sshKeyValue = process.env.DEPLOY_SSH_KEY
+
+  // check if it's a path to an existing file (local usage) or key content (CI usage)
+  if (existsSync(sshKeyValue)) {
+    console.info(`  using ssh key from: ${sshKeyValue}`)
+    return
+  }
+
+  // CI usage - DEPLOY_SSH_KEY contains the actual key content
+  console.info('🔑 setting up ssh key from environment...')
+  const sshDir = join(homedir(), '.ssh')
+  const keyPath = join(sshDir, 'uncloud_deploy')
+
+  if (!existsSync(sshDir)) {
+    await mkdir(sshDir, { recursive: true })
+  }
+
+  // decode base64-encoded keys (github secrets often store keys as base64)
+  let keyContent = sshKeyValue
+  if (
+    !sshKeyValue.includes('-----BEGIN') &&
+    /^[A-Za-z0-9+/=\s]+$/.test(sshKeyValue.trim())
+  ) {
+    console.info('  detected base64-encoded key, decoding...')
+    keyContent = Buffer.from(sshKeyValue.trim(), 'base64').toString('utf-8')
+  }
+
+  // ensure trailing newline (github secrets can strip it)
+  if (!keyContent.endsWith('\n')) {
+    keyContent += '\n'
+  }
+
+  await writeFile(keyPath, keyContent, { mode: 0o600 })
+
+  // add host to known_hosts
+  if (process.env.DEPLOY_HOST) {
+    try {
+      await run(
+        `ssh-keyscan -H ${process.env.DEPLOY_HOST} >> ${join(sshDir, 'known_hosts')}`,
+        { silent: true, timeout: time.ms.seconds(10) }
+      )
+    } catch {
+      // ignore - ssh will prompt if needed
+    }
+  }
+
+  // override env var to point to the file we created
+  process.env.DEPLOY_SSH_KEY = keyPath
+  console.info(`  ssh key written to ${keyPath}`)
+}

package/src/helpers/uncloud.ts

@@ -0,0 +1,187 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+import { run } from './run'
+
+export interface UncloudConfig {
+  context?: string
+}
+
+function ucCmd(config?: UncloudConfig): string {
+  return config?.context ? `uc -c ${config.context}` : 'uc'
+}
+
+export async function checkUncloudCLI(): Promise<void> {
+  try {
+    const { stdout } = await run('uc --version', { silent: true, captureOutput: true })
+    console.info(`✅ uncloud cli installed (${stdout.trim()})`)
+  } catch {
+    throw new Error(
+      `uncloud cli not found - install: curl -fsS https://get.uncloud.run/install.sh | sh`
+    )
+  }
+}
+
+function ensureUncloudContext(host: string, sshKey: string, contextName: string): void {
+  const configDir = join(homedir(), '.config', 'uncloud')
+  const configPath = join(configDir, 'config.yaml')
+
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true })
+  }
+
+  // check if config already has context pointing to correct host
+  if (existsSync(configPath)) {
+    const existing = readFileSync(configPath, 'utf-8')
+    if (existing.includes(`${contextName}:`) && existing.includes(host.split('@')[1])) {
+      console.info(`✅ uncloud config already has ${contextName} context for ${host}`)
+      return
+    }
+  }
+
+  // only create config if it doesn't exist - don't overwrite existing config
+  // which may have other contexts
+  if (!existsSync(configPath)) {
+    const config = `current_context: ${contextName}
+contexts:
+  ${contextName}:
+    connections:
+      - ssh: ${host}
+        ssh_key_file: ${sshKey}
+`
+    writeFileSync(configPath, config)
+    console.info(`✅ created uncloud config at ${configPath}`)
+  } else {
+    console.info(`✅ using existing uncloud config (context: ${contextName})`)
+  }
+}
+
+export async function initUncloud(
+  host: string,
+  sshKey: string,
+  options: { noDNS?: boolean; noCaddy?: boolean; context?: string } = {}
+): Promise<void> {
+  console.info('\n🚀 initializing uncloud...\n')
+
+  const uc = ucCmd(options)
+  const contextName = options.context || 'default'
+
+  // check if we already have local context that works
+  try {
+    await run(`${uc} ls`, { silent: true })
+    console.info('✅ local cluster context exists and connected')
+    return
+  } catch {
+    // no local context - check if server has uncloud running
+  }
+
+  const sshCmd = `ssh -i ${sshKey} -o StrictHostKeyChecking=no ${host}`
+
+  // check if server already has uncloud daemon running
+  let serverHasUncloud = false
+  try {
+    await run(`${sshCmd} "systemctl is-active uncloud.service"`, { silent: true })
+    serverHasUncloud = true
+    console.info('✅ server has uncloud daemon running')
+  } catch {
+    try {
+      await run(`${sshCmd} "test -f /usr/local/bin/uncloudd"`, { silent: true })
+      serverHasUncloud = true
+      console.info('✅ server has uncloud installed')
+    } catch {
+      // server doesn't have uncloud - needs fresh init
+    }
+  }
+
+  if (serverHasUncloud) {
+    ensureUncloudContext(host, sshKey, contextName)
+    console.info('   (skipping init to avoid cluster reset)')
+    return
+  }
+
+  // fresh server - need to initialize
+  console.info('📦 uncloud not installed on server - initializing...')
+
+  const flags: string[] = []
+  if (options.noDNS) flags.push('--no-dns')
+  if (options.noCaddy) flags.push('--no-caddy')
+  const flagStr = flags.join(' ')
+
+  await run(`echo "y" | uc machine init ${host} -i ${sshKey} ${flagStr}`)
+
+  console.info('✅ uncloud initialized')
+}
+
+export async function pushImage(
+  imageName: string,
+  config?: UncloudConfig
+): Promise<void> {
+  console.info('\n📤 pushing image to cluster...\n')
+
+  await run(`${ucCmd(config)} image push ${imageName}`)
+  console.info('✅ image pushed')
+}
+
+export async function deployStack(
+  composeFile: string,
+  options?: { profile?: string } & UncloudConfig
+): Promise<void> {
+  console.info('\n📦 deploying stack...\n')
+
+  const profileFlag = options?.profile ? `--profile ${options.profile}` : ''
+  // --recreate ensures containers are recreated even if config unchanged (pulls fresh images)
+  await run(`${ucCmd(options)} deploy -f ${composeFile} ${profileFlag} --recreate --yes`)
+
+  console.info('\n✅ deployment complete!')
+}
+
+export async function showStatus(config?: UncloudConfig): Promise<void> {
+  console.info('\n📊 deployment status:\n')
+
+  try {
+    await run(`${ucCmd(config)} ls`)
+  } catch {
+    console.error('could not fetch status')
+  }
+}
+
+export async function showContainers(config?: UncloudConfig): Promise<void> {
+  console.info('\n📦 container status:\n')
+
+  try {
+    await run(`${ucCmd(config)} ps`)
+  } catch {
+    console.error('could not fetch container status')
+  }
+}
+
+export async function startService(
+  service?: string,
+  config?: UncloudConfig
+): Promise<void> {
+  const target = service || 'all services'
+  console.info(`\n▶️  starting ${target}...\n`)
+
+  try {
+    await run(`${ucCmd(config)} start${service ? ` ${service}` : ''}`)
+    console.info(`✅ ${target} started`)
+  } catch {
+    throw new Error(`failed to start ${target}`)
+  }
+}
+
+export async function stopService(
+  service?: string,
+  config?: UncloudConfig
+): Promise<void> {
+  const target = service || 'all services'
+  console.info(`\n⏹️  stopping ${target}...\n`)
+
+  try {
+    await run(`${ucCmd(config)} stop${service ? ` ${service}` : ''}`)
+    console.info(`✅ ${target} stopped`)
+  } catch {
+    throw new Error(`failed to stop ${target}`)
+  }
+}