ninedeploy 0.10.6 → 0.16.0

package/src/commands/services.ts

@@ -0,0 +1,249 @@
+import { NineDeployError } from '@ninedeploy/sdk';
+import type { NineDeployClient } from '../client.js';
+import { c, error, fmtTime, header, info, kv, spinner, statusColor, success, table } from '../lib/format.js';
+import { prompt } from '../prompts.js';
+
+/** `ninedeploy services list` */
+export async function servicesList(client: NineDeployClient): Promise<void> {
+  header('Services');
+  await spinner('Fetching services', async () => {
+    const services = await client.services.list();
+    if (services.length === 0) { info('No services yet. Run `ninedeploy services create`.'); return; }
+    table(
+      services.map((s) => ({
+        id: s.id,
+        name: s.name,
+        type: s.type,
+        status: s.status,
+        port: s.port ?? '—',
+        updated: fmtTime(s.updatedAt),
+      })),
+      ['id', 'name', 'type', 'status', 'port', 'updated'],
+    );
+  });
+}
+
+/** `ninedeploy services create` — interactive wizard */
+export async function servicesCreate(client: NineDeployClient): Promise<void> {
+  header('Create Service');
+  console.log(c.dim('  Answer a few questions to deploy your app.\n'));
+
+  const name = await prompt('Service name');
+  if (!name) return error('Name is required');
+
+  const mode = await prompt('Deploy from (1) Git repo  (2) Docker image', '1');
+  const useRepo = mode !== '2';
+
+  let repoUrl = '';
+  let image = '';
+  let branch = 'main';
+  if (useRepo) {
+    repoUrl = await prompt('Repository URL', '');
+    if (!repoUrl) return error('Repository URL is required');
+    branch = await prompt('Branch', 'main');
+  } else {
+    image = await prompt('Docker image (e.g. nginx:alpine)');
+    if (!image) return error('Image is required');
+  }
+
+  const portStr = await prompt('Port (optional)', '');
+  const port = portStr ? Number(portStr) : undefined;
+  const pubPortStr = await prompt('Direct host port (optional)', '');
+  const publishedPort = pubPortStr ? Number(pubPortStr) : undefined;
+  const volume = await prompt('Persistent volume path (optional)', '');
+
+  console.log();
+  try {
+    const svc = await spinner('Creating service', () =>
+      client.services.create({
+        name, type: 'docker',
+        repoUrl: useRepo ? repoUrl : undefined,
+        image: useRepo ? undefined : image,
+        branch, port, publishedPort, volumeMount: volume || undefined,
+      }),
+    );
+    success(`Service "${svc.name}" created (id: ${svc.id})`);
+
+    const deployNow = await prompt('Deploy now? (y/n)', 'y');
+    if (deployNow.toLowerCase().startsWith('y')) {
+      const res = await spinner('Deploying', () => client.deploys.trigger(svc.id));
+      success(`Deployment #${res.deploymentId} queued. Check logs: ninedeploy services logs ${svc.id}`);
+    }
+  } catch (err) {
+    error(err instanceof NineDeployError ? err.message : String(err));
+  }
+}
+
+/** `ninedeploy services get <id>` */
+export async function servicesGet(client: NineDeployClient, idStr: string): Promise<void> {
+  const id = Number(idStr);
+  if (!id) return error('Usage: ninedeploy services get <id>');
+  header('Service Details');
+  await spinner('Fetching', async () => {
+    const svc = await client.services.get(id);
+    kv('ID', svc.id);
+    kv('Name', svc.name);
+    kv('Slug', svc.slug);
+    kv('Type', svc.type);
+    kv('Status', statusColor(svc.status));
+    kv('Repo', svc.repoUrl ?? '—');
+    kv('Branch', svc.branch);
+    kv('Image', svc.image ?? '—');
+    kv('Port', svc.port ?? '—');
+    if (svc.publishedPort) kv('Host Port', c.green(`:${svc.publishedPort}`));
+    kv('Volume', svc.volumeMount ?? '—');
+    kv('Health', svc.healthPath);
+    kv('Runtime', svc.runtimeId ?? '—');
+    kv('Commit', svc.commitSha ?? '—');
+    if (svc.autoUrl) kv('URL', c.cyan(`http://${svc.autoUrl}`));
+    kv('Created', fmtTime(svc.createdAt));
+    kv('Updated', fmtTime(svc.updatedAt));
+  });
+}
+
+/** `ninedeploy services deploy <id>` */
+export async function servicesDeploy(client: NineDeployClient, idStr: string): Promise<void> {
+  const id = Number(idStr);
+  if (!id) return error('Usage: ninedeploy services deploy <id>');
+  try {
+    const res = await spinner('Triggering deploy', () => client.deploys.trigger(id));
+    success(`Deployment #${res.deploymentId} queued.`);
+    info(`Watch logs: ninedeploy services logs ${id}`);
+  } catch (err) { error(err instanceof Error ? err.message : String(err)); }
+}
+
+/** `ninedeploy services logs <id>` */
+export async function servicesLogs(client: NineDeployClient, idStr: string): Promise<void> {
+  const id = Number(idStr);
+  if (!id) return error('Usage: ninedeploy services logs <id>');
+  header('Runtime Logs');
+  try {
+    const { lines } = await client.services.logs(id);
+    if (!lines.trim()) { info('No logs yet.'); return; }
+    console.log(lines.split('\n').slice(0, 50).map((l) => `  ${c.dim(l)}`).join('\n'));
+  } catch (err) { error(err instanceof Error ? err.message : String(err)); }
+}
+
+/** `ninedeploy services stop|start|restart <id>` */
+export async function servicesLifecycle(client: NineDeployClient, action: 'stop' | 'start' | 'restart', idStr: string): Promise<void> {
+  const id = Number(idStr);
+  if (!id) return error(`Usage: ninedeploy services ${action} <id>`);
+  try {
+    await spinner(`${action}ing service`, () => client.services[action](id));
+    success(`Service ${action}ed.`);
+  } catch (err) { error(err instanceof Error ? err.message : String(err)); }
+}
+
+/** `ninedeploy services delete <id>` */
+export async function servicesDelete(client: NineDeployClient, idStr: string): Promise<void> {
+  const id = Number(idStr);
+  if (!id) return error('Usage: ninedeploy services delete <id>');
+  const confirmText = await prompt(`Type the service ID (${id}) to confirm deletion`);
+  if (confirmText !== String(id)) return error('Cancelled.');
+  try {
+    await spinner('Deleting service', () => client.services.remove(id));
+    success('Service deleted.');
+  } catch (err) { error(err instanceof Error ? err.message : String(err)); }
+}
+
+/** Pure entry point for `ninedeploy services sticky <id> --enable|--disable` (G-28). */
+export async function servicesSticky(
+  client: NineDeployClient,
+  idStr: string,
+  opts: { enable?: boolean; disable?: boolean } = {},
+): Promise<{ id: number; enabled: boolean; active: boolean }> {
+  const id = Number(idStr);
+  if (!id) throw new Error('Usage: ninedeploy services sticky <id> --enable|--disable');
+  if (opts.enable === undefined && opts.disable === undefined) {
+    throw new Error('Specify either --enable or --disable');
+  }
+  if (opts.enable && opts.disable) {
+    throw new Error('Specify only one of --enable or --disable');
+  }
+  return await client.domains.setStickySession(id, Boolean(opts.enable));
+}
+
+/** Formatted wrapper for the CLI. */
+export async function servicesStickyAction(
+  client: NineDeployClient,
+  idStr: string,
+  opts: { enable?: boolean; disable?: boolean } = {},
+): Promise<void> {
+  header('Sticky session');
+  let result: Awaited<ReturnType<typeof servicesSticky>>;
+  try {
+    result = await servicesSticky(client, idStr, opts);
+  } catch (err) {
+    error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+  success(result.enabled
+    ? `Sticky session enabled for service #${result.id} (Traefik will pick this up on the next reload)`
+    : `Sticky session disabled for service #${result.id}`);
+}
+
+/** `ninedeploy services export <id>` */
+export async function servicesExport(client: NineDeployClient, idStr: string): Promise<void> {
+  const id = Number(idStr);
+  if (!id) return error('Usage: ninedeploy services export <id>');
+  const { writeFileSync } = await import('node:fs');
+  const { authedFetch } = await import('../client.js');
+  try {
+    const svc = await client.services.get(id);
+    const data = await spinner('Exporting', () =>
+      (async () => {
+        // r550: refresh-aware and base-path preserving (was a bare fetch).
+        const res = await authedFetch(`/v1/services/${id}/export`);
+        if (!res.ok) throw new Error(`Export failed (HTTP ${res.status})`);
+        return res.text();
+      })(),
+    );
+    const filename = `${svc.slug}-export.json`;
+    writeFileSync(filename, data);
+    success(`Exported to ${filename}`);
+  } catch (err) { error(err instanceof Error ? err.message : String(err)); }
+}
+
+/** `ninedeploy services compose <id>` */
+export async function servicesCompose(client: NineDeployClient, idStr: string): Promise<void> {
+  const id = Number(idStr);
+  if (!id) return error('Usage: ninedeploy services compose <id>');
+  header('Runtime Docker Compose Manifest');
+  try {
+    const svc = await client.services.get(id);
+    const container = svc.runtimeId || `nd-svc-${svc.slug}-1`;
+    const res = await spinner('Generating manifest', () => client.containers.compose(container));
+    console.log(c.dim(`\n  # Container: ${container}\n`));
+    console.log(res.yaml.split('\n').map((l) => `  ${c.cyan(l)}`).join('\n'));
+    console.log();
+  } catch (err) { error(err instanceof Error ? err.message : String(err)); }
+}
+
+/** `ninedeploy services inspect <id>` */
+export async function servicesInspect(client: NineDeployClient, idStr: string): Promise<void> {
+  const id = Number(idStr);
+  if (!id) return error('Usage: ninedeploy services inspect <id>');
+  header('Container Runtime Inspection');
+  try {
+    const svc = await client.services.get(id);
+    const container = svc.runtimeId || `nd-svc-${svc.slug}-1`;
+    const data = await spinner('Inspecting container', () => client.containers.inspect(container));
+    kv('Container ID', data.id);
+    kv('Name', data.name);
+    kv('Image', data.image);
+    kv('Status', statusColor(data.state.status));
+    kv('Running', data.state.running ? c.green('true') : c.red('false'));
+    if (data.resources.memoryLimitBytes > 0) kv('Memory Limit', `${Math.round(data.resources.memoryLimitBytes / (1024 * 1024))} MB`);
+    if (data.resources.cpuShares > 0) kv('CPU Shares', `${data.resources.cpuShares}`);
+    kv('Restart Policy', data.resources.restartPolicy);
+
+    if (Object.keys(data.traefikTags).length > 0) {
+      console.log(c.dim('\n  Traefik Dynamic Ingress Tags:'));
+      for (const [k, v] of Object.entries(data.traefikTags)) {
+        console.log(`    ${c.yellow(k)}: ${c.dim(v)}`);
+      }
+    }
+    console.log();
+  } catch (err) { error(err instanceof Error ? err.message : String(err)); }
+}

package/src/commands/setup.ts

@@ -0,0 +1,94 @@
+import { createClient, NineDeployError } from '@ninedeploy/sdk';
+import { loadConfig, saveConfig } from '../config.js';
+import { prompt, promptHidden } from '../prompts.js';
+import {
+  isDockerAvailable,
+  isServerReachable,
+  normalizeServerUrl,
+  readLocalSetupToken,
+  startServerContainer,
+  waitForServerReady,
+} from '../lib/serverRunner.js';
+import { spinner, success } from '../lib/format.js';
+
+/** `ninedeploy setup` — create the first admin user on a fresh instance. */
+export async function setupAction(opts: { setupToken?: string } = {}): Promise<void> {
+  const existing = loadConfig();
+  const rawUrl = await prompt('Server URL', existing.baseUrl);
+  const baseUrl = normalizeServerUrl(rawUrl);
+
+  // If local host and not currently reachable, check if user wants to bootstrap it via Docker
+  const isLocal = baseUrl.includes('localhost') || baseUrl.includes('127.0.0.1');
+  if (isLocal) {
+    const reachable = await isServerReachable(baseUrl, 600);
+    if (!reachable) {
+      const dockerOk = await isDockerAvailable();
+      if (dockerOk) {
+        console.log(`\n  ℹ No NineDeploy server detected at ${baseUrl}`);
+        const startDocker = (await prompt('  Start a local NineDeploy server with Docker now? (Y/n)', 'Y')).toLowerCase().startsWith('y');
+        if (startDocker) {
+          try {
+            await spinner('Starting local NineDeploy server container', async () => {
+              const url = new URL(baseUrl);
+              const port = url.port ? Number(url.port) : 3000;
+              await startServerContainer({ port });
+              const ready = await waitForServerReady(baseUrl, 30, 1000);
+              if (!ready) throw new Error('Server container did not become ready in 30s');
+            });
+            success(`Server is ready at ${baseUrl}\n`);
+          } catch (err) {
+            console.error(`  ✗ Failed to start Docker container: ${err instanceof Error ? err.message : String(err)}`);
+          }
+        }
+      }
+    }
+  }
+
+  const email = await prompt('Admin email');
+  if (!email) {
+    console.error('Email is required.');
+    process.exitCode = 1;
+    return;
+  }
+  const name = (await prompt('Display name (optional)')) || undefined;
+  const password = await promptHidden('Password (min 8 chars)');
+  if (!password || password.length < 8) {
+    console.error('Password must be at least 8 characters.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const client = createClient({ baseUrl });
+  // 0.16: a fresh production instance gates the bootstrap on the installer's
+  // one-time setup token. Ask only when the server says it needs one (an
+  // older server has no such field and takes none).
+  let setupToken = (opts.setupToken ?? process.env['NINEDEPLOY_SETUP_TOKEN'] ?? '').trim();
+  if (!setupToken) {
+    const status = await Promise.resolve().then(() => client.auth.status()).catch(() => null);
+    if (status?.setupTokenRequired) {
+      // A panel this CLI started locally keeps its generated token in the container.
+      if (isLocal) setupToken = (await readLocalSetupToken()) ?? '';
+      if (!setupToken) setupToken = (await prompt('Setup token (printed by the installer)')).trim();
+    }
+  }
+  try {
+    const session = await client.auth.setup(setupToken ? { email, password, name, setupToken } : { email, password, name });
+    // Both tokens: the access token alone dies with the 15-minute TTL.
+    saveConfig({ baseUrl, token: session.tokens.accessToken, refreshToken: session.tokens.refreshToken });
+    console.log(`✓ Admin account created: ${session.user.email}`);
+    console.log('  Credentials saved — you are logged in.');
+  } catch (err) {
+    if (err instanceof NineDeployError) {
+      console.error(`✗ Setup failed (${err.status}): ${err.message}`);
+      if (err.status === 409) console.error('  The instance already has an admin user.');
+      if (err.status === 403) console.error('  Pass the setup token the installer printed: ninedeploy setup --setup-token <token>');
+    } else {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error('✗ Setup failed:', msg);
+      if (msg.includes('fetch failed') || msg.includes('ECONNREFUSED') || msg.includes('ENOTFOUND')) {
+        console.error(`  Could not connect to NineDeploy server at ${baseUrl}. Ensure the server is running.`);
+      }
+    }
+    process.exitCode = 1;
+  }
+}

package/src/commands/sources.ts

@@ -0,0 +1,317 @@
+import process from 'node:process';
+import type { NineDeployClient } from '../client.js';
+import { prompt, promptHidden } from '../prompts.js';
+import { c, error, header, info, kv, spinner, success, table } from '../lib/format.js';
+
+const PROVIDERS = ['github', 'gitlab', 'gitea', 'registry', 'custom'] as const;
+type Provider = (typeof PROVIDERS)[number];
+
+/** `ninedeploy sources list` */
+export async function sourcesList(client: NineDeployClient): Promise<void> {
+  header('Sources');
+  const rows = await spinner('Fetching sources', () => client.sources.list());
+  if (rows.length === 0) {
+    info('No sources yet. Run `ninedeploy sources add` to add a GitHub/GitLab PAT or SSH key.');
+    return;
+  }
+  table(
+    rows.map((s) => ({
+      id: s.id,
+      name: s.name,
+      type: s.type,
+      token: s.hasToken ? c.green('✓') : c.gray('—'),
+      deployKey: s.hasDeployKey ? c.green('✓') : c.gray('—'),
+      branch: s.defaultBranch ?? 'main',
+    })),
+    ['id', 'name', 'type', 'token', 'deployKey', 'branch'],
+  );
+}
+
+/**
+ * 0.13: a Gitea base URL from `--base-url`. Shape only (http(s), no
+ * credentials, query or fragment); the server re-checks it and refuses
+ * `http:` unless private egress is allowed.
+ */
+function parseBaseUrl(raw: string): string | null {
+  const trimmed = raw.trim().replace(/\/+$/, '');
+  try {
+    const url = new URL(trimmed);
+    if ((url.protocol !== 'https:' && url.protocol !== 'http:') || url.username || url.password || url.search || url.hash) return null;
+    return trimmed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve a credential with a strict, documented precedence:
+ *   1. explicit CLI flag (already handled by the caller)
+ *   2. NINEDEPLOY_GITHUB_TOKEN / NINEDEPLOY_GITLAB_TOKEN / NINEDEPLOY_SOURCE_TOKEN env var
+ *   3. interactive masked prompt
+ *
+ * The env fallback is the documented "no-stdin / CI" path: an operator
+ * piping `echo '' | ninedeploy …` keeps working without hanging.
+ */
+async function resolveSecret(envName: string, label: string): Promise<string> {
+  const fromEnv = process.env[envName]?.trim();
+  if (fromEnv) return fromEnv;
+  // Last resort: masked prompt. Honors a piped-stdin default (empty).
+  return await promptHidden(label);
+}
+
+/**
+ * F596: the generic provider-token env var for gitea / registry / custom.
+ * NOT `NINEDEPLOY_TOKEN` — that is the documented panel API token (MCP / API
+ * clients); reading it here stored the panel credential on the source and
+ * sent it to the third-party git host / registry, without a prompt.
+ */
+const SOURCE_TOKEN_ENV = 'NINEDEPLOY_SOURCE_TOKEN';
+
+/**
+ * F597: the prompt asks for the key on one line with escaped newlines (a
+ * hidden prompt ends at the first real newline). Turn the escapes back into
+ * the newlines the key file needs — a PEM/OpenSSH key never holds a backslash.
+ */
+async function resolveDeployKey(): Promise<string> {
+  const key = await resolveSecret('NINEDEPLOY_SSH_KEY', 'SSH private key (PEM, single line — escape newlines)');
+  return key.replace(/(?:\\r)?\\n/g, '\n');
+}
+
+/**
+ * F598: canonical decimal id only, as the server's parseId accepts it.
+ * `Number()` mapped `1e1`→10 and `0x4`→4, and NaN fell into the picker whose
+ * default is the first listed source — keygen then rewrote the wrong source.
+ */
+function parseSourceId(raw: string): number {
+  const t = raw.trim();
+  return /^[1-9]\d*$/.test(t) && Number.isSafeInteger(Number(t)) ? Number(t) : 0;
+}
+
+/** `ninedeploy sources add [name] [--base-url <url>]` */
+export async function sourcesAdd(client: NineDeployClient, nameArg?: string, opts: { baseUrl?: string } = {}): Promise<void> {
+  header('Add Source');
+  let baseUrl: string | undefined;
+  if (opts.baseUrl !== undefined) {
+    const parsed = parseBaseUrl(opts.baseUrl);
+    if (!parsed) return error(`Invalid --base-url: ${opts.baseUrl} (expected https://host[/path])`);
+    baseUrl = parsed;
+  }
+  const name = nameArg ?? (await prompt('Display name (e.g. github-personal)'));
+  /* v8 ignore next -- the dedicated "rejects when no name" test covers the truthy/falsy split, but
+   * v8 counts the early-return as a separate branch that the existing test only ticks on one side. */
+  if (!name) return error('Name is required');
+  const type = (await prompt('Provider (github | gitlab | gitea | registry | custom)', 'github')) as Provider;
+  if (!PROVIDERS.includes(type)) {
+    return error(`Unknown provider: ${type}. Choose one of: ${PROVIDERS.join(', ')}`);
+  }
+  if (baseUrl && type !== 'gitea') return error('--base-url applies to gitea sources only');
+  const defaultBranch = (await prompt('Default branch (used as suggestion only)', 'main')) || 'main';
+
+  let token: string | undefined;
+  let deployKey: string | undefined;
+  let registryUsername: string | undefined;
+
+  if (type === 'registry') {
+    registryUsername = (await prompt('Registry username (e.g. ci-bot)')) || undefined;
+    token = await resolveSecret(SOURCE_TOKEN_ENV, 'Registry password / access token (PAT)');
+  } else if (type === 'gitea') {
+    if (!baseUrl) {
+      const typed = (await prompt('Gitea base URL (e.g. https://git.example.com; empty = no live test or repo list)')).trim();
+      if (typed) {
+        const parsed = parseBaseUrl(typed);
+        if (!parsed) return error(`Invalid Gitea base URL: ${typed}`);
+        baseUrl = parsed;
+      }
+    }
+    token = await resolveSecret(SOURCE_TOKEN_ENV, 'Gitea access token');
+  } else if (type === 'custom') {
+    // Custom source: token or SSH key, your choice
+    const authKind = (await prompt('Auth kind (token | ssh)', 'token')) === 'ssh' ? 'ssh' : 'token';
+    if (authKind === 'ssh') {
+      deployKey = await resolveDeployKey();
+    } else {
+      token = await resolveSecret(SOURCE_TOKEN_ENV, 'Access token (PAT)');
+    }
+  } else {
+    // github / gitlab — both accept token or SSH
+    const authKind = (await prompt('Auth kind (token | ssh)', 'token')) === 'ssh' ? 'ssh' : 'token';
+    if (authKind === 'ssh') {
+      deployKey = await resolveDeployKey();
+    } else {
+      const envName = type === 'github' ? 'NINEDEPLOY_GITHUB_TOKEN' : 'NINEDEPLOY_GITLAB_TOKEN';
+      token = await resolveSecret(envName, `${type === 'github' ? 'GitHub' : 'GitLab'} Personal Access Token (PAT)`);
+    }
+  }
+
+  if (!token && !deployKey) {
+    return error('Either a token or an SSH deploy key is required');
+  }
+
+  try {
+    const created = await spinner('Creating source', () =>
+      client.sources.create({
+        name,
+        type,
+        token: token || undefined,
+        deployKey: deployKey || undefined,
+        registryUsername,
+        defaultBranch,
+        ...(baseUrl ? { baseUrl } : {}),
+      }),
+    );
+    success(`Source "${created.name}" created (id: ${created.id})`);
+    // Live validation right away — saves the user a DeployWizard round-trip.
+    if ((type === 'github' || type === 'gitlab' || (type === 'gitea' && baseUrl)) && token) {
+      await sourcesTest(client, String(created.id));
+    }
+  } catch (err) {
+    /* v8 ignore next -- exercised by the "API error" test which routes the error through error() */
+    error(err instanceof Error ? err.message : String(err));
+  }
+}
+
+/**
+ * F1011: the login, name, scopes, warnings and failure text come from the Git
+ * provider's API response (relayed by the server), so they must not drive the
+ * operator's terminal — the class F538 (`deploys watch`) and F880
+ * (`logs search`) closed for log lines. Same pattern set, but these are
+ * one-line metadata fields, so nothing is kept: OSC/DCS/APC/PM/SOS strings,
+ * every CSI (SGR included), stray escapes, and all C0/DEL/C1 controls
+ * (tab/LF/CR too — a newline in a login could forge a second status line).
+ */
+const ESC = String.fromCharCode(27);
+const PROVIDER_TEXT_CONTROL = new RegExp(
+  `${ESC}[\\]PX^_][\\s\\S]*?(?:${String.fromCharCode(7)}|${ESC}\\\\|$)` +
+    `|${ESC}\\[[0-?]*[ -/]*[@-~]` +
+    `|${ESC}[\\s\\S]?` +
+    '|[\\u0000-\\u001f\\u007f-\\u009f]',
+  'g',
+);
+export const plain = (value: unknown): string => String(value).replace(PROVIDER_TEXT_CONTROL, '');
+
+/**
+ * `ninedeploy sources test [id]` — verify the stored token still authenticates.
+ * GitHub successes also print what the token can see (F1008/F1011): its kind,
+ * its classic/OAuth scopes and each warning about missing private repositories.
+ */
+export async function sourcesTest(client: NineDeployClient, idArg?: string): Promise<void> {
+  header('Test Source Credentials');
+  if (idArg !== undefined && !parseSourceId(idArg)) return error(`Invalid source id: ${idArg}`);
+  let id = idArg === undefined ? 0 : parseSourceId(idArg);
+  if (!id) {
+    const sources = await spinner('Fetching sources', () => client.sources.list());
+    if (sources.length === 0) {
+      info('No sources yet. Add one with `ninedeploy sources add`.');
+      return;
+    }
+    table(
+      sources.map((s) => ({ id: s.id, name: s.name, type: s.type })),
+      ['id', 'name', 'type'],
+    );
+    const picked = await prompt('Source id to test', String(sources[0]!.id));
+    id = parseSourceId(picked);
+    if (!id) return error('A numeric source id is required');
+  }
+  const result = await spinner('Verifying credentials', () => client.sources.test(id));
+  if (result.ok) {
+    success(`${plain(result.provider)} token authenticates as ${plain(result.login)}${result.name ? ` (${plain(result.name)})` : ''}`);
+    if (result.tokenKind) kv('Token type', plain(result.tokenKind));
+    if (Array.isArray(result.scopes)) kv('Scopes', result.scopes.length > 0 ? result.scopes.map(plain).join(', ') : c.gray('none'));
+    // 0.13: a GitHub App source reports its installation's repository selection.
+    if (result.repositorySelection) kv('Repositories', plain(result.repositorySelection));
+    for (const warning of result.warnings ?? []) {
+      console.log(`  ${c.yellow('!')} ${c.yellow(`warning: ${plain(warning)}`)}`);
+    }
+  } else {
+    error(`${plain(result.provider ?? 'source')} check failed (status ${plain(result.status ?? 'n/a')}): ${plain(result.error ?? 'unknown error')}`);
+  }
+}
+
+/**
+ * `ninedeploy sources keygen [id]` — ask the panel server to generate an
+ * ed25519 deploy key pair for the source, then print the public key so it
+ * can be pasted into the Git host's "Deploy keys" UI.
+ */
+export async function sourcesKeygen(client: NineDeployClient, idArg?: string): Promise<void> {
+  header('Generate Deploy Key');
+  if (idArg !== undefined && !parseSourceId(idArg)) return error(`Invalid source id: ${idArg}`);
+  let id = idArg === undefined ? 0 : parseSourceId(idArg);
+  if (!id) {
+    const sources = await spinner('Fetching sources', () => client.sources.list());
+    if (sources.length === 0) {
+      info('No sources yet. Add one with `ninedeploy sources add` first.');
+      return;
+    }
+    table(
+      sources.map((s) => ({ id: s.id, name: s.name, type: s.type })),
+      ['id', 'name', 'type'],
+    );
+    const picked = await prompt('Source id to generate a deploy key for', String(sources[0]!.id));
+    id = parseSourceId(picked);
+    if (!id) return error('A numeric source id is required');
+  }
+  const result = await spinner('Generating ed25519 key pair on the panel server', () => client.sources.generateDeployKey(id));
+  success(`Deploy key generated (fingerprint ${result.fingerprint}).`);
+  console.log();
+  console.log(`  ${c.bold('Public key — paste this into your Git host\'s Deploy keys:')}`);
+  console.log(`    ${c.cyan(result.publicKey)}`);
+  console.log();
+  console.log(`  ${c.gray('GitHub:    repo → Settings → Security → Deploy keys → Add deploy key')}`);
+  console.log(`  ${c.gray('GitLab:    project → Settings → Repository → Deploy keys')}`);
+  console.log(`  ${c.gray('Gitea:     repo → Settings → Deploy keys')}`);
+  console.log();
+  info('The private key is encrypted at rest on the panel and never shown.');
+}
+
+/** `ninedeploy sources remove [id]` */
+export async function sourcesRemove(client: NineDeployClient, idArg?: string): Promise<void> {
+  header('Remove Source');
+  if (idArg !== undefined && !parseSourceId(idArg)) return error(`Invalid source id: ${idArg}`);
+  let id = idArg === undefined ? 0 : parseSourceId(idArg);
+  if (!id) {
+    const sources = await spinner('Fetching sources', () => client.sources.list());
+    if (sources.length === 0) {
+      info('No sources to remove.');
+      return;
+    }
+    table(
+      sources.map((s) => ({ id: s.id, name: s.name, type: s.type })),
+      ['id', 'name', 'type'],
+    );
+    const picked = await prompt('Source id to remove', String(sources[0]!.id));
+    id = parseSourceId(picked);
+    if (!id) return error('A numeric source id is required');
+  }
+  const confirm = await prompt(`Type "delete" to confirm removal of source #${id}`, '');
+  if (confirm.trim() !== 'delete') {
+    info('Aborted.');
+    return;
+  }
+  try {
+    await spinner('Removing source', () => client.sources.remove(id));
+    success(`Source #${id} removed.`);
+    info('Services deployed from it keep working, but new clones of private repos will fail until it is re-added.');
+  } catch (err) {
+    /* v8 ignore next -- exercised by the "API error" test which routes the error through error() */
+    error(err instanceof Error ? err.message : String(err));
+  }
+}
+
+/** `ninedeploy sources show <id>` */
+export async function sourcesShow(client: NineDeployClient, idArg: string): Promise<void> {
+  const id = Number(idArg);
+  if (!id) return error('Usage: ninedeploy sources show <id>');
+  header(`Source #${id}`);
+  const sources = await spinner('Fetching', () => client.sources.list());
+  const s = sources.find((x) => x.id === id);
+  if (!s) return error(`Source #${id} not found`);
+  kv('Name', s.name);
+  kv('Type', s.type);
+  kv('Token', s.hasToken ? c.green('✓ set') : c.gray('—'));
+  kv('Deploy key', s.hasDeployKey ? c.green('✓ set') : c.gray('—'));
+  kv('Registry user', s.registryUsername ?? '—');
+  if (s.type === 'gitea') kv('Base URL', s.baseUrl ?? c.gray('not set (no live test or repo list)'));
+  kv('Default branch', s.defaultBranch ?? 'main');
+  kv('Created', s.createdAt);
+  kv('Updated', s.updatedAt);
+}