@localctl/cli 0.5.0-beta.2 → 0.5.0

package/src/lib/appSecrets.js

@@ -1,6 +1,7 @@
-const { run, capture } = require('./exec');
+const { run, capture, sleepSync } = require('./exec');
+const { isNotFound, isConflict, firstLine } = require('./kubeErrors');
 
-// One Secret per app, holding whatever keys `.local/config.json`'s "secrets" array declares.
+// One Secret per app, holding whatever keys `.local/config.yaml`'s "secrets" array declares.
 // Unlike addon-generated secrets (random values, never seen by you), these are values *you*
 // supply - an API key, a third-party token - so there's no "generate once" step: you set them
 // with `localctl app secrets set`, and manifestGen.js just references them via secretKeyRef.
@@ -8,53 +9,123 @@ function secretNameFor(cfg) {
   return `${cfg.name}-secrets`;
 }
 
-function ensureNamespace(namespace) {
-  if (capture('kubectl', ['get', 'namespace', namespace]).status !== 0) {
-    run('kubectl', ['create', 'namespace', namespace], { stdio: 'ignore', allowFail: true });
+const { ensureManagedNamespace: ensureNamespace, assertNamespaceOwnership, MANAGED_LABEL } = require('./namespaces');
+
+const MAX_VALUE_BYTES = 512 * 1024; // a Secret is limited to 1 MiB in total
+const LAST_APPLIED = 'kubectl.kubernetes.io/last-applied-configuration';
+
+// The Secret as stored, with what is needed to write it back safely: its data (key -> base64, kept
+// in base64 end to end so binary values survive), its resourceVersion, and its labels/annotations.
+// Anything unexpected in the answer is an error: a wrong guess here would overwrite real data.
+function readSecret(cfg) {
+  assertNamespaceOwnership(cfg);
+  const name = secretNameFor(cfg);
+  const res = capture('kubectl', ['get', 'secret', name, '-n', cfg.namespace, '-o', 'json', '--request-timeout=20s']);
+  if (res.status !== 0) {
+    if (isNotFound(res.stderr, 'secrets', name)) return { exists: false, data: {} };
+    throw new Error(`Couldn't read the secrets of "${cfg.name}": ${firstLine(res.stderr || res.stdout || 'kubectl failed')}`);
+  }
+  let obj;
+  try {
+    obj = JSON.parse(res.stdout);
+  } catch (e) {
+    obj = null;
+  }
+  const meta = obj && typeof obj === 'object' && !Array.isArray(obj) ? obj.metadata : null;
+  const data = obj && obj.data === undefined ? {} : obj && obj.data;
+  const isMap = data !== null && typeof data === 'object' && !Array.isArray(data) && Object.values(data).every((v) => typeof v === 'string');
+  if (!meta || typeof meta.resourceVersion !== 'string' || !isMap) {
+    throw new Error(`The cluster returned the Secret "${name}" in an unexpected form, so it won't be changed.`);
   }
+  // Only a Secret localctl created is edited. Adopting one that happens to have the same name would
+  // mix its keys into the app's environment (and `replace` would drop its labels' meaning).
+  if ((meta.labels || {})[MANAGED_LABEL] !== 'true') {
+    throw new Error(
+      `A Secret named "${name}" already exists in namespace "${cfg.namespace}" and wasn't created by localctl. ` +
+      `Rename it, or if it is yours: kubectl label secret ${name} -n ${cfg.namespace} ${MANAGED_LABEL}=true`,
+    );
+  }
+  return { exists: true, data, resourceVersion: meta.resourceVersion, labels: meta.labels, annotations: meta.annotations };
+}
+
+function readRaw(cfg) {
+  return readSecret(cfg).data;
 }
 
 function readAll(cfg) {
-  const res = capture('kubectl', ['get', 'secret', secretNameFor(cfg), '-n', cfg.namespace, '-o', 'json']);
-  if (res.status !== 0) return {};
-  const data = JSON.parse(res.stdout).data || {};
-  return Object.fromEntries(Object.entries(data).map(([k, v]) => [k, Buffer.from(v, 'base64').toString('utf8')]));
-}
-
-// Rewrites the whole Secret from a plain key->value map. `apply` (not `create`) makes this
-// idempotent - a re-run with the same data is a no-op, a changed one updates in place.
-function writeAll(cfg, data) {
-  ensureNamespace(cfg.namespace);
-  const doc = {
-    apiVersion: 'v1',
-    kind: 'Secret',
-    metadata: { name: secretNameFor(cfg), namespace: cfg.namespace },
-    type: 'Opaque',
-    stringData: data,
-  };
-  run('kubectl', ['apply', '-f', '-'], { stdio: ['pipe', 'inherit', 'inherit'], input: JSON.stringify(doc) });
+  return Object.fromEntries(Object.entries(readRaw(cfg)).map(([k, v]) => [k, Buffer.from(v, 'base64').toString('utf8')]));
+}
+
+// Writes the Secret with create/replace, not `apply`: apply keeps a copy of what it sent in the
+// kubectl.kubernetes.io/last-applied-configuration annotation, which would leave every value
+// readable in plain text next to the Secret, and it doesn't drop a key that is no longer in the
+// new data. `replace` carries the resourceVersion that was read, so if someone changed the Secret
+// in between, the write is refused (returns false) instead of silently overwriting their change.
+function writeSecret(cfg, snapshot, data) {
+  const name = secretNameFor(cfg);
+  const annotations = { ...(snapshot.annotations || {}) };
+  delete annotations[LAST_APPLIED]; // a copy of old plaintext values from an earlier `kubectl apply`
+  const metadata = { name, namespace: cfg.namespace, labels: { ...(snapshot.labels || {}), [MANAGED_LABEL]: 'true' } };
+  if (Object.keys(annotations).length) metadata.annotations = annotations;
+  if (snapshot.exists) metadata.resourceVersion = snapshot.resourceVersion;
+  const doc = { apiVersion: 'v1', kind: 'Secret', metadata, type: 'Opaque', data };
+  const res = capture('kubectl', [snapshot.exists ? 'replace' : 'create', '-f', '-', '--request-timeout=30s'], { input: JSON.stringify(doc) });
+  if (res.status === 0) return true;
+  // Changed or created by someone else meanwhile, or deleted since we read it: read again and retry.
+  if (isConflict(res.stderr) || (snapshot.exists && isNotFound(res.stderr, 'secrets', name))) return false;
+  throw new Error(`Couldn't write the secrets of "${cfg.name}": ${firstLine(res.stderr || res.stdout || 'kubectl failed')}`);
+}
+
+// Read-modify-write that survives two processes changing the same Secret at once: on a conflict it
+// reads again and re-applies the change. `change(data)` returns the new data, or null for "nothing
+// to do".
+function updateSecret(cfg, change) {
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    const snapshot = readSecret(cfg);
+    const next = change({ ...snapshot.data });
+    if (next === null) return false;
+    if (Object.keys(next).length === 0) {
+      // Empty the Secret under the same resourceVersion check first (so a concurrent writer is
+      // noticed), then remove it.
+      if (snapshot.exists && !writeSecret(cfg, snapshot, {})) {
+        sleepSync(100 + Math.floor(Math.random() * 300));
+        continue;
+      }
+      run('kubectl', ['delete', 'secret', secretNameFor(cfg), '-n', cfg.namespace, '--ignore-not-found=true'], { stdio: 'ignore' });
+      return true;
+    }
+    ensureNamespace(cfg.namespace, cfg.name);
+    if (writeSecret(cfg, snapshot, next)) return true;
+    sleepSync(100 + Math.floor(Math.random() * 300));
+  }
+  throw new Error(`The secrets of "${cfg.name}" kept changing while updating them; try again.`);
+}
+
+function assertKey(key) {
+  if (!/^[A-Z][A-Z0-9_]*$/.test(key) || key.length > 253) throw new Error(`"${key}" is not a valid secret name: use UPPER_SNAKE_CASE.`);
 }
 
 function setSecret(cfg, key, value) {
-  const data = readAll(cfg);
-  data[key] = value;
-  writeAll(cfg, data);
+  assertKey(key);
+  const bytes = Buffer.from(String(value), 'utf8');
+  if (bytes.length > MAX_VALUE_BYTES) throw new Error(`The value for "${key}" is ${Math.round(bytes.length / 1024)} KB; a secret value can be at most ${MAX_VALUE_BYTES / 1024} KB.`);
+  updateSecret(cfg, (data) => ({ ...data, [key]: bytes.toString('base64') }));
 }
 
 function unsetSecret(cfg, key) {
-  const data = readAll(cfg);
-  if (!(key in data)) return false;
-  delete data[key];
-  if (Object.keys(data).length === 0) {
-    run('kubectl', ['delete', 'secret', secretNameFor(cfg), '-n', cfg.namespace, '--ignore-not-found=true'], { stdio: 'ignore' });
-  } else {
-    writeAll(cfg, data);
-  }
-  return true;
+  assertKey(key);
+  let found = false;
+  updateSecret(cfg, (data) => {
+    if (!(key in data)) return null;
+    found = true;
+    delete data[key];
+    return data;
+  });
+  return found;
 }
 
 function listKeys(cfg) {
-  return Object.keys(readAll(cfg));
+  return Object.keys(readRaw(cfg));
 }
 
 module.exports = { secretNameFor, setSecret, unsetSecret, listKeys, readAll };

package/src/lib/clusterProvision.js

@@ -3,13 +3,11 @@ const fs = require('fs');
 const path = require('path');
 const yaml = require('js-yaml');
 const { run, capture, sleepSync, commandExists } = require('./exec');
-const { detectEngine, warnIfExperimental, warnIfExperimentalPlatform } = require('./engine');
-const { installIfMissing, installTiltWindows, nssInstallHint } = require('./toolInstall');
-const { ensureInsecureRegistry, ensurePodmanSocket, blockedPrivilegedPorts } = require('./podman');
+const { detectEngine, warnIfExperimental } = require('./engine');
+const { installIfMissing, installTiltWindows } = require('./toolInstall');
+const { ensureInsecureRegistry } = require('./podman');
 const { DOMAIN } = require('./constants');
 const logger = require('./logger');
-const { CERTS_DIR } = require('./paths');
-const { detectDistro, dockerInstallSteps } = require('./linuxDistro');
 
 // Cluster-level manifests: bundled under cli/assets/ in the npm package (copied there by
 // scripts/sync-assets.js at pack time), or read straight from the repo root in a git checkout.
@@ -18,15 +16,6 @@ const MANIFESTS_DIR = fs.existsSync(BUNDLED_MANIFESTS_DIR)
   ? BUNDLED_MANIFESTS_DIR
   : path.resolve(__dirname, '..', '..', '..', 'cluster', 'manifests');
 
-function isWsl() {
-  if (process.platform !== 'linux') return false;
-  try {
-    return /microsoft/i.test(fs.readFileSync('/proc/version', 'utf8'));
-  } catch (e) {
-    return false;
-  }
-}
-
 function registryNameFor(clusterName) {
   return `${clusterName}-registry`;
 }
@@ -38,163 +27,16 @@ function clusterExists(clusterName) {
     .includes(clusterName);
 }
 
-// k3d writes the API server as https://0.0.0.0:<port> into kubeconfig. Linux and Windows treat
-// 0.0.0.0 as "this host", but macOS refuses to connect to it ("can't assign requested address"),
-// so every kubectl call fails. Selects the cluster's context and points it at 127.0.0.1 instead,
-// which also repairs clusters created before this fix.
-function useClusterContext(clusterName) {
-  const context = `k3d-${clusterName}`;
-  // The cluster can exist while this kubeconfig knows nothing about it (a deleted or replaced
-  // ~/.kube/config, a different KUBECONFIG): ask k3d to write it back instead of failing.
-  const known = capture('kubectl', ['config', 'get-contexts', '-o', 'name']).stdout.split('\n');
-  if (!known.includes(context)) {
-    run('k3d', ['kubeconfig', 'merge', clusterName, '--kubeconfig-merge-default'], { stdio: 'ignore', allowFail: true });
-  }
-  run('kubectl', ['config', 'use-context', context], { stdio: 'ignore' });
-  const server = capture('kubectl', [
-    'config', 'view', '--minify', '-o', 'jsonpath={.clusters[0].cluster.server}',
-  ]).stdout;
-  if (server.includes('//0.0.0.0:')) {
-    run('kubectl', [
-      'config', 'set-cluster', context, `--server=${server.replace('//0.0.0.0:', '//127.0.0.1:')}`,
-    ], { stdio: 'ignore' });
-  }
-}
-
-// Generated fresh per call, not a static file: every Main project needs its own cluster name,
-// ports, and registry mirror name baked in.
-function buildK3dConfig({ clusterName, httpPort, httpsPort, registryName }) {
-  return {
-    apiVersion: 'k3d.io/v1alpha5',
-    kind: 'Simple',
-    metadata: { name: clusterName },
-    servers: 1,
-    agents: 0,
-    ports: [
-      { port: `${httpPort}:80`, nodeFilters: ['loadbalancer'] },
-      { port: `${httpsPort}:443`, nodeFilters: ['loadbalancer'] },
-    ],
-    options: {
-      k3s: {
-        // metrics-server only feeds `kubectl top` and HPAs, which a local dev loop doesn't use;
-        // dropping it saves memory. servicelb must stay: it's what opens :80/:443 on the node for
-        // Traefik's LoadBalancer Service, so disabling it would break every ingress.
-        extraArgs: [{ arg: '--disable=metrics-server', nodeFilters: ['server:*'] }],
-      },
-    },
-    // Plain container + mirror config, not k3d's built-in `registries.create`: that hard-codes
-    // attaching to a network literally named "bridge", which Docker has by default but Podman
-    // does not, breaking cluster creation there.
-    registries: {
-      config: yaml.dump({ mirrors: { [`${registryName}:5000`]: { endpoint: [`http://${registryName}:5000`] } } }),
-    },
-  };
-}
-
-// Right after a (re)start the load balancer can accept connections before the API server is
-// answering (EOF / connection refused), so wait for it before the first real kubectl call.
-// Also after an engine restart the server container can get a new IP while the load balancer
-// (nginx, resolves upstreams only at startup) keeps the old one, so the API never answers;
-// restarting the load balancer once re-resolves it. Returns true once the API is ready.
-function waitForClusterApi(engineBin, clusterName, { attempts = 60, quiet = false } = {}) {
-  if (!quiet) logger.step('Waiting for the Kubernetes API...');
-  let lbRestarted = false;
-  for (let i = 0; i < attempts; i += 1) {
-    if (capture('kubectl', ['get', '--raw', '/readyz']).status === 0) return true;
-    if (i === 5 && !lbRestarted) {
-      lbRestarted = true;
-      run(engineBin, ['restart', `k3d-${clusterName}-serverlb`], { stdio: 'ignore', allowFail: true });
-    }
-    sleepSync(2000);
-  }
-  return false;
-}
-
-// k3d's --wait only waits for node readiness, not for Traefik's helm-install job to finish
-// registering its CRDs, so applying TLSStore any earlier races and fails intermittently. On a slow
-// machine (first image pulls, a nested engine) that takes minutes, so poll for the CRD to be
-// *Established* instead of giving up after one fixed wait, and say why if it never is.
-function waitForTraefikCrds(attempts = 150) {
-  logger.step('Waiting for Traefik CRDs...');
-  let last = 'not found yet';
-  for (let i = 0; i < attempts; i += 1) {
-    const r = capture('kubectl', [
-      'get', 'crd', 'tlsstores.traefik.io',
-      '-o', 'jsonpath={.status.conditions[?(@.type=="Established")].status}',
-    ]);
-    if (r.status === 0 && r.stdout === 'True') return;
-    last = r.status === 0 ? `Established=${r.stdout || 'unknown'}` : (r.stderr.split('\n')[0] || 'not found yet');
-    sleepSync(2000);
-  }
-  throw new Error(
-    `Traefik's CRDs (tlsstores.traefik.io) were not ready after ${Math.round((attempts * 2) / 60)} minutes (${last}). ` +
-    'Check "kubectl -n kube-system get pods" - the traefik helm-install jobs are probably still pulling images.',
-  );
-}
-
-// The CRDs existing does not mean Traefik is serving: on a slow machine its pod can still be
-// starting minutes later, and an app deployed in that window answers with a dropped connection.
-// Waiting here makes "cluster ready" mean the ingress actually accepts traffic.
-function waitForTraefik(attempts = 150) {
-  logger.step('Waiting for Traefik to accept traffic...');
-  for (let i = 0; i < attempts; i += 1) {
-    if (capture('kubectl', ['get', 'deployment', 'traefik', '-n', 'kube-system']).status === 0) break;
-    sleepSync(2000);
-  }
-  const res = capture('kubectl', ['rollout', 'status', 'deployment/traefik', '-n', 'kube-system', '--timeout=300s']);
-  if (res.status !== 0) {
-    throw new Error(
-      `Traefik did not become ready in 5 minutes (${(res.stderr || res.stdout).split('\n')[0]}). ` +
-      'Check "kubectl -n kube-system get pods".',
-    );
-  }
-}
-
-// A CRD can be Established a moment before the API server's discovery serves it, which surfaces as
-// "no matches for kind". Retrying the apply covers that window.
-function applyWithRetry(file, attempts = 15) {
-  let res;
-  for (let i = 0; i < attempts; i += 1) {
-    res = capture('kubectl', ['apply', '-f', file]);
-    if (res.status === 0) {
-      if (res.stdout) console.log(res.stdout);
-      return;
-    }
-    sleepSync(2000);
-  }
-  throw new Error(`kubectl apply -f ${path.basename(file)} failed after ${attempts} attempts: ${res.stderr}`);
-}
-
 // Brings up (idempotently) one Main project's cluster: container engine + tool checks, the k3d
 // cluster itself (own ports, since two clusters can't both bind host :80/:443), its own local
 // registry container, and the shared *.local.test TLS cert wired into its Traefik. Used by both
 // `localctl setup` (the "default" profile, unchanged ports/names from before multi-project
 // support) and `localctl profiles new`/`switch` (any other Main project).
 function provisionCluster({ clusterName, httpPort, httpsPort, registryPort }) {
-  warnIfExperimentalPlatform();
-  if (isWsl()) {
-    logger.warn('WSL detected: browsers on Windows read C:\\Windows\\System32\\drivers\\etc\\hosts, not this distro\'s /etc/hosts, and WSL may regenerate /etc/hosts on restart. Add the *.local.test entries to the Windows hosts file too (localctl prints them), or run localctl from Windows instead.');
-  }
   logger.step('Detecting container engine...');
   const detected = detectEngine();
   if (!detected) {
-    let linuxHint = '';
-    if (process.platform === 'linux') {
-      if (commandExists('docker') || commandExists('podman')) {
-        // Installed but not usable: reinstalling won't help, the daemon or permissions are the issue.
-        linuxHint = '\nA container engine is installed but not responding. Start the service' +
-          ' (`sudo systemctl enable --now docker`, or `systemctl --user enable --now podman.socket` for Podman;' +
-          ' without systemd, start `dockerd` yourself) and make sure your user can reach it' +
-          ' (member of the "docker" group, then log out and in).';
-      } else {
-        const { family, id } = detectDistro();
-        const steps = dockerInstallSteps(family, id);
-        linuxHint = steps
-          ? `\nTo install Docker Engine, run "localctl setup --install-docker", or by hand:\n  ${steps.join('\n  ')}`
-          : '\nInstall Docker Engine for your distro: https://docs.docker.com/engine/install/';
-      }
-    }
-    throw new Error(`No running container engine found. Start Docker Desktop, Podman, or Rancher Desktop and re-run.${linuxHint}`);
+    throw new Error('No running container engine found. Start Docker Desktop, Podman, or Rancher Desktop and re-run.');
   }
   const { engine, bin: engineBin } = detected;
   logger.success(`Using container engine: ${engine} (${engineBin} CLI)`);
@@ -205,14 +47,6 @@ function provisionCluster({ clusterName, httpPort, httpsPort, registryPort }) {
   // exist, but re-running it per registry port is cheap and idempotent.
   if (engine === 'podman') {
     ensureInsecureRegistry(registryPort);
-    if (process.platform === 'linux') {
-      const socketProblem = ensurePodmanSocket();
-      if (socketProblem) logger.warn(socketProblem);
-      const blocked = blockedPrivilegedPorts([httpPort, httpsPort]);
-      if (blocked.length) {
-        logger.warn(`Rootless Podman can't bind host port(s) ${blocked.join(', ')}. Allow it with: sudo sysctl net.ipv4.ip_unprivileged_port_start=80 (add it to /etc/sysctl.d/ to persist).`);
-      }
-    }
   }
 
   installIfMissing('k3d', 'k3d', 'k3d.k3d');
@@ -220,53 +54,39 @@ function provisionCluster({ clusterName, httpPort, httpsPort, registryPort }) {
   installIfMissing('tilt', 'tilt', installTiltWindows);
   installIfMissing('mkcert', 'mkcert', 'FiloSottile.mkcert');
   installIfMissing('helm', 'helm', 'Helm.Helm');
-  // mkcert can only add its CA to Firefox's trust store when NSS's certutil is present. It's
-  // optional (Safari/Chrome don't need it), so a failed or impossible install - e.g. no Homebrew -
-  // only warns. macOS installs it automatically; Linux needs sudo, so it only prints the command.
-  if (!commandExists('certutil')) {
-    if (process.platform === 'darwin') {
-      if (commandExists('brew')) {
-        try {
-          installIfMissing('certutil', 'nss');
-        } catch (e) {
-          logger.warn(`Couldn't install nss (${e.message}). Firefox won't trust the local CA until you run "brew install nss && mkcert -install".`);
-        }
-      } else {
-        logger.warn('Homebrew not found, skipping nss. Firefox won\'t trust the local CA until certutil is installed and "mkcert -install" is re-run.');
-        logger.info('Tip: install Homebrew (https://brew.sh) so localctl can install missing tools for you, then run "brew install nss".');
-      }
-    } else if (process.platform === 'linux') {
-      logger.warn(`certutil not found, so Firefox/Chromium won't trust the local CA. Install it with: ${nssInstallHint()} - then re-run "mkcert -install".`);
-    }
-  }
 
   const registryName = registryNameFor(clusterName);
 
   if (clusterExists(clusterName)) {
     logger.success(`k3d cluster '${clusterName}' already exists`);
-    // A reboot or engine restart leaves the cluster stopped; `start` is a no-op when it's running.
-    run('k3d', ['cluster', 'start', clusterName, '--wait'], { stdio: 'ignore', allowFail: true });
   } else {
     logger.step(`Creating k3d cluster '${clusterName}'...`);
-    const k3dConfig = buildK3dConfig({ clusterName, httpPort, httpsPort, registryName });
+    // Generated fresh per call, not a static file: every Main project needs its own cluster
+    // name, ports, and registry mirror name baked in.
+    const k3dConfig = {
+      apiVersion: 'k3d.io/v1alpha5',
+      kind: 'Simple',
+      metadata: { name: clusterName },
+      servers: 1,
+      agents: 0,
+      ports: [
+        { port: `${httpPort}:80`, nodeFilters: ['loadbalancer'] },
+        { port: `${httpsPort}:443`, nodeFilters: ['loadbalancer'] },
+      ],
+      // Plain container + mirror config, not k3d's built-in `registries.create`: that hard-codes
+      // attaching to a network literally named "bridge", which Docker has by default but Podman
+      // does not, breaking cluster creation there.
+      registries: {
+        config: yaml.dump({ mirrors: { [`${registryName}:5000`]: { endpoint: [`http://${registryName}:5000`] } } }),
+      },
+    };
     const tmpConfig = path.join(os.tmpdir(), `localctl-k3d-config-${clusterName}.yaml`);
     fs.writeFileSync(tmpConfig, yaml.dump(k3dConfig));
     run('k3d', ['cluster', 'create', '--config', tmpConfig, '--wait']);
     fs.rmSync(tmpConfig, { force: true });
     logger.success('Cluster created');
   }
-  useClusterContext(clusterName);
-
-  // Up to ~5 minutes: k3s can exit once during start-up (a known race between its cloud controller
-  // and RBAC bootstrap) and is restarted by the engine, which a 2-minute wait would not outlast on
-  // a slow machine. If it never answers, stop here with the reason instead of failing later on an
-  // unrelated "EOF" from kubectl apply.
-  if (!waitForClusterApi(engineBin, clusterName, { attempts: 150 })) {
-    throw new Error(
-      `The Kubernetes API of cluster '${clusterName}' did not become ready in 5 minutes. ` +
-      `See why with: ${engineBin} logs --tail 50 k3d-${clusterName}-server-0`,
-    );
-  }
+  run('kubectl', ['config', 'use-context', `k3d-${clusterName}`], { stdio: 'ignore' });
 
   const registryNetwork = `k3d-${clusterName}`;
   const existingNames = capture(engineBin, ['ps', '-a', '--format', '{{.Names}}']).stdout.split('\n');
@@ -290,7 +110,7 @@ function provisionCluster({ clusterName, httpPort, httpsPort, registryPort }) {
   // domain everywhere; only the namespace/subdomain prefix or the cluster differs).
   logger.step(`Setting up local TLS for *.${DOMAIN}...`);
   run('mkcert', ['-install']);
-  const certDir = CERTS_DIR;
+  const certDir = path.join(os.homedir(), '.localctl', 'certs');
   fs.mkdirSync(certDir, { recursive: true });
   const certFile = path.join(certDir, 'local-dev.pem');
   const keyFile = path.join(certDir, 'local-dev-key.pem');
@@ -307,10 +127,15 @@ function provisionCluster({ clusterName, httpPort, httpsPort, registryPort }) {
 
   // k3d's --wait only waits for node readiness, not for Traefik's helm-install job to finish
   // registering its CRDs, so applying TLSStore any earlier races and fails intermittently.
-  waitForTraefikCrds();
-  applyWithRetry(path.join(MANIFESTS_DIR, 'tls-store.yaml'));
-  applyWithRetry(path.join(MANIFESTS_DIR, 'namespace-addons.yaml'));
-  waitForTraefik();
+  logger.step('Waiting for Traefik CRDs...');
+  for (let i = 0; i < 60; i += 1) {
+    if (capture('kubectl', ['get', 'crd', 'tlsstores.traefik.io']).status === 0) break;
+    sleepSync(2000);
+  }
+  run('kubectl', ['wait', '--for=condition=Established', 'crd/tlsstores.traefik.io', '--timeout=60s'], { stdio: 'ignore' });
+
+  run('kubectl', ['apply', '-f', path.join(MANIFESTS_DIR, 'tls-store.yaml')]);
+  run('kubectl', ['apply', '-f', path.join(MANIFESTS_DIR, 'namespace-addons.yaml')]);
   logger.success('TLS configured, default cert wired into Traefik');
 }
 
@@ -340,7 +165,16 @@ function ensureClusterUp(clusterName, profileName) {
     const fix = profileName === 'default' ? 'localctl setup' : `localctl profiles switch ${profileName}`;
     throw new Error(`No cluster running for project "${profileName}". Run "${fix}" to start it.`);
   }
-  useClusterContext(clusterName);
+  // Switching context rewrites the kubeconfig under a file lock, which makes parallel localctl runs
+  // fail at random. Skip it when this context is already the current one, and retry the rest.
+  const wanted = `k3d-${clusterName}`;
+  if (capture('kubectl', ['config', 'current-context']).stdout === wanted) return;
+  for (let attempt = 0; ; attempt += 1) {
+    const res = capture('kubectl', ['config', 'use-context', wanted]);
+    if (res.status === 0) return;
+    if (attempt >= 4) throw new Error(`Couldn't switch kubectl to ${wanted}: ${String(res.stderr || res.stdout).split('\n')[0].slice(0, 200)}`);
+    sleepSync(150 + Math.floor(Math.random() * 250));
+  }
 }
 
-module.exports = { buildK3dConfig, useClusterContext, waitForClusterApi, provisionCluster, teardownCluster, clusterExists, registryNameFor, ensureClusterUp };
+module.exports = { provisionCluster, teardownCluster, clusterExists, registryNameFor, ensureClusterUp };