@localctl/cli 0.2.0

package/src/commands/setup.js

@@ -0,0 +1,36 @@
+const { provisionCluster } = require('../lib/clusterProvision');
+const { syncHosts } = require('../lib/hostsFile');
+const { setActive } = require('../lib/profileStore');
+const { DEFAULT_CLUSTER_NAME, DEFAULT_HTTP_PORT, DEFAULT_HTTPS_PORT, DOMAIN, REGISTRY_HOST_PORT } = require('../lib/constants');
+const logger = require('../lib/logger');
+
+function setup() {
+  provisionCluster({
+    clusterName: DEFAULT_CLUSTER_NAME,
+    httpPort: DEFAULT_HTTP_PORT,
+    httpsPort: DEFAULT_HTTPS_PORT,
+    registryPort: REGISTRY_HOST_PORT,
+  });
+  setActive('default');
+
+  // Hosts file: seed it now (prompts for sudo here, once, instead of surprising you mid
+  // `localctl app up` later). Only adds `local.test` itself at this point - per-app subdomains get
+  // added the same way when you run `localctl app new`/`up` for each app.
+  logger.step('Syncing hosts file...');
+  syncHosts();
+
+  console.log();
+  logger.success('Setup complete.');
+  console.log('Next steps:');
+  console.log('  1. cd into an app repo');
+  console.log('  2. localctl app new');
+  console.log('  3. localctl app up');
+  console.log(`  4. open https://<subdomain>.${DOMAIN}`);
+}
+
+module.exports = (program) => {
+  program
+    .command('setup')
+    .description('One-click local infra setup for the default project: container engine, tools, k3d cluster, TLS, hosts')
+    .action(setup);
+};

package/src/commands/status.js

@@ -0,0 +1,136 @@
+const fs = require('fs');
+const { isRunning } = require('../lib/exec');
+const { runFiles, CONFIG_PATH } = require('../lib/paths');
+const { getList, workloadsWithPrefix } = require('../lib/workloadReadiness');
+const { loadConfig } = require('../lib/loadConfig');
+const { ensureClusterUp } = require('../lib/clusterProvision');
+const { getActive, clusterNameFor } = require('../lib/profileStore');
+const ui = require('../lib/ui');
+const logger = require('../lib/logger');
+
+function key(obj) {
+  return `${obj.metadata.namespace}/${obj.metadata.name}`;
+}
+
+function collect() {
+  const deployments = getList(['get', 'deployment', '-A', '-l', 'localctl.dev/managed=true']);
+  const ingresses = getList(['get', 'ingress', '-A', '-l', 'localctl.dev/managed=true']);
+  const services = getList(['get', 'service', '-A', '-l', 'localctl.dev/managed=true']);
+  return {
+    deployments,
+    ingressByKey: new Map(ingresses.map((i) => [key(i), i])),
+    serviceByKey: new Map(services.map((s) => [key(s), s])),
+  };
+}
+
+function devLoop(name) {
+  const { pidFile } = runFiles(name);
+  if (!fs.existsSync(pidFile)) return ui.dim('-');
+  const pid = parseInt(fs.readFileSync(pidFile, 'utf8'), 10);
+  if (Number.isFinite(pid) && isRunning(pid)) return ui.ok(`running (pid ${pid})`);
+  return ui.warn('stopped');
+}
+
+function readyLabel(dep) {
+  return ui.readyLabel(dep.status.readyReplicas || 0, dep.spec.replicas);
+}
+
+function urlFor(dep, ingressByKey) {
+  const ing = ingressByKey.get(key(dep));
+  const rule = ing && ing.spec.rules && ing.spec.rules[0];
+  if (!rule) return ui.dim('-');
+  const scheme = ing.spec.tls && ing.spec.tls.length ? 'https' : 'http';
+  return ui.url(`${scheme}://${rule.host}`);
+}
+
+function debugPortFor(dep, serviceByKey) {
+  const svc = serviceByKey.get(key(dep));
+  const port = svc && svc.spec.ports.find((p) => p.name === 'debug');
+  return port ? String(port.port) : null;
+}
+
+function dependenciesFor(dep) {
+  // Real Helm charts pick whichever workload kind fits them - not every addon is a plain
+  // Deployment like the app itself always is (see lib/workloadReadiness.js).
+  const prefix = `${dep.metadata.name}-`;
+  return workloadsWithPrefix(dep.metadata.namespace, prefix)
+    .map((w) => ({ name: w.name, ready: ui.readyLabel(w.ready, w.desired) }));
+}
+
+function printSingle(dep, ingressByKey, serviceByKey) {
+  const debugPort = debugPortFor(dep, serviceByKey);
+  console.log(`${ui.bold(dep.metadata.name)}`);
+  console.log(`  namespace: ${dep.metadata.namespace}`);
+  console.log(`  ready:     ${readyLabel(dep)}`);
+  console.log(`  url:       ${urlFor(dep, ingressByKey)}`);
+  if (debugPort) console.log(`  debug:     localhost:${debugPort}`);
+  console.log(`  dev loop:  ${devLoop(dep.metadata.name)}`);
+
+  const deps = dependenciesFor(dep);
+  if (deps.length > 0) {
+    console.log('  dependencies:');
+    deps.forEach((d) => console.log(`    ${d.name}  ${d.ready}`));
+  }
+}
+
+function printAll(deployments, ingressByKey, serviceByKey) {
+  const rows = deployments.map((dep) => [
+    dep.metadata.name,
+    dep.metadata.namespace,
+    readyLabel(dep),
+    urlFor(dep, ingressByKey),
+    devLoop(dep.metadata.name),
+  ]);
+  ui.printTable(['APP', 'NAMESPACE', 'READY', 'URL', 'DEV LOOP'], rows);
+
+  if (!deployments.some((dep) => devLoop(dep.metadata.name).includes('running'))) {
+    console.log('');
+    logger.info('Dev loop not running locally for any app - "localctl app up" from an app\'s directory to start one.');
+  }
+}
+
+module.exports = (program) => {
+  program
+    .command('status')
+    .option('-a, --app <name>', 'show status for one app by name, in the currently active project\'s cluster')
+    .option('-A, --all', 'show every app in the currently active project\'s cluster, even from inside an app repo')
+    .description('Show every localctl-managed app in a cluster: readiness, URL, local dev-loop state')
+    .action((opts) => {
+      let targetName = opts.app;
+      let targetNamespace = null;
+
+      // Directory-resolved single-app view: figures out which project (and so which cluster and
+      // namespace/subdomain prefix) this app belongs to on its own - see loadConfig.js.
+      if (!targetName && !opts.all && fs.existsSync(CONFIG_PATH)) {
+        const cfg = loadConfig();
+        ensureClusterUp(cfg.clusterName, cfg.profile);
+        targetName = cfg.name;
+        targetNamespace = cfg.namespace;
+      } else {
+        // No directory context (elsewhere, -a, or -A): fall back to whichever project is
+        // currently active (see "localctl profiles switch").
+        const active = getActive();
+        ensureClusterUp(clusterNameFor(active), active);
+      }
+
+      const { deployments, ingressByKey, serviceByKey } = collect();
+      if (deployments.length === 0) {
+        logger.info('No localctl-managed apps found in the cluster.');
+        return;
+      }
+
+      if (targetName) {
+        const dep = deployments.find(
+          (d) => d.metadata.name === targetName && (!targetNamespace || d.metadata.namespace === targetNamespace),
+        );
+        if (!dep) {
+          logger.warn(`No deployed app named "${targetName}" found in the cluster.`);
+          return;
+        }
+        printSingle(dep, ingressByKey, serviceByKey);
+        return;
+      }
+
+      printAll(deployments, ingressByKey, serviceByKey);
+    });
+};

package/src/commands/uninstall.js

@@ -0,0 +1,105 @@
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const { isRunning } = require('../lib/exec');
+const { detectEngine } = require('../lib/engine');
+const { teardownCluster, clusterExists } = require('../lib/clusterProvision');
+const { teardownInsecureRegistry } = require('../lib/podman');
+const { clearHosts } = require('../lib/hostsFile');
+const { listProfiles } = require('../lib/profileStore');
+const { confirm } = require('../lib/prompt');
+const { RUN_DIR, PROFILES_PATH } = require('../lib/paths');
+const logger = require('../lib/logger');
+
+// Every Main (cluster-isolation) project this machine knows about - each one owns a real,
+// separate cluster that needs tearing down individually.
+function mainProjects() {
+  return Object.entries(listProfiles())
+    .filter(([, def]) => def.isolation === 'cluster')
+    .map(([name, def]) => ({ name, cluster: def.cluster }));
+}
+
+async function uninstall(opts) {
+  const projects = mainProjects();
+  console.log('This will remove everything "localctl setup"/"localctl profiles" set up:');
+  console.log(`  - Every project's k3d cluster (${projects.map((p) => p.cluster).join(', ')}) and everything deployed in them`);
+  console.log('  - Their local image registry containers');
+  console.log('  - Podman VM insecure-registry config (Podman only, if present)');
+  console.log('  - The *.local.test block in your hosts file');
+  console.log('  - Any background dev loop `localctl app up` left running, and its state');
+  console.log('  - ~/.localctl/certs, the app registry state, and the project registry (~/.localctl/profiles.json)');
+  console.log('');
+  console.log("It will NOT remove: k3d, kubectl, tilt, mkcert, node, the localctl CLI itself, or");
+  console.log("mkcert's root CA trust. To remove the CLI too, use whichever matches how you");
+  console.log('installed it: `npm uninstall -g @localctl/cli`, or `bin/uninstall.sh` /');
+  console.log("`uninstall.ps1` if you used bin/bootstrap.sh's PATH shim instead.");
+  console.log('');
+
+  if (!opts.yes) {
+    const answer = await confirm('Continue? [y/N] ');
+    if (!/^y(es)?$/i.test(answer)) {
+      console.log('Aborted.');
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  try {
+    clearHosts();
+  } catch (e) {
+    logger.warn(`Could not clear hosts file: ${e.message}`);
+  }
+
+  for (const project of projects) {
+    if (clusterExists(project.cluster)) {
+      teardownCluster(project.cluster);
+    }
+  }
+
+  const detected = detectEngine();
+  if (detected && detected.engine === 'podman') {
+    teardownInsecureRegistry();
+  }
+
+  // Stop any background dev loops `localctl app up` left running (e.g. if `localctl app down` was
+  // never run for them) before deleting their pid/log files out from under them.
+  if (fs.existsSync(RUN_DIR)) {
+    fs.readdirSync(RUN_DIR)
+      .filter((f) => f.endsWith('.pid'))
+      .forEach((f) => {
+        const pid = parseInt(fs.readFileSync(path.join(RUN_DIR, f), 'utf8'), 10);
+        if (Number.isFinite(pid) && isRunning(pid)) {
+          logger.step(`Stopping background Tilt process for "${f.replace(/\.pid$/, '')}" (pid ${pid})...`);
+          try {
+            process.kill(pid, 'SIGTERM');
+          } catch (e) {
+            // already gone
+          }
+        }
+      });
+    fs.rmSync(RUN_DIR, { recursive: true, force: true });
+  }
+
+  const certsDir = path.join(os.homedir(), '.localctl', 'certs');
+  const appsRegistry = path.join(os.homedir(), '.localctl', 'apps.json');
+  if (fs.existsSync(certsDir)) fs.rmSync(certsDir, { recursive: true, force: true });
+  if (fs.existsSync(appsRegistry)) fs.rmSync(appsRegistry, { force: true });
+  if (fs.existsSync(PROFILES_PATH)) fs.rmSync(PROFILES_PATH, { force: true });
+  logger.success('Removed ~/.localctl state (certs, app registry, project registry, background dev-loop tracking)');
+
+  console.log();
+  logger.success('Uninstall complete.');
+  console.log('');
+  console.log('Left in place (remove yourself if you want them gone too):');
+  console.log('  brew uninstall k3d kubectl tilt mkcert node   # only if nothing else needs them');
+  console.log("  mkcert -uninstall   # removes the root CA from trust stores - affects EVERY");
+  console.log('                      # mkcert-issued cert on this machine, not just *.local.test');
+}
+
+module.exports = (program) => {
+  program
+    .command('uninstall')
+    .option('-y, --yes', 'skip the confirmation prompt')
+    .description('Remove everything "localctl setup"/"localctl profiles" set up: every project\'s cluster, registries, hosts entries, state')
+    .action(uninstall);
+};

package/src/commands/up.js

@@ -0,0 +1,123 @@
+const fs = require('fs');
+const { loadConfig } = require('../lib/loadConfig');
+const { syncHosts, registerApp } = require('../lib/hostsFile');
+const { run, capture, sleepSync, spawnDetached, getFreePort, isRunning } = require('../lib/exec');
+const { detectEngine } = require('../lib/engine');
+const { ensureClusterUp } = require('../lib/clusterProvision');
+const { portsFor } = require('../lib/profileStore');
+const { listKeys } = require('../lib/appSecrets');
+const { runFiles } = require('../lib/paths');
+const { DOMAIN, DEFAULT_HTTPS_PORT } = require('../lib/constants');
+const ui = require('../lib/ui');
+const logger = require('../lib/logger');
+
+function podmanBuildEnv() {
+  const env = { ...process.env };
+  const detected = detectEngine();
+  if (detected && detected.engine === 'podman') {
+    // Podman's Docker-API-compat socket doesn't implement BuildKit's gRPC build protocol
+    // (Tilt's docker_build fails with "unable to upgrade to h2c" otherwise).
+    env.DOCKER_BUILDKIT = '0';
+    logger.info('Podman detected: disabling BuildKit for this build.');
+  }
+  return env;
+}
+
+function printEndpoints(cfg) {
+  const { httpsPort } = portsFor(cfg.profile);
+  const suffix = httpsPort === DEFAULT_HTTPS_PORT ? '' : `:${httpsPort}`;
+  const url = `https://${cfg.subdomain}.${DOMAIN}${suffix}`;
+  console.log('');
+  console.log(`${ui.check} ${ui.bold(cfg.name)} -> ${ui.url(url)}`);
+  if (cfg.debug.enabled && cfg.debug.port) {
+    console.log(`  debug:  localhost:${cfg.debug.port}`);
+  }
+  console.log(`  logs:   localctl app logs ${cfg.name} -f`);
+  console.log(`  status: localctl app status`);
+  console.log(`  stop:   localctl app down`);
+  console.log('');
+}
+
+function tailLog(logFile, lines) {
+  if (!fs.existsSync(logFile)) return null;
+  return fs.readFileSync(logFile, 'utf8').trim().split('\n').slice(-lines).join('\n');
+}
+
+module.exports = (program) => {
+  program
+    .command('up')
+    .option('-f, --foreground', 'run in the foreground with the interactive Tilt UI (default: detached, survives closing this terminal)')
+    .description('Deploy/dev-loop the app in the current directory')
+    .action(async (opts) => {
+      const cfg = loadConfig();
+      ensureClusterUp(cfg.clusterName, cfg.profile);
+
+      if (cfg.secrets.length > 0) {
+        const set = new Set(listKeys(cfg));
+        const missing = cfg.secrets.filter((key) => !set.has(key));
+        if (missing.length > 0) {
+          throw new Error(
+            `Missing secret value${missing.length > 1 ? 's' : ''} for: ${missing.join(', ')}. Set ` +
+            `${missing.length > 1 ? 'them' : 'it'} first:\n` +
+            missing.map((key) => `  localctl app secrets set ${key}`).join('\n'),
+          );
+        }
+      }
+
+      registerApp(cfg.subdomain);
+      syncHosts();
+      const env = podmanBuildEnv();
+
+      // Each app gets its own Tilt web UI port. Tilt's default (10350) is shared/fixed, so two
+      // apps running `localctl up` at once - the whole point of detached mode - would otherwise
+      // collide outright, and Tilt's resulting error doesn't explain why to someone who never
+      // asked to think about Tilt's own dashboard port in the first place.
+      const tiltPort = await getFreePort();
+
+      if (opts.foreground) {
+        logger.step(`Starting Tilt for "${cfg.name}" -> https://${cfg.subdomain}.${DOMAIN}`);
+        run('tilt', ['up', '--port', String(tiltPort)], { env });
+        return;
+      }
+
+      const { pidFile, portFile, logFile } = runFiles(cfg.name);
+      const pid = spawnDetached('tilt', ['up', '--port', String(tiltPort)], { cwd: process.cwd(), env, logFile });
+      fs.writeFileSync(pidFile, String(pid));
+      fs.writeFileSync(portFile, String(tiltPort));
+      logger.step(`Starting Tilt for "${cfg.name}" in the background (pid ${pid})...`);
+      logger.info(`Full Tilt output: tail -f ${logFile}`);
+
+      logger.step('Waiting for the deployment to become ready...');
+      // Tilt needs a moment to apply the generated manifests - "rollout status" errors outright
+      // on a Deployment that doesn't exist yet, it doesn't wait for one to appear.
+      let exists = false;
+      for (let i = 0; i < 30; i += 1) {
+        if (capture('kubectl', ['get', 'deployment', cfg.name, '-n', cfg.namespace]).status === 0) {
+          exists = true;
+          break;
+        }
+        if (!isRunning(pid)) break; // Tilt already died - no point waiting out the rest of the poll
+        sleepSync(1000);
+      }
+
+      const rollout = exists
+        ? run(
+            'kubectl',
+            ['rollout', 'status', `deployment/${cfg.name}`, '-n', cfg.namespace, '--timeout=180s'],
+            { allowFail: true },
+          )
+        : { status: 1 };
+
+      if (rollout.status === 0) {
+        printEndpoints(cfg);
+        return;
+      }
+
+      if (!isRunning(pid)) {
+        logger.warn(`Tilt exited before the deployment came up. Last lines of ${logFile}:`);
+        console.log(ui.dim(tailLog(logFile, 15) || '(log file is empty)'));
+      } else {
+        logger.warn(`Still starting (or something's wrong) - check "localctl app logs ${cfg.name} -f" or "localctl app status".`);
+      }
+    });
+};

package/src/index.js

@@ -0,0 +1,36 @@
+const { Command } = require('commander');
+const { version } = require('../package.json');
+
+const program = new Command();
+program
+  .name('localctl')
+  .description('Local Kubernetes dev platform CLI')
+  .version(version);
+
+// Global/machine-level - not tied to any one app or addon.
+require('./commands/setup')(program);
+require('./commands/uninstall')(program);
+require('./commands/doctor')(program);
+require('./commands/hosts')(program);
+
+// Feature-level command groups.
+const app = program.command('app').description('Manage a single app: scaffold, deploy, monitor');
+require('./commands/new')(app);
+require('./commands/up')(app);
+require('./commands/down')(app);
+require('./commands/status')(app);
+require('./commands/logs')(app);
+require('./commands/reload')(app);
+require('./commands/generateManifests')(app);
+require('./commands/registryInfo')(app);
+require('./commands/exec')(app);
+require('./commands/prune')(app);
+require('./commands/secrets')(app); // its own subgroup: set/unset/list/show
+
+require('./commands/addons')(program); // already its own group: list/enable/disable/status
+require('./commands/profiles')(program); // already its own group: new/list/switch/status
+
+program.parseAsync(process.argv).catch((err) => {
+  console.error(err && err.message ? err.message : err);
+  process.exit(1);
+});

package/src/lib/addonDirs.js

@@ -0,0 +1,43 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Addons are searched in two places, in precedence order:
+//   1. USER_DIR   - yours, never touched by a `localctl` update/reinstall. Defaults to
+//                   ~/.localctl/addons, overridable via LOCALCTL_ADDONS_DIR (e.g. to point at a
+//                   folder checked into your own infra repo instead).
+//   2. BUILTIN_DIR - the addons shipped with this CLI (postgres/redis/mongo/cluster/logging).
+// A user-dir addon of the same name replaces the built-in one; a new name just adds to the list.
+// This is what lets someone install this tool without inheriting its author's addon set, and
+// without forking the tool to add their own - see docs/adding-tools.md.
+const BUILTIN_DIR = path.join(__dirname, 'addons');
+const USER_DIR = process.env.LOCALCTL_ADDONS_DIR || path.join(os.homedir(), '.localctl', 'addons');
+
+function roots(...segments) {
+  return [path.join(USER_DIR, ...segments), path.join(BUILTIN_DIR, ...segments)];
+}
+
+// First matching addon.yaml wins - user dir searched before built-in.
+function findAddonDir(name, ...segments) {
+  for (const root of roots(...segments)) {
+    const dir = path.join(root, name);
+    if (fs.existsSync(path.join(dir, 'addon.yaml'))) return dir;
+  }
+  return null;
+}
+
+// Every addon name available across both locations, user-dir entries deduplicated against
+// built-ins of the same name (a listing, not a "which one wins" answer - see findAddonDir for that).
+function listAddonNames(...segments) {
+  const names = new Set();
+  for (const root of roots(...segments)) {
+    if (!fs.existsSync(root)) continue;
+    fs.readdirSync(root, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .filter((e) => fs.existsSync(path.join(root, e.name, 'addon.yaml')))
+      .forEach((e) => names.add(e.name));
+  }
+  return [...names];
+}
+
+module.exports = { BUILTIN_DIR, USER_DIR, findAddonDir, listAddonNames };

package/src/lib/addonLoader.js

@@ -0,0 +1,190 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+const yaml = require('js-yaml');
+const { run, capture } = require('./exec');
+
+// Generic Helm-based addon loader. An addon is a folder containing an addon.yaml (what chart to
+// pull and how to configure it) and, optionally, a config/ folder (literal files - dashboards,
+// datasources, init scripts - that don't belong in Helm values but need to reach the chart as a
+// ConfigMap). See docs/adding-tools.md for the full addon.yaml reference and a worked example.
+
+function repoNameFor(url) {
+  return `localctl-${crypto.createHash('md5').update(url).digest('hex').slice(0, 8)}`;
+}
+
+function ensureRepo(url) {
+  const name = repoNameFor(url);
+  // --force-update: idempotent even if re-pointed at a different URL under the same generated name.
+  run('helm', ['repo', 'add', name, url, '--force-update'], { stdio: 'ignore' });
+  run('helm', ['repo', 'update', name], { stdio: 'ignore', allowFail: true });
+  return name;
+}
+
+function substitute(template, vars) {
+  return String(template).replace(/\{\{\s*([\w.]+)\s*\}\}/g, (match, key) => {
+    if (!(key in vars)) throw new Error(`Addon references unknown template variable "{{${key}}}"`);
+    return vars[key];
+  });
+}
+
+function ensureNamespace(ns) {
+  if (capture('kubectl', ['get', 'namespace', ns]).status !== 0) {
+    run('kubectl', ['create', 'namespace', ns], { stdio: 'ignore', allowFail: true });
+  }
+}
+
+// Generates each secret's value once and stores it as a real k8s Secret; a re-run that finds the
+// Secret already there leaves it alone, so app data doesn't lose its password out from under it
+// on every `localctl up`.
+function ensureSecret(name, namespace, keys) {
+  ensureNamespace(namespace);
+  if (capture('kubectl', ['get', 'secret', name, '-n', namespace]).status === 0) return;
+  const args = ['create', 'secret', 'generic', name, '-n', namespace];
+  for (const key of keys) {
+    args.push(`--from-literal=${key}=${crypto.randomBytes(16).toString('hex')}`);
+  }
+  run('kubectl', args, { stdio: 'ignore' });
+}
+
+// Turns a folder of literal files (dashboards, datasource definitions, init scripts - whatever
+// the chart expects to mount, not a Helm value) into a real ConfigMap.
+function ensureConfigMap(name, namespace, configDir) {
+  ensureNamespace(namespace);
+  const files = fs.readdirSync(configDir).filter((f) => fs.statSync(path.join(configDir, f)).isFile());
+  const args = ['create', 'configmap', name, '-n', namespace, '--dry-run=client', '-o', 'yaml'];
+  files.forEach((f) => args.push(`--from-file=${path.join(configDir, f)}`));
+  const rendered = capture('kubectl', args);
+  if (rendered.status !== 0) throw new Error(`Failed to render ConfigMap for ${configDir}: ${rendered.stderr}`);
+  run('kubectl', ['apply', '-f', '-'], { stdio: ['pipe', 'ignore', 'inherit'], input: rendered.stdout });
+}
+
+function helmTemplate(release, chart, valuesObj, namespace) {
+  const repoName = ensureRepo(chart.repo);
+  const tmpValues = path.join(os.tmpdir(), `localctl-addon-values-${process.pid}-${Date.now()}.yaml`);
+  fs.writeFileSync(tmpValues, yaml.dump(valuesObj));
+  try {
+    // --no-hooks: excludes `helm test` pods and similar hook resources from the rendered output -
+    // we apply this YAML with plain `kubectl apply`, not `helm install`, so nothing would ever
+    // run `helm test` to use them; left in, they'd just sit in the namespace as inert clutter.
+    const args = ['template', release, `${repoName}/${chart.name}`, '-f', tmpValues, '-n', namespace, '--no-hooks'];
+    if (chart.version) args.push('--version', chart.version);
+    const res = capture('helm', args);
+    if (res.status !== 0) {
+      throw new Error(`helm template failed for chart "${chart.name}":\n${res.stderr}`);
+    }
+    return res.stdout;
+  } finally {
+    fs.rmSync(tmpValues, { force: true });
+  }
+}
+
+// Every chart names its Service differently (Bitnami's own "dedupe release name vs chart name"
+// logic alone means postgresql uses `<release>-postgresql` but redis uses `<release>-master`, no
+// chart name at all, when the release name already contains "redis") - predicting it from a
+// naming convention is fragile per-chart guesswork. Reading it back out of the chart's own
+// rendered output is not: whatever the chart actually created is, by definition, correct.
+function findPrimaryService(manifestYaml) {
+  const docs = yaml.loadAll(manifestYaml).filter(Boolean);
+  const services = docs.filter((d) => d.kind === 'Service');
+  return services.find((s) => !/-headless$|-hl$/.test(s.metadata.name)) || services[0] || null;
+}
+
+function findServiceHost(manifestYaml) {
+  const svc = findPrimaryService(manifestYaml);
+  return svc ? svc.metadata.name : null;
+}
+
+// Same "read it back, don't guess" reasoning as findServiceHost - a wait-for-dependency init
+// container (manifestGen.js) needs a real port, and addon.yaml's own `env` block is free to name
+// its port var anything (POSTGRES_PORT, REDIS_PORT, ...), so it's not something to parse generically.
+function findServicePort(manifestYaml) {
+  const svc = findPrimaryService(manifestYaml);
+  const port = svc && svc.spec.ports && svc.spec.ports[0];
+  return port ? port.port : null;
+}
+
+// A small tracking ConfigMap bundled into the addon's own manifest output, so its lifecycle is
+// tied to the addon's (created and deleted together, no separate cleanup code needed). This is
+// what `localctl addons status` reads to list every addon instance in the cluster - it doesn't
+// try to guess which workload kind(s) a given chart happens to use (Deployment, StatefulSet,
+// DaemonSet all show up in real charts; guessing which is exactly the fragility that bit
+// `localctl status`'s own dependency listing once already).
+function buildAddonRecord({ release, namespace, addonName, chart, owner }) {
+  return {
+    apiVersion: 'v1',
+    kind: 'ConfigMap',
+    metadata: {
+      name: `${release}-localctl-addon`,
+      namespace,
+      labels: { 'localctl.dev/addon': 'true' },
+    },
+    data: {
+      addon: addonName,
+      chart: chart.name,
+      version: String(chart.version || ''),
+      owner: owner || '',
+    },
+  };
+}
+
+// Loads one addon (given its folder) and returns the rendered manifest YAML, plus any env vars
+// it wants injected into the caller's own container (per-app addons only - see manifestGen.js).
+function loadAddon(addonDir, { release, namespace, addonName, owner, extraVars = {}, chartVersionOverride }) {
+  const specPath = path.join(addonDir, 'addon.yaml');
+  const spec = yaml.load(fs.readFileSync(specPath, 'utf8'));
+
+  const chart = { ...spec.chart, version: chartVersionOverride || spec.chart.version };
+  const vars = { release, namespace, ...extraVars };
+
+  if (spec.secrets) {
+    const secretName = `${release}-secret`;
+    ensureSecret(secretName, namespace, Object.keys(spec.secrets));
+    vars.secretName = secretName;
+  }
+
+  const configDir = path.join(addonDir, 'config');
+  if (spec.config && fs.existsSync(configDir)) {
+    const configMapName = `${release}-config`;
+    ensureConfigMap(configMapName, namespace, configDir);
+    vars.configMapName = configMapName;
+  }
+
+  const valuesYaml = substitute(spec.values, vars);
+  const valuesObj = yaml.load(valuesYaml) || {};
+  const manifestYaml = helmTemplate(release, chart, valuesObj, namespace);
+  vars.serviceHost = findServiceHost(manifestYaml);
+  const servicePort = findServicePort(manifestYaml);
+
+  const env = {};
+  if (spec.env) {
+    for (const [k, v] of Object.entries(spec.env)) {
+      env[k] = substitute(v, vars);
+    }
+  }
+
+  // Unlike `env` (plain values), these become a real k8s secretKeyRef in the app's Deployment -
+  // the actual password never passes through a plaintext env value, config file, or `helm` value.
+  const envFromSecret = {};
+  if (spec.envFromSecret) {
+    for (const [k, ref] of Object.entries(spec.envFromSecret)) {
+      envFromSecret[k] = { secret: substitute(ref.secret, vars), key: substitute(ref.key, vars) };
+    }
+  }
+
+  const record = buildAddonRecord({ release, namespace, addonName: addonName || path.basename(addonDir), chart, owner });
+  // trimEnd() + explicit '\n' before the separator: `helm template` output doesn't always end
+  // with a trailing newline, and joining on a bare '---\n' in that case glues the separator
+  // directly onto the last line's content with no line break, corrupting the YAML.
+  const fullManifestYaml = [manifestYaml.trimEnd(), yaml.dump(record).trimEnd()].join('\n---\n');
+
+  // The addon's real, rendered host+port - not env's POSTGRES_HOST/POSTGRES_PORT (those are only
+  // as reliable as each addon.yaml's own naming), so a wait-for-dependency init container
+  // (manifestGen.js) can work for any addon generically, built-in or your own.
+  const connect = vars.serviceHost && servicePort ? { host: vars.serviceHost, port: servicePort } : null;
+
+  return { manifestYaml: fullManifestYaml, env, envFromSecret, connect };
+}
+
+module.exports = { loadAddon, substitute };