elestio 1.0.2 → 1.1.0

package/src/router.js

@@ -0,0 +1,188 @@
+import { colors, log } from './utils.js';
+
+/**
+ * Declarative command dispatch.
+ *
+ * Commands describe themselves - group, usage, flags, sub-actions - so the
+ * help screens are generated from the same data the router dispatches on.
+ * A command and its documentation cannot drift apart.
+ */
+
+/**
+ * @typedef {object} Command
+ * @property {string}   group     heading it appears under in `elestio --help`
+ * @property {string}   summary   one line, shown in the command list
+ * @property {string}   [usage]   argument shape, without the leading `elestio`
+ * @property {object}   [actions] sub-action name -> { summary, usage, run }
+ * @property {string}   [defaultAction] action used when none is given
+ * @property {Function} [run]     handler for commands without sub-actions
+ * @property {string[]} [flags]   documented flags, shown in `elestio <cmd> --help`
+ */
+
+export function findCommand(registry, name) {
+  if (registry[name]) return { name, command: registry[name] };
+
+  // Accept an unambiguous prefix so `elestio clust list` works.
+  const matches = Object.keys(registry).filter(key => key.startsWith(name));
+  if (matches.length === 1) return { name: matches[0], command: registry[matches[0]] };
+
+  return { name: null, command: null, ambiguous: matches.length > 1 ? matches : null };
+}
+
+export function suggest(registry, name) {
+  // Generous enough to catch a transposition ("clsuter" is 3 edits from
+  // "clusters"), tight enough not to propose unrelated commands.
+  const threshold = Math.max(2, Math.ceil(name.length / 3));
+
+  const candidates = Object.keys(registry)
+    .map(key => ({
+      key,
+      // A command that contains what was typed is almost always the one meant.
+      distance: key.includes(name) || name.includes(key) ? 0 : editDistance(name, key)
+    }))
+    .filter(c => c.distance <= threshold)
+    .sort((a, b) => a.distance - b.distance || a.key.length - b.key.length);
+
+  return candidates.slice(0, 3).map(c => c.key);
+}
+
+function editDistance(a, b) {
+  const rows = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 0; j <= b.length; j++) rows[0][j] = j;
+
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      rows[i][j] = a[i - 1] === b[j - 1]
+        ? rows[i - 1][j - 1]
+        : 1 + Math.min(rows[i - 1][j], rows[i][j - 1], rows[i - 1][j - 1]);
+    }
+  }
+  return rows[a.length][b.length];
+}
+
+export function renderMainHelp(registry, version) {
+  const groups = new Map();
+  for (const [name, command] of Object.entries(registry)) {
+    if (command.hidden) continue;
+    if (!groups.has(command.group)) groups.set(command.group, []);
+    groups.get(command.group).push({ name, ...command });
+  }
+
+  const width = Math.max(...Object.keys(registry).map(n => n.length)) + 2;
+  const lines = [
+    '',
+    `${colors.bold}Elestio CLI${colors.reset} v${version}`,
+    'Deploy and manage services on the Elestio DevOps platform.',
+    '',
+    `${colors.bold}Usage:${colors.reset} elestio <command> [action] [options]`,
+    ''
+  ];
+
+  for (const [group, commands] of groups) {
+    lines.push(`${colors.bold}${group}${colors.reset}`);
+    for (const command of commands) {
+      lines.push(`  ${colors.cyan}${command.name.padEnd(width)}${colors.reset}${command.summary}`);
+    }
+    lines.push('');
+  }
+
+  lines.push(
+    `${colors.bold}Global Options${colors.reset}`,
+    `  ${'--json'.padEnd(width + 2)}Output in JSON format`,
+    `  ${'--project <id>'.padEnd(width + 2)}Project ID (overrides the default)`,
+    `  ${'--debug'.padEnd(width + 2)}Print full error stack traces`,
+    `  ${'--help, -h'.padEnd(width + 2)}Show help`,
+    `  ${'--version, -v'.padEnd(width + 2)}Show version`,
+    '',
+    `Run ${colors.cyan}elestio <command> --help${colors.reset} for a command's actions and flags.`,
+    `Use ${colors.cyan}--flag=value${colors.reset} for values that start with a dash.`,
+    ''
+  );
+
+  return lines.join('\n');
+}
+
+export function renderCommandHelp(name, command) {
+  const lines = ['', `${colors.bold}elestio ${command.usage || name}${colors.reset}`, `  ${command.summary}`, ''];
+
+  if (command.actions) {
+    const entries = Object.entries(command.actions).filter(([, a]) => !a.hidden);
+    const width = Math.max(...entries.map(([, a]) => (a.usage || '').length), 12) + 2;
+
+    lines.push(`${colors.bold}Actions${colors.reset}`);
+    for (const [actionName, action] of entries) {
+      const usage = action.usage || actionName;
+      const marker = actionName === command.defaultAction ? `${colors.dim} (default)${colors.reset}` : '';
+      lines.push(`  ${colors.cyan}${usage.padEnd(width)}${colors.reset}${action.summary}${marker}`);
+    }
+    lines.push('');
+  }
+
+  if (command.flags?.length) {
+    const width = Math.max(...command.flags.map(f => f.name.length)) + 2;
+    lines.push(`${colors.bold}Options${colors.reset}`);
+    for (const flag of command.flags) {
+      lines.push(`  ${flag.name.padEnd(width)}${flag.summary}`);
+    }
+    lines.push('');
+  }
+
+  if (command.examples?.length) {
+    lines.push(`${colors.bold}Examples${colors.reset}`);
+    for (const example of command.examples) {
+      lines.push(`  ${colors.dim}# ${example.description}${colors.reset}`);
+      lines.push(`  ${example.command}`);
+      lines.push('');
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Resolves a command and its action, then runs it.
+ * Returns an exit code; never throws for user error.
+ */
+export async function dispatch(registry, argv, args, context) {
+  const requested = args._[0];
+  const { name, command, ambiguous } = findCommand(registry, requested);
+
+  if (ambiguous) {
+    log('error', `"${requested}" is ambiguous: ${ambiguous.join(', ')}`);
+    return 1;
+  }
+
+  if (!command) {
+    log('error', `Unknown command: ${requested}`);
+    const suggestions = suggest(registry, requested);
+    if (suggestions.length > 0) {
+      log('info', `Did you mean: ${suggestions.join(', ')}?`);
+    }
+    log('info', 'Run "elestio --help" for the full list');
+    return 1;
+  }
+
+  if (args.help || args.h) {
+    console.log(renderCommandHelp(name, command));
+    return 0;
+  }
+
+  if (!command.actions) {
+    await command.run({ ...context, args, json: context.json });
+    return 0;
+  }
+
+  const requestedAction = args._[1];
+  const actionName = requestedAction && command.actions[requestedAction]
+    ? requestedAction
+    : (!requestedAction ? command.defaultAction : null);
+
+  if (!actionName) {
+    log('error', `Unknown action "${requestedAction}" for "${name}"`);
+    console.log(renderCommandHelp(name, command));
+    return 1;
+  }
+
+  await command.actions[actionName].run({ ...context, args, json: context.json });
+  return 0;
+}

package/src/templates/elestio-config.js

@@ -0,0 +1,188 @@
+import { randomInt } from 'crypto';
+
+/**
+ * Reading and applying `elestio.yml`, the file every repo under
+ * github.com/elestio-examples carries to describe how it must be deployed.
+ *
+ * The backend parses the YAML for us (`getGitContent` with file="elestio"),
+ * so this module only normalises the resulting object and resolves the
+ * placeholders the dashboard resolves at pipeline-creation time.
+ */
+
+const ALPHANUM = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+
+function randomString(length) {
+  let out = '';
+  for (let i = 0; i < length; i++) out += ALPHANUM[randomInt(ALPHANUM.length)];
+  return out;
+}
+
+/**
+ * Same shape as the dashboard's generated app password: 8-4-8, guaranteed to
+ * mix cases and digits so it satisfies the software's own password policies.
+ */
+export function generateAppPassword() {
+  for (;;) {
+    const password = `${randomString(8)}-${randomString(4)}-${randomString(8)}`;
+    if (/[a-z]/.test(password) && /[A-Z]/.test(password) && /[0-9]/.test(password)) {
+      return password;
+    }
+  }
+}
+
+export function generateShortPassword() {
+  return `${randomString(8)}-${randomString(7)}`;
+}
+
+/**
+ * Placeholders resolved when the pipeline is created.
+ *
+ * `[CI_CD_DOMAIN]` is deliberately left untouched: the pipeline's CNAME does
+ * not exist yet at this point, and the deployment agent substitutes it later.
+ * The dashboard behaves the same way.
+ */
+export function createSubstitutions(email) {
+  return {
+    password: generateAppPassword(),
+    shortPassword: generateShortPassword(),
+    email: email || ''
+  };
+}
+
+export function substitute(value, subs) {
+  if (typeof value !== 'string') return value;
+  // `random_password_16` must be replaced first, otherwise `random_password`
+  // matches its prefix and leaves a dangling `_16`.
+  return value
+    .replaceAll('random_password_16', subs.shortPassword)
+    .replaceAll('random_password', subs.password)
+    .replaceAll('[EMAIL]', subs.email);
+}
+
+function substituteDeep(node, subs) {
+  if (Array.isArray(node)) return node.map(item => substituteDeep(item, subs));
+  if (node && typeof node === 'object') {
+    return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, substituteDeep(v, subs)]));
+  }
+  return substitute(node, subs);
+}
+
+/** Keys that mean the repo really does carry an elestio.yml. */
+const CONFIG_KEYS = ['config', 'environments', 'ports', 'exposedPorts', 'lifeCycleConfig', 'copyCommandConfig', 'webUI'];
+
+const EMPTY_LIFECYCLE = {
+  preInstallCommand: '', postInstallCommand: '',
+  preBackupCommand: '', postBackupCommand: '',
+  preRestoreCommand: '', postRestoreCommand: '',
+  preUpdateCommand: '', postUpdateCommand: '',
+  preDeployCommand: '', postDeployCommand: ''
+};
+
+/**
+ * `environments: [{key, value}]` becomes the newline-separated string the
+ * backend expects -- it calls variables.trim(), so an array raises a 500.
+ */
+export function environmentsToVariables(environments, subs) {
+  if (!Array.isArray(environments)) return '';
+
+  return environments
+    .filter(env => env && env.key !== undefined && env.key !== null && env.key !== '')
+    .map(env => `${env.key}=${substitute(String(env.value ?? ''), subs)}`)
+    .join('\n');
+}
+
+function normalizePort(port) {
+  return {
+    protocol: String(port.protocol || 'HTTPS').toUpperCase(),
+    targetProtocol: String(port.targetProtocol || 'HTTP').toUpperCase(),
+    listeningPort: String(port.listeningPort || '443'),
+    targetPort: String(port.targetPort || '3000'),
+    targetIP: port.targetIP || '172.17.0.1',
+    public: port.public !== false,
+    path: port.path || '/',
+    isAuth: port.isAuth === true,
+    login: port.login || '',
+    password: port.password || '',
+    loginTitle: port.loginTitle || ''
+  };
+}
+
+function normalizeExposedPort(port) {
+  return {
+    protocol: String(port.protocol || 'HTTP').toUpperCase(),
+    hostPort: String(port.hostPort ?? port.targetPort ?? '3000'),
+    containerPort: String(port.containerPort ?? port.targetPort ?? '3000'),
+    interface: port.interface || '172.17.0.1'
+  };
+}
+
+/**
+ * Turns a parsed elestio.yml into the pieces a pipeline payload needs.
+ *
+ * @param {object} raw     parsed elestio.yml (may be null for repos without one)
+ * @param {object} subs    from createSubstitutions()
+ */
+export function normalizeElestioConfig(raw, subs) {
+  const source = raw && typeof raw === 'object' ? raw : {};
+  const config = substituteDeep(source.config || {}, subs);
+  const ports = Array.isArray(source.ports) ? substituteDeep(source.ports, subs).map(normalizePort) : [];
+  const exposedPorts = Array.isArray(source.exposedPorts)
+    ? substituteDeep(source.exposedPorts, subs).map(normalizeExposedPort)
+    : [];
+
+  return {
+    // A repo with no elestio.yml still answers 200, with {"status":"ok"} and
+    // nothing else -- so presence is decided on the config keys themselves.
+    // Treating that reply as a config is what builds a pipeline that runs
+    // nothing.
+    hasConfig: CONFIG_KEYS.some(key => source[key] !== undefined && source[key] !== null),
+    config: {
+      runTime: config.runTime || '',
+      version: config.version === undefined || config.version === null ? '' : String(config.version),
+      framework: config.framework || 'NoFramework',
+      buildDir: normalizeDir(config.buildDir, '/'),
+      rootDir: normalizeDir(config.rootDir, '/'),
+      buildCmd: config.buildCommand || '',
+      runCmd: config.runCommand || '',
+      installCmd: config.installCommand || '',
+      isMonoRepoPackageInRoot: config.isMonoRepoPackageInRoot || false
+    },
+    ports,
+    exposedPorts,
+    variables: environmentsToVariables(source.environments, subs),
+    lifeCycleCommand: { ...EMPTY_LIFECYCLE, ...substituteDeep(source.lifeCycleConfig || {}, subs) },
+    copyCommandConfig: Array.isArray(source.copyCommandConfig) ? substituteDeep(source.copyCommandConfig, subs) : [],
+    webUI: Array.isArray(source.webUI) ? substituteDeep(source.webUI, subs) : []
+  };
+}
+
+function normalizeDir(dir, fallback) {
+  if (!dir) return fallback;
+  const str = String(dir);
+  return str.startsWith('/') ? str : `/${str}`;
+}
+
+export { EMPTY_LIFECYCLE };
+
+/**
+ * Bind mounts whose source is a file that lives in the template repo.
+ *
+ * Without a repo checkout Docker creates the missing source as a *directory*,
+ * and the container then fails to start with "not a directory". n8n hits this
+ * on ./n8n-task-runners.json. Directory mounts (./db_data) are fine: Docker
+ * creating them empty is exactly what is wanted.
+ *
+ * A source is treated as a file when its last segment has an extension, which
+ * is what tells ./n8n-task-runners.json apart from ./redis_data.
+ */
+export function repoFileMounts(compose) {
+  if (typeof compose !== 'string') return [];
+
+  const mounts = new Set();
+  for (const match of compose.matchAll(/^\s*-\s+(\.{1,2}\/[^\s:]+):[^\s]+/gm)) {
+    const source = match[1];
+    const lastSegment = source.slice(source.lastIndexOf('/') + 1);
+    if (/\.[A-Za-z0-9]{1,10}$/.test(lastSegment)) mounts.add(source);
+  }
+  return [...mounts];
+}

package/src/utils.js

@@ -36,22 +36,26 @@ export function parseArgs(argv) {
   while (i < argv.length) {
     const arg = argv[i];
 
-    if (arg.startsWith('--')) {
-      const key = arg.slice(2);
-      const next = argv[i + 1];
+    // Everything after `--` is positional, never parsed as a flag.
+    if (arg === '--') {
+      args._.push(...argv.slice(i + 1));
+      break;
+    }
 
-      if (next && !next.startsWith('-')) {
-        args[key] = next;
-        i += 2;
-      } else {
-        args[key] = true;
-        i++;
-      }
-    } else if (arg.startsWith('-') && arg.length === 2) {
-      const key = arg.slice(1);
+    // `--key=value` is the unambiguous form: it is the only way to pass a value
+    // that itself starts with a dash (passwords, negative numbers).
+    if (arg.startsWith('--') && arg.includes('=')) {
+      const eq = arg.indexOf('=');
+      args[arg.slice(2, eq)] = arg.slice(eq + 1);
+      i++;
+      continue;
+    }
+
+    if (arg.startsWith('--') || (arg.startsWith('-') && arg.length === 2)) {
+      const key = arg.startsWith('--') ? arg.slice(2) : arg.slice(1);
       const next = argv[i + 1];
 
-      if (next && !next.startsWith('-')) {
+      if (next !== undefined && !looksLikeFlag(next)) {
         args[key] = next;
         i += 2;
       } else {
@@ -67,6 +71,14 @@ export function parseArgs(argv) {
   return args;
 }
 
+/**
+ * `-p` and `--port` are flags; `-5`, `-p@ssw0rd` and `-` are values.
+ * Values that are genuinely ambiguous must use the `--key=value` form.
+ */
+function looksLikeFlag(token) {
+  return /^--[a-zA-Z]/.test(token) || /^-[a-zA-Z]$/.test(token);
+}
+
 // ── Table formatting ──
 
 export function formatTable(data, columns) {
@@ -103,8 +115,8 @@ export function formatBytes(bytes) {
 
 export function formatPrice(pricePerHour) {
   const hourly = parseFloat(pricePerHour);
-  const monthly = (hourly * 24 * 30).toFixed(2);
-  return `$${monthly}/mo`;
+  if (!Number.isFinite(hourly)) return 'N/A';
+  return `$${(hourly * 24 * 30).toFixed(2)}/mo`;
 }
 
 export function validateServerName(name) {