ninedeploy 0.18.26 → 0.18.27

package/src/commands/importPlan.ts

@@ -0,0 +1,143 @@
+/**
+ * `ninedeploy import plan <coolify|dokploy|caprover> --url <source panel>`
+ *
+ * A1 step 1 (docs/plans/COMPETITIVE_ROADMAP_2026-11.md): read another
+ * platform's API from this machine and print what NineDeploy would create,
+ * what it cannot carry, and what needs a person. Nothing is created on
+ * NineDeploy and nothing changes on the source. The source credential is read
+ * from an environment variable or a hidden prompt, never from the command
+ * line, and stays on this machine; the plan holds variable names only.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { planFromCaprover } from '../lib/importers/caprover.js';
+import { planFromHeroku } from '../lib/importers/heroku.js';
+import { planFromCoolify } from '../lib/importers/coolify.js';
+import { planFromDokploy } from '../lib/importers/dokploy.js';
+import type { ImportPlan, SourceGet, SourceKind } from '../lib/importers/plan.js';
+import { caproverSource, coolifySource, dokploySource, normaliseBase, OtpRequiredError, SourceError } from '../lib/importers/sources.js';
+import { c, error, header, info, success } from '../lib/format.js';
+import { promptHidden } from '../prompts.js';
+
+export const IMPORT_SOURCES: readonly SourceKind[] = ['coolify', 'dokploy', 'caprover', 'heroku'];
+
+type PanelSource = Exclude<SourceKind, 'heroku'>;
+
+/** Where each source's credential comes from, without the command line. Heroku is read from files and needs none. */
+export const CREDENTIAL_ENV: Record<PanelSource, string> = {
+  coolify: 'NINEDEPLOY_IMPORT_TOKEN',
+  dokploy: 'NINEDEPLOY_IMPORT_TOKEN',
+  caprover: 'NINEDEPLOY_IMPORT_PASSWORD',
+};
+const PROMPT: Record<PanelSource, string> = {
+  coolify: 'Coolify API token (a "read" token is enough): ',
+  dokploy: 'Dokploy API key: ',
+  caprover: 'CapRover password: ',
+};
+
+export interface ImportPlanDeps {
+  /** Heroku: the checkout to read app.json / Procfile from, the branch, and the Heroku app name. */
+  heroku?: { dir?: string; branch?: string; app?: string };
+  /** Reads a file of the checkout, or undefined when it does not exist (tests replace it). */
+  readFile?: (file: string) => string | undefined;
+  env?: NodeJS.ProcessEnv;
+  ask?: (message: string) => Promise<string>;
+  fetch?: typeof fetch;
+}
+
+/** Build the plan (no output). Throws SourceError with a reason a person can act on. */
+export async function buildImportPlan(kind: string, url: string, deps: ImportPlanDeps = {}): Promise<ImportPlan> {
+  if (!IMPORT_SOURCES.includes(kind as SourceKind)) throw new SourceError(`Unknown source "${kind}" (expected ${IMPORT_SOURCES.join(', ')}).`);
+  const source = kind as SourceKind;
+  if (source === 'heroku') {
+    // The repository URL stays whole (normaliseBase would cut its path).
+    const dir = path.resolve(deps.heroku?.dir ?? '.');
+    const read = deps.readFile ?? ((f: string) => (existsSync(f) ? readFileSync(f, 'utf8') : undefined));
+    try {
+      return planFromHeroku(
+        { appJson: read(path.join(dir, 'app.json')), procfile: read(path.join(dir, 'Procfile')), herokuYml: read(path.join(dir, 'heroku.yml')) !== undefined },
+        { repoUrl: url.trim(), branch: deps.heroku?.branch ?? 'main', app: deps.heroku?.app, dirName: path.basename(dir) },
+      );
+    } catch (err) {
+      throw new SourceError(err instanceof Error ? err.message : String(err));
+    }
+  }
+  const env = deps.env ?? process.env;
+  const ask = deps.ask ?? promptHidden;
+  const base = normaliseBase(url);
+  const credential = env[CREDENTIAL_ENV[source]]?.trim() || (await ask(PROMPT[source])).trim();
+  if (!credential) throw new SourceError(`No credential: set ${CREDENTIAL_ENV[source]} or type it at the prompt.`);
+  let get: SourceGet;
+  if (source === 'coolify') get = coolifySource(base, credential, deps.fetch);
+  else if (source === 'dokploy') get = dokploySource(base, credential, deps.fetch);
+  else {
+    const otpEnv = env['NINEDEPLOY_IMPORT_OTP']?.trim();
+    try {
+      get = await caproverSource(base, credential, otpEnv || undefined, deps.fetch);
+    } catch (err) {
+      if (!(err instanceof OtpRequiredError) || otpEnv) throw err;
+      const otp = (await ask('CapRover two-factor code: ')).trim();
+      get = await caproverSource(base, credential, otp, deps.fetch);
+    }
+  }
+  if (source === 'coolify') return planFromCoolify(get, base);
+  if (source === 'dokploy') return planFromDokploy(get, base);
+  return planFromCaprover(get, base);
+}
+
+/** The plan as text a person reads: per item, what would be created and what needs them. */
+export function renderImportPlan(plan: ImportPlan): string {
+  const lines: string[] = [];
+  const s = plan.source;
+  lines.push(`Source: ${s.kind}${s.version ? ` ${s.version}` : ''} at ${s.url}`);
+  lines.push(`Scope: ${s.scope}`);
+  lines.push('');
+  lines.push(`Services (${plan.services.length})`);
+  for (const svc of plan.services) {
+    const what = svc.kind === 'image' ? `image ${svc.create.image ?? '(unknown)'}` : svc.kind === 'git' ? `git ${svc.create.repoUrl ?? '(no repository)'}${svc.create.branch ? `@${svc.create.branch}` : ''}` : 'compose stack';
+    lines.push(`  • ${svc.name}: ${what}${svc.create.port ? `, port ${svc.create.port}` : ''}`);
+    if (svc.domains.length) lines.push(`      domains: ${svc.domains.map((d) => `${d.https ? 'https' : 'http'}://${d.host}${d.sourceDefault ? " (the source's own host; stays)" : ''}`).join(', ')}`);
+    if (svc.env.length) lines.push(`      env: ${svc.env.length} variable(s): ${svc.env.map((e) => e.key).join(', ')} (names only)`);
+    if (svc.volumes.length) lines.push(`      volumes: ${svc.volumes.map((v) => v.mountPath).join(', ')}`);
+    if (svc.create.build?.startCmd) lines.push(`      start: ${svc.create.build.startCmd}`);
+    if (svc.settings?.healthCheck) lines.push(`      health check: ${svc.settings.healthCheck}`);
+    if (svc.attachments?.length) lines.push(`      attaches: ${svc.attachments.map((a) => `${a.database} as ${a.envAlias}`).join(', ')}`);
+    for (const i of svc.issues) lines.push(`      ${i.level === 'unsupported' ? '✗' : i.level === 'manual' ? '!' : '·'} ${i.option}: ${i.detail}`);
+  }
+  lines.push('');
+  lines.push(`Databases (${plan.databases.length})`);
+  for (const db of plan.databases) {
+    lines.push(`  • ${db.name}: ${db.engine ?? 'no managed equivalent'}${db.image ? ` (${db.image})` : ''}`);
+    for (const i of db.issues) lines.push(`      ${i.level === 'unsupported' ? '✗' : i.level === 'manual' ? '!' : '·'} ${i.option}: ${i.detail}`);
+  }
+  lines.push('');
+  for (const n of plan.notes) lines.push(`Note: ${n}`);
+  return lines.join('\n');
+}
+
+export async function importPlanAction(
+  kind: string,
+  opts: { url: string; json?: boolean; out?: string; dir?: string; branch?: string; app?: string },
+  deps: ImportPlanDeps = {},
+): Promise<void> {
+  let plan: ImportPlan;
+  try {
+    plan = await buildImportPlan(kind, opts.url, { ...deps, heroku: { dir: opts.dir, branch: opts.branch, app: opts.app } });
+  } catch (err) {
+    error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+  const json = `${JSON.stringify(plan, null, 2)}\n`;
+  if (opts.out) {
+    writeFileSync(opts.out, json);
+    success(`Plan written to ${opts.out}`);
+  }
+  if (opts.json) {
+    process.stdout.write(json);
+    return;
+  }
+  header(`Import plan: ${plan.services.length} service(s), ${plan.databases.length} database(s)`);
+  console.log(renderImportPlan(plan));
+  info(`${c.dim('Nothing was created or changed.')} Save it with --out plan.json, then preview step 2 with \`ninedeploy import apply plan.json\`.`);
+}

package/src/commands/importVolumes.ts

@@ -0,0 +1,168 @@
+/**
+ * `ninedeploy import data <plan> --volume <service>=<file.tar.gz>` (A1 step 3).
+ *
+ * Moves the contents of a service's data volume: the volume mounted at the
+ * path the service was created with (`create.volumeMount`), which NineDeploy
+ * keeps in `nd-svc-<slug>-data`.
+ *
+ * - The command printed for the source host mounts a named volume by its
+ *   name, read-only (no container needed: a Swarm service scaled to 0 has
+ *   none); a bind mount is read through the source container instead. It
+ *   writes a gzipped tar with numeric owners, the format the panel restores.
+ * - The archive goes through the panel's chunked volume import with its
+ *   sha256, which the panel checks before the volume is touched. The panel
+ *   snapshots a volume that already exists, then swaps the archive in.
+ * - The receipt records the import id, sha256 and size. A stopped upload
+ *   resumes, a volume already imported is not imported again.
+ */
+import path from 'node:path';
+import type { VolumeImport } from '@ninedeploy/schemas';
+import type { NineDeployClient } from '../client.js';
+import type { ImportPlan, PlanService } from '../lib/importers/plan.js';
+import { fileBase, flagArg, isPlainName, shellQuote, sourceTarget } from '../lib/importers/shell.js';
+import type { ImportReceipt } from './importApply.js';
+
+/** The panel calls the volume half makes; NineDeployClient satisfies it. */
+export interface VolumeClient {
+  volumeImports: {
+    importFile: NineDeployClient['volumeImports']['importFile'];
+    get: NineDeployClient['volumeImports']['get'];
+    wait: NineDeployClient['volumeImports']['wait'];
+  };
+}
+
+/** The helper image the panel itself tars volumes with (server lib/inventory.ts HELPER_IMAGE). */
+const TAR_IMAGE = 'alpine:3.21';
+
+/**
+ * The source-host command that archives a service's data volume, or why it
+ * cannot be printed. Null when the service has no data volume.
+ */
+export function volumeCommand(s: PlanService): { command: string; file: string; notes: string[] } | { manual: string } | null {
+  const mount = s.create.volumeMount;
+  if (!mount) return null;
+  const v = s.volumes.find((x) => x.mountPath === mount);
+  if (v?.source === 'file') return { manual: `${mount} is a file mount on the source; recreate it under Service → File mounts` };
+  const notes: string[] = [];
+  const others = s.volumes.filter((x) => x.mountPath !== mount && x.source !== 'file');
+  if (others.length) notes.push(`Only ${mount} moves; copy ${others.map((x) => x.mountPath).join(', ')} by hand.`);
+  const file = `${fileBase(s.name)}.volume.tar.gz`;
+  // A named volume is mounted by its name: that needs no container, and a
+  // Swarm service scaled to 0 has none left (checked live on CapRover 1.16,
+  // which names the Docker volume exactly as the app's volumeName).
+  if (v?.source === 'volume' && v.name && isPlainName(v.name)) {
+    return { command: `docker run --rm -v ${v.name}:/v:ro ${TAR_IMAGE} tar -czf - --numeric-owner -C /v . > ${file}`, file, notes };
+  }
+  // A bind mount, or a volume whose name the plan does not hold: borrow the
+  // source container's mounts, which works only while it still exists.
+  const { target, note } = sourceTarget(s.runtime, `${s.name}'s container`, true);
+  if (note) notes.push(note);
+  notes.push('This reads the mount through the source container, so stop the app without removing its container (a Swarm service scaled to 0 has none left); or archive the host directory yourself with tar -czf - --numeric-owner -C <dir> .');
+  return {
+    command: `docker run --rm --volumes-from ${target}:ro ${TAR_IMAGE} tar -czf - --numeric-owner -C ${shellQuote(mount)} . > ${file}`,
+    file,
+    notes,
+  };
+}
+
+/** The preview lines for every service with a data volume. */
+export function renderVolumePreview(plan: ImportPlan, receipt: ImportReceipt | null): string[] {
+  const out: string[] = [];
+  for (const s of plan.services) {
+    const cmd = volumeCommand(s);
+    if (!cmd) continue;
+    if (out.length === 0) out.push('', 'Volumes (the data volume of each service; stop the service on the source first):');
+    const created = receipt?.items[`service:${s.ref}`];
+    const done = receipt?.items[`volume:${s.ref}`];
+    if (!created || created.state !== 'done') out.push(`  – ${s.name}: not created yet (run import apply first)`);
+    else if (done?.state === 'done') out.push(`  ✓ ${s.name}: imported (#${done.importId}, sha256 ${done.sha256?.slice(0, 12)}…)`);
+    else if ('manual' in cmd) out.push(`  – ${s.name}: ${cmd.manual}`);
+    else {
+      out.push(`  + ${s.name} (${s.create.volumeMount}, NineDeploy service #${created.id}):`);
+      out.push(`      ${cmd.command}`);
+      for (const n of cmd.notes) out.push(`      ${n}`);
+      out.push(`      then: --volume ${flagArg(s.name, cmd.file)}`);
+    }
+  }
+  return out;
+}
+
+export interface VolumeDeps {
+  client: VolumeClient;
+  receipt: ImportReceipt;
+  save: (receipt: ImportReceipt) => void;
+  hashFile: (file: string) => Promise<{ sha256: string; bytes: number }>;
+  open: (file: string) => (offset: number) => AsyncIterable<Uint8Array>;
+  now?: () => Date;
+}
+
+/** Check every archive, then import each, recording every step in the receipt. */
+export async function importVolumes(plan: ImportPlan, archives: Record<string, string>, deps: VolumeDeps): Promise<ImportReceipt> {
+  const now = deps.now ?? (() => new Date());
+  const { receipt } = deps;
+  const jobs: Array<{ s: PlanService; serviceId: number; file: string; sha256: string; bytes: number }> = [];
+  for (const [name, file] of Object.entries(archives)) {
+    const s = plan.services.find((x) => x.name === name);
+    if (!s) throw new Error(`--volume names no service in the plan: ${name}.`);
+    const created = receipt.items[`service:${s.ref}`];
+    if (created?.state !== 'done' || created.id === undefined) throw new Error(`${name} has not been created yet: run \`ninedeploy import apply\` first.`);
+    if (!s.create.volumeMount) throw new Error(`${name} has no data volume in the plan (no volume mount), so there is nothing to import into.`);
+    const { sha256, bytes } = await deps.hashFile(file);
+    if (bytes === 0) throw new Error(`${file} is empty.`);
+    const prior = receipt.items[`volume:${s.ref}`];
+    if (prior?.sha256 !== undefined && prior.sha256 !== sha256 && (prior.state === 'done' || prior.importId !== undefined)) {
+      throw new Error(`${name} already has volume import #${prior.importId} recorded for a different archive. import data does not import twice; restore its pre-import snapshot or use the panel if you mean to.`);
+    }
+    jobs.push({ s, serviceId: created.id, file, sha256, bytes });
+  }
+
+  for (const job of jobs) {
+    const key = `volume:${job.s.ref}`;
+    const prior = receipt.items[key];
+    if (prior?.state === 'done') continue;
+    const base = { kind: 'volume' as const, ref: job.s.ref, name: job.s.name, id: job.serviceId, sha256: job.sha256, bytes: job.bytes };
+    const put = (state: 'pending' | 'done' | 'failed', notes: string[], importId?: number) => {
+      receipt.items[key] = { ...base, state, notes, ...(importId !== undefined ? { importId } : {}), at: now().toISOString() };
+      deps.save(receipt);
+    };
+    let resumeImportId = prior?.sha256 === job.sha256 ? prior.importId : undefined;
+    put('pending', [], resumeImportId);
+    let row: VolumeImport;
+    try {
+      const existing = resumeImportId === undefined ? undefined : await deps.client.volumeImports.get(job.serviceId, resumeImportId);
+      if (existing?.status === 'completed') row = existing;
+      else if (existing?.status === 'running') row = await deps.client.volumeImports.wait(job.serviceId, existing.id);
+      else {
+        if (existing && ['failed', 'cancelled', 'expired'].includes(existing.status)) {
+          resumeImportId = undefined;
+          put('pending', []);
+        }
+        row = await deps.client.volumeImports.importFile(job.serviceId, deps.open(job.file), {
+          sizeBytes: job.bytes,
+          sha256: job.sha256,
+          filename: path.basename(job.file),
+          ...(resumeImportId !== undefined ? { resumeImportId } : {}),
+          onCreated: (r) => put('pending', [], r.id),
+        });
+        row = await deps.client.volumeImports.wait(job.serviceId, row.id);
+      }
+    } catch (err) {
+      const status = (err as { status?: number }).status;
+      const message = status === 404 && receipt.items[key]?.importId === undefined
+        ? 'This panel has no volume import yet: update it, or copy the files by hand.'
+        : err instanceof Error ? err.message : String(err);
+      put('failed', [message], receipt.items[key]?.importId);
+      continue;
+    }
+    if (row.status === 'completed') {
+      put('done', [
+        `Imported into ${row.volumeName}: ${job.bytes} bytes, sha256 checked by the panel.`,
+        ...(row.safetyBackupId ? [`The volume's earlier contents are in volume backup #${row.safetyBackupId} (pre-import).`] : []),
+      ], row.id);
+    } else {
+      // The panel's message can quote file names from the archive, so the receipt keeps the status only.
+      put('failed', [`Volume import #${row.id} ended ${row.status}. Details: the service's volume imports on the panel.`], row.id);
+    }
+  }
+  return receipt;
+}

package/src/index.ts

@@ -38,6 +38,7 @@ import {
 } from './commands/notifications.js';
 import { databasePgbouncer } from './commands/pgbouncer.js';
 import { pitrBaseBackup, pitrDisable, pitrEnable, pitrRecover, pitrRecoveries, pitrStatus } from './commands/pitr.js';
+import { upgradeFinalize, upgradeRollback, upgradeStart, upgradeStatus } from './commands/databaseUpgrade.js';
 import { backupPolicyGet, backupPolicySet } from './commands/backupPolicy.js';
 import { logsSearch } from './commands/logs.js';
 import {
@@ -128,6 +129,10 @@ import {
 import {
   egressClearAction, egressListAction, egressSetAction,
 } from './commands/egress.js';
+import { importPlanAction } from './commands/importPlan.js';
+import { importApplyAction } from './commands/importApply.js';
+import { importDataAction } from './commands/importData.js';
+import { type ImportCutoverOpts, importCutoverAction } from './commands/importCutover.js';
 import { ipsForgetAction, ipsListAction, ipsSetAction } from './commands/hostIps.js';
 import {
   ssoAddAction, ssoListAction, ssoRemoveAction,
@@ -358,6 +363,24 @@ databases
     databasePgbouncer(getClient(), dbId, action, opts),
   );
 
+// ── Major-version upgrades (O2) ──────────────────────────────────────────
+const upgradeCmd = databases
+  .command('upgrade')
+  .description('Move a PostgreSQL database to a newer major: dump, restore into a new volume, compare, switch (previous volume kept)');
+upgradeCmd.command('status <dbId>').description('The running major, the majors it can move to, and the upgrade history')
+  .action((dbId: string) => upgradeStatus(getClient(), dbId));
+upgradeCmd.command('start <dbId>').description('Upgrade to a newer major; the database stops until it is done (database admin)')
+  .requiredOption('--to <major>', 'Target PostgreSQL major, e.g. 18')
+  .option('-y, --yes', 'Skip the confirmation')
+  .option('--no-wait', 'Return once the upgrade is admitted')
+  .action((dbId: string, o: { to?: string; yes?: boolean; wait?: boolean }) => upgradeStart(getClient(), dbId, o));
+upgradeCmd.command('rollback <dbId> <upgradeId>').description('Point the database back at the previous volume (database admin)')
+  .option('-y, --yes', 'Skip the confirmation')
+  .action((dbId: string, upgradeId: string, o: { yes?: boolean }) => upgradeRollback(getClient(), dbId, upgradeId, o));
+upgradeCmd.command('finalize <dbId> <upgradeId>').description('Delete the volume the database no longer uses; no rollback after this (database admin)')
+  .option('-y, --yes', 'Skip the confirmation')
+  .action((dbId: string, upgradeId: string, o: { yes?: boolean }) => upgradeFinalize(getClient(), dbId, upgradeId, o));
+
 // ── PostgreSQL point-in-time recovery (R3) ───────────────────────────────
 const pitrCmd = databases
   .command('pitr')
@@ -695,6 +718,44 @@ egressCmd
   .option('--driver <name>', 'Target a specific driver (default: first registered)')
   .action((projectId: string, opts: { driver?: string }) => egressClearAction(getClient(), projectId, opts));
 
+// ── Import from another platform (A1 step 1: read-only plan) ─────────────
+const importCmd = program.command('import').description('Move from Coolify, Dokploy, CapRover or Heroku: plan (read-only), apply, data, cutover');
+importCmd
+  .command('plan <source>')
+  .description('Read a coolify | dokploy | caprover panel, or a Heroku app\'s app.json and Procfile, and print what NineDeploy would create. Nothing is created or changed. The credential comes from NINEDEPLOY_IMPORT_TOKEN (Coolify, Dokploy) or NINEDEPLOY_IMPORT_PASSWORD (CapRover, plus NINEDEPLOY_IMPORT_OTP), or a hidden prompt; Heroku needs none.')
+  .requiredOption('--url <url>', 'The source panel (e.g. https://coolify.example.com), or for heroku the app\'s git repository')
+  .option('--dir <path>', 'heroku: a checkout of the repository holding app.json / Procfile (default: .)')
+  .option('--branch <branch>', 'heroku: the branch NineDeploy deploys (default: main)')
+  .option('--app <name>', 'heroku: the Heroku app name, for the pg:backups command')
+  .option('--json', 'Print the plan as JSON')
+  .option('--out <file>', 'Also write the plan (JSON, names only) to a file')
+  .action((source: string, opts: { url: string; json?: boolean; out?: string; dir?: string; branch?: string; app?: string }) => importPlanAction(source, opts));
+importCmd
+  .command('apply <plan>')
+  .description('Create the services and databases of a saved plan (import plan --out) on this panel. Without --yes it only shows what it would create. Never deploys and never adds a domain; keeps a resumable receipt next to the plan.')
+  .option('--yes', 'Create them')
+  .option('--project <id>', 'Tag every created service and database with this project')
+  .option('--dotenv <service=path>', 'Environment values for a service, from a .env file (repeatable)', (v: string, prev: string[]) => [...prev, v], [] as string[])
+  .option('--receipt <file>', 'Receipt file (default: <plan>.receipt.json)')
+  .action((plan: string, opts: { yes?: boolean; project?: string; dotenv?: string[]; receipt?: string }) => importApplyAction(plan, opts));
+importCmd
+  .command('data <plan>')
+  .description('Move database contents into the databases import apply created. Without --yes it prints the cutover order and the dump command to run on the source host for each database.')
+  .option('--dump <database=file>', 'A dump to import into that database (repeatable); its sha256 is checked by the panel', (v: string, prev: string[]) => [...prev, v], [] as string[])
+  .option('--volume <service=file>', 'A gzipped tar of that service\'s data volume (repeatable); restored after a snapshot of what is there', (v: string, prev: string[]) => [...prev, v], [] as string[])
+  .option('--yes', 'Import the dumps and archives')
+  .option('--receipt <file>', 'Receipt file (default: <plan>.receipt.json)')
+  .action((plan: string, opts: { dump?: string[]; volume?: string[]; yes?: boolean; receipt?: string }) => importDataAction(plan, opts));
+importCmd
+  .command('cutover <plan>')
+  .description('Add the planned domains once each service runs a successful deploy and the hostname\'s DNS already points at this panel. Without --yes it only reports what is ready.')
+  .option('--yes', 'Add (or verify) the domains that pass')
+  .option('--expect <address>', 'The address DNS must point at (repeatable; default: Settings → DNS records)', (v: string, prev: string[]) => [...prev, v], [] as string[])
+  .option('--resolver <ip>', 'DNS server to query (default: the system\'s)')
+  .option('--skip-dns-check <host>', 'Skip the DNS check for a proxied host (repeatable; refused while the Cloudflare integration is on)', (v: string, prev: string[]) => [...prev, v], [] as string[])
+  .option('--receipt <file>', 'Receipt file (default: <plan>.receipt.json)')
+  .action((plan: string, opts: ImportCutoverOpts) => importCutoverAction(plan, opts));
+
 // ── SSO (G-22) ───────────────────────────────────────────────────────────
 const ssoCmd = program.command('sso').description('Manage OIDC / SAML SSO providers (G-22)');
 ssoCmd.command('list').description('List every configured provider').action(() => ssoListAction(getClient()));

package/src/lib/importers/caprover.ts

@@ -0,0 +1,141 @@
+/**
+ * CapRover (field names checked against v1.16.0, 74a61ff2): one call,
+ * `GET /api/v2/user/apps/appDefinitions/`, returns every app. The fetcher
+ * signs in, sends `x-captain-auth`, and unwraps CapRover's `{status, data}`
+ * envelope (errors arrive with HTTP 200 and a non-100 status).
+ *
+ * CapRover returns secrets in plain text in that list: env values, the git
+ * password and SSH key, webhook and deploy tokens, the HTTP-auth hash. The
+ * adapter copies none of them into the plan.
+ */
+import {
+  DATA_NOT_MOVED, emptyPlan, firstVolumeMount, planDomain, replicasFor, stripUserinfo,
+  type ImportPlan, type PlanDatabase, type PlanEngine, type PlanIssue, type PlanService, type SourceGet,
+} from './plan.js';
+
+type Obj = Record<string, unknown>;
+const str = (v: unknown): string | undefined => (typeof v === 'string' && v.trim() ? v.trim() : undefined);
+const list = (v: unknown): Obj[] => (Array.isArray(v) ? (v as Obj[]) : []);
+
+/** One-click database apps carry the template name as a tag (OneClickAppDeploymentHelper). */
+const ONE_CLICK_DATABASES: Record<string, PlanEngine> = {
+  postgres: 'postgres', mysql: 'mysql', mariadb: 'mariadb', mongodb: 'mongo', redis: 'redis', keydb: 'keydb', dragonfly: 'dragonfly', clickhouse: 'clickhouse',
+};
+
+/** The image CapRover runs for the deployed version, if it is not one it built itself. */
+function deployedImage(app: Obj): { image?: string; builtByCaprover: boolean; neverDeployed?: boolean } {
+  const deployed = Number(app['deployedVersion']);
+  const version = list(app['versions']).find((v) => Number(v['version']) === deployed);
+  const image = str(version?.['deployedImageName']);
+  if (!image) return { builtByCaprover: true };
+  // A registered app runs CapRover's placeholder until its first deploy (checked live on v1.16.0).
+  if (/^caprover\/caprover-placeholder-app(:|$)/.test(image)) return { builtByCaprover: false, neverDeployed: true };
+  // Images CapRover builds are tagged img-captain-<app>, optionally in its own registry.
+  if (/(^|\/)img-captain-/.test(image)) return { builtByCaprover: true };
+  return { image, builtByCaprover: false };
+}
+
+function appItem(app: Obj, rootDomain: string): PlanService | null {
+  const name = String(app['appName']);
+  const issues: PlanIssue[] = [];
+  const repoInfo = (app['appPushWebhook'] as Obj | undefined)?.['repoInfo'] as Obj | undefined;
+  const repo = str(repoInfo?.['repo']);
+  const { image, builtByCaprover, neverDeployed } = deployedImage(app);
+  const base = { name, type: 'docker' as const };
+  let kind: PlanService['kind'];
+  let create: PlanService['create'];
+  if (repo) {
+    kind = 'git';
+    create = { ...base, repoUrl: stripUserinfo(repo), branch: str(repoInfo?.['branch']), build: { buildPack: 'auto' } };
+    const def = str(app['captainDefinitionRelativeFilePath']);
+    issues.push({ level: 'info', option: 'captain-definition', detail: `Built from ${def ?? './captain-definition'}; NineDeploy detects the build (a Dockerfile it references keeps working with Build pack: Dockerfile).` });
+    if (str(repoInfo?.['user']) || str(repoInfo?.['sshKey']) || str(repoInfo?.['password'])) {
+      issues.push({ level: 'manual', option: 'repoInfo', detail: 'Repository credentials do not transfer: reconnect the repository in NineDeploy.' });
+    }
+  } else if (image && !builtByCaprover) {
+    kind = 'image';
+    create = { ...base, image };
+  } else if (neverDeployed) {
+    kind = 'image';
+    create = base;
+    issues.push({ level: 'manual', option: 'deployedVersion', detail: 'Never deployed in CapRover (it still runs the placeholder app): set an image or a repository for it in NineDeploy.' });
+  } else {
+    kind = 'image';
+    create = base;
+    issues.push({ level: 'unsupported', option: 'deployedImageName', detail: 'Built by CapRover from an upload or the CLI, with no repository on record: its image lives in CapRover. Push the source to a repository, or the image to a registry, then import.' });
+  }
+
+  const port = Number(app['containerHttpPort']);
+  if (Number.isInteger(port) && port > 0) create.port = port;
+  const replicas = replicasFor(app['instanceCount'], issues);
+  if (replicas) create.replicas = replicas;
+  if (app['instanceCount'] === 0) issues.push({ level: 'info', option: 'instanceCount', detail: 'Stopped in CapRover (0 instances); NineDeploy runs one when it deploys the service.' });
+
+  const domains: PlanService['domains'] = [];
+  if (app['notExposeAsWebApp'] !== true) {
+    domains.push(planDomain(`${name}.${rootDomain}`, app['hasDefaultSubDomainSsl'] === true, true));
+    issues.push({ level: 'info', option: 'default subdomain', detail: `${name}.${rootDomain} is CapRover's own subdomain; it moves only if that DNS points at NineDeploy.` });
+  }
+  for (const d of list(app['customDomain'])) {
+    const host = str(d['publicDomain']);
+    if (host) domains.push(planDomain(host, d['hasSsl'] === true));
+  }
+
+  const volumes: PlanService['volumes'] = list(app['volumes'])
+    .map((v) => ({ mountPath: str(v['containerPath']) ?? '', source: (str(v['hostPath']) ? 'bind' : 'volume') as 'bind' | 'volume', name: str(v['volumeName']) }))
+    .filter((v) => v.mountPath);
+  const mount = firstVolumeMount(volumes, issues);
+  if (mount) create.volumeMount = mount;
+
+  const ports = list(app['ports']);
+  if (ports.length) issues.push({ level: 'manual', option: 'ports', detail: `${ports.length} host port mapping(s) (${ports.map((p) => `${p['hostPort']}:${p['containerPort']}`).join(', ')}); set Public Host Port or port mappings by hand.` });
+  if (app['httpAuth']) issues.push({ level: 'manual', option: 'httpAuth', detail: 'HTTP basic auth was on; protect the service with forward auth in NineDeploy (the password hash is not carried).' });
+  if (str(app['customNginxConfig'])) issues.push({ level: 'unsupported', option: 'customNginxConfig', detail: 'A custom nginx config has no equivalent; NineDeploy routes with Traefik (redirects, headers and middlewares are set per domain).' });
+  if (str(app['preDeployFunction'])) issues.push({ level: 'unsupported', option: 'preDeployFunction', detail: 'CapRover pre-deploy scripts have no equivalent.' });
+  if (str(app['serviceUpdateOverride'])) issues.push({ level: 'unsupported', option: 'serviceUpdateOverride', detail: 'Swarm service overrides are not carried.' });
+  if (str(app['nodeId'])) issues.push({ level: 'manual', option: 'nodeId', detail: 'Pinned to a CapRover node; choose a NineDeploy server for it.' });
+
+  return {
+    ref: name, name, kind, create, domains,
+    env: list(app['envVars']).map((e) => str(e['key'])).filter((k): k is string => !!k).map((key) => ({ key })),
+    volumes, issues,
+    // The Swarm service, as for one-click databases (srv-captain-- only for isLegacyAppName apps).
+    runtime: { kind: 'swarm-service', name: app['isLegacyAppName'] === true ? `srv-captain--${name}` : name },
+  };
+}
+
+/** A one-click database app is listed as a database, not as a service. */
+function databaseOf(app: Obj): PlanDatabase | null {
+  for (const t of list(app['tags'])) {
+    const engine = ONE_CLICK_DATABASES[String(t['tagName'] ?? '').toLowerCase()];
+    if (!engine) continue;
+    const { image, neverDeployed } = deployedImage(app);
+    const issues: PlanIssue[] = [DATA_NOT_MOVED];
+    if (neverDeployed) issues.push({ level: 'info', option: 'deployedVersion', detail: 'Never deployed in CapRover, so the source has no engine version: choose one in NineDeploy.' });
+    if (list(app['ports']).length) issues.push({ level: 'manual', option: 'ports', detail: 'A host port was published; turn on public access in NineDeploy if you still need it.' });
+    // The app's Swarm service is named after it; apps from before the namespace change
+    // (isLegacyAppName) keep the srv-captain-- prefix. Checked live on v1.16.0.
+    const appName = String(app['appName']);
+    const service = app['isLegacyAppName'] === true ? `srv-captain--${appName}` : appName;
+    return { ref: appName, name: appName, engine, image: image ?? null, runtime: { kind: 'swarm-service', name: service }, issues };
+  }
+  return null;
+}
+
+export async function planFromCaprover(get: SourceGet, url: string): Promise<ImportPlan> {
+  const data = ((await get('/api/v2/user/apps/appDefinitions/')) ?? {}) as Obj;
+  const info = (await get('/api/v2/user/system/info/').catch(() => null)) as Obj | null;
+  const rootDomain = str(info?.['rootDomain']) ?? str(data['rootDomain']) ?? 'captain.localhost';
+  const versionInfo = (await get('/api/v2/user/system/versionInfo/').catch(() => null)) as Obj | null;
+  const plan = emptyPlan('caprover', url, str(versionInfo?.['currentVersion']) ?? null, 'every app on this CapRover instance');
+  for (const app of list(data['appDefinitions'])) {
+    if (!str(app['appName'])) continue;
+    const db = databaseOf(app);
+    if (db) plan.databases.push(db);
+    else {
+      const item = appItem(app, rootDomain);
+      if (item) plan.services.push(item);
+    }
+  }
+  return plan;
+}