@localctl/cli 0.5.0-beta.3 → 0.5.0

package/src/lib/namespaces.js

@@ -0,0 +1,83 @@
+const { capture } = require('./exec');
+const { isNotFound, isAlreadyExists, firstLine } = require('./kubeErrors');
+
+const MANAGED_LABEL = 'localctl.dev/managed';
+const APP_ANNOTATION = 'localctl.dev/app';
+
+// Namespaces a config may never claim: Kubernetes' own, and the ones localctl's addons use.
+const RESERVED_NAMESPACES = ['default', 'kube-system', 'kube-public', 'kube-node-lease', 'observability', 'cert-manager', 'traefik', 'ingress-nginx', 'localctl'];
+
+// Also anything starting with kube-, and the common cluster add-ons, which a config has no business
+// deploying into.
+const RESERVED_PATTERN = /^kube-/;
+const isReservedNamespace = (ns) => RESERVED_NAMESPACES.includes(ns) || RESERVED_PATTERN.test(ns);
+
+// Creates a namespace that is marked as managed by localctl and records which app owns it, in one
+// request, so there is no moment where it exists without an owner. Does nothing when it already
+// exists: assertNamespaceOwnership decides whether that one may be used.
+function ensureManagedNamespace(namespace, owner) {
+  const existing = capture('kubectl', ['get', 'namespace', namespace, '--request-timeout=20s']);
+  if (existing.status === 0) return;
+  if (!isNotFound(existing.stderr, 'namespaces', namespace)) {
+    throw new Error(`Couldn't check namespace "${namespace}": ${firstLine(existing.stderr || existing.stdout || 'kubectl failed')}`);
+  }
+  const manifest = {
+    apiVersion: 'v1',
+    kind: 'Namespace',
+    metadata: {
+      name: namespace,
+      labels: { [MANAGED_LABEL]: 'true' },
+      annotations: owner ? { [APP_ANNOTATION]: owner } : undefined,
+    },
+  };
+  // `create` (not apply) fails if someone created it a moment ago instead of silently adopting it.
+  const created = capture('kubectl', ['create', '-f', '-'], { input: JSON.stringify(manifest) });
+  if (created.status !== 0 && !isAlreadyExists(created.stderr)) {
+    throw new Error(`Couldn't create namespace "${namespace}": ${firstLine(created.stderr || created.stdout || 'kubectl failed')}`);
+  }
+  // If someone else created it first, what is there must be ours before anything goes into it.
+  if (owner) assertNamespaceOwnership({ name: owner, namespace });
+}
+
+// Refuses to touch a namespace that exists but was not created by localctl for this app. Without
+// this, a config that names `namespace: shop` could make `app up` overwrite objects in someone
+// else's namespace and `app down` or `app prune` delete it. A namespace that doesn't exist yet is
+// fine: it gets created, marked and annotated on first deploy. Any answer other than "found" or
+// "not found" (API unreachable, no permission, odd output) is an error, never a pass.
+function assertNamespaceOwnership(cfg) {
+  const res = capture('kubectl', ['get', 'namespace', cfg.namespace, '-o', 'json', '--request-timeout=20s']);
+  if (res.status !== 0) {
+    if (isNotFound(res.stderr, 'namespaces', cfg.namespace)) return;
+    throw new Error(`Couldn't check whether namespace "${cfg.namespace}" is yours: ${firstLine(res.stderr || res.stdout || 'kubectl failed')}`);
+  }
+  let meta;
+  try {
+    meta = JSON.parse(res.stdout).metadata;
+  } catch (e) {
+    meta = null;
+  }
+  if (!meta || typeof meta !== 'object') {
+    throw new Error(`Couldn't read namespace "${cfg.namespace}" from the cluster, so it won't be touched.`);
+  }
+  if (meta.deletionTimestamp) {
+    throw new Error(`Namespace "${cfg.namespace}" is being deleted; wait a moment and try again.`);
+  }
+  const labels = meta.labels || {};
+  const owner = (meta.annotations || {})[APP_ANNOTATION];
+  if (labels[MANAGED_LABEL] !== 'true') {
+    throw new Error(
+      `Namespace "${cfg.namespace}" already exists and wasn't created by localctl, so it won't be touched. ` +
+      `Pick another "namespace" in .local/config.yaml, or if it is yours: kubectl label namespace ${cfg.namespace} ${MANAGED_LABEL}=true && ` +
+      `kubectl annotate namespace ${cfg.namespace} ${APP_ANNOTATION}=${cfg.name}`,
+    );
+  }
+  if (owner !== cfg.name) {
+    throw new Error(
+      owner
+        ? `Namespace "${cfg.namespace}" belongs to the app "${owner}", not "${cfg.name}". Use a different "namespace" so the two apps stay apart.`
+        : `Namespace "${cfg.namespace}" is managed by localctl but has no owner recorded. Claim it with: kubectl annotate namespace ${cfg.namespace} ${APP_ANNOTATION}=${cfg.name}`,
+    );
+  }
+}
+
+module.exports = { ensureManagedNamespace, assertNamespaceOwnership, isReservedNamespace, RESERVED_NAMESPACES, MANAGED_LABEL, APP_ANNOTATION };

package/src/lib/pathGuard.js

@@ -0,0 +1,79 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// The folder a config's relative paths may reach: the nearest ancestor of the app that holds a
+// `.git`, so a monorepo can use `context: ..` for a shared folder, but never leave the repository.
+// Without a git repository it is the app folder itself. A `.git` in the home directory (a dotfiles
+// repo) is not a project root, or every app under $HOME would be allowed to reach all of it.
+function projectRoot(appDir) {
+  const app = fs.realpathSync(appDir);
+  let home = null;
+  try { home = fs.realpathSync(os.homedir()); } catch (e) { /* no home: nothing to exclude */ }
+  let dir = app;
+  for (let i = 0; i < 12; i += 1) {
+    if (dir === home) break;
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return app;
+}
+
+function isInside(root, target) {
+  const rel = path.relative(root, target);
+  return rel === '' || (!rel.startsWith(`..${path.sep}`) && rel !== '..' && !path.isAbsolute(rel));
+}
+
+// Resolves `value` from `base` the way the filesystem would: every symlink is followed as it is
+// met, so `link/..` goes to the parent of the link's TARGET (not of the link), and a path that
+// does not exist yet is judged by its deepest existing ancestor. A dangling symlink is an error.
+function physicalResolve(base, value) {
+  let current = fs.realpathSync(base);
+  // On POSIX a backslash is an ordinary character in a file name, so only `/` separates there.
+  for (const segment of value.split(path.sep === '\\' ? /[\\/]+/ : /\/+/)) {
+    if (segment === '' || segment === '.') continue;
+    if (segment === '..') {
+      current = path.dirname(current);
+      continue;
+    }
+    const next = path.join(current, segment);
+    let info = null;
+    try { info = fs.lstatSync(next); } catch (e) { info = null; }
+    if (!info) {
+      current = next; // does not exist yet: keep going lexically from here
+      continue;
+    }
+    try {
+      current = fs.realpathSync(next);
+    } catch (e) {
+      throw new Error(`"${value}" goes through a symbolic link that points nowhere (${segment}).`);
+    }
+  }
+  return current;
+}
+
+// build.context, build.dockerfile and sync[].localPath are resolved from the app folder and must
+// stay inside the project. `..` is allowed only as far as the repository root.
+function assertPathsInsideProject(cfg, appDir) {
+  const root = projectRoot(appDir);
+  const entries = [
+    ['build.context', cfg.build.context],
+    ['build.dockerfile', cfg.build.dockerfile],
+    ...cfg.sync.map((s, i) => [`sync.${i}.localPath`, s.localPath]),
+  ];
+  for (const [field, value] of entries) {
+    let resolved;
+    try {
+      resolved = physicalResolve(appDir, value);
+    } catch (e) {
+      throw new Error(`${field}: ${e.message}`);
+    }
+    if (!isInside(root, resolved)) {
+      throw new Error(`${field} "${value}" points outside the project (${root}). Paths can go up with ".." only as far as the repository root.`);
+    }
+  }
+}
+
+module.exports = { assertPathsInsideProject, projectRoot };

package/src/lib/paths.js

@@ -4,11 +4,8 @@ const fs = require('fs');
 
 const APP_DIR = process.cwd();
 const LOCAL_DIR = path.join(APP_DIR, '.local');
-const CONFIG_PATH = path.join(LOCAL_DIR, 'config.json');
-// $LOCALCTL_HOME relocates all machine-level state (profiles, apps, certs, run files). The e2e
-// suite uses it to run against a throwaway directory instead of your real ~/.localctl.
-const HOME_STATE_DIR = process.env.LOCALCTL_HOME || path.join(os.homedir(), '.localctl');
-const CERTS_DIR = path.join(HOME_STATE_DIR, 'certs');
+const CONFIG_PATH = path.join(LOCAL_DIR, 'config.yaml');
+const HOME_STATE_DIR = path.join(os.homedir(), '.localctl');
 const APPS_REGISTRY_PATH = path.join(HOME_STATE_DIR, 'apps.json');
 const PROFILES_PATH = path.join(HOME_STATE_DIR, 'profiles.json');
 const RUN_DIR = path.join(HOME_STATE_DIR, 'run');
@@ -36,7 +33,6 @@ module.exports = {
   LOCAL_DIR,
   CONFIG_PATH,
   HOME_STATE_DIR,
-  CERTS_DIR,
   APPS_REGISTRY_PATH,
   PROFILES_PATH,
   RUN_DIR,

package/src/lib/podman.js

@@ -1,46 +1,8 @@
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
 const { run, capture } = require('./exec');
 const logger = require('./logger');
 
 const CONF_PATH = '/etc/containers/registries.conf.d/999-local-dev.conf';
 
-// Native Podman (Linux) has no VM: its registries.conf lives on the host. Rootless Podman reads
-// the per-user drop-in directory (no sudo needed); root reads the system one.
-function nativeConfPath() {
-  if (typeof process.getuid === 'function' && process.getuid() === 0) return CONF_PATH;
-  const configHome = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
-  return path.join(configHome, 'containers', 'registries.conf.d', '999-local-dev.conf');
-}
-
-// Linux native Podman: no `podman machine`. Containers-image re-reads registries.conf on every
-// invocation, so unlike the VM case there's nothing to restart.
-function ensureInsecureRegistryNative(hostPort) {
-  const file = nativeConfPath();
-  const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
-  if (current.includes(`location = "localhost:${hostPort}"`)) {
-    logger.success(`Podman already trusts localhost:${hostPort} as an insecure registry`);
-    return;
-  }
-  logger.step(`Marking localhost:${hostPort} as an insecure registry for Podman (${file})...`);
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const next = `${current.trimEnd()}\n\n${registryBlock(hostPort)}`.trim().concat('\n');
-  fs.writeFileSync(file, next);
-  logger.success('Podman registry config updated');
-}
-
-function teardownInsecureRegistryNative() {
-  const file = nativeConfPath();
-  if (!fs.existsSync(file)) return;
-  fs.rmSync(file, { force: true });
-  logger.success(`Removed insecure-registry config ${file}`);
-}
-
-function isNativePodman() {
-  return process.platform === 'linux';
-}
-
 function machineName() {
   const res = capture('podman', ['machine', 'list', '--format', '{{.Name}}']);
   const [first] = res.stdout.split('\n').filter(Boolean);
@@ -72,10 +34,7 @@ function registryBlock(hostPort) {
 // something tried to use it. One file, one block per port ever provisioned on this machine.
 function ensureInsecureRegistry(hostPort) {
   const machine = machineName();
-  if (!machine) {
-    if (isNativePodman()) ensureInsecureRegistryNative(hostPort);
-    return;
-  }
+  if (!machine) return;
 
   const current = capture('podman', ['machine', 'ssh', machine, `cat ${CONF_PATH} 2>/dev/null`]).stdout;
   if (current.includes(`location = "localhost:${hostPort}"`)) {
@@ -98,10 +57,7 @@ function ensureInsecureRegistry(hostPort) {
 
 function teardownInsecureRegistry() {
   const machine = machineName();
-  if (!machine) {
-    if (isNativePodman()) teardownInsecureRegistryNative();
-    return;
-  }
+  if (!machine) return;
 
   const exists = capture('podman', ['machine', 'ssh', machine, `test -f ${CONF_PATH} && echo yes`]).stdout;
   if (exists.trim() !== 'yes') return;
@@ -113,50 +69,4 @@ function teardownInsecureRegistry() {
   logger.success('Podman VM config removed and machine restarted');
 }
 
-// k3d talks to the container engine through the Docker API socket. Docker exposes it by default;
-// Podman only when its socket service is running, and k3d finds it through DOCKER_HOST. Points
-// DOCKER_HOST at Podman's socket when it exists, and returns a problem description (or null).
-function ensurePodmanSocket() {
-  if (process.env.DOCKER_HOST) return null;
-  const res = capture('podman', ['info', '--format', '{{.Host.RemoteSocket.Path}}']);
-  const socket = res.status === 0 ? res.stdout.replace(/^unix:\/\//, '') : '';
-  if (socket && fs.existsSync(socket)) {
-    process.env.DOCKER_HOST = `unix://${socket}`;
-    logger.info(`Using the Podman socket at ${socket} (DOCKER_HOST)`);
-    return null;
-  }
-  return 'Podman\'s API socket isn\'t running, which k3d needs. Start it with: systemctl --user enable --now podman.socket';
-}
-
-// Rootless Podman can't bind host ports below net.ipv4.ip_unprivileged_port_start (1024 by
-// default), and the cluster maps host :80/:443. Returns the ports that will fail to bind.
-function blockedPrivilegedPorts(ports) {
-  const rootless = capture('podman', ['info', '--format', '{{.Host.Security.Rootless}}']).stdout === 'true';
-  if (!rootless) return [];
-  let start = 1024;
-  try {
-    start = parseInt(fs.readFileSync('/proc/sys/net/ipv4/ip_unprivileged_port_start', 'utf8'), 10);
-  } catch (e) {
-    // keep the default
-  }
-  return ports.filter((p) => p < start);
-}
-
-// Memory (MB) available to containers: the Podman VM on macOS/Windows, the host on native Linux.
-// Returns null when it can't be determined. Docker Desktop's VM size comes from `docker info`.
-function engineMemoryMb(engineBin) {
-  const res = capture(engineBin, ['info', '--format', '{{.MemTotal}}']);
-  const bytes = parseInt(res.stdout, 10);
-  if (res.status === 0 && Number.isFinite(bytes) && bytes > 0) return Math.round(bytes / 1024 / 1024);
-  const info = capture(engineBin, ['info', '--format', '{{.Host.MemTotal}}']);
-  const hostBytes = parseInt(info.stdout, 10);
-  return info.status === 0 && Number.isFinite(hostBytes) && hostBytes > 0 ? Math.round(hostBytes / 1024 / 1024) : null;
-}
-
-module.exports = {
-  engineMemoryMb,
-  ensureInsecureRegistry,
-  teardownInsecureRegistry,
-  ensurePodmanSocket,
-  blockedPrivilegedPorts,
-};
+module.exports = { ensureInsecureRegistry, teardownInsecureRegistry };

package/src/lib/projectContext.js

@@ -4,7 +4,7 @@ const path = require('path');
 // Same lookup shape as git finding .git, or Claude finding .claude: walk up from a directory
 // looking for the nearest `.local/project.json`, at that directory or any ancestor. This lets a
 // single project.json at a parent folder govern every app subfolder underneath it, or a single
-// `.local` folder hold both the project.json and an app's own config.json together - whichever
+// `.local` folder hold both the project.json and an app's own config.yaml together - whichever
 // layout a given repo uses.
 function findProjectFile(startDir) {
   let dir = startDir;
@@ -19,7 +19,7 @@ function findProjectFile(startDir) {
 
 // Which profile governs `startDir` - the name from the nearest ancestor's project.json, or
 // "default" if none exists anywhere above it. This is independent of app config resolution
-// (CONFIG_PATH is always just cwd's own .local/config.json) - only the profile/cluster scope
+// (CONFIG_PATH is always just cwd's own .local/config.yaml) - only the profile/cluster scope
 // walks up.
 function resolveProfileName(startDir = process.cwd()) {
   const file = findProjectFile(startDir);

package/src/lib/quantities.js

@@ -0,0 +1,20 @@
+// Kubernetes resource quantities, parsed exactly with BigInt. cpu is in millicores (up to 1024
+// cores), memory in bytes (up to 1 TiB). Neither can be zero, memory has no milli suffix, and a
+// request can't exceed its limit.
+const CPU=/^(\d{1,7})(\.\d{1,3})?(m)?$/, MEM=/^(\d{1,13})(\.\d{1,3})?(k|Ki|Mi|Gi|Ti|M|G|T)?$/;
+const MUL={'':1n,k:10n**3n,M:10n**6n,G:10n**9n,T:10n**12n,Ki:1n<<10n,Mi:1n<<20n,Gi:1n<<30n,Ti:1n<<40n};
+const MAX_CPU_M=1024n*1000n, MAX_MEM=1n<<40n; // 1024 cores, 1 TiB
+function scaled(int,frac,mult){ // exact: (int.frac)*mult, rejects sub-unit remainders
+  const f=(frac||'').slice(1), den=10n**BigInt(f.length), num=BigInt(int+f)*mult;
+  if(num%den!==0n) throw new Error('too precise'); return num/den; }
+function parseCpu(v){const m=CPU.exec(String(v)); if(!m) throw new Error(`cpu "${v}": use 500m, 1 or 0.5`);
+  const milli=m[3]? scaled(m[1],m[2],1n) : scaled(m[1],m[2],1000n);
+  if(milli<=0n) throw new Error('cpu must be > 0'); if(milli>MAX_CPU_M) throw new Error('cpu max 1024 cores'); return milli;}
+function parseMem(v){const m=MEM.exec(String(v)); if(!m) throw new Error(`memory "${v}": use 256Mi, 2Gi, 1G`);
+  const b=scaled(m[1],m[2],MUL[m[3]||'']); if(b<=0n) throw new Error('memory must be > 0'); if(b>MAX_MEM) throw new Error('memory max 1Ti'); return b;}
+function checkResources({requests={},limits={}}={}){
+  for(const [k,p] of [['cpu',parseCpu],['memory',parseMem]]){
+    const r=requests[k]!==undefined?p(requests[k]):null, l=limits[k]!==undefined?p(limits[k]):null;
+    if(r!==null&&l!==null&&r>l) throw new Error(`${k} request ${requests[k]} exceeds limit ${limits[k]}`);}
+  return true;}
+module.exports={parseCpu,parseMem,checkResources};

package/src/lib/safeRead.js

@@ -0,0 +1,41 @@
+const fs = require('fs');
+
+// Reads a text file that must be a plain file, up to `maxBytes`. Checking `stat.size` alone is not
+// enough: a FIFO or /dev/zero reports size 0 and would block or read forever. The file is opened
+// first (without following a final symlink) and the checks use that open handle, so the file that
+// was checked is the file that is read.
+function readRegularFile(file, maxBytes, label = file) {
+  if (fs.lstatSync(file).isSymbolicLink()) throw new Error(`${label} is a symbolic link; use a plain file.`);
+  const before = fs.statSync(file);
+  if (!before.isFile()) throw new Error(`${label} is not a regular file.`);
+  const noFollow = fs.constants.O_NOFOLLOW || 0;
+  let fd;
+  try {
+    fd = fs.openSync(file, fs.constants.O_RDONLY | noFollow);
+  } catch (e) {
+    if (e.code === 'ELOOP') throw new Error(`${label} is a symbolic link (or was swapped for one while being read); use a plain file.`);
+    throw e;
+  }
+  try {
+    const info = fs.fstatSync(fd);
+    if (!info.isFile()) throw new Error(`${label} is not a regular file.`);
+    if (info.nlink > 1) throw new Error(`${label} has several hard links; use a plain file inside the app folder.`);
+    if (info.size > maxBytes) throw new Error(`${label} is larger than ${Math.round(maxBytes / 1024)} KB.`);
+    const buffer = Buffer.alloc(info.size);
+    let offset = 0;
+    while (offset < info.size) {
+      const n = fs.readSync(fd, buffer, offset, info.size - offset, offset);
+      if (n === 0) break;
+      offset += n;
+    }
+    try {
+      return new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, offset));
+    } catch (e) {
+      throw new Error(`${label} is not valid UTF-8 text.`);
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+module.exports = { readRegularFile };

package/src/lib/tiltConfig.js

@@ -0,0 +1,25 @@
+// What the Tiltfile needs from the app's config, already resolved (defaults applied, derived
+// values computed). The Tiltfile reads this instead of parsing .local/config.yaml itself, so a new
+// config field only needs a change here and never an edit to every app's generated Tiltfile.
+function tiltConfig(cfg) {
+  const portForwards = [`${cfg.port}:${cfg.port}`];
+  if (cfg.debug.enabled && cfg.debug.port) portForwards.push(`${cfg.debug.port}:${cfg.debug.port}`);
+  for (const extra of cfg.ports) {
+    if (extra.forward && extra.protocol === 'TCP') portForwards.push(`${extra.port}:${extra.port}`);
+  }
+  return {
+    name: cfg.name,
+    build: {
+      context: cfg.build.context,
+      dockerfile: cfg.build.dockerfile,
+      target: cfg.build.target || '',
+      args: cfg.build.args,
+      ignore: cfg.build.ignore,
+    },
+    sync: cfg.sync.map((s) => ({ localPath: s.localPath, remotePath: s.remotePath })),
+    run: cfg.run.map((r) => ({ command: r.command, trigger: r.trigger || [] })),
+    portForwards,
+  };
+}
+
+module.exports = { tiltConfig };

package/src/lib/toolInstall.js

@@ -1,9 +1,7 @@
 const fs = require('fs');
-const os = require('os');
 const path = require('path');
-const { commandExists, run, capture } = require('./exec');
+const { commandExists, run } = require('./exec');
 const logger = require('./logger');
-const { detectDistro } = require('./linuxDistro');
 const { HOME_STATE_DIR } = require('./paths');
 
 // Tools that have no package-manager package on a platform get downloaded here instead. The
@@ -67,141 +65,6 @@ function installTiltWindows() {
   logger.success(`tilt installed in ${TOOLS_DIR} (added to your PATH for new terminals)`);
 }
 
-
-// ---- Linux ----
-// There's no single package manager to lean on across distros, so missing tools are fetched as
-// the vendors' own release binaries straight into TOOLS_DIR (no sudo, no distro packages). That
-// directory is on this process's PATH via addToolsDirToPath(), so setup carries on immediately.
-// Needs only curl (and tar for tilt/helm), which every mainstream distro ships.
-
-const LINUX_ARCH = { x64: 'amd64', arm64: 'arm64' };
-
-function linuxArch() {
-  const arch = LINUX_ARCH[process.arch];
-  if (!arch) throw new Error(`Unsupported CPU architecture "${process.arch}". Install the tool manually.`);
-  return arch;
-}
-
-function requireLinuxDownloadTools(...tools) {
-  const missing = tools.filter((t) => !commandExists(t));
-  if (missing.length) {
-    throw new Error(`${missing.join(' and ')} ${missing.length > 1 ? 'are' : 'is'} needed to download missing tools. Install ${missing.length > 1 ? 'them' : 'it'} with your package manager and re-run.`);
-  }
-}
-
-function download(url, dest) {
-  logger.info(`Downloading ${url}`);
-  run('curl', ['-fsSL', '--retry', '3', '-o', dest, url]);
-}
-
-// Final path segment of the URL a redirect lands on, e.g. ".../releases/tag/v0.33.0" -> "v0.33.0".
-function latestGitHubTag(repo) {
-  const res = capture('curl', [
-    '-fsSLI', '-o', '/dev/null', '-w', '%{url_effective}',
-    `https://github.com/${repo}/releases/latest`,
-  ]);
-  const tag = res.stdout.split('/').pop();
-  if (res.status !== 0 || !/^v?\d/.test(tag)) throw new Error(`Couldn't resolve the latest ${repo} release.`);
-  return tag;
-}
-
-function makeExecutable(file) {
-  fs.chmodSync(file, 0o755);
-}
-
-function installBinaryLinux(bin, url) {
-  fs.mkdirSync(TOOLS_DIR, { recursive: true });
-  const dest = path.join(TOOLS_DIR, bin);
-  download(url, dest);
-  makeExecutable(dest);
-}
-
-// Downloads a .tar.gz and moves one file out of it into TOOLS_DIR.
-function installFromTarballLinux(bin, url, innerPath) {
-  fs.mkdirSync(TOOLS_DIR, { recursive: true });
-  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), `localctl-${bin}-`));
-  try {
-    const archive = path.join(tmp, 'archive.tar.gz');
-    download(url, archive);
-    run('tar', ['-xzf', archive, '-C', tmp]);
-    const dest = path.join(TOOLS_DIR, bin);
-    fs.copyFileSync(path.join(tmp, innerPath), dest);
-    makeExecutable(dest);
-  } finally {
-    fs.rmSync(tmp, { recursive: true, force: true });
-  }
-}
-
-const LINUX_INSTALLERS = {
-  k3d() {
-    installBinaryLinux('k3d', `https://github.com/k3d-io/k3d/releases/latest/download/k3d-linux-${linuxArch()}`);
-  },
-  kubectl() {
-    const version = capture('curl', ['-fsSL', 'https://dl.k8s.io/release/stable.txt']).stdout;
-    if (!/^v\d/.test(version)) throw new Error("Couldn't resolve the latest kubectl release.");
-    installBinaryLinux('kubectl', `https://dl.k8s.io/release/${version}/bin/linux/${linuxArch()}/kubectl`);
-  },
-  mkcert() {
-    installBinaryLinux('mkcert', `https://dl.filippo.io/mkcert/latest?for=linux/${linuxArch()}`);
-  },
-  helm() {
-    const version = capture('curl', ['-fsSL', 'https://get.helm.sh/helm-latest-version']).stdout;
-    if (!/^v\d/.test(version)) throw new Error("Couldn't resolve the latest helm release.");
-    const arch = linuxArch();
-    installFromTarballLinux('helm', `https://get.helm.sh/helm-${version}-linux-${arch}.tar.gz`, `linux-${arch}/helm`);
-  },
-  tilt() {
-    const version = latestGitHubTag('tilt-dev/tilt').replace(/^v/, '');
-    const arch = process.arch === 'arm64' ? 'arm64' : 'x86_64';
-    installFromTarballLinux('tilt', `https://github.com/tilt-dev/tilt/releases/download/v${version}/tilt.${version}.linux.${arch}.tar.gz`, 'tilt');
-  },
-};
-
-// Tools land in TOOLS_DIR, which localctl puts on its own PATH, but a terminal opened later (to
-// run `kubectl` by hand, say) wouldn't see them. Persist it in the shell's rc file, with the same
-// marker bin/bootstrap.sh uses so bin/uninstall.sh cleans it up. bash and zsh only: other shells
-// get the line to add themselves.
-function persistToolsDirOnPath() {
-  const shell = path.basename(process.env.SHELL || '');
-  const rcName = { zsh: '.zshrc', bash: '.bashrc' }[shell];
-  const line = 'export PATH="$HOME/.localctl/tools:$PATH"';
-  if (!rcName) {
-    logger.info(`Add ${TOOLS_DIR} to your PATH to use these tools from your own terminal: ${line}`);
-    return;
-  }
-  const rc = path.join(os.homedir(), rcName);
-  const current = fs.existsSync(rc) ? fs.readFileSync(rc, 'utf8') : '';
-  if (current.includes('.localctl/tools')) return;
-  fs.appendFileSync(rc, `\n# Added by localctl bootstrap\n${line}\n`);
-  logger.info(`Added ${TOOLS_DIR} to PATH in ~/${rcName} - open a new terminal to pick it up.`);
-}
-
-function installLinux(bin) {
-  const installer = LINUX_INSTALLERS[bin];
-  if (!installer) {
-    throw new Error(`"${bin}" is missing and automatic install isn't supported for it on Linux. Install it with your package manager.`);
-  }
-  requireLinuxDownloadTools('curl', ...(bin === 'helm' || bin === 'tilt' ? ['tar'] : []));
-  logger.step(`Installing ${bin} from its official release (no sudo, into ${TOOLS_DIR})...`);
-  installer();
-  addToolsDirToPath();
-  persistToolsDirOnPath();
-  logger.success(`${bin} installed in ${TOOLS_DIR}`);
-}
-
-// Distro-specific command for the NSS tools (certutil), which mkcert needs to trust its CA in
-// Firefox/Chromium. Not installed automatically: it needs sudo, and it's optional.
-function nssInstallHint() {
-  const { family } = detectDistro();
-  return {
-    debian: 'sudo apt install libnss3-tools',
-    rhel: 'sudo dnf install nss-tools',
-    arch: 'sudo pacman -S nss',
-    suse: 'sudo zypper install mozilla-nss-tools',
-    alpine: 'sudo apk add nss-tools',
-  }[family] || "your distro's NSS tools package (provides certutil)";
-}
-
 // macId: Homebrew formula name. winId: winget package id, or a function that installs the tool
 // when winget doesn't have it.
 function installIfMissing(bin, macId, winId) {
@@ -229,11 +92,9 @@ function installIfMissing(bin, macId, winId) {
       '--accept-package-agreements', '--accept-source-agreements',
     ]);
     addWingetLinksToPath();
-  } else if (process.platform === 'linux') {
-    installLinux(bin);
   } else {
     throw new Error(`"${bin}" is missing and automatic install isn't supported on this platform. Install it manually.`);
   }
 }
 
-module.exports = { installIfMissing, installTiltWindows, addToolsDirToPath, nssInstallHint, TOOLS_DIR };
+module.exports = { installIfMissing, installTiltWindows, addToolsDirToPath, TOOLS_DIR };

package/src/lib/yamlLoad.js

@@ -0,0 +1,48 @@
+const yaml = require('js-yaml');
+
+// A YAML loader that keeps text as text. The default schema turns `1e3` into 1000, `0x10` into 16,
+// `0777` into 511, `1.10` into 1.1, `+1` into 1, `2001-12-14` into a Date and a 20-digit number
+// into a rounded one: all silently, in fields like environment variables where the exact text
+// matters. Here a plain scalar becomes a number only when writing the number back gives the same
+// text (`3000`, `0.5`, `-2`); everything else stays a string. Booleans (true/false only), null,
+// anchors, aliases and merge keys work as usual; timestamps are plain strings.
+const keep = yaml.DEFAULT_SCHEMA.implicit.filter((t) => !/:(int|float|timestamp)$/.test(t.tag));
+const plain = (d) => /^-?(0|[1-9][0-9]*)(\.[0-9]*[1-9])?$/.test(d) && String(Number(d)) === d;
+const intType = new yaml.Type('tag:yaml.org,2002:int', {
+  kind: 'scalar',
+  resolve: (d) => plain(d) && !d.includes('.') && Number.isSafeInteger(Number(d)),
+  construct: Number,
+  predicate: Number.isInteger,
+});
+const floatType = new yaml.Type('tag:yaml.org,2002:float', {
+  kind: 'scalar',
+  resolve: (d) => plain(d) && d.includes('.'),
+  construct: Number,
+  predicate: (o) => typeof o === 'number',
+});
+// `explicit` (not `include`) so the !!str tag keeps working.
+const STRICT = new yaml.Schema({ explicit: [...yaml.FAILSAFE_SCHEMA.explicit], implicit: [...keep, intType, floatType] });
+
+const MAX_ALIASES = 200;
+
+// `?` as the YAML "complex key" indicator: at the start of a line (also after `- ` list markers),
+// or right after `{`, `[` or `,` in flow style, followed by whitespace or the end of the line.
+const COMPLEX_KEY = /(?:^|[\r\n])[ \t]*(?:-[ \t]+)*\?(?:[ \t\r\n]|$)|[{[,][ \t]*\?(?:[ \t\r\n]|$)/;
+
+// An alias is `*` followed by a name, and a name can be almost anything (js-yaml accepts é, `.`, `+`),
+// so match any non-space, non-flow character after a `*` that starts a token.
+const ALIAS = /(?:^|[\s,[{:(-])\*[^\s,[\]{}]/g;
+
+// A config uses a handful of anchors at most. Complex keys (`? [a, b]`) and masses of aliases are
+// the way to make a small file expensive to parse (each alias copies its anchor), so refuse them
+// before parsing.
+function loadYaml(text) {
+  if (COMPLEX_KEY.test(text)) {
+    throw new Error('complex mapping keys ("? ...") are not supported in a config (if this is a line of text inside a quoted or block string that starts with "? ", reword it).');
+  }
+  const aliases = text.match(ALIAS);
+  if (aliases && aliases.length > MAX_ALIASES) throw new Error(`too many YAML aliases (${aliases.length}); a config can use at most ${MAX_ALIASES}.`);
+  return yaml.load(text, { schema: STRICT });
+}
+
+module.exports = { loadYaml };