ninedeploy 0.18.25 → 0.18.27

package/src/lib/importers/plan.ts

@@ -0,0 +1,209 @@
+/**
+ * A1 step 1 (docs/plans/COMPETITIVE_ROADMAP_2026-11.md): a read-only import
+ * plan. An adapter reads another platform's API (Coolify, Dokploy, CapRover)
+ * and describes, per item, what NineDeploy would create, what it cannot carry,
+ * and what needs a person. Nothing is created and the source is not changed.
+ *
+ * Secret hygiene is part of the type: a plan carries environment variable
+ * NAMES only, never values, passwords, tokens or keys, and every URL has its
+ * userinfo removed before it enters the plan. Step 2 (`import apply`, in
+ * commands/importApply.ts) takes values only from .env files the person passes.
+ */
+import type { CreateService } from '@ninedeploy/schemas';
+
+export type SourceKind = 'coolify' | 'dokploy' | 'caprover' | 'heroku';
+
+/** GET a JSON path on the source panel (auth already applied). */
+export type SourceGet = (path: string) => Promise<unknown>;
+
+export type IssueLevel = 'unsupported' | 'manual' | 'info';
+export interface PlanIssue {
+  level: IssueLevel;
+  /** The source option or field the issue is about, e.g. `build_pack`. */
+  option: string;
+  detail: string;
+}
+
+/** The createService fields a step-2 apply would send (subset, never secrets). */
+export type ServiceCreateFields = Pick<CreateService, 'name' | 'type'> &
+  Partial<Pick<CreateService, 'image' | 'repoUrl' | 'branch' | 'port' | 'publishedPort' | 'replicas' | 'cpuLimitMilli' | 'memLimitMb' | 'healthPath' | 'volumeMount'>> & {
+    build?: { buildPack?: NonNullable<CreateService['build']>['buildPack']; baseDir?: string; dockerfilePath?: string; outputDir?: string; startCmd?: string };
+  };
+
+/**
+ * A domain of a service. `sourceDefault` marks a host the source generated
+ * for itself (CapRover's <app>.<root domain>, Coolify's sslip.io, Dokploy's
+ * traefik.me): it stays with the source and is never added to NineDeploy.
+ * Optional and additive, so planVersion stays 1.
+ */
+export interface PlanDomain {
+  host: string;
+  https: boolean;
+  sourceDefault?: true;
+}
+
+/** Wildcard-DNS hosts the sources generate (they resolve to an IP in the name, or to the source). */
+export function isGeneratedHost(host: string): boolean {
+  return /\.(sslip\.io|nip\.io|traefik\.me)$/i.test(host);
+}
+
+export function planDomain(host: string, https: boolean, sourceDefault = isGeneratedHost(host)): PlanDomain {
+  return sourceDefault ? { host, https, sourceDefault: true } : { host, https };
+}
+
+export interface PlanService {
+  /** Stable reference in the source (uuid / id / appName). */
+  ref: string;
+  name: string;
+  kind: 'image' | 'git' | 'compose';
+  create: ServiceCreateFields;
+  domains: PlanDomain[];
+  /** Names only. `secret` marks values the source keeps hidden or flags as secret. */
+  env: Array<{ key: string }>;
+  volumes: Array<{ mountPath: string; source: 'volume' | 'bind' | 'file'; name?: string }>;
+  issues: PlanIssue[];
+  /**
+   * Where it runs on the source host, for the volume command of `import
+   * data` (same shape as PlanDatabase.runtime). Optional and additive.
+   */
+  runtime?: PlanRuntime;
+  /** Settings apply sets right after create (an update; not create fields). Optional and additive. */
+  settings?: { healthCheck?: 'running' };
+  /** Databases of the plan to attach under a variable (Heroku add-ons). Optional and additive. */
+  attachments?: Array<{ database: string; envAlias: string }>;
+}
+
+/**
+ * Where an item runs on the source: a container, a Swarm service, or (Heroku
+ * add-ons) the Heroku app that owns it. Every reader switches on `kind`.
+ */
+export type PlanRuntime = { kind: 'container' | 'swarm-service' | 'heroku-app'; name: string };
+
+export type PlanEngine = 'postgres' | 'mysql' | 'mariadb' | 'mongo' | 'redis' | 'keydb' | 'dragonfly' | 'clickhouse';
+export interface PlanDatabase {
+  ref: string;
+  name: string;
+  /** NineDeploy engine, or null when NineDeploy has no managed equivalent. */
+  engine: PlanEngine | null;
+  /** The source image (the version lives in its tag), when the source says. */
+  image: string | null;
+  /**
+   * Where it runs on the source host, for the dump commands of `import data`:
+   * a plain container name, or a Swarm service whose task container is found
+   * by its com.docker.swarm.service.name label. Optional and additive.
+   */
+  runtime?: PlanRuntime;
+  issues: PlanIssue[];
+}
+
+export interface ImportPlan {
+  planVersion: 1;
+  source: { kind: SourceKind; url: string; version: string | null; scope: string };
+  generatedAt: string;
+  services: PlanService[];
+  databases: PlanDatabase[];
+  /** Plan-wide notes (scope limits, what step 1 does not do). */
+  notes: string[];
+}
+
+/** Always present: what this plan is and is not. */
+export const PLAN_NOTES = [
+  'Read-only: nothing was created here and nothing was changed on the source.',
+  'Environment variables are listed by name only. Values, passwords, tokens and keys are never written to a plan.',
+  'Database contents and volume data are not moved by this step.',
+];
+
+/** Remove `user:password@` from a URL; non-URLs pass through unchanged. */
+export function stripUserinfo(raw: string): string {
+  // Only `scheme://` strings are URLs here: `user:secret@host:repo` would
+  // otherwise parse as scheme "user:" and keep its password.
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) {
+    try {
+      const u = new URL(raw);
+      if (!u.username && !u.password) return raw;
+      u.username = '';
+      u.password = '';
+      return u.toString();
+    } catch {
+      /* fall through to the textual rule */
+    }
+  }
+  // scp-style remotes: `git@host:owner/repo.git` (no password) stays as it is;
+  // `user:secret@host…` loses its credentials.
+  return raw.replace(/^[^@/\s]+:[^@/\s]*@/, '');
+}
+
+/** `KEY=VALUE` lines (Dokploy's env blob) → names only. Comments and blanks skipped. */
+export function envNames(blob: string | null | undefined): Array<{ key: string }> {
+  const out: Array<{ key: string }> = [];
+  for (const line of (blob ?? '').split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t || t.startsWith('#')) continue;
+    const eq = t.indexOf('=');
+    const key = (eq === -1 ? t : t.slice(0, eq)).replace(/^export\s+/, '').trim();
+    if (/^[A-Za-z_][A-Za-z0-9_.-]*$/.test(key)) out.push({ key });
+  }
+  return out;
+}
+
+/** Each URL or bare host in a list → `{host, https}` (Coolify's comma-separated `fqdn`). */
+export function domainsFrom(list: string | null | undefined): PlanDomain[] {
+  const out: PlanDomain[] = [];
+  for (const part of (list ?? '').split(',')) {
+    const t = part.trim();
+    if (!t) continue;
+    try {
+      const u = new URL(/^[a-z]+:\/\//i.test(t) ? t : `http://${t}`);
+      if (u.hostname) out.push(planDomain(u.hostname, u.protocol === 'https:'));
+    } catch {
+      /* not a host */
+    }
+  }
+  return out;
+}
+
+/** "512M" / "2g" / "1024" (bytes or MB per source) → megabytes, or undefined. */
+export function memToMb(raw: string | number | null | undefined, plainUnit: 'bytes' | 'mb' = 'bytes'): number | undefined {
+  if (raw == null || raw === '' || raw === '0' || raw === 0) return undefined;
+  const m = /^(\d+(?:\.\d+)?)\s*([kmgt]?)b?$/i.exec(String(raw).trim());
+  if (!m) return undefined;
+  const n = Number(m[1]);
+  const unit = (m[2] ?? '').toLowerCase();
+  const mb = unit === 'k' ? n / 1024 : unit === 'm' ? n : unit === 'g' ? n * 1024 : unit === 't' ? n * 1024 * 1024 : plainUnit === 'mb' ? n : n / (1024 * 1024);
+  return mb >= 1 ? Math.round(mb) : undefined;
+}
+
+/** "1.5" cores → 1500 millicores, or undefined. */
+export function cpusToMilli(raw: string | number | null | undefined): number | undefined {
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? Math.round(n * 1000) : undefined;
+}
+
+/** NineDeploy accepts 1..10 replicas. */
+export function replicasFor(raw: unknown, issues: PlanIssue[]): number | undefined {
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n <= 1) return undefined;
+  if (n > 10) {
+    issues.push({ level: 'manual', option: 'replicas', detail: `${n} replicas in the source; NineDeploy runs at most 10 per service, so the plan uses 10.` });
+    return 10;
+  }
+  return n;
+}
+
+/** The first volume becomes `volumeMount`; any others are listed for a person. */
+export function firstVolumeMount(volumes: PlanService['volumes'], issues: PlanIssue[]): string | undefined {
+  const named = volumes.filter((v) => v.source !== 'file');
+  if (named.length > 1) {
+    issues.push({ level: 'manual', option: 'volumes', detail: `${named.length} volumes; a new service gets one at create time (${named[0]!.mountPath}). Attach the others under Volumes & Storage.` });
+  }
+  for (const f of volumes.filter((v) => v.source === 'file')) {
+    issues.push({ level: 'manual', option: 'file mount', detail: `File mount ${f.mountPath}: recreate it under Service → File mounts (its content is not read).` });
+  }
+  return named[0]?.mountPath;
+}
+
+export const DATA_NOT_MOVED: PlanIssue = { level: 'manual', option: 'data', detail: 'Data is not moved by this step: create the database, then restore a dump into it (step 3).' };
+
+export function emptyPlan(kind: SourceKind, url: string, version: string | null, scope: string): ImportPlan {
+  return { planVersion: 1, source: { kind, url: stripUserinfo(url), version, scope }, generatedAt: new Date().toISOString(), services: [], databases: [], notes: [...PLAN_NOTES] };
+}

package/src/lib/importers/shell.ts

@@ -0,0 +1,56 @@
+/**
+ * Pieces of the commands `import data` prints for the source host. The names
+ * in them come from the source platform's API, and the person pastes the
+ * command into a shell, so a name only goes in when it is a plain Docker
+ * name; anything else becomes a placeholder to fill in by hand.
+ */
+
+import type { PlanRuntime } from './plan.js';
+
+/** A Docker container or service name: no spaces, quotes, `$`, `;` or other shell syntax. */
+const DOCKER_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,254}$/;
+
+export const isPlainName = (name: string): boolean => DOCKER_NAME.test(name);
+
+/** Single-quote for POSIX sh. */
+export const shellQuote = (s: string): string => `'${s.replace(/'/g, `'\\''`)}'`;
+
+/** A file name made of safe characters only. */
+export function fileBase(name: string): string {
+  const safe = name.replace(/[^A-Za-z0-9_.-]/g, '_').replace(/^[.-]+/, '_');
+  return safe || 'import';
+}
+
+/**
+ * The container to reach on the source host: a container name, or the newest
+ * task container of a Swarm service (`all` also finds stopped ones). A
+ * missing or unusual name gives `<container>` and a note saying so.
+ */
+export function sourceTarget(
+  runtime: PlanRuntime | undefined,
+  what: string,
+  all = false,
+): { target: string; note: string | null } {
+  if (runtime && isPlainName(runtime.name)) {
+    switch (runtime.kind) {
+      case 'container':
+        return { target: runtime.name, note: null };
+      case 'swarm-service':
+        return { target: `$(docker ps -${all ? 'a' : ''}q --filter label=com.docker.swarm.service.name=${runtime.name} | head -n 1)`, note: null };
+      case 'heroku-app':
+        // A Heroku app has no container on a host you run docker on.
+        return { target: '<container>', note: `Replace <container> with ${what}; Heroku runs it, so there is no docker host to read it from.` };
+      default: {
+        const never: never = runtime.kind;
+        return never;
+      }
+    }
+  }
+  const why = runtime ? ` (its name on the source, ${JSON.stringify(runtime.name)}, is not a plain Docker name, so it is not put in a shell command)` : '';
+  return { target: '<container>', note: `Replace <container> with ${what} on the source host (docker ps${all ? ' -a' : ''})${why}.` };
+}
+
+/** `<name>=<file>` for a --dump / --volume flag, quoted when the name is not plain. */
+export function flagArg(name: string, file: string): string {
+  return isPlainName(name) ? `${name}=${file}` : shellQuote(`${name}=${file}`);
+}

package/src/lib/importers/sources.ts

@@ -0,0 +1,96 @@
+/**
+ * HTTP clients for the import sources (A1 step 1). Native fetch only. The
+ * credentials come from the caller (an env var or a hidden prompt, never
+ * argv) and never appear in an error message.
+ */
+import type { SourceGet } from './plan.js';
+import { stripUserinfo } from './plan.js';
+
+export class SourceError extends Error {}
+/** CapRover asked for a two-factor code (status 1114). */
+export class OtpRequiredError extends SourceError {}
+
+type Fetch = typeof fetch;
+
+/** `https://host[:port][/prefix]` without a trailing slash or userinfo. */
+export function normaliseBase(raw: string): string {
+  let u: URL;
+  try {
+    u = new URL(raw);
+  } catch {
+    throw new SourceError(`Not a URL: ${stripUserinfo(raw)}`);
+  }
+  if (u.protocol !== 'https:' && u.protocol !== 'http:') throw new SourceError('The source URL must start with https:// (or http://).');
+  return stripUserinfo(`${u.origin}${u.pathname}`).replace(/\/+$/, '');
+}
+
+async function body(res: Response): Promise<unknown> {
+  const text = await res.text();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function httpError(res: Response, what: string, hint = ''): SourceError {
+  return new SourceError(`${what} answered HTTP ${res.status}${hint ? `: ${hint}` : ''}`);
+}
+
+/** Coolify: `Authorization: Bearer <token>`; a plain `read` token is enough. */
+export function coolifySource(base: string, token: string, f: Fetch = fetch): SourceGet {
+  return async (path) => {
+    const res = await f(`${base}${path}`, { headers: { authorization: `Bearer ${token}`, accept: 'application/json' } });
+    const data = await body(res);
+    if (res.ok) return data;
+    const message = typeof data === 'object' && data && 'message' in data ? String((data as { message: unknown }).message) : '';
+    if (res.status === 403 && /api is disabled/i.test(message)) throw httpError(res, 'Coolify', 'the API is off. Turn it on under Settings → Advanced → API access.');
+    if (res.status === 401) throw httpError(res, 'Coolify', 'the token was refused (create one under Keys & Tokens → API tokens, with "read").');
+    if (res.status === 403) throw httpError(res, 'Coolify', message || 'the token lacks access (IP allow-list, scope or ability).');
+    throw httpError(res, `Coolify ${path}`, message);
+  };
+}
+
+/** Dokploy: `x-api-key`, tRPC procedures as `GET /api/<procedure>?<input>`. */
+export function dokploySource(base: string, apiKey: string, f: Fetch = fetch): SourceGet {
+  return async (path) => {
+    const res = await f(`${base}${path}`, { headers: { 'x-api-key': apiKey, accept: 'application/json' } });
+    const data = await body(res);
+    if (res.ok) return data;
+    // Dokploy answers a plain 401 for a wrong key and for one past its rate limit alike (checked live on v0.31.0).
+    if (res.status === 401) throw httpError(res, 'Dokploy', 'the API key was refused: it is wrong, belongs to another organization, or has used up its rate limit. A Dokploy key allows 10 requests a day unless it was created with rate limiting off, and a plan makes 2 plus one per application, compose stack and database. Create one under Profile → API keys with rate limiting off.');
+    const message = typeof data === 'object' && data && 'message' in data ? String((data as { message: unknown }).message) : '';
+    throw httpError(res, `Dokploy ${path.split('?')[0]}`, message);
+  };
+}
+
+interface CaproverEnvelope { status?: number; description?: string; data?: unknown }
+
+/**
+ * CapRover: sign in once (never retried: each wrong password starts a 30 s
+ * back-off), then send `x-captain-auth`. Errors arrive with HTTP 200 and a
+ * non-100 `status` in the envelope.
+ */
+export async function caproverSource(base: string, password: string, otp: string | undefined, f: Fetch = fetch): Promise<SourceGet> {
+  const res = await f(`${base}/api/v2/login/`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-namespace': 'captain' },
+    body: JSON.stringify(otp ? { password, otpToken: otp } : { password }),
+  });
+  if (!res.ok) throw httpError(res, 'CapRover sign-in');
+  const env = (await body(res)) as CaproverEnvelope | null;
+  if (env?.status === 1114) throw new OtpRequiredError('CapRover asks for a two-factor code.');
+  if (env?.status === 1113) throw new SourceError('CapRover is pausing sign-ins after a wrong password; wait 30 seconds and try again.');
+  if (env?.status === 1105) throw new SourceError('CapRover refused the password (or the two-factor code).');
+  const token = (env?.data as { token?: unknown } | undefined)?.token;
+  if (env?.status !== 100 || typeof token !== 'string') throw new SourceError(`CapRover sign-in failed (status ${env?.status ?? '?'}).`);
+  return async (path) => {
+    const r = await f(`${base}${path}`, { headers: { 'x-captain-auth': token, 'x-namespace': 'captain', accept: 'application/json' } });
+    if (!r.ok) throw httpError(r, `CapRover ${path}`);
+    const e = (await body(r)) as CaproverEnvelope | null;
+    if (e?.status === 1106) throw new SourceError('CapRover no longer accepts the session (it restarted, or the password changed); run the import again.');
+    if (e?.status !== 100) throw new SourceError(`CapRover ${path} failed (status ${e?.status ?? '?'}${e?.description ? `: ${e.description}` : ''}).`);
+    return e.data;
+  };
+}