@localctl/cli 0.2.0

package/src/lib/addons/cluster/logging/addon.yaml

@@ -0,0 +1,46 @@
+# Cluster-wide logging addon - deploys Grafana Labs' own official loki-stack chart (Loki +
+# Promtail + Grafana, all in one). Enabled via `localctl addons enable logging`.
+#
+# `config` demonstrates the addon config/ folder feature: any file dropped in ./config/ becomes a
+# ConfigMap ("<release>-config"), and {{configMapName}} below wires it in as a Grafana dashboard.
+# See docs/adding-tools.md.
+
+chart:
+  repo: https://grafana.github.io/helm-charts
+  name: loki-stack
+  version: "2.10.3"
+
+config: true
+
+values: |
+  loki:
+    enabled: true
+  promtail:
+    enabled: true
+  grafana:
+    enabled: true
+    adminUser: admin
+    dashboardProviders:
+      dashboardproviders.yaml:
+        apiVersion: 1
+        providers:
+          - name: default
+            orgId: 1
+            folder: ""
+            type: file
+            disableDeletion: false
+            editable: true
+            options:
+              path: /var/lib/grafana/dashboards/default
+    dashboardsConfigMaps:
+      default: "{{configMapName}}"
+    ingress:
+      enabled: true
+      ingressClassName: traefik
+      annotations:
+        traefik.ingress.kubernetes.io/router.entrypoints: web,websecure
+      hosts:
+        - "grafana.{{domain}}"
+      tls:
+        - hosts:
+            - "grafana.{{domain}}"

package/src/lib/addons/cluster/logging/config/all-logs.json

@@ -0,0 +1,21 @@
+{
+  "title": "All Logs",
+  "uid": "localctl-all-logs",
+  "schemaVersion": 39,
+  "timezone": "browser",
+  "time": { "from": "now-1h", "to": "now" },
+  "panels": [
+    {
+      "type": "logs",
+      "title": "Every pod, every namespace",
+      "gridPos": { "h": 20, "w": 24, "x": 0, "y": 0 },
+      "datasource": { "type": "loki", "uid": "Loki" },
+      "targets": [
+        {
+          "expr": "{namespace=~\".+\"}",
+          "refId": "A"
+        }
+      ]
+    }
+  ]
+}

package/src/lib/addons/cluster/monitoring/addon.yaml

@@ -0,0 +1,33 @@
+# Cluster-wide metrics addon - deploys the real prometheus-community Prometheus chart (server +
+# kube-state-metrics + node-exporter). Enabled via `localctl addons enable monitoring`.
+#
+# No bundled Grafana here (the `logging` addon already brings one) - point it at this Prometheus
+# instance yourself as a datasource if you want dashboards
+# (http://monitoring-prometheus-server.observability.svc.cluster.local - the chart's own Service
+# name, check `kubectl get svc -n observability` if it ever renames itself in a future chart
+# version rather than trusting this comment). Keeping the two addons independent means either
+# works without the other.
+
+chart:
+  repo: https://prometheus-community.github.io/helm-charts
+  name: prometheus
+  version: "29.34.0"
+
+values: |
+  alertmanager:
+    enabled: false
+  prometheus-pushgateway:
+    enabled: false
+  server:
+    persistentVolume:
+      size: 2Gi
+    ingress:
+      enabled: true
+      ingressClassName: traefik
+      annotations:
+        traefik.ingress.kubernetes.io/router.entrypoints: web,websecure
+      hosts:
+        - "monitoring.{{domain}}"
+      tls:
+        - hosts:
+            - "monitoring.{{domain}}"

package/src/lib/addons/mongo/addon.yaml

@@ -0,0 +1,18 @@
+# Mongo addon - deploys the real Bitnami MongoDB chart. Auth disabled by default, matching this
+# addon's old behavior (local dev only, not meant to hold anything sensitive) - set auth.enabled
+# and add a secrets/envFromSecret block here (see postgres/addon.yaml) if you want it.
+
+chart:
+  repo: https://charts.bitnami.com/bitnami
+  name: mongodb
+  version: "19.3.1"
+
+env:
+  MONGO_HOST: "{{serviceHost}}"
+  MONGO_PORT: "27017"
+
+values: |
+  auth:
+    enabled: false
+  persistence:
+    size: "{{storage}}"

package/src/lib/addons/postgres/addon.yaml

@@ -0,0 +1,39 @@
+# Postgres addon - deploys the real Bitnami PostgreSQL chart, configured for local dev.
+# See docs/adding-tools.md for the full addon.yaml reference.
+
+chart:
+  repo: https://charts.bitnami.com/bitnami
+  name: postgresql
+  version: "18.12.2"
+
+# Generates a random value once per key, stored as a real k8s Secret named "<release>-secret" -
+# never written to disk, never in this file. {{secretName}} below refers to that Secret's name.
+secrets:
+  password:
+    length: 20
+
+# Plain env vars injected into the app's own container automatically.
+env:
+  POSTGRES_HOST: "{{serviceHost}}"
+  POSTGRES_PORT: "5432"
+  POSTGRES_DB: "{{database}}"
+  POSTGRES_USER: "localdev"
+
+# Unlike `env`, these become a real secretKeyRef - the password itself never passes through a
+# plaintext value anywhere in this pipeline.
+envFromSecret:
+  POSTGRES_PASSWORD:
+    secret: "{{secretName}}"
+    key: password
+
+# Passed to `helm template` as -f values.yaml. {{...}} is substituted first: {{database}}/
+# {{storage}}/{{version}} come from the app's own .local/config.json dependency entry (with
+# fallback defaults), {{secretName}} from the generated Secret above.
+values: |
+  auth:
+    username: localdev
+    database: "{{database}}"
+    existingSecret: "{{secretName}}"
+  primary:
+    persistence:
+      size: "{{storage}}"

package/src/lib/addons/redis/addon.yaml

@@ -0,0 +1,29 @@
+# Redis addon - deploys the real Bitnami Redis chart, configured for local dev (standalone, no
+# replicas). See docs/adding-tools.md for the full addon.yaml reference.
+
+chart:
+  repo: https://charts.bitnami.com/bitnami
+  name: redis
+  version: "28.2.4"
+
+secrets:
+  password:
+    length: 20
+
+env:
+  REDIS_HOST: "{{serviceHost}}"
+  REDIS_PORT: "6379"
+
+envFromSecret:
+  REDIS_PASSWORD:
+    secret: "{{secretName}}"
+    key: password
+
+values: |
+  architecture: standalone
+  auth:
+    existingSecret: "{{secretName}}"
+    existingSecretPasswordKey: password
+  master:
+    persistence:
+      size: "{{storage}}"

package/src/lib/appSecrets.js

@@ -0,0 +1,60 @@
+const { run, capture } = require('./exec');
+
+// One Secret per app, holding whatever keys `.local/config.json`'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.
+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 });
+  }
+}
+
+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) });
+}
+
+function setSecret(cfg, key, value) {
+  const data = readAll(cfg);
+  data[key] = value;
+  writeAll(cfg, data);
+}
+
+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;
+}
+
+function listKeys(cfg) {
+  return Object.keys(readAll(cfg));
+}
+
+module.exports = { secretNameFor, setSecret, unsetSecret, listKeys, readAll };

package/src/lib/clusterAddons.js

@@ -0,0 +1,59 @@
+const { run } = require('./exec');
+const { loadAddon } = require('./addonLoader');
+const { findAddonDir, listAddonNames } = require('./addonDirs');
+const { getList, workloadsWithPrefix } = require('./workloadReadiness');
+const { DOMAIN, OBSERVABILITY_NAMESPACE } = require('./constants');
+const ui = require('./ui');
+
+// Cluster-wide addons live at <addons-dir>/cluster/<name>/addon.yaml - your own addons dir
+// (~/.localctl/addons, or $LOCALCTL_ADDONS_DIR) is searched before the ones bundled with this
+// CLI, and a name there overrides a built-in one of the same name. See docs/adding-tools.md.
+// Shared by `localctl addons` and `localctl profiles new`'s "carry over which addons?" wizard.
+function addonDirFor(name) {
+  const dir = findAddonDir(name, 'cluster');
+  if (!dir) {
+    throw new Error(`Unknown addon "${name}". Known: ${listAddonNames('cluster').join(', ')}.`);
+  }
+  return dir;
+}
+
+function renderClusterAddon(name) {
+  const { manifestYaml } = loadAddon(addonDirFor(name), {
+    release: name,
+    namespace: OBSERVABILITY_NAMESPACE,
+    addonName: name,
+    extraVars: { domain: DOMAIN },
+  });
+  return manifestYaml;
+}
+
+function enableClusterAddon(name) {
+  run('kubectl', ['apply', '-f', '-'], { stdio: ['pipe', 'inherit', 'inherit'], input: renderClusterAddon(name) });
+}
+
+function disableClusterAddon(name) {
+  run('kubectl', ['delete', '-f', '-', '--ignore-not-found=true'], { stdio: ['pipe', 'inherit', 'inherit'], input: renderClusterAddon(name) });
+}
+
+function readyLabel(workloads) {
+  if (workloads.length === 0) return ui.dim('-');
+  const ready = workloads.reduce((sum, w) => sum + w.ready, 0);
+  const desired = workloads.reduce((sum, w) => sum + w.desired, 0);
+  return ui.readyLabel(ready, desired);
+}
+
+function clusterAddonInstances() {
+  const records = getList(['get', 'configmap', '-A', '-l', 'localctl.dev/addon=true']);
+  return records.map((r) => {
+    const release = r.metadata.name.replace(/-localctl-addon$/, '');
+    return {
+      release,
+      owner: r.data.owner || null,
+      namespace: r.metadata.namespace,
+      chart: `${r.data.chart}@${r.data.version}`,
+      ready: readyLabel(workloadsWithPrefix(r.metadata.namespace, release)),
+    };
+  });
+}
+
+module.exports = { renderClusterAddon, enableClusterAddon, disableClusterAddon, clusterAddonInstances };

package/src/lib/clusterProvision.js

@@ -0,0 +1,170 @@
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const { run, capture, sleepSync, commandExists } = require('./exec');
+const { detectEngine } = require('./engine');
+const { installIfMissing } = require('./toolInstall');
+const { ensureInsecureRegistry } = require('./podman');
+const { DOMAIN } = require('./constants');
+const logger = require('./logger');
+
+// 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.
+const BUNDLED_MANIFESTS_DIR = path.resolve(__dirname, '..', '..', 'assets', 'manifests');
+const MANIFESTS_DIR = fs.existsSync(BUNDLED_MANIFESTS_DIR)
+  ? BUNDLED_MANIFESTS_DIR
+  : path.resolve(__dirname, '..', '..', '..', 'cluster', 'manifests');
+
+function registryNameFor(clusterName) {
+  return `${clusterName}-registry`;
+}
+
+function clusterExists(clusterName) {
+  return capture('k3d', ['cluster', 'list']).stdout
+    .split('\n')
+    .map((line) => line.trim().split(/\s+/)[0])
+    .includes(clusterName);
+}
+
+// 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 }) {
+  logger.step('Detecting container engine...');
+  const detected = detectEngine();
+  if (!detected) {
+    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)`);
+
+  // Podman-specific, and must happen before the cluster/registry exist - see lib/podman.js. The
+  // insecure-registry trust is VM-wide, so it only needs doing once no matter how many clusters
+  // exist, but re-running it per registry port is cheap and idempotent.
+  if (engine === 'podman') {
+    ensureInsecureRegistry(registryPort);
+  }
+
+  installIfMissing('k3d', 'k3d', 'k3d-io.k3d');
+  installIfMissing('kubectl', 'kubernetes-cli', 'Kubernetes.kubectl');
+  installIfMissing('tilt', 'tilt', 'Tilt.dev.tilt');
+  installIfMissing('mkcert', 'mkcert', 'FiloSottile.mkcert');
+  installIfMissing('helm', 'helm', 'Helm.Helm');
+
+  const registryName = registryNameFor(clusterName);
+
+  if (clusterExists(clusterName)) {
+    logger.success(`k3d cluster '${clusterName}' already exists`);
+  } else {
+    logger.step(`Creating k3d cluster '${clusterName}'...`);
+    // 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');
+  }
+  run('kubectl', ['config', 'use-context', `k3d-${clusterName}`], { stdio: 'ignore' });
+
+  const registryNetwork = `k3d-${clusterName}`;
+  const existingNames = capture(engineBin, ['ps', '-a', '--format', '{{.Names}}']).stdout.split('\n');
+  if (existingNames.includes(registryName)) {
+    logger.success('Registry container already exists');
+    run(engineBin, ['start', registryName], { stdio: 'ignore', allowFail: true });
+  } else {
+    logger.step('Starting local image registry...');
+    run(engineBin, [
+      'run', '-d',
+      '--name', registryName,
+      '--network', registryNetwork,
+      '-p', `0.0.0.0:${registryPort}:5000`,
+      '--restart=always',
+      'registry:2',
+    ]);
+    logger.success(`Registry running at localhost:${registryPort} (in-cluster name: ${registryName}:5000)`);
+  }
+
+  // TLS via mkcert - one *.local.test cert/key, shared across every cluster (it's the same
+  // domain everywhere; only the namespace/subdomain prefix or the cluster differs).
+  logger.step(`Setting up local TLS for *.${DOMAIN}...`);
+  run('mkcert', ['-install']);
+  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');
+  if (!fs.existsSync(certFile) || !fs.existsSync(keyFile)) {
+    run('mkcert', ['-cert-file', certFile, '-key-file', keyFile, `*.${DOMAIN}`, DOMAIN]);
+  }
+
+  const secretYaml = capture('kubectl', [
+    'create', 'secret', 'tls', 'local-dev-tls',
+    `--cert=${certFile}`, `--key=${keyFile}`,
+    '-n', 'kube-system', '--dry-run=client', '-o', 'yaml',
+  ]).stdout;
+  run('kubectl', ['apply', '-f', '-'], { stdio: ['pipe', 'inherit', 'inherit'], input: secretYaml });
+
+  // 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.
+  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');
+}
+
+// Reverses provisionCluster() for one Main project: deletes its cluster, registry container,
+// network, and image volume. Does NOT touch the Podman VM's insecure-registry trust (that's
+// VM-wide, torn down once by `localctl uninstall`, not per-cluster) or *.local.test hosts/certs
+// (shared across every cluster).
+function teardownCluster(clusterName) {
+  if (commandExists('k3d')) {
+    logger.step(`Deleting k3d cluster '${clusterName}'...`);
+    run('k3d', ['cluster', 'delete', clusterName], { allowFail: true });
+  }
+  const detected = detectEngine();
+  if (detected) {
+    const { bin: engineBin } = detected;
+    run(engineBin, ['rm', '-f', '-v', registryNameFor(clusterName)], { stdio: 'ignore', allowFail: true });
+    run(engineBin, ['network', 'rm', `k3d-${clusterName}`], { stdio: 'ignore', allowFail: true });
+    run(engineBin, ['volume', 'rm', `k3d-${clusterName}-images`], { stdio: 'ignore', allowFail: true });
+  }
+}
+
+// Throws with the exact fix command if `clusterName` isn't up yet, otherwise points kubectl at
+// it. Called by every app-scoped command before it does anything else, so "cd in and run a
+// command" fails with a clear instruction instead of a confusing kubectl error further down.
+function ensureClusterUp(clusterName, profileName) {
+  if (!clusterExists(clusterName)) {
+    const fix = profileName === 'default' ? 'localctl setup' : `localctl profiles switch ${profileName}`;
+    throw new Error(`No cluster running for project "${profileName}". Run "${fix}" to start it.`);
+  }
+  run('kubectl', ['config', 'use-context', `k3d-${clusterName}`], { stdio: 'ignore' });
+}
+
+module.exports = { provisionCluster, teardownCluster, clusterExists, registryNameFor, ensureClusterUp };

package/src/lib/configSchema.js

@@ -0,0 +1,103 @@
+const { z } = require('zod');
+const { knownAddonTypes } = require('./manifestGen');
+
+// Dependency types are discovered from cli/src/lib/addons/<type>/addon.yaml (see
+// docs/adding-tools.md) rather than hardcoded here - dropping in a new addon folder is enough to
+// make it usable, no code change needed.
+const dependencySchema = z.object({
+  type: z.enum(knownAddonTypes()),
+  version: z.string().optional(),
+  database: z.string().optional(),
+  storage: z.string().optional(),
+});
+
+const debugSchema = z
+  .object({
+    enabled: z.boolean().default(false),
+    port: z.number().int().optional(),
+    type: z.enum(['node', 'python', 'go', 'java', 'dotnet']).optional(),
+  })
+  .default({ enabled: false });
+
+const syncEntrySchema = z.object({
+  localPath: z.string(),
+  remotePath: z.string(),
+});
+
+// An extra container in the same pod as your app - the classic k8s sidecar pattern (a DB admin
+// UI next to a database, a log/metrics shipper, a background job runner next to a web app). It
+// shares the pod's network namespace with your app automatically - no Service needed for your app
+// to reach it, just `localhost:<port>`. See docs/config-schema.md for a worked example.
+const sidecarSchema = z.object({
+  name: z.string().regex(/^[a-z0-9-]+$/, 'must be lowercase alphanumeric + dashes only'),
+  image: z.string(),
+  port: z.number().int().optional(),
+  command: z.array(z.string()).optional(),
+  args: z.array(z.string()).optional(),
+  env: z.record(z.string()).default({}),
+});
+
+const resourceSpec = z
+  .object({
+    cpu: z.string().optional(),
+    memory: z.string().optional(),
+  })
+  .optional();
+
+// A single probe - defaults to a plain TCP check on the app's own `port` if `path` isn't given
+// (see buildProbe() in manifestGen.js). Applies to the main app container only.
+const probeSchema = z.object({
+  path: z.string().optional(),
+  initialDelaySeconds: z.number().int().optional(),
+  periodSeconds: z.number().int().optional(),
+});
+
+const probesSchema = z
+  .object({
+    readiness: probeSchema.optional(),
+    liveness: probeSchema.optional(),
+  })
+  .default({});
+
+const appConfigSchema = z
+  .object({
+    name: z
+      .string()
+      .regex(/^[a-z0-9-]+$/, 'must be lowercase alphanumeric + dashes only'),
+    subdomain: z.string().regex(/^[a-z0-9-]+$/).optional(),
+    namespace: z.string().optional(),
+    port: z.number().int(),
+    build: z.object({
+      context: z.string().default('.'),
+      dockerfile: z.string().default('Dockerfile'),
+    }),
+    env: z.record(z.string()).default({}),
+    // Names only - values never live here. Set with `localctl app secrets set <KEY>`, which
+    // stores the value once as a real k8s Secret and injects it via secretKeyRef, the same
+    // never-plaintext principle addon-provided credentials already follow.
+    secrets: z
+      .array(z.string().regex(/^[A-Z][A-Z0-9_]*$/, 'must be UPPER_SNAKE_CASE'))
+      .default([]),
+    replicas: z.number().int().min(1).default(1),
+    resources: z
+      .object({ requests: resourceSpec, limits: resourceSpec })
+      .optional(),
+    debug: debugSchema,
+    probes: probesSchema,
+    dependencies: z.array(dependencySchema).default([]),
+    sidecars: z.array(sidecarSchema).default([]),
+    sync: z.array(syncEntrySchema).default([]),
+    tls: z.boolean().default(true),
+  })
+  .superRefine((cfg, ctx) => {
+    const overlap = cfg.secrets.filter((key) => key in cfg.env);
+    if (overlap.length > 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['secrets'],
+        message: `${overlap.join(', ')} can't be in both "env" and "secrets" - pick one.`,
+      });
+    }
+  });
+
+module.exports = { appConfigSchema };

package/src/lib/constants.js

@@ -0,0 +1,16 @@
+module.exports = {
+  // The "default" profile's cluster name - the single cluster this whole tool managed before
+  // multi-project support existed. Other Main-level projects get their own `local-dev-<name>`
+  // cluster (see profileStore.js).
+  DEFAULT_CLUSTER_NAME: 'local-dev',
+  DEFAULT_HTTP_PORT: 80,
+  DEFAULT_HTTPS_PORT: 443,
+  // .test (RFC 2606) is reserved for testing and guaranteed to never resolve publicly or be
+  // HSTS-preloaded. Not .dev: it's a real, live gTLD (Google-operated) that's HSTS-preloaded at
+  // the TLD level - every browser force-HTTPS's *any* .dev domain, including made-up ones, with
+  // no way to click through a self-signed cert warning, and "local.dev" itself is registered by
+  // an unrelated third party.
+  DOMAIN: 'local.test',
+  REGISTRY_HOST_PORT: '5050',
+  OBSERVABILITY_NAMESPACE: 'observability',
+};

package/src/lib/engine.js

@@ -0,0 +1,20 @@
+const { commandExists, capture } = require('./exec');
+
+// Returns { engine, bin } - `engine` names what's actually running (docker/podman/rancher-desktop),
+// `bin` is the CLI to drive it with (usually the same, except Rancher Desktop, which exposes
+// docker or nerdctl depending on how it's configured). Returns null if nothing usable is found.
+function detectEngine() {
+  if (commandExists('docker') && capture('docker', ['info']).status === 0) {
+    return { engine: 'docker', bin: 'docker' };
+  }
+  if (commandExists('podman') && capture('podman', ['info']).status === 0) {
+    return { engine: 'podman', bin: 'podman' };
+  }
+  if (commandExists('rdctl')) {
+    if (commandExists('docker')) return { engine: 'rancher-desktop', bin: 'docker' };
+    if (commandExists('nerdctl')) return { engine: 'rancher-desktop', bin: 'nerdctl' };
+  }
+  return null;
+}
+
+module.exports = { detectEngine };