ninedeploy 0.10.6 → 0.16.1

package/src/commands/pgbouncer.ts

@@ -0,0 +1,65 @@
+/**
+ * `ninedeploy databases pgbouncer <dbId> <action>` — G-32
+ * PgBouncer sidecar. Only the `postgres` engine is
+ * supported; the server returns 422 for any other engine.
+ *
+ * Actions:
+ *   - enable  : start a co-located pgbouncer container and
+ *               stamp the row.
+ *   - disable : stop + remove the sidecar, clear the row.
+ *   - status  : print the current sidecar state and the
+ *               pooled connection string.
+ */
+import type { NineDeployClient } from '../client.js';
+import { c, error, header, info, spinner, success } 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;
+};
+
+export async function databasePgbouncer(
+  client: NineDeployClient,
+  dbIdStr: string,
+  action: string,
+  opts: { port?: number } = {},
+): Promise<void> {
+  const dbId = num(dbIdStr, 'Usage: ninedeploy databases pgbouncer <dbId> <enable|disable|status>');
+  const normalized = action.toLowerCase();
+  if (!['enable', 'disable', 'status'].includes(normalized)) {
+    error('Action must be one of: enable, disable, status');
+    process.exitCode = 1;
+    return;
+  }
+  if (normalized === 'enable') {
+    const res = await spinner('Starting PgBouncer sidecar', () =>
+      client.databases.enablePgbouncer(dbId, opts.port ? { port: opts.port } : {}),
+    );
+    success(`PgBouncer sidecar started on port ${res.port}.`);
+    info(`Connection URL: ${res.pooledConnectionString ?? '(pending)'}`);
+    return;
+  }
+  if (normalized === 'disable') {
+    const res = await spinner('Stopping PgBouncer sidecar', () => client.databases.disablePgbouncer(dbId));
+    success('PgBouncer sidecar stopped.');
+    if (res.enabled) info(`Sidecar still reporting enabled: ${res.containerName ?? '(unknown)'}`);
+    return;
+  }
+  // status
+  const res = await spinner('Reading sidecar status', () => client.databases.pgbouncerStatus(dbId));
+  header('PgBouncer sidecar');
+  info(`Enabled:     ${res.enabled ? 'yes' : 'no'}`);
+  info(`Container:   ${res.containerName ?? c.dim('(none)')}`);
+  info(`Port:        ${res.port}`);
+  info(`Running:     ${res.running ? 'yes' : c.yellow('no — enabled but container is down')}`);
+  if (res.poolMode) info(`Pool mode:   ${res.poolMode}`);
+  if (res.pooledConnectionString) {
+    console.log();
+    info(`Pooled URL (use this for new attachments):`);
+    console.log(`  ${c.cyan(res.pooledConnectionString)}`);
+  }
+}

package/src/commands/plugins.ts

@@ -0,0 +1,123 @@
+import type { NineDeployClient } from '@ninedeploy/sdk';
+import { table } from '../lib/format.js';
+
+export async function pluginsList(client: NineDeployClient): Promise<void> {
+  const { plugins } = await client.plugins.list();
+  if (plugins.length === 0) {
+    console.log('  No plugins installed.');
+    return;
+  }
+
+  table(
+    plugins.map((p) => ({
+      id: p.id,
+      name: p.name,
+      version: `v${p.version}`,
+      type: p.isOfficial ? 'Official' : 'Community',
+      status: p.status,
+    })),
+    ['id', 'name', 'version', 'type', 'status'],
+  );
+}
+
+export async function pluginsMarketplace(client: NineDeployClient): Promise<void> {
+  const { catalog, live, keyId, fetchedAt } = await client.plugins.marketplace();
+  if (catalog.length === 0) {
+    console.log('  Marketplace catalog is currently empty.');
+    return;
+  }
+
+  // Surface the source (live signed index vs. static
+  // fallback) so the operator knows whether a planned
+  // install was discovered automatically or is a
+  // roadmap item.
+  const source = live
+    ? `live signed index (key=${keyId ?? 'unknown'})`
+    : 'static fallback (upstream unreachable or NINEDEPLOY_MARKETPLACE_URL not set)';
+  console.log(`  Source: ${source}`);
+  if (fetchedAt) {
+    const ageMin = Math.max(0, Math.round((Date.now() - fetchedAt) / 60_000));
+    console.log(`  Fetched: ${ageMin} min ago`);
+  }
+  console.log();
+
+  table(
+    catalog.map((c) => ({
+      id: c.id,
+      name: c.name,
+      category: c.category,
+      version: `v${c.version}`,
+      type: c.isOfficial ? 'Official' : 'Community',
+      status: c.isInstalled ? '✓ Installed' : 'Available',
+    })),
+    ['id', 'name', 'category', 'version', 'type', 'status'],
+  );
+}
+
+/** `ninedeploy plugins marketplace refresh` — bypass the
+ *  5-minute cache and re-fetch the live signed index. */
+export async function pluginsMarketplaceRefresh(client: NineDeployClient): Promise<void> {
+  const res = await client.plugins.marketplace({ refresh: true });
+  console.log(
+    `  ✓ Refreshed (${res.catalog.length} entries, live=${res.live}, keyId=${res.keyId ?? 'n/a'}).`,
+  );
+}
+
+export async function pluginsInstall(
+  client: NineDeployClient,
+  target: string,
+  // r440: matches the server's LOADABLE_SOURCES — the old union advertised
+  // npm/git/local, which the server refuses with 400 every time.
+  opts: { source?: 'marketplace' | 'sandbox'; name?: string; version?: string; desc?: string },
+): Promise<void> {
+  const source = opts.source ?? 'marketplace';
+  const res = await client.plugins.install({
+    source,
+    target,
+    name: opts.name,
+    version: opts.version,
+    description: opts.desc,
+  });
+  console.log(`  ✓ Installed plugin "${res.id}" (status: ${res.status}).`);
+}
+
+export async function pluginsEnable(client: NineDeployClient, id: string): Promise<void> {
+  const res = await client.plugins.enable(id);
+  console.log(`  ✓ Plugin "${res.id}" enabled.`);
+}
+
+export async function pluginsDisable(client: NineDeployClient, id: string): Promise<void> {
+  const res = await client.plugins.disable(id);
+  console.log(`  ✓ Plugin "${res.id}" disabled.`);
+}
+
+export async function pluginsUninstall(client: NineDeployClient, id: string): Promise<void> {
+  const res = await client.plugins.uninstall(id);
+  console.log(`  ✓ Plugin "${res.id}" uninstalled.`);
+}
+
+export async function pluginsInspect(client: NineDeployClient, id: string): Promise<void> {
+  const p = await client.plugins.inspect(id);
+  console.log(`  Plugin:       ${p.name} (${p.id})`);
+  console.log(`  Version:      v${p.version}`);
+  console.log(`  Type:         ${p.isOfficial ? 'Official' : 'Community'}`);
+  console.log(`  Status:       ${p.status}${p.enabled ? ' (enabled)' : ' (disabled)'}`);
+  console.log(`  Author:       ${p.author ?? 'N/A'}`);
+  console.log(`  Description:  ${p.description ?? 'N/A'}`);
+  console.log(`  Dependencies: ${p.dependencies.length > 0 ? p.dependencies.join(', ') : 'none'}`);
+  console.log(`  Tapped Hooks: ${p.hooks.length > 0 ? p.hooks.join(', ') : 'none'}`);
+  console.log(`  Backgrounds:  ${p.services.length > 0 ? p.services.join(', ') : 'none'}`);
+  console.log(`  Config Keys:  ${p.configSchema.length} registered`);
+  console.log(`  Nav Menus:    ${p.menus.length} registered`);
+  if (p.error) {
+    console.log(`  Error:        ${p.error}`);
+  }
+  // r286: null = the kernel does not track this per plugin.
+  console.log(`  Events Run:   ${p.runtimeStats.eventsHandled ?? 'not tracked'}`);
+  console.log(`  Uptime:       ${p.runtimeStats.uptimeSeconds == null ? 'not tracked' : `${p.runtimeStats.uptimeSeconds}s`}`);
+}
+
+export async function pluginsReload(client: NineDeployClient, id: string): Promise<void> {
+  const res = await client.plugins.reload(id);
+  console.log(`  ✓ Plugin "${res.id}" reloaded (status: ${res.status}).`);
+}

package/src/commands/proxyConfig.ts

@@ -0,0 +1,117 @@
+import { readFileSync } from 'node:fs';
+import type { TraefikCustomConfigIssue } from '@ninedeploy/sdk';
+import type { NineDeployClient } from '../client.js';
+import { prompt } from '../prompts.js';
+import { c, error, header, info, kv, spinner, success } from '../lib/format.js';
+import { plain } from './sources.js';
+
+/**
+ * 0.14: the operator's custom Traefik dynamic config (`custom.yml`) —
+ * `ninedeploy proxy config get|validate|set|clear`. Operator only on the
+ * server. Findings, errors and the stored YAML are printed through the F1011
+ * sanitiser (line by line, so the YAML keeps its line breaks).
+ */
+
+const message = (err: unknown): string => plain(err instanceof Error ? err.message : String(err));
+
+/** Multi-line text with every control sequence removed from each line. */
+const lines = (text: string): string =>
+  text
+    .split(/\r?\n/)
+    .map((l) => plain(l))
+    .join('\n');
+
+function printIssues(label: string, issues: TraefikCustomConfigIssue[], color: (s: string) => string): void {
+  if (issues.length === 0) return;
+  console.log(`  ${color(label)}`);
+  for (const i of issues) console.log(`    ${color('•')} ${i.path ? `${plain(i.path)}: ` : ''}${plain(i.message)}`);
+}
+
+function readConfigFile(file: string | undefined, usage: string): string | null {
+  if (!file) {
+    error(usage);
+    return null;
+  }
+  try {
+    const content = readFileSync(file, 'utf8');
+    if (!content.trim()) {
+      error(`${file} is empty`);
+      return null;
+    }
+    return content;
+  } catch (err) {
+    error(`Cannot read ${file}: ${message(err)}`);
+    return null;
+  }
+}
+
+/** `ninedeploy proxy config get` */
+export async function proxyConfigGet(client: NineDeployClient): Promise<void> {
+  try {
+    const cfg = await spinner('Reading the custom config', () => client.traefik.customConfig.get());
+    header('Custom Traefik config');
+    const color = cfg.status === 'applied' ? c.green : cfg.status === 'rejected' ? c.red : c.gray;
+    kv('Status', color(cfg.status));
+    kv('SHA-256', cfg.sha256);
+    kv('Updated', cfg.updatedAt ? new Date(cfg.updatedAt).toLocaleString() : null);
+    kv('Updated by', cfg.updatedBy === null ? null : `user #${cfg.updatedBy}`);
+    if (cfg.lastError) kv('Last error', c.red(plain(cfg.lastError)));
+    if (cfg.content === null) {
+      info('No custom config saved. Write one and run `ninedeploy proxy config set --file <path>`.');
+      return;
+    }
+    console.log();
+    console.log(lines(cfg.content));
+  } catch (err) {
+    error(message(err));
+  }
+}
+
+/** `ninedeploy proxy config validate --file <path>` — no state change. */
+export async function proxyConfigValidate(client: NineDeployClient, opts: { file?: string } = {}): Promise<void> {
+  const content = readConfigFile(opts.file, 'Usage: ninedeploy proxy config validate --file <path>');
+  if (content === null) return;
+  try {
+    const res = await spinner('Validating', () => client.traefik.customConfig.validate(content));
+    printIssues('Errors', res.errors, c.red);
+    printIssues('Warnings', res.warnings, c.yellow);
+    if (res.ok) success('The config is valid');
+    else error(`The config has ${res.errors.length} error(s)`);
+  } catch (err) {
+    error(message(err));
+  }
+}
+
+/** `ninedeploy proxy config set --file <path>` — validated and applied atomically by the server. */
+export async function proxyConfigSet(client: NineDeployClient, opts: { file?: string } = {}): Promise<void> {
+  const content = readConfigFile(opts.file, 'Usage: ninedeploy proxy config set --file <path>');
+  if (content === null) return;
+  try {
+    const res = await spinner('Validating and applying', () => client.traefik.customConfig.set(content));
+    success(`Custom config applied (sha256 ${res.sha256.slice(0, 12)})`);
+    printIssues('Warnings', res.warnings, c.yellow);
+  } catch (err) {
+    const details = (err as { details?: { errors?: TraefikCustomConfigIssue[]; warnings?: TraefikCustomConfigIssue[] } }).details;
+    if (details?.errors) printIssues('Errors', details.errors, c.red);
+    if (details?.warnings) printIssues('Warnings', details.warnings, c.yellow);
+    error(message(err));
+  }
+}
+
+/** `ninedeploy proxy config clear [--yes]` — removes every custom router, service and middleware. */
+export async function proxyConfigClear(client: NineDeployClient, opts: { yes?: boolean } = {}): Promise<void> {
+  if (!opts.yes) {
+    const confirm = await prompt('Type "clear" to remove the custom Traefik config', '');
+    if (confirm.trim() !== 'clear') {
+      info('Aborted.');
+      return;
+    }
+  }
+  try {
+    const res = await spinner('Clearing the custom config', () => client.traefik.customConfig.clear());
+    if (res.cleared) success('Custom config removed');
+    else info('There was no custom config to remove.');
+  } catch (err) {
+    error(message(err));
+  }
+}

package/src/commands/secretProviders.ts

@@ -0,0 +1,228 @@
+import { readFileSync } from 'node:fs';
+import process from 'node:process';
+import type { AwsProviderPut, SecretProviderKind, SecretProviderView, VaultProviderPut } from '@ninedeploy/sdk';
+import type { NineDeployClient } from '../client.js';
+import { prompt } from '../prompts.js';
+import { c, error, fmtTime, header, info, kv, spinner, success, table } from '../lib/format.js';
+import { plain } from './sources.js';
+
+/**
+ * 0.14: HashiCorp Vault / OpenBao and AWS Secrets Manager —
+ * `ninedeploy secrets providers list|set-vault|set-aws|test|delete`.
+ * Operator only on the server.
+ *
+ * Secrets never travel on argv (they would land in shell history and `ps`):
+ * a Vault token, AppRole role/secret id, AWS secret access key and session
+ * token come from a file (`--token-file`, …) or an environment variable.
+ * The AWS access key id is an identifier and may be passed as a flag. An
+ * omitted credential keeps the stored value. Provider detail and test errors
+ * are relayed provider text, so they pass through the F1011 sanitiser.
+ */
+
+export const VAULT_TOKEN_ENV = 'NINEDEPLOY_VAULT_TOKEN';
+export const VAULT_ROLE_ID_ENV = 'NINEDEPLOY_VAULT_ROLE_ID';
+export const VAULT_SECRET_ID_ENV = 'NINEDEPLOY_VAULT_SECRET_ID';
+export const AWS_ACCESS_KEY_ID_ENV = 'NINEDEPLOY_AWS_ACCESS_KEY_ID';
+export const AWS_SECRET_ACCESS_KEY_ENV = 'NINEDEPLOY_AWS_SECRET_ACCESS_KEY';
+export const AWS_SESSION_TOKEN_ENV = 'NINEDEPLOY_AWS_SESSION_TOKEN';
+
+const message = (err: unknown): string => plain(err instanceof Error ? err.message : String(err));
+
+/** A secret from `file`, else the environment variable `env`; undefined when neither is set. */
+function readSecret(file: string | undefined, env: string): string | undefined {
+  if (file) return readFileSync(file, 'utf8').trim() || undefined;
+  return process.env[env]?.trim() || undefined;
+}
+
+function parseKind(raw: string | undefined): SecretProviderKind | null {
+  return raw === 'vault' || raw === 'aws' ? raw : null;
+}
+
+function enabledFrom(opts: { enable?: boolean; disable?: boolean }): { enabled?: boolean } | null {
+  if (opts.enable && opts.disable) return null;
+  if (opts.enable) return { enabled: true };
+  if (opts.disable) return { enabled: false };
+  return {};
+}
+
+const configText = (config: Record<string, unknown>): string => {
+  const entries = Object.entries(config);
+  return entries.length > 0 ? entries.map(([k, v]) => `${plain(k)}=${plain(typeof v === 'string' ? v : JSON.stringify(v))}`).join(' ') : '—';
+};
+
+function printView(v: SecretProviderView): void {
+  kv('Configured', v.configured ? c.green('yes') : c.gray('no'));
+  kv('Enabled', v.enabled ? 'yes' : 'no');
+  kv('Credentials', v.hasCredential ? 'stored' : c.yellow('missing'));
+  kv('Settings', configText(v.config));
+}
+
+/** `ninedeploy secrets providers list` */
+export async function secretProvidersList(client: NineDeployClient): Promise<void> {
+  try {
+    const rows = await spinner('Reading secret managers', () => client.settings.secretProviders.list());
+    header('Secret managers');
+    table(
+      rows.map((r) => ({
+        kind: r.kind,
+        configured: r.configured ? c.green('yes') : c.gray('no'),
+        enabled: r.enabled ? 'yes' : 'no',
+        credentials: r.hasCredential ? 'stored' : c.dim('—'),
+        tested: fmtTime(r.lastTestedAt),
+        lastError: r.lastTestError ? c.red(plain(r.lastTestError).slice(0, 80)) : '',
+        settings: configText(r.config),
+      })),
+      ['kind', 'configured', 'enabled', 'credentials', 'tested', 'lastError', 'settings'],
+    );
+    info(`Reference syntax: \${{vault:<path>#<field>}} and \${{aws:<secretId>}} or \${{aws:<secretId>#<jsonKey>}}`);
+  } catch (err) {
+    error(message(err));
+  }
+}
+
+export interface VaultCliOptions {
+  address?: string;
+  namespace?: string;
+  mount?: string;
+  auth?: string;
+  approleMount?: string;
+  tokenFile?: string;
+  roleIdFile?: string;
+  secretIdFile?: string;
+  enable?: boolean;
+  disable?: boolean;
+}
+
+/** `ninedeploy secrets providers set-vault --address <url> [--auth token|approle] ...` */
+export async function secretProvidersSetVault(client: NineDeployClient, opts: VaultCliOptions = {}): Promise<void> {
+  const address = opts.address?.trim();
+  if (!address) return error('Usage: ninedeploy secrets providers set-vault --address <https://vault…> [--auth token|approle] [--token-file <path>]');
+  const authMethod = opts.auth ?? 'token';
+  if (authMethod !== 'token' && authMethod !== 'approle') return error('--auth must be "token" or "approle"');
+  const enabled = enabledFrom(opts);
+  if (!enabled) return error('--enable and --disable cannot be combined');
+  const credentials: NonNullable<VaultProviderPut['credentials']> = {};
+  try {
+    if (authMethod === 'token') {
+      const token = readSecret(opts.tokenFile, VAULT_TOKEN_ENV);
+      if (token) credentials.token = token;
+    } else {
+      const roleId = readSecret(opts.roleIdFile, VAULT_ROLE_ID_ENV);
+      const secretId = readSecret(opts.secretIdFile, VAULT_SECRET_ID_ENV);
+      if (roleId) credentials.roleId = roleId;
+      if (secretId) credentials.secretId = secretId;
+    }
+  } catch (err) {
+    return error(`Could not read a credential file: ${message(err)}`);
+  }
+  const input: VaultProviderPut = {
+    ...enabled,
+    config: {
+      address,
+      authMethod,
+      ...(opts.namespace ? { namespace: opts.namespace } : {}),
+      ...(opts.mount ? { mount: opts.mount } : {}),
+      ...(opts.approleMount ? { approleMount: opts.approleMount } : {}),
+    },
+    ...(Object.keys(credentials).length > 0 ? { credentials } : {}),
+  };
+  try {
+    const view = await spinner('Saving the Vault settings', () => client.settings.secretProviders.set('vault', input));
+    success('Vault / OpenBao saved');
+    printView(view);
+    info('Run `ninedeploy secrets providers test vault` to check the connection.');
+  } catch (err) {
+    error(message(err));
+  }
+}
+
+export interface AwsCliOptions {
+  region?: string;
+  endpoint?: string;
+  roleArn?: string;
+  externalId?: string;
+  roleSessionName?: string;
+  accessKeyId?: string;
+  secretAccessKeyFile?: string;
+  sessionTokenFile?: string;
+  enable?: boolean;
+  disable?: boolean;
+}
+
+/** `ninedeploy secrets providers set-aws --region <region> ...` */
+export async function secretProvidersSetAws(client: NineDeployClient, opts: AwsCliOptions = {}): Promise<void> {
+  const region = opts.region?.trim();
+  if (!region) return error('Usage: ninedeploy secrets providers set-aws --region <region> [--access-key-id <id>] [--secret-access-key-file <path>]');
+  const enabled = enabledFrom(opts);
+  if (!enabled) return error('--enable and --disable cannot be combined');
+  const credentials: NonNullable<AwsProviderPut['credentials']> = {};
+  try {
+    const accessKeyId = opts.accessKeyId?.trim() || process.env[AWS_ACCESS_KEY_ID_ENV]?.trim();
+    const secretAccessKey = readSecret(opts.secretAccessKeyFile, AWS_SECRET_ACCESS_KEY_ENV);
+    const sessionToken = readSecret(opts.sessionTokenFile, AWS_SESSION_TOKEN_ENV);
+    if (accessKeyId) credentials.accessKeyId = accessKeyId;
+    if (secretAccessKey) credentials.secretAccessKey = secretAccessKey;
+    if (sessionToken) credentials.sessionToken = sessionToken;
+  } catch (err) {
+    return error(`Could not read a credential file: ${message(err)}`);
+  }
+  const input: AwsProviderPut = {
+    ...enabled,
+    config: {
+      region,
+      ...(opts.endpoint ? { endpoint: opts.endpoint } : {}),
+      ...(opts.roleArn ? { roleArn: opts.roleArn } : {}),
+      ...(opts.externalId ? { externalId: opts.externalId } : {}),
+      ...(opts.roleSessionName ? { roleSessionName: opts.roleSessionName } : {}),
+    },
+    ...(Object.keys(credentials).length > 0 ? { credentials } : {}),
+  };
+  try {
+    const view = await spinner('Saving the AWS settings', () => client.settings.secretProviders.set('aws', input));
+    success('AWS Secrets Manager saved');
+    printView(view);
+    info('Run `ninedeploy secrets providers test aws` to check the connection.');
+  } catch (err) {
+    error(message(err));
+  }
+}
+
+/** `ninedeploy secrets providers test <kind> [--probe-path <path>] [--probe-secret-id <id>]` */
+export async function secretProvidersTest(
+  client: NineDeployClient,
+  kindArg: string,
+  opts: { probePath?: string; probeSecretId?: string } = {},
+): Promise<void> {
+  const kind = parseKind(kindArg);
+  if (!kind) return error('Usage: ninedeploy secrets providers test <vault|aws> [--probe-path <path>] [--probe-secret-id <id>]');
+  if (kind === 'vault' && opts.probeSecretId) return error('--probe-secret-id belongs to the aws provider');
+  if (kind === 'aws' && opts.probePath) return error('--probe-path belongs to the vault provider');
+  const probe = kind === 'vault' ? (opts.probePath ? { probePath: opts.probePath } : {}) : opts.probeSecretId ? { probeSecretId: opts.probeSecretId } : {};
+  try {
+    const res = await spinner(`Testing the ${kind} secret manager`, () => client.settings.secretProviders.test(kind, probe));
+    if (res.ok) success(plain(res.detail));
+    else error(plain(res.detail));
+  } catch (err) {
+    error(message(err));
+  }
+}
+
+/** `ninedeploy secrets providers delete <kind> [--yes]` */
+export async function secretProvidersDelete(client: NineDeployClient, kindArg: string, opts: { yes?: boolean } = {}): Promise<void> {
+  const kind = parseKind(kindArg);
+  if (!kind) return error('Usage: ninedeploy secrets providers delete <vault|aws> [--yes]');
+  if (!opts.yes) {
+    const confirm = await prompt(`Type "delete" to remove the ${kind} secret manager (its references stay literal at deploy)`, '');
+    if (confirm.trim() !== 'delete') {
+      info('Aborted.');
+      return;
+    }
+  }
+  try {
+    const res = await spinner(`Removing the ${kind} secret manager`, () => client.settings.secretProviders.delete(kind));
+    if (res.deleted) success(`The ${kind} secret manager was removed`);
+    else info(`No ${kind} secret manager was configured.`);
+  } catch (err) {
+    error(message(err));
+  }
+}

package/src/commands/server.ts

@@ -0,0 +1,126 @@
+import { c, error, header, info, kv, spinner, success } from '../lib/format.js';
+import {
+  getContainerState,
+  getServerLogs,
+  isDockerAvailable,
+  isServerReachable,
+  startServerContainer,
+  stopServerContainer,
+  waitForServerReady,
+} from '../lib/serverRunner.js';
+
+export async function serverStartAction(opts: {
+  port?: string;
+  image?: string;
+  name?: string;
+}): Promise<void> {
+  header('Start Local Server');
+
+  const dockerOk = await isDockerAvailable();
+  if (!dockerOk) {
+    return error('Docker is not installed or the Docker daemon is not running.');
+  }
+
+  const port = Number(opts.port ?? 3000);
+  // `--port abc` used to mint `http://localhost:NaN` and a baffling docker
+  // error two steps later — validate where it is typed.
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    return error(`Invalid port: ${opts.port ?? 3000} (expected 1–65535)`);
+  }
+  const containerName = opts.name ?? 'ninedeploy';
+  const baseUrl = `http://localhost:${port}`;
+
+  const reachable = await isServerReachable(baseUrl, 500);
+  if (reachable) {
+    info(`NineDeploy server is already running and reachable at ${baseUrl}`);
+    return;
+  }
+
+  try {
+    await spinner(`Starting NineDeploy server container (${containerName})`, async () => {
+      await startServerContainer({
+        port,
+        image: opts.image,
+        containerName,
+      });
+      const ready = await waitForServerReady(baseUrl, 30, 1000);
+      if (!ready) {
+        throw new Error('Server container started but failed to respond within 30s.');
+      }
+    });
+
+    success(`NineDeploy server is now running at ${baseUrl}`);
+    console.log(`\n  Next steps:`);
+    console.log(`    1. Run ${c.cyan('ninedeploy setup')} to create your admin account.`);
+    console.log(`    2. Open ${c.cyan(baseUrl)} to view the web dashboard.\n`);
+  } catch (err) {
+    error(`Failed to start server: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+export async function serverStopAction(opts: { name?: string } = {}): Promise<void> {
+  header('Stop Local Server');
+
+  const dockerOk = await isDockerAvailable();
+  if (!dockerOk) {
+    return error('Docker is not installed or the Docker daemon is not running.');
+  }
+
+  const containerName = opts.name ?? 'ninedeploy';
+  const state = await getContainerState(containerName);
+  if (!state.exists || !state.running) {
+    info(`Server container (${containerName}) is not running.`);
+    return;
+  }
+
+  try {
+    await spinner(`Stopping container ${containerName}`, () => stopServerContainer(containerName));
+    success(`NineDeploy server stopped.`);
+  } catch (err) {
+    error(`Failed to stop server: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+export async function serverStatusAction(opts: { name?: string; port?: string } = {}): Promise<void> {
+  header('Local Server Status');
+
+  const dockerOk = await isDockerAvailable();
+  if (!dockerOk) {
+    kv('Docker', c.red('not available'));
+    return;
+  }
+
+  const containerName = opts.name ?? 'ninedeploy';
+  const port = Number(opts.port ?? 3000);
+  const baseUrl = `http://localhost:${port}`;
+
+  const state = await getContainerState(containerName);
+  const reachable = await isServerReachable(baseUrl, 800);
+
+  kv('Container', containerName);
+  kv('Container ID', state.id ?? c.gray('—'));
+  kv('Docker Status', state.running ? c.green(state.status) : c.yellow(state.status));
+  kv('HTTP API', reachable ? c.green(`reachable @ ${baseUrl}`) : c.red(`unreachable @ ${baseUrl}`));
+  console.log();
+}
+
+export async function serverLogsAction(opts: { name?: string; lines?: string } = {}): Promise<void> {
+  const dockerOk = await isDockerAvailable();
+  if (!dockerOk) {
+    return error('Docker is not installed or the Docker daemon is not running.');
+  }
+
+  const containerName = opts.name ?? 'ninedeploy';
+  const lines = Number(opts.lines ?? 50);
+
+  try {
+    const logs = await getServerLogs(containerName, lines);
+    if (!logs.trim()) {
+      console.log(c.gray('  (no logs recorded)'));
+      return;
+    }
+    console.log(logs);
+  } catch (err) {
+    error(`Failed to get server logs: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}