@localctl/cli 0.2.0 → 0.3.0

package/src/lib/engine.js

@@ -1,20 +1,36 @@
-const { commandExists, capture } = require('./exec');
-
-// Returns { engine, bin } - `engine` names what's actually running (docker/podman/rancher-desktop),
-// `bin` is the CLI to drive it with (usually the same, except Rancher Desktop, which exposes
-// docker or nerdctl depending on how it's configured). Returns null if nothing usable is found.
-function detectEngine() {
-  if (commandExists('docker') && capture('docker', ['info']).status === 0) {
-    return { engine: 'docker', bin: 'docker' };
-  }
-  if (commandExists('podman') && capture('podman', ['info']).status === 0) {
-    return { engine: 'podman', bin: 'podman' };
-  }
-  if (commandExists('rdctl')) {
-    if (commandExists('docker')) return { engine: 'rancher-desktop', bin: 'docker' };
-    if (commandExists('nerdctl')) return { engine: 'rancher-desktop', bin: 'nerdctl' };
-  }
-  return null;
-}
-
-module.exports = { detectEngine };
+const { commandExists, capture } = require('./exec');
+const logger = require('./logger');
+
+// Support status per engine lives in cli/package.json ("localctl.containerEngines"), so marking an
+// engine as tested is a one-word config change, not a code change. "tested" means verified end to
+// end; anything else (or an engine missing from the map) gets the experimental warning.
+const { localctl: { containerEngines = {} } = {} } = require('../../package.json');
+const ENGINE_LABELS = { docker: 'Docker Desktop', podman: 'Podman', 'rancher-desktop': 'Rancher Desktop' };
+const ISSUES_URL = 'https://github.com/psilvmoreira/localctl/issues';
+
+// Returns { engine, bin } - `engine` names what's actually running (docker/podman/rancher-desktop),
+// `bin` is the CLI to drive it with (usually the same, except Rancher Desktop, which exposes
+// docker or nerdctl depending on how it's configured). Returns null if nothing usable is found.
+function detectEngine() {
+  if (commandExists('docker') && capture('docker', ['info']).status === 0) {
+    return { engine: 'docker', bin: 'docker' };
+  }
+  if (commandExists('podman') && capture('podman', ['info']).status === 0) {
+    return { engine: 'podman', bin: 'podman' };
+  }
+  if (commandExists('rdctl')) {
+    if (commandExists('docker')) return { engine: 'rancher-desktop', bin: 'docker' };
+    if (commandExists('nerdctl')) return { engine: 'rancher-desktop', bin: 'nerdctl' };
+  }
+  return null;
+}
+
+function warnIfExperimental(engine) {
+  if (containerEngines[engine] === 'tested') return;
+  const tested = Object.keys(containerEngines).filter((e) => containerEngines[e] === 'tested');
+  const testedList = tested.map((e) => ENGINE_LABELS[e] || e).join(', ') || 'none';
+  logger.warn(`${ENGINE_LABELS[engine] || engine} support is experimental - fully tested so far: ${testedList}.`);
+  logger.warn(`If something breaks, please report it: ${ISSUES_URL}`);
+}
+
+module.exports = { detectEngine, warnIfExperimental };

package/src/lib/exec.js

@@ -1,77 +1,77 @@
-const { spawnSync, spawn } = require('child_process');
-const fs = require('fs');
-const net = require('net');
-
-function run(cmd, args, opts = {}) {
-  const res = spawnSync(cmd, args, { stdio: 'inherit', ...opts });
-  if (res.error) throw res.error;
-  if (res.status !== 0 && !opts.allowFail) {
-    throw new Error(`Command failed (${res.status}): ${cmd} ${args.join(' ')}`);
-  }
-  return res;
-}
-
-function capture(cmd, args, opts = {}) {
-  const res = spawnSync(cmd, args, { encoding: 'utf8', ...opts });
-  return {
-    status: res.status,
-    stdout: (res.stdout || '').trim(),
-    stderr: (res.stderr || '').trim(),
-  };
-}
-
-function commandExists(cmd) {
-  const probe = process.platform === 'win32' ? 'where' : 'which';
-  const res = spawnSync(probe, [cmd], { stdio: 'ignore' });
-  return res.status === 0;
-}
-
-// Blocking sleep with no native dependency - used for poll loops (e.g. waiting on a CRD to
-// register) where an async setTimeout would need restructuring the whole command as a promise
-// chain for no real benefit.
-function sleepSync(ms) {
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-
-// Starts a fully detached child that outlives this process (and the terminal it's running in) -
-// used for `localctl up --detach`. stdout/stderr go to logFile since there's no terminal to
-// inherit once the parent exits. Returns the child's pid.
-function spawnDetached(cmd, args, { cwd, env, logFile } = {}) {
-  const out = fs.openSync(logFile, 'a');
-  const child = spawn(cmd, args, {
-    cwd,
-    env,
-    detached: true,
-    stdio: ['ignore', out, out],
-  });
-  child.unref();
-  return child.pid;
-}
-
-// True if a process with this pid is currently running (doesn't actually signal it).
-function isRunning(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (e) {
-    return false;
-  }
-}
-
-// Asks the OS for a free TCP port (binds to port 0, reads back what it picked). Used to give each
-// app's Tilt instance its own web UI port - Tilt otherwise always binds the same default port,
-// so two apps running `localctl up` at once (the whole point of detached mode) collide outright,
-// and the resulting error doesn't explain why.
-function getFreePort() {
-  return new Promise((resolve, reject) => {
-    const srv = net.createServer();
-    srv.unref();
-    srv.on('error', reject);
-    srv.listen(0, '127.0.0.1', () => {
-      const { port } = srv.address();
-      srv.close(() => resolve(port));
-    });
-  });
-}
-
-module.exports = { run, capture, commandExists, sleepSync, spawnDetached, isRunning, getFreePort };
+const { spawnSync, spawn } = require('child_process');
+const fs = require('fs');
+const net = require('net');
+
+function run(cmd, args, opts = {}) {
+  const res = spawnSync(cmd, args, { stdio: 'inherit', ...opts });
+  if (res.error) throw res.error;
+  if (res.status !== 0 && !opts.allowFail) {
+    throw new Error(`Command failed (${res.status}): ${cmd} ${args.join(' ')}`);
+  }
+  return res;
+}
+
+function capture(cmd, args, opts = {}) {
+  const res = spawnSync(cmd, args, { encoding: 'utf8', ...opts });
+  return {
+    status: res.status,
+    stdout: (res.stdout || '').trim(),
+    stderr: (res.stderr || '').trim(),
+  };
+}
+
+function commandExists(cmd) {
+  const probe = process.platform === 'win32' ? 'where' : 'which';
+  const res = spawnSync(probe, [cmd], { stdio: 'ignore' });
+  return res.status === 0;
+}
+
+// Blocking sleep with no native dependency - used for poll loops (e.g. waiting on a CRD to
+// register) where an async setTimeout would need restructuring the whole command as a promise
+// chain for no real benefit.
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+// Starts a fully detached child that outlives this process (and the terminal it's running in) -
+// used for `localctl up --detach`. stdout/stderr go to logFile since there's no terminal to
+// inherit once the parent exits. Returns the child's pid.
+function spawnDetached(cmd, args, { cwd, env, logFile } = {}) {
+  const out = fs.openSync(logFile, 'a');
+  const child = spawn(cmd, args, {
+    cwd,
+    env,
+    detached: true,
+    stdio: ['ignore', out, out],
+  });
+  child.unref();
+  return child.pid;
+}
+
+// True if a process with this pid is currently running (doesn't actually signal it).
+function isRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+// Asks the OS for a free TCP port (binds to port 0, reads back what it picked). Used to give each
+// app's Tilt instance its own web UI port - Tilt otherwise always binds the same default port,
+// so two apps running `localctl up` at once (the whole point of detached mode) collide outright,
+// and the resulting error doesn't explain why.
+function getFreePort() {
+  return new Promise((resolve, reject) => {
+    const srv = net.createServer();
+    srv.unref();
+    srv.on('error', reject);
+    srv.listen(0, '127.0.0.1', () => {
+      const { port } = srv.address();
+      srv.close(() => resolve(port));
+    });
+  });
+}
+
+module.exports = { run, capture, commandExists, sleepSync, spawnDetached, isRunning, getFreePort };

package/src/lib/hostsFile.js

@@ -1,79 +1,79 @@
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { spawnSync } = require('child_process');
-const logger = require('./logger');
-const { ensureHomeState, APPS_REGISTRY_PATH } = require('./paths');
-const { DOMAIN } = require('./constants');
-
-const MARK_START = '# >>> localctl managed block >>>';
-const MARK_END = '# <<< localctl managed block <<<';
-const HOSTS_PATH =
-  process.platform === 'win32' ? 'C:\\Windows\\System32\\drivers\\etc\\hosts' : '/etc/hosts';
-
-function registerApp(subdomain) {
-  ensureHomeState();
-  const registry = JSON.parse(fs.readFileSync(APPS_REGISTRY_PATH, 'utf8'));
-  registry[subdomain] = true;
-  fs.writeFileSync(APPS_REGISTRY_PATH, JSON.stringify(registry, null, 2));
-}
-
-function listApps() {
-  ensureHomeState();
-  const registry = JSON.parse(fs.readFileSync(APPS_REGISTRY_PATH, 'utf8'));
-  return Object.keys(registry);
-}
-
-function writeHosts(next, current) {
-  if (next === current) {
-    logger.info('Hosts file already up to date.');
-    return;
-  }
-
-  try {
-    fs.writeFileSync(HOSTS_PATH, next);
-    logger.success(`Updated ${HOSTS_PATH}`);
-  } catch (e) {
-    if (e.code !== 'EACCES' && e.code !== 'EPERM') throw e;
-    const tmp = path.join(os.tmpdir(), 'localctl-hosts-new');
-    fs.writeFileSync(tmp, next);
-    if (process.platform === 'win32') {
-      logger.warn('Need Administrator rights to update the hosts file. Run in an elevated PowerShell:');
-      console.log(`  Copy-Item "${tmp}" "${HOSTS_PATH}" -Force`);
-    } else {
-      logger.warn('Need sudo to update the hosts file.');
-      const res = spawnSync('sudo', ['cp', tmp, HOSTS_PATH], { stdio: 'inherit' });
-      if (res.status === 0) logger.success(`Updated ${HOSTS_PATH}`);
-      else logger.warn(`Run manually: sudo cp ${tmp} ${HOSTS_PATH}`);
-    }
-  }
-}
-
-function syncHosts() {
-  const apps = listApps();
-  const lines = [
-    MARK_START,
-    ...apps.map((s) => `127.0.0.1 ${s}.${DOMAIN}`),
-    `127.0.0.1 ${DOMAIN}`,
-    MARK_END,
-  ];
-  const block = lines.join(os.EOL);
-
-  const current = fs.readFileSync(HOSTS_PATH, 'utf8');
-  const re = new RegExp(`${MARK_START}[\\s\\S]*?${MARK_END}`, 'm');
-  const next = re.test(current)
-    ? current.replace(re, block)
-    : `${current.trimEnd()}${os.EOL}${block}${os.EOL}`;
-
-  writeHosts(next, current);
-}
-
-// Used by uninstall: strips the whole managed block, leaving the rest of the hosts file alone.
-function clearHosts() {
-  const current = fs.readFileSync(HOSTS_PATH, 'utf8');
-  const re = new RegExp(`(${os.EOL}|\\n)?${MARK_START}[\\s\\S]*?${MARK_END}(${os.EOL}|\\n)?`, 'm');
-  const next = current.replace(re, os.EOL);
-  writeHosts(next, current);
-}
-
-module.exports = { syncHosts, clearHosts, registerApp, listApps };
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const logger = require('./logger');
+const { ensureHomeState, APPS_REGISTRY_PATH } = require('./paths');
+const { DOMAIN } = require('./constants');
+
+const MARK_START = '# >>> localctl managed block >>>';
+const MARK_END = '# <<< localctl managed block <<<';
+const HOSTS_PATH =
+  process.platform === 'win32' ? 'C:\\Windows\\System32\\drivers\\etc\\hosts' : '/etc/hosts';
+
+function registerApp(subdomain) {
+  ensureHomeState();
+  const registry = JSON.parse(fs.readFileSync(APPS_REGISTRY_PATH, 'utf8'));
+  registry[subdomain] = true;
+  fs.writeFileSync(APPS_REGISTRY_PATH, JSON.stringify(registry, null, 2));
+}
+
+function listApps() {
+  ensureHomeState();
+  const registry = JSON.parse(fs.readFileSync(APPS_REGISTRY_PATH, 'utf8'));
+  return Object.keys(registry);
+}
+
+function writeHosts(next, current) {
+  if (next === current) {
+    logger.info('Hosts file already up to date.');
+    return;
+  }
+
+  try {
+    fs.writeFileSync(HOSTS_PATH, next);
+    logger.success(`Updated ${HOSTS_PATH}`);
+  } catch (e) {
+    if (e.code !== 'EACCES' && e.code !== 'EPERM') throw e;
+    const tmp = path.join(os.tmpdir(), 'localctl-hosts-new');
+    fs.writeFileSync(tmp, next);
+    if (process.platform === 'win32') {
+      logger.warn('Need Administrator rights to update the hosts file. Run in an elevated PowerShell:');
+      console.log(`  Copy-Item "${tmp}" "${HOSTS_PATH}" -Force`);
+    } else {
+      logger.warn('Need sudo to update the hosts file.');
+      const res = spawnSync('sudo', ['cp', tmp, HOSTS_PATH], { stdio: 'inherit' });
+      if (res.status === 0) logger.success(`Updated ${HOSTS_PATH}`);
+      else logger.warn(`Run manually: sudo cp ${tmp} ${HOSTS_PATH}`);
+    }
+  }
+}
+
+function syncHosts() {
+  const apps = listApps();
+  const lines = [
+    MARK_START,
+    ...apps.map((s) => `127.0.0.1 ${s}.${DOMAIN}`),
+    `127.0.0.1 ${DOMAIN}`,
+    MARK_END,
+  ];
+  const block = lines.join(os.EOL);
+
+  const current = fs.readFileSync(HOSTS_PATH, 'utf8');
+  const re = new RegExp(`${MARK_START}[\\s\\S]*?${MARK_END}`, 'm');
+  const next = re.test(current)
+    ? current.replace(re, block)
+    : `${current.trimEnd()}${os.EOL}${block}${os.EOL}`;
+
+  writeHosts(next, current);
+}
+
+// Used by uninstall: strips the whole managed block, leaving the rest of the hosts file alone.
+function clearHosts() {
+  const current = fs.readFileSync(HOSTS_PATH, 'utf8');
+  const re = new RegExp(`(${os.EOL}|\\n)?${MARK_START}[\\s\\S]*?${MARK_END}(${os.EOL}|\\n)?`, 'm');
+  const next = current.replace(re, os.EOL);
+  writeHosts(next, current);
+}
+
+module.exports = { syncHosts, clearHosts, registerApp, listApps };

package/src/lib/loadConfig.js

@@ -1,51 +1,51 @@
-const fs = require('fs');
-const path = require('path');
-const { appConfigSchema } = require('./configSchema');
-const { CONFIG_PATH } = require('./paths');
-const { resolveProfileName } = require('./projectContext');
-const { getProfile, clusterNameFor, namespaceScopeFor } = require('./profileStore');
-
-function loadConfig(configPath = CONFIG_PATH) {
-  if (!fs.existsSync(configPath)) {
-    throw new Error(`No config found at ${configPath}. Run "localctl app new" first.`);
-  }
-  const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-  const parsed = appConfigSchema.safeParse(raw);
-  if (!parsed.success) {
-    const issues = parsed.error.issues
-      .map((i) => `  - ${i.path.join('.') || '(root)'}: ${i.message}`)
-      .join('\n');
-    throw new Error(`Invalid .local/config.json:\n${issues}`);
-  }
-  const cfg = parsed.data;
-  cfg.namespace = cfg.namespace || cfg.name;
-  cfg.subdomain = cfg.subdomain || cfg.name;
-
-  // Which project this app belongs to - walking up from the app's own directory for the nearest
-  // .local/project.json, same lookup as git finding .git (see projectContext.js). No
-  // project.json anywhere above it -> the app belongs to "default", today's single cluster,
-  // unchanged.
-  const appDir = path.dirname(path.dirname(configPath));
-  const profileName = resolveProfileName(appDir);
-  const profile = getProfile(profileName);
-  if (!profile) {
-    throw new Error(
-      `Profile "${profileName}" (from .local/project.json) isn't registered on this machine. ` +
-      `Run "localctl profiles new ${profileName}" first.`,
-    );
-  }
-
-  // A namespace-level project shares its parent's cluster, isolated only by a namespace/subdomain
-  // prefix - a Main (cluster-isolation) project owns its whole cluster, nothing to prefix.
-  const scope = namespaceScopeFor(profileName);
-  if (scope) {
-    cfg.namespace = `${scope}-${cfg.namespace}`;
-    cfg.subdomain = `${scope}-${cfg.subdomain}`;
-  }
-
-  cfg.profile = profileName;
-  cfg.clusterName = clusterNameFor(profileName);
-  return cfg;
-}
-
-module.exports = { loadConfig };
+const fs = require('fs');
+const path = require('path');
+const { appConfigSchema } = require('./configSchema');
+const { CONFIG_PATH } = require('./paths');
+const { resolveProfileName } = require('./projectContext');
+const { getProfile, clusterNameFor, namespaceScopeFor } = require('./profileStore');
+
+function loadConfig(configPath = CONFIG_PATH) {
+  if (!fs.existsSync(configPath)) {
+    throw new Error(`No config found at ${configPath}. Run "localctl app new" first.`);
+  }
+  const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  const parsed = appConfigSchema.safeParse(raw);
+  if (!parsed.success) {
+    const issues = parsed.error.issues
+      .map((i) => `  - ${i.path.join('.') || '(root)'}: ${i.message}`)
+      .join('\n');
+    throw new Error(`Invalid .local/config.json:\n${issues}`);
+  }
+  const cfg = parsed.data;
+  cfg.namespace = cfg.namespace || cfg.name;
+  cfg.subdomain = cfg.subdomain || cfg.name;
+
+  // Which project this app belongs to - walking up from the app's own directory for the nearest
+  // .local/project.json, same lookup as git finding .git (see projectContext.js). No
+  // project.json anywhere above it -> the app belongs to "default", today's single cluster,
+  // unchanged.
+  const appDir = path.dirname(path.dirname(configPath));
+  const profileName = resolveProfileName(appDir);
+  const profile = getProfile(profileName);
+  if (!profile) {
+    throw new Error(
+      `Profile "${profileName}" (from .local/project.json) isn't registered on this machine. ` +
+      `Run "localctl profiles new ${profileName}" first.`,
+    );
+  }
+
+  // A namespace-level project shares its parent's cluster, isolated only by a namespace/subdomain
+  // prefix - a Main (cluster-isolation) project owns its whole cluster, nothing to prefix.
+  const scope = namespaceScopeFor(profileName);
+  if (scope) {
+    cfg.namespace = `${scope}-${cfg.namespace}`;
+    cfg.subdomain = `${scope}-${cfg.subdomain}`;
+  }
+
+  cfg.profile = profileName;
+  cfg.clusterName = clusterNameFor(profileName);
+  return cfg;
+}
+
+module.exports = { loadConfig };

package/src/lib/logger.js

@@ -1,9 +1,9 @@
-const chalk = require('chalk');
-
-module.exports = {
-  info: (msg) => console.log(chalk.cyan('info'), msg),
-  warn: (msg) => console.log(chalk.yellow('warn'), msg),
-  error: (msg) => console.error(chalk.red('error'), msg),
-  success: (msg) => console.log(chalk.green('ok'), msg),
-  step: (msg) => console.log(chalk.magenta('>'), msg),
-};
+const chalk = require('chalk');
+
+module.exports = {
+  info: (msg) => console.log(chalk.cyan('info'), msg),
+  warn: (msg) => console.log(chalk.yellow('warn'), msg),
+  error: (msg) => console.error(chalk.red('error'), msg),
+  success: (msg) => console.log(chalk.green('ok'), msg),
+  step: (msg) => console.log(chalk.magenta('>'), msg),
+};