@localctl/cli 0.2.0

package/src/lib/exec.js

@@ -0,0 +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 };

package/src/lib/hostsFile.js

@@ -0,0 +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 };

package/src/lib/loadConfig.js

@@ -0,0 +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 };

package/src/lib/logger.js

@@ -0,0 +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),
+};

package/src/lib/manifestGen.js

@@ -0,0 +1,210 @@
+const yaml = require('js-yaml');
+const { DOMAIN } = require('./constants');
+const { loadAddon } = require('./addonLoader');
+const { findAddonDir, listAddonNames } = require('./addonDirs');
+const { secretNameFor } = require('./appSecrets');
+
+function buildNamespace(cfg) {
+  return { apiVersion: 'v1', kind: 'Namespace', metadata: { name: cfg.namespace } };
+}
+
+// A sidecar - an extra container sharing the pod's network namespace with the main app container.
+// No Service needed for the app to reach it: same pod means `localhost:<port>` already works.
+function buildSidecarContainer(sidecar) {
+  const container = { name: sidecar.name, image: sidecar.image };
+  if (sidecar.command) container.command = sidecar.command;
+  if (sidecar.args) container.args = sidecar.args;
+  if (sidecar.port) container.ports = [{ name: sidecar.name, containerPort: sidecar.port }];
+  const envVars = Object.entries(sidecar.env || {}).map(([name, value]) => ({ name, value: String(value) }));
+  if (envVars.length) container.env = envVars;
+  return container;
+}
+
+// Defaults to a plain TCP check on the app's own port when nothing more specific is configured -
+// zero-config, but still real: `kubectl rollout status` succeeding used to only mean "the process
+// started," not "it's actually accepting connections." An explicit `path` upgrades it to an HTTP
+// check instead.
+function buildProbe(probeCfg, port, defaults) {
+  const check = probeCfg && probeCfg.path
+    ? { httpGet: { path: probeCfg.path, port } }
+    : { tcpSocket: { port } };
+  return {
+    ...check,
+    initialDelaySeconds: (probeCfg && probeCfg.initialDelaySeconds) ?? defaults.initialDelaySeconds,
+    periodSeconds: (probeCfg && probeCfg.periodSeconds) ?? defaults.periodSeconds,
+  };
+}
+
+// Blocks the main container from starting until a dependency's real Service is actually accepting
+// connections - without this, a dependency that isn't ready yet when the app's own container
+// starts is a race the app has to handle itself (or crash-loop until it wins it).
+function buildWaitInitContainer(depType, connect) {
+  return {
+    name: `wait-for-${depType}`,
+    image: 'busybox:1.36',
+    command: ['sh', '-c', `until nc -z -w1 ${connect.host} ${connect.port}; do echo "waiting for ${depType} (${connect.host}:${connect.port})..."; sleep 1; done`],
+  };
+}
+
+function buildDeployment(cfg, envVars, initContainers) {
+  const ports = [{ name: 'http', containerPort: cfg.port }];
+  if (cfg.debug.enabled && cfg.debug.port) ports.push({ name: 'debug', containerPort: cfg.debug.port });
+
+  return {
+    apiVersion: 'apps/v1',
+    kind: 'Deployment',
+    metadata: {
+      name: cfg.name,
+      namespace: cfg.namespace,
+      labels: { app: cfg.name, 'localctl.dev/managed': 'true' },
+    },
+    spec: {
+      replicas: cfg.replicas,
+      selector: { matchLabels: { app: cfg.name } },
+      template: {
+        metadata: { labels: { app: cfg.name } },
+        spec: {
+          initContainers: initContainers.length ? initContainers : undefined,
+          containers: [
+            {
+              name: cfg.name,
+              // Rewritten to the local registry by Tilt's default_registry()/docker_build().
+              image: cfg.name,
+              ports,
+              env: envVars,
+              readinessProbe: buildProbe(cfg.probes.readiness, cfg.port, { initialDelaySeconds: 3, periodSeconds: 10 }),
+              livenessProbe: buildProbe(cfg.probes.liveness, cfg.port, { initialDelaySeconds: 10, periodSeconds: 20 }),
+              resources: cfg.resources
+                ? { requests: cfg.resources.requests, limits: cfg.resources.limits }
+                : undefined,
+            },
+            ...cfg.sidecars.map(buildSidecarContainer),
+          ],
+        },
+      },
+    },
+  };
+}
+
+function buildService(cfg) {
+  const ports = [{ name: 'http', port: cfg.port, targetPort: cfg.port }];
+  if (cfg.debug.enabled && cfg.debug.port) {
+    ports.push({ name: 'debug', port: cfg.debug.port, targetPort: cfg.debug.port });
+  }
+  return {
+    apiVersion: 'v1',
+    kind: 'Service',
+    metadata: {
+      name: cfg.name,
+      namespace: cfg.namespace,
+      labels: { app: cfg.name, 'localctl.dev/managed': 'true' },
+    },
+    spec: { selector: { app: cfg.name }, ports },
+  };
+}
+
+function buildIngress(cfg) {
+  const host = `${cfg.subdomain}.${DOMAIN}`;
+  const ingress = {
+    apiVersion: 'networking.k8s.io/v1',
+    kind: 'Ingress',
+    metadata: {
+      name: cfg.name,
+      namespace: cfg.namespace,
+      labels: { app: cfg.name, 'localctl.dev/managed': 'true' },
+      annotations: {
+        'traefik.ingress.kubernetes.io/router.entrypoints': cfg.tls ? 'websecure' : 'web',
+      },
+    },
+    spec: {
+      rules: [
+        {
+          host,
+          http: {
+            paths: [
+              {
+                path: '/',
+                pathType: 'Prefix',
+                backend: { service: { name: cfg.name, port: { number: cfg.port } } },
+              },
+            ],
+          },
+        },
+      ],
+    },
+  };
+  // Empty secretName: Traefik falls back to the cluster's default TLSStore certificate
+  // (the *.local.test cert installed by bin/bootstrap.sh / bootstrap.ps1).
+  if (cfg.tls) ingress.spec.tls = [{ hosts: [host] }];
+  return ingress;
+}
+
+// Every addon type is a folder named <type>/addon.yaml, found in your own addons dir
+// (~/.localctl/addons, or $LOCALCTL_ADDONS_DIR) if present, else the ones bundled with this CLI
+// (see docs/adding-tools.md) - there's no hardcoded list to keep in sync, dropping in a new folder
+// is enough to make a new dependency type usable, and a name in your own dir overrides a built-in
+// one of the same name.
+function knownAddonTypes() {
+  return listAddonNames();
+}
+
+function generateManifests(cfg) {
+  const literalEnv = { ...cfg.env };
+  const secretEnv = {}; // envVarName -> { secret, key }
+  const addonYamls = [];
+  const initContainers = [];
+
+  for (const dep of cfg.dependencies) {
+    const addonDir = findAddonDir(dep.type);
+    if (!addonDir) {
+      throw new Error(
+        `Unknown dependency type "${dep.type}" (no addon.yaml found for it in ~/.localctl/addons ` +
+        `or the CLI's built-in addons). Known types: ${knownAddonTypes().join(', ')}. See ` +
+        'docs/adding-tools.md to add a new one.',
+      );
+    }
+    const release = `${cfg.name}-${dep.type}`;
+    const { manifestYaml, env, envFromSecret, connect } = loadAddon(addonDir, {
+      release,
+      namespace: cfg.namespace,
+      addonName: dep.type,
+      owner: cfg.name,
+      chartVersionOverride: dep.version,
+      extraVars: {
+        database: dep.database || cfg.name,
+        storage: dep.storage || '1Gi',
+      },
+    });
+    addonYamls.push(manifestYaml);
+    Object.assign(literalEnv, env);
+    Object.assign(secretEnv, envFromSecret);
+    if (connect) initContainers.push(buildWaitInitContainer(dep.type, connect));
+  }
+  // cfg.env (what the developer explicitly set) always wins over an addon's auto-injected default.
+  Object.assign(literalEnv, cfg.env);
+
+  // Your own secrets (API keys, third-party tokens - not addon-generated credentials): declared by
+  // name only in config, values set separately via `localctl app secrets set`, injected the same
+  // never-plaintext way as an addon's. configSchema.js already rejects a key appearing in both
+  // "env" and "secrets", so no collision to resolve here.
+  for (const key of cfg.secrets) {
+    secretEnv[key] = { secret: secretNameFor(cfg), key };
+  }
+
+  const envVars = [
+    ...Object.entries(literalEnv).map(([name, value]) => ({ name, value: String(value) })),
+    ...Object.entries(secretEnv).map(([name, ref]) => ({
+      name,
+      valueFrom: { secretKeyRef: { name: ref.secret, key: ref.key } },
+    })),
+  ];
+
+  const docs = [buildNamespace(cfg), buildDeployment(cfg, envVars, initContainers), buildService(cfg), buildIngress(cfg)];
+  const rendered = docs.map((d) => yaml.dump(d)).join('---\n');
+  // trimEnd() before joining: addon YAML doesn't reliably end with a trailing newline (see
+  // addonLoader.js), and joining on a bare '---\n' in that case glues the separator directly onto
+  // the previous piece's last line with no line break, corrupting the YAML.
+  return [rendered, ...addonYamls].map((doc) => doc.trimEnd()).join('\n---\n');
+}
+
+module.exports = { generateManifests, knownAddonTypes };

package/src/lib/paths.js

@@ -0,0 +1,41 @@
+const path = require('path');
+const os = require('os');
+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');
+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');
+
+function ensureHomeState() {
+  if (!fs.existsSync(HOME_STATE_DIR)) fs.mkdirSync(HOME_STATE_DIR, { recursive: true });
+  if (!fs.existsSync(APPS_REGISTRY_PATH)) fs.writeFileSync(APPS_REGISTRY_PATH, '{}');
+}
+
+// One {pidFile, portFile, logFile} set per app name, used by `localctl up` (detached mode),
+// `localctl down`, and `localctl reload` to track/clean up/talk to a background Tilt process.
+// portFile holds the random port that app's Tilt instance's web/API server is bound to (each app
+// gets its own - see up.js/getFreePort), needed to address it with `tilt trigger --port <n>`.
+function runFiles(name) {
+  if (!fs.existsSync(RUN_DIR)) fs.mkdirSync(RUN_DIR, { recursive: true });
+  return {
+    pidFile: path.join(RUN_DIR, `${name}.pid`),
+    portFile: path.join(RUN_DIR, `${name}.port`),
+    logFile: path.join(RUN_DIR, `${name}.log`),
+  };
+}
+
+module.exports = {
+  APP_DIR,
+  LOCAL_DIR,
+  CONFIG_PATH,
+  HOME_STATE_DIR,
+  APPS_REGISTRY_PATH,
+  PROFILES_PATH,
+  RUN_DIR,
+  ensureHomeState,
+  runFiles,
+};

package/src/lib/podman.js

@@ -0,0 +1,72 @@
+const { run, capture } = require('./exec');
+const logger = require('./logger');
+
+const CONF_PATH = '/etc/containers/registries.conf.d/999-local-dev.conf';
+
+function machineName() {
+  const res = capture('podman', ['machine', 'list', '--format', '{{.Name}}']);
+  const [first] = res.stdout.split('\n').filter(Boolean);
+  return first || null;
+}
+
+function registryBlock(hostPort) {
+  return [
+    '[[registry]]',
+    `location = "localhost:${hostPort}"`,
+    'insecure = true',
+    '',
+    '[[registry]]',
+    `location = "127.0.0.1:${hostPort}"`,
+    'insecure = true',
+    '',
+  ].join('\n');
+}
+
+// Podman's daemon runs inside a lightweight VM on macOS/Windows - registries.conf lives inside
+// that VM, not on the host, so a host-side config file can't mark our (deliberately TLS-less)
+// local registry as insecure. Done before the cluster/registry even exist, because applying it
+// needs a VM restart, which would otherwise kill and require restarting every container already
+// running.
+//
+// Appends this port's block to whatever's already there instead of overwriting the file: a
+// second Main project (its own registry port) provisioned after the first would otherwise replace
+// the first project's trust entry outright, silently breaking its push access the next time
+// something tried to use it. One file, one block per port ever provisioned on this machine.
+function ensureInsecureRegistry(hostPort) {
+  const machine = machineName();
+  if (!machine) return;
+
+  const current = capture('podman', ['machine', 'ssh', machine, `cat ${CONF_PATH} 2>/dev/null`]).stdout;
+  if (current.includes(`location = "localhost:${hostPort}"`)) {
+    logger.success(`Podman VM already trusts localhost:${hostPort} as an insecure registry`);
+    return;
+  }
+
+  const next = `${current.trimEnd()}\n\n${registryBlock(hostPort)}`.trim().concat('\n');
+  logger.step(`Marking localhost:${hostPort} as an insecure registry inside the Podman VM...`);
+  run('podman', ['machine', 'ssh', machine, 'sudo mkdir -p /etc/containers/registries.conf.d']);
+  run('podman', ['machine', 'ssh', machine, `sudo tee ${CONF_PATH} > /dev/null`], {
+    stdio: ['pipe', 'inherit', 'inherit'],
+    input: next,
+  });
+  logger.step('Restarting Podman machine to apply...');
+  run('podman', ['machine', 'stop', machine], { stdio: 'ignore' });
+  run('podman', ['machine', 'start', machine], { stdio: 'ignore' });
+  logger.success('Podman machine restarted');
+}
+
+function teardownInsecureRegistry() {
+  const machine = machineName();
+  if (!machine) return;
+
+  const exists = capture('podman', ['machine', 'ssh', machine, `test -f ${CONF_PATH} && echo yes`]).stdout;
+  if (exists.trim() !== 'yes') return;
+
+  logger.step('Removing insecure-registry config from the Podman VM...');
+  run('podman', ['machine', 'ssh', machine, `sudo rm -f ${CONF_PATH}`], { stdio: 'ignore', allowFail: true });
+  run('podman', ['machine', 'stop', machine], { stdio: 'ignore', allowFail: true });
+  run('podman', ['machine', 'start', machine], { stdio: 'ignore', allowFail: true });
+  logger.success('Podman VM config removed and machine restarted');
+}
+
+module.exports = { ensureInsecureRegistry, teardownInsecureRegistry };

package/src/lib/profileStore.js

@@ -0,0 +1,134 @@
+const fs = require('fs');
+const { HOME_STATE_DIR, PROFILES_PATH } = require('./paths');
+const { DEFAULT_CLUSTER_NAME, DEFAULT_HTTP_PORT, DEFAULT_HTTPS_PORT, REGISTRY_HOST_PORT } = require('./constants');
+
+// ~/.localctl/profiles.json is the single source of truth for every project this machine knows
+// about, and which one ad-hoc/global commands (doctor, hosts, addons) currently target.
+//
+// Two kinds of profile, distinguished by `isolation`:
+//   - "cluster" (a "Main project"): owns a real, separate k3d cluster/registry - `cluster`,
+//     `exclusive`, and (for a non-exclusive one, which needs its own ports since two clusters
+//     can't both bind host :80/:443) `httpPort`/`httpsPort`/`registryPort` all live here.
+//   - "namespace" (nested under exactly one Main project via `parent`): shares that Main
+//     project's cluster/registry/cert, isolated only by a namespace + subdomain prefix
+//     (`namespace`, defaulting to its own name).
+//
+// "default" always exists - it's today's single always-there cluster, `local-dev`.
+function defaultRegistry() {
+  return {
+    active: 'default',
+    profiles: {
+      default: { isolation: 'cluster', cluster: DEFAULT_CLUSTER_NAME, exclusive: true },
+    },
+  };
+}
+
+function ensureRegistry() {
+  if (!fs.existsSync(HOME_STATE_DIR)) fs.mkdirSync(HOME_STATE_DIR, { recursive: true });
+  if (!fs.existsSync(PROFILES_PATH)) save(defaultRegistry());
+}
+
+function load() {
+  ensureRegistry();
+  return JSON.parse(fs.readFileSync(PROFILES_PATH, 'utf8'));
+}
+
+function save(data) {
+  fs.writeFileSync(PROFILES_PATH, JSON.stringify(data, null, 2));
+}
+
+function getProfile(name) {
+  return load().profiles[name] || null;
+}
+
+function upsertProfile(name, def) {
+  const data = load();
+  data.profiles[name] = def;
+  save(data);
+}
+
+function listProfiles() {
+  return load().profiles;
+}
+
+function getActive() {
+  return load().active;
+}
+
+function setActive(name) {
+  const data = load();
+  if (!data.profiles[name]) throw new Error(`Unknown profile "${name}". Run "localctl profiles list".`);
+  data.active = name;
+  save(data);
+}
+
+// Climbs `parent` links up to the Main (isolation: "cluster") project that actually owns a
+// cluster - a namespace-level project's own entry never has one.
+function mainProjectFor(name) {
+  const { profiles } = load();
+  let cur = name;
+  const seen = new Set();
+  for (;;) {
+    if (seen.has(cur)) throw new Error(`Circular "parent" chain detected starting at profile "${cur}".`);
+    seen.add(cur);
+    const def = profiles[cur];
+    if (!def) {
+      throw new Error(`Unknown profile "${cur}". Run "localctl profiles list", or "localctl profiles new ${cur}" to create it.`);
+    }
+    if (def.isolation === 'cluster') return { name: cur, def };
+    cur = def.parent;
+  }
+}
+
+function clusterNameFor(name) {
+  return mainProjectFor(name).def.cluster;
+}
+
+function portsFor(name) {
+  const { def } = mainProjectFor(name);
+  return {
+    httpPort: def.httpPort || DEFAULT_HTTP_PORT,
+    httpsPort: def.httpsPort || DEFAULT_HTTPS_PORT,
+    registryPort: def.registryPort || REGISTRY_HOST_PORT,
+  };
+}
+
+// The namespace/subdomain prefix a namespace-level project's apps get scoped under - null for a
+// Main project itself (it owns the whole cluster, nothing to prefix).
+function namespaceScopeFor(name) {
+  const def = getProfile(name);
+  if (!def) throw new Error(`Unknown profile "${name}". Run "localctl profiles list".`);
+  if (def.isolation === 'cluster') return null;
+  return def.namespace || name;
+}
+
+// Every namespace-level project nested under a given Main project, for `profiles list`.
+function childrenOf(mainName) {
+  const { profiles } = load();
+  return Object.entries(profiles)
+    .filter(([, def]) => def.isolation === 'namespace' && def.parent === mainName)
+    .map(([name]) => name);
+}
+
+function removeProfile(name) {
+  const data = load();
+  delete data.profiles[name];
+  if (data.active === name) data.active = 'default';
+  save(data);
+}
+
+module.exports = {
+  load,
+  save,
+  getProfile,
+  upsertProfile,
+  removeProfile,
+  listProfiles,
+  getActive,
+  setActive,
+  mainProjectFor,
+  clusterNameFor,
+  portsFor,
+  namespaceScopeFor,
+  childrenOf,
+};