ninedeploy 0.10.5 → 0.16.0

package/src/commands/doctor.ts

@@ -0,0 +1,170 @@
+import { existsSync, mkdirSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import type { NineDeployClient } from '../client.js';
+import { loadConfig } from '../config.js';
+import { c, header, kv } from '../lib/format.js';
+import { getContainerState, isDockerAvailable, isServerReachable, startServerContainer } from '../lib/serverRunner.js';
+
+export interface DoctorOptions {
+  fix?: boolean;
+}
+
+export async function doctorAction(client: NineDeployClient, opts: DoctorOptions = {}): Promise<void> {
+  header('NineDeploy Doctor Diagnostics');
+
+  let issues = 0;
+  const prescriptions: string[] = [];
+  const fixes: string[] = [];
+
+  // 1. Environment & Memory Diagnostics
+  console.log(`  ${c.bold('1. Local Environment & Memory:')}`);
+  kv('Node.js', `${process.version} (${process.arch})`);
+  kv('Platform', `${os.platform()} (${os.release()})`);
+  const totalRamGb = (os.totalmem() / (1024 * 1024 * 1024)).toFixed(1);
+  const freeRamGb = (os.freemem() / (1024 * 1024 * 1024)).toFixed(1);
+  kv('System Memory', `${freeRamGb} GB free / ${totalRamGb} GB total`);
+
+  // Swap space check (Linux)
+  /* v8 ignore start */
+  if (os.platform() === 'linux') {
+    try {
+      const fs = await import('node:fs/promises');
+      const meminfo = await fs.readFile('/proc/meminfo', 'utf8').catch(() => '');
+      const swapMatch = meminfo.match(/SwapTotal:\s+(\d+)\s+kB/);
+      const swapKb = swapMatch?.[1] ? Number.parseInt(swapMatch[1], 10) : 0;
+      const swapMb = Math.round(swapKb / 1024);
+      if (swapMb < 1024 && Number.parseFloat(totalRamGb) <= 4) {
+        kv('Swap Memory', c.yellow(`${swapMb} MB (Low - recommended ≥ 2GB for heavy Docker pulls)`));
+        prescriptions.push('Allocate 2GB swap space: sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile');
+      } else {
+        kv('Swap Memory', c.green(`${swapMb} MB`));
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+  /* v8 ignore stop */
+  console.log();
+
+  // 2. Docker & Process Engine Diagnostics
+  console.log(`  ${c.bold('2. Docker & Process Daemon:')}`);
+  const dockerOk = await isDockerAvailable();
+  if (dockerOk) {
+    kv('Docker CLI', c.green('available'));
+    const container = await getContainerState('ninedeploy');
+    if (container.exists) {
+      kv('Docker Container', container.running ? c.green('running') : c.yellow('stopped'));
+      if (!container.running) {
+        if (opts.fix) {
+          try {
+            await startServerContainer({});
+            fixes.push('Started stopped ninedeploy Docker container.');
+          } catch (err) {
+            prescriptions.push(`Start server container: ninedeploy server start (${String(err)})`);
+          }
+        } else {
+          prescriptions.push('Start server container: ninedeploy server start');
+        }
+      }
+    } else {
+      kv('Docker Container', c.gray('not in use (baremetal / systemd mode)'));
+    }
+  } else {
+    kv('Docker CLI', c.yellow('not found or daemon not running'));
+    prescriptions.push('Install or start Docker Engine: sudo systemctl start docker (or https://docs.docker.com/engine/install/)');
+    issues++;
+  }
+  console.log();
+
+  // 3. Local Storage & Database Integrity
+  console.log(`  ${c.bold('3. Local Storage & Database:')}`);
+  /* v8 ignore start */
+  const optDataDir = '/opt/ninedeploy/.data';
+  const defaultDataDir = existsSync(path.resolve(process.cwd(), '.data'))
+    ? path.resolve(process.cwd(), '.data')
+    : (existsSync(optDataDir) ? optDataDir : path.resolve(process.cwd(), '.data'));
+  const dbFile = path.join(defaultDataDir, 'ninedeploy.db');
+  if (existsSync(defaultDataDir)) {
+    kv('.data Directory', c.green(`exists (${defaultDataDir})`));
+    if (existsSync(dbFile)) {
+      try {
+        const stats = statSync(dbFile);
+        kv('SQLite Database', c.green(`present (${(stats.size / 1024).toFixed(1)} KB)`));
+      } catch {
+        kv('SQLite Database', c.yellow('found (unable to read stats)'));
+      }
+    } else {
+      kv('SQLite Database', c.gray('fresh (will be created on first start)'));
+    }
+  } else {
+    kv('.data Directory', c.gray('not present in cwd or /opt/ninedeploy'));
+    if (opts.fix) {
+      try {
+        mkdirSync(defaultDataDir, { recursive: true });
+        fixes.push('Created missing .data directory.');
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  /* v8 ignore stop */
+  console.log();
+
+  // 4. Server Reachability & API Health
+  const cfg = loadConfig();
+  console.log(`  ${c.bold('4. NineDeploy Server:')}`);
+  kv('Target URL', cfg.baseUrl);
+  const start = Date.now();
+  const reachable = await isServerReachable(cfg.baseUrl, 1500);
+  const latency = Date.now() - start;
+  if (reachable) {
+    kv('Connectivity', c.green(`connected (${latency}ms)`));
+  } else {
+    kv('Connectivity', c.red('unreachable'));
+    prescriptions.push(`Ensure NineDeploy is running at ${cfg.baseUrl}: sudo systemctl status ninedeploy (or ninedeploy server start)`);
+    issues++;
+  }
+  console.log();
+
+  // 5. Authentication Check
+  console.log(`  ${c.bold('5. Authentication & Credentials:')}`);
+  if (!cfg.token) {
+    kv('Session', c.yellow('not logged in (run `ninedeploy login` or `ninedeploy setup`)'));
+  } else {
+    try {
+      const user = await client.auth.me();
+      kv('Logged In User', `${user.email} (${user.isOperator ? 'operator' : 'member'})`);
+      kv('Token Status', c.green('valid'));
+    } catch {
+      kv('Token Status', c.red('invalid or expired'));
+      prescriptions.push('Re-authenticate: ninedeploy login (or ninedeploy setup)');
+      issues++;
+    }
+  }
+  console.log();
+
+  // Summary & Prescriptions
+  if (fixes.length > 0) {
+    console.log(`  ${c.bold('Healed Issues (--fix):')}`);
+    for (const fix of fixes) {
+      console.log(`    ${c.green('✓')} ${fix}`);
+    }
+    console.log();
+  }
+
+  if (prescriptions.length > 0) {
+    console.log(`  ${c.bold('Prescriptions & Solutions:')}`);
+    for (const rx of prescriptions) {
+      console.log(`    ${c.cyan('➜')} ${rx}`);
+    }
+    console.log();
+  }
+
+  if (issues === 0) {
+    console.log(`  ${c.green('✓ All critical checks passed. NineDeploy CLI is ready.')}\n`);
+  } else {
+    console.log(`  ${c.yellow(`! Found ${issues} issue(s). Check the items marked in red above.`)}\n`);
+  }
+}

package/src/commands/domains.ts

@@ -0,0 +1,170 @@
+/**
+ * `ninedeploy domains preset {list,apply}` — Sprint 2, Gap G-07, PR-D.
+ *
+ * The plugin (G-07 PR-C) reacts to the audit firehose so a `domain.add`
+ * from the panel can create the matching DNS record on its own. This
+ * CLI subcommand lets an operator do the same thing on demand without
+ * having to round-trip through the panel's domain flow — useful when a
+ * record is missing after a partial outage, or when an operator is
+ * testing the DNS pipeline against a fresh hostname.
+ *
+ * Split:
+ *   - `list` calls `GET /v1/domain-presets` and prints the registered
+ *     `IDomainProvider` names so the operator can sanity-check the
+ *     kernel boot before chasing a misconfiguration on the provider
+ *     side.
+ *   - `apply <hostname>` calls `POST /v1/domain-presets/apply`, which
+ *     resolves the active provider from the existing
+ *     `dns_records_provider` setting, calls `findZoneForHost` +
+ *     `createRecord` on it, and emits a `domain.preset.manual` audit
+ *     event so the panel's activity log mirrors what the audit-bus path
+ *     produces. The `--content` flag lets the operator override the
+ *     resolved record content (handy for CNAME setups or smoke tests).
+ */
+import type { NineDeployClient } from '../client.js';
+import { error, header, info, success } from '../lib/format.js';
+
+export interface DomainsPresetApplyOptions {
+  /** Optional override for the record content (e.g. an explicit CNAME target). */
+  content?: string;
+}
+
+// ── `ninedeploy domains preset list` ────────────────────────────────────────
+
+/**
+ * Pure entry point — same shape used by the CLI action and the unit
+ * test. Returns the parsed provider list so the test can assert it
+ * without depending on stdout framing.
+ */
+export async function domainsPresetList(
+  client: NineDeployClient,
+): Promise<{ providers: string[] }> {
+  return await client.domainPresets.list();
+}
+
+export async function domainsPresetListAction(client: NineDeployClient): Promise<void> {
+  header('Domain presets');
+  let result: { providers: string[] };
+  try {
+    result = await domainsPresetList(client);
+  } catch (err) {
+    error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+  if (result.providers.length === 0) {
+    info('No IDomainProvider drivers are registered on this kernel.');
+    info('Set dns_records_provider in Settings → DNS to enable one.');
+    return;
+  }
+  for (const name of result.providers) {
+    info(`• ${name}`);
+  }
+}
+
+// ── `ninedeploy domains preset apply <hostname>` ────────────────────────────
+
+/**
+ * Pure entry point — same shape used by the CLI action and the unit
+ * test. Returns the upstream response so the test can assert it
+ * without depending on stdout framing.
+ */
+export async function domainsPresetApply(
+  client: NineDeployClient,
+  hostname: string,
+  opts: DomainsPresetApplyOptions = {},
+): Promise<{
+  hostname: string;
+  provider: string;
+  zone: string;
+  recordId: string;
+  type: 'A' | 'CNAME';
+  content: string;
+}> {
+  return await client.domainPresets.apply({ hostname, content: opts.content });
+}
+
+export async function domainsPresetApplyAction(
+  client: NineDeployClient,
+  hostname: string,
+  opts: DomainsPresetApplyOptions = {},
+): Promise<void> {
+  header('Domain preset apply');
+
+  if (!hostname) {
+    error('Usage: ninedeploy domains preset apply <hostname> [--content <value>]');
+    process.exitCode = 1;
+    return;
+  }
+
+  let result: Awaited<ReturnType<typeof domainsPresetApply>>;
+  try {
+    result = await domainsPresetApply(client, hostname, opts);
+  } catch (err) {
+    error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+
+  success(`Applied ${result.type} record for ${result.hostname}`);
+  info(`Provider: ${result.provider}`);
+  info(`Zone:     ${result.zone}`);
+  info(`Record:   ${result.recordId}`);
+  info(`Content:  ${result.content}`);
+}
+
+// ── `ninedeploy domains preset add namecheap` ────────────────────────────
+
+export interface DomainsPresetAddNamecheapOptions {
+  /** Namecheap username (the account owner). */
+  apiUser?: string;
+  /** Namecheap API key (encrypted at rest by the server). */
+  apiKey?: string;
+  /** Whitelisted public IP of the server. */
+  clientIp?: string;
+}
+
+/**
+ * Pure entry point for the Namecheap credential upsert. The handler
+ * shape mirrors the rest of the file (returns the upstream response,
+ * the action layer frames stdout/exit-code).
+ */
+export async function domainsPresetAddNamecheap(
+  client: NineDeployClient,
+  opts: DomainsPresetAddNamecheapOptions,
+): Promise<{ ok: boolean; apiUser: string }> {
+  if (!opts.apiUser || !opts.apiKey || !opts.clientIp) {
+    throw new Error('Missing required flags: --api-user, --api-key, --client-ip');
+  }
+  return await client.settings.namecheap.set({
+    apiUser: opts.apiUser,
+    apiKey: opts.apiKey,
+    clientIp: opts.clientIp,
+  });
+}
+
+export async function domainsPresetAddNamecheapAction(
+  client: NineDeployClient,
+  opts: DomainsPresetAddNamecheapOptions,
+): Promise<void> {
+  header('Domain preset add (Namecheap)');
+
+  if (!opts.apiUser || !opts.apiKey || !opts.clientIp) {
+    error('Usage: ninedeploy domains preset add namecheap --api-user <u> --api-key <k> --client-ip <ip>');
+    error('The client IP must already be whitelisted on the Namecheap account panel.');
+    process.exitCode = 1;
+    return;
+  }
+
+  let result: Awaited<ReturnType<typeof domainsPresetAddNamecheap>>;
+  try {
+    result = await domainsPresetAddNamecheap(client, opts);
+  } catch (err) {
+    error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+
+  success(`Saved Namecheap credentials for ${result.apiUser}`);
+  info('Set dns_records_provider=namecheap in Settings → DNS to use them.');
+}

package/src/commands/egress.ts

@@ -0,0 +1,135 @@
+/**
+ * `ninedeploy egress {list,set,clear}` — Sprint 5, Gap G-15.
+ *
+ * Operator-side wrapper around the active `IEgressIpDriver`. The
+ * CLI is the canonical way to attach a stable outbound IP to a
+ * project: hosting providers run `ninedeploy egress set <projectId>
+ * <ip>` after the project is created, and the next deploy's
+ * `service.deployed` event fires the matching iptables SNAT.
+ */
+import type { NineDeployClient } from '../client.js';
+import { error, header, info, success } from '../lib/format.js';
+
+export interface EgressRule {
+  selector: { projectId: number; sourceCidr?: string };
+  ip: string;
+  createdAt: string;
+}
+
+export interface EgressDriverView {
+  name: string;
+  rules: EgressRule[];
+}
+
+// ── `ninedeploy egress list` ──────────────────────────────────────────────
+
+/** Pure entry point — same shape used by the CLI action and the unit test. */
+export async function egressList(client: NineDeployClient): Promise<{ drivers: EgressDriverView[] }> {
+  return await client.egress.list();
+}
+
+export async function egressListAction(client: NineDeployClient): Promise<void> {
+  header('Egress IP rules');
+  let result: { drivers: EgressDriverView[] };
+  try {
+    result = await egressList(client);
+  } catch (err) {
+    error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+  if (result.drivers.length === 0) {
+    info('No egress IP drivers are registered. Install one via Settings → Plugins.');
+    return;
+  }
+  for (const d of result.drivers) {
+    info(`Driver: ${d.name}`);
+    if (d.rules.length === 0) {
+      info('  (no rules)');
+    } else {
+      for (const r of d.rules) {
+        info(`  project ${r.selector.projectId} → ${r.ip}  (since ${r.createdAt})`);
+      }
+    }
+  }
+}
+
+// ── `ninedeploy egress set <projectId> <ip>` ──────────────────────────────
+
+/** Pure entry point — same shape used by the CLI action and the unit test. */
+export async function egressSet(
+  client: NineDeployClient,
+  projectId: number,
+  ip: string,
+  driver?: string,
+): Promise<{ ok: boolean; driver: string; rule: EgressRule; error?: string }> {
+  return await client.egress.set({ projectId, ip, driver });
+}
+
+export async function egressSetAction(
+  client: NineDeployClient,
+  projectIdStr: string,
+  ip: string,
+  opts: { driver?: string } = {},
+): Promise<void> {
+  const projectId = Number(projectIdStr);
+  if (!Number.isFinite(projectId)) {
+    error('Usage: ninedeploy egress set <projectId> <ip> [--driver <name>]');
+    process.exitCode = 1;
+    return;
+  }
+  let result: Awaited<ReturnType<typeof egressSet>>;
+  try {
+    result = await egressSet(client, projectId, ip, opts.driver);
+  } catch (err) {
+    error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+  // r198: the route answers a refusal as 200 `{ ok: false, error }`; this
+  // used to dereference the missing `rule` and crash with a TypeError.
+  if (!result.ok) {
+    error(result.error ?? 'Egress IP attach was refused');
+    process.exitCode = 1;
+    return;
+  }
+  success(`Egress IP ${result.rule.ip} attached to project ${projectId} via ${result.driver}`);
+}
+
+// ── `ninedeploy egress clear <projectId>` ────────────────────────────────
+
+/** Pure entry point — same shape used by the CLI action and the unit test. */
+export async function egressClear(
+  client: NineDeployClient,
+  projectId: number,
+  driver?: string,
+): Promise<{ ok: boolean; driver: string; error?: string }> {
+  return driver ? await client.egress.clear(projectId, driver) : await client.egress.clear(projectId);
+}
+
+export async function egressClearAction(
+  client: NineDeployClient,
+  projectIdStr: string,
+  opts: { driver?: string } = {},
+): Promise<void> {
+  const projectId = Number(projectIdStr);
+  if (!Number.isFinite(projectId)) {
+    error('Usage: ninedeploy egress clear <projectId> [--driver <name>]');
+    process.exitCode = 1;
+    return;
+  }
+  let result: Awaited<ReturnType<typeof egressClear>>;
+  try {
+    result = await egressClear(client, projectId, opts.driver);
+  } catch (err) {
+    error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+  if (!result.ok) {
+    error(result.error ?? 'Egress IP detach was refused');
+    process.exitCode = 1;
+    return;
+  }
+  success(`Egress IP cleared for project ${projectId} via ${result.driver}`);
+}

package/src/commands/emailTemplates.ts

@@ -0,0 +1,112 @@
+/**
+ * `ninedeploy email-templates {list,set,reset,preview}` —
+ * G-30 transactional email template overrides.
+ *
+ * The CLI is a thin wrapper around the SDK; the heavy
+ * lifting is `lib/emailTemplates.ts`. The `set` and
+ * `reset` commands require the workspace's admin role
+ * server-side, so a non-admin operator gets a clean
+ * 403 rather than a silent no-op.
+ */
+import type { NineDeployClient, EmailTemplateName } from '@ninedeploy/sdk';
+import { c, error, header, info, spinner, success, table } from '../lib/format.js';
+
+const num = (v: string, usage: string): number => {
+  const n = Number(v);
+  if (Number.isNaN(n)) {
+    error(usage);
+    throw new Error(usage);
+  }
+  return n;
+};
+
+const fail = (err: unknown): void => {
+  error(err instanceof Error ? err.message : String(err));
+};
+
+const NAMES: EmailTemplateName[] = [
+  'password-reset',
+  'workspace-invitation',
+  'domain-transfer',
+  'backup-drill-failed',
+];
+
+export async function emailTemplatesList(client: NineDeployClient, widStr: string): Promise<void> {
+  const wid = num(widStr, 'Usage: ninedeploy email-templates list <workspaceId>');
+  const res = await spinner('Fetching', () => client.emailTemplates.list(wid));
+  header(`Email templates (workspace ${wid})`);
+  table(
+    res.templates.map((t) => ({
+      name: t.name,
+      overridden: t.overridden ? 'yes' : c.dim('no'),
+      subject: t.subject ?? c.dim('(default)'),
+    })),
+    ['name', 'overridden', 'subject'],
+  );
+}
+
+export async function emailTemplatesPreview(
+  client: NineDeployClient,
+  widStr: string,
+  name: string,
+  vars: string[] = [],
+): Promise<void> {
+  const wid = num(widStr, 'Usage: ninedeploy email-templates preview <workspaceId> <name> [key=value ...]');
+  if (!NAMES.includes(name as EmailTemplateName)) {
+    error(`Unknown template: ${name}. Valid names: ${NAMES.join(', ')}`);
+    process.exitCode = 1;
+    return;
+  }
+  const parsed: Record<string, string> = {};
+  for (const raw of vars) {
+    const eq = raw.indexOf('=');
+    if (eq <= 0) {
+      error(`--var expects key=value pairs, got: ${raw}`);
+      return;
+    }
+    parsed[raw.slice(0, eq)] = raw.slice(eq + 1);
+  }
+  const res = await spinner('Rendering', () =>
+    client.emailTemplates.preview(wid, name as EmailTemplateName, parsed),
+  );
+  header(`Preview: ${name}${res.overridden ? c.cyan(' (overridden)') : ''}`);
+  info(`Subject:  ${res.subject}`);
+  console.log();
+  console.log(res.text);
+}
+
+export async function emailTemplatesSet(
+  client: NineDeployClient,
+  widStr: string,
+  name: string,
+  opts: { subject: string; text: string },
+): Promise<void> {
+  const wid = num(widStr, 'Usage: ninedeploy email-templates set <workspaceId> <name> --subject <s> --text <t>');
+  if (!NAMES.includes(name as EmailTemplateName)) {
+    error(`Unknown template: ${name}. Valid names: ${NAMES.join(', ')}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (!opts.subject || !opts.text) {
+    error('Both --subject and --text are required');
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    await client.emailTemplates.set(wid, name as EmailTemplateName, opts.subject, opts.text);
+    success(`Override set for ${name}.`);
+  } catch (err) { fail(err); }
+}
+
+export async function emailTemplatesReset(client: NineDeployClient, widStr: string, name: string): Promise<void> {
+  const wid = num(widStr, 'Usage: ninedeploy email-templates reset <workspaceId> <name>');
+  if (!NAMES.includes(name as EmailTemplateName)) {
+    error(`Unknown template: ${name}. Valid names: ${NAMES.join(', ')}`);
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    await client.emailTemplates.reset(wid, name as EmailTemplateName);
+    success(`Override removed for ${name}.`);
+  } catch (err) { fail(err); }
+}

package/src/commands/firewall.ts

@@ -0,0 +1,82 @@
+import type { NineDeployClient } from '@ninedeploy/sdk';
+
+export async function firewallStatus(client: NineDeployClient): Promise<void> {
+  try {
+    const status = await client.firewall.status();
+    console.log();
+    console.log(`  \x1b[1mHost Firewall (UFW) Status:\x1b[0m ${status.active ? '\x1b[32mActive (Protecting)\x1b[0m' : '\x1b[33mInactive\x1b[0m'}`);
+    console.log(`  \x1b[90mInstalled:\x1b[0m         ${status.installed ? 'yes' : 'no'}`);
+    console.log(`  \x1b[90mDefault Policies:\x1b[0m  Incoming: ${status.defaultIncoming} | Outgoing: ${status.defaultOutgoing}`);
+    console.log();
+
+    if (status.rules && status.rules.length > 0) {
+      console.log('  \x1b[1mActive Ingress & Port Rules:\x1b[0m');
+      console.log(`  ${'-'.repeat(70)}`);
+      console.log(`  ${'ID'.padEnd(5)} ${'To (Port)'.padEnd(20)} ${'Action'.padEnd(12)} ${'From'.padEnd(20)} Comment`);
+      console.log(`  ${'-'.repeat(70)}`);
+      for (const r of status.rules) {
+        const actionColor = r.action.includes('ALLOW') ? '\x1b[32m' : '\x1b[31m';
+        console.log(
+          `  ${String(r.id).padEnd(5)} ${r.to.padEnd(20)} ${actionColor}${r.action.padEnd(12)}\x1b[0m ${r.from.padEnd(20)} ${r.comment || ''}`
+        );
+      }
+      console.log(`  ${'-'.repeat(70)}`);
+    } else {
+      console.log('  \x1b[90mNo active port rules configured.\x1b[0m');
+    }
+    console.log();
+  } catch (err) {
+    console.error(`  \x1b[31m✗ Could not fetch firewall status:\x1b[0m ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}
+
+export async function firewallToggle(client: NineDeployClient, enable: boolean): Promise<void> {
+  try {
+    await client.firewall.toggle(enable);
+    console.log(`  \x1b[32m✓ Host firewall ${enable ? 'enabled' : 'disabled'}.\x1b[0m`);
+  } catch (err) {
+    console.error(`  \x1b[31m✗ Failed to toggle firewall:\x1b[0m ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}
+
+export async function firewallAddRule(
+  client: NineDeployClient,
+  port: string,
+  opts: { proto?: 'tcp' | 'udp' | 'any'; action?: 'allow' | 'deny' | 'limit'; from?: string; comment?: string }
+): Promise<void> {
+  try {
+    await client.firewall.addRule({
+      port,
+      proto: opts.proto ?? 'tcp',
+      action: opts.action ?? 'allow',
+      from: opts.from,
+      comment: opts.comment,
+    });
+    console.log(`  \x1b[32m✓ Rule added: ${opts.action ?? 'allow'} port ${port}/${opts.proto ?? 'tcp'}\x1b[0m`);
+  } catch (err) {
+    console.error(`  \x1b[31m✗ Failed to add firewall rule:\x1b[0m ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}
+
+export async function firewallDeleteRule(client: NineDeployClient, id: string): Promise<void> {
+  try {
+    await client.firewall.deleteRule(id);
+    console.log(`  \x1b[32m✓ Rule ${id} deleted.\x1b[0m`);
+  } catch (err) {
+    console.error(`  \x1b[31m✗ Failed to delete firewall rule:\x1b[0m ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}
+
+export async function firewallApplyRecommended(client: NineDeployClient): Promise<void> {
+  try {
+    await client.firewall.applyRecommended();
+    console.log('  \x1b[32m✓ Recommended VPS firewall profile applied (22 SSH, 80 HTTP, 443 HTTPS allowed; UFW enabled).\x1b[0m');
+  } catch (err) {
+    console.error(`  \x1b[31m✗ Failed to apply recommended firewall profile:\x1b[0m ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}