@localctl/cli 0.2.0

package/src/commands/addons.js

@@ -0,0 +1,56 @@
+const { listAddonNames } = require('../lib/addonDirs');
+const { enableClusterAddon, disableClusterAddon, clusterAddonInstances } = require('../lib/clusterAddons');
+const { ensureClusterUp } = require('../lib/clusterProvision');
+const { getActive, clusterNameFor } = require('../lib/profileStore');
+const ui = require('../lib/ui');
+const logger = require('../lib/logger');
+
+// Cluster-wide addons apply to whichever project is currently active (see "localctl profiles
+// switch") - there's no per-app directory to resolve one from, unlike `app` commands.
+function ensureActiveClusterUp() {
+  const active = getActive();
+  ensureClusterUp(clusterNameFor(active), active);
+}
+
+module.exports = (program) => {
+  const addons = program.command('addons').description('Manage cluster-wide addons (logging, etc.) in the active project');
+
+  addons
+    .command('list')
+    .description('List available cluster-wide addons')
+    .action(() => {
+      listAddonNames('cluster').forEach((n) => console.log(n));
+    });
+
+  addons
+    .command('enable <name>')
+    .description('Enable a cluster-wide addon')
+    .action((name) => {
+      ensureActiveClusterUp();
+      enableClusterAddon(name);
+      logger.success(`Addon "${name}" applied.`);
+    });
+
+  addons
+    .command('disable <name>')
+    .description('Remove a cluster-wide addon')
+    .action((name) => {
+      ensureActiveClusterUp();
+      disableClusterAddon(name);
+      logger.success(`Addon "${name}" removed.`);
+    });
+
+  addons
+    .command('status')
+    .description('Show every addon instance in the cluster - infrastructure helpers, separate from your apps')
+    .action(() => {
+      ensureActiveClusterUp();
+      const records = clusterAddonInstances();
+      if (records.length === 0) {
+        logger.info('No addon instances found in the cluster.');
+        return;
+      }
+      const rows = records.map((r) => [r.release, r.owner || ui.dim('(cluster-wide)'), r.namespace, r.chart, r.ready]);
+      ui.printTable(['ADDON', 'OWNER', 'NAMESPACE', 'CHART', 'READY'], rows);
+    });
+};

package/src/commands/doctor.js

@@ -0,0 +1,43 @@
+const { commandExists, capture } = require('../lib/exec');
+const { detectEngine } = require('../lib/engine');
+const { getActive, clusterNameFor } = require('../lib/profileStore');
+const ui = require('../lib/ui');
+const logger = require('../lib/logger');
+
+function check(label, fn) {
+  try {
+    const passed = fn();
+    console.log(`  ${passed ? ui.check : ui.cross} ${label}`);
+    return passed;
+  } catch (e) {
+    console.log(`  ${ui.cross} ${label} - ${ui.dim(e.message)}`);
+    return false;
+  }
+}
+
+module.exports = (program) => {
+  program
+    .command('doctor')
+    .description('Check the local environment for missing/broken pieces')
+    .action(() => {
+      logger.step('Checking environment...');
+      const detected = detectEngine();
+      check(`container engine available${detected ? ` (${detected.engine})` : ''}`, () => Boolean(detected));
+      if (detected && detected.engine === 'podman') {
+        logger.info('Podman detected: "localctl app up" will disable BuildKit automatically for image builds.');
+      }
+      check('k3d installed', () => commandExists('k3d'));
+      check('kubectl installed', () => commandExists('kubectl'));
+      check('tilt installed', () => commandExists('tilt'));
+      check('mkcert installed', () => commandExists('mkcert'));
+      check('helm installed', () => commandExists('helm'));
+      const active = getActive();
+      const activeCluster = clusterNameFor(active);
+      check(`active project's cluster exists ("${active}" -> ${activeCluster})`, () => {
+        const res = capture('k3d', ['cluster', 'list']);
+        return res.stdout.split('\n').some((line) => line.trim().split(/\s+/)[0] === activeCluster);
+      });
+      check('kubectl context reachable', () => capture('kubectl', ['cluster-info']).status === 0);
+      logger.step(`Fix any ${ui.cross} above, or run "localctl setup" (or "localctl profiles switch ${active}" for a non-default project) to (re)install/repair.`);
+    });
+};

package/src/commands/down.js

@@ -0,0 +1,35 @@
+const fs = require('fs');
+const { loadConfig } = require('../lib/loadConfig');
+const { run, isRunning, sleepSync } = require('../lib/exec');
+const { ensureClusterUp } = require('../lib/clusterProvision');
+const { runFiles } = require('../lib/paths');
+const logger = require('../lib/logger');
+
+module.exports = (program) => {
+  program
+    .command('down')
+    .description('Tear down the app deployed from the current directory (runs "tilt down")')
+    .action(() => {
+      const cfg = loadConfig();
+      ensureClusterUp(cfg.clusterName, cfg.profile);
+      const { pidFile, portFile, logFile } = runFiles(cfg.name);
+
+      // If `localctl up` started a detached Tilt process for this app, it needs to be stopped
+      // first - otherwise it keeps live-syncing/reconciling against resources `tilt down` is
+      // about to delete out from under it.
+      if (fs.existsSync(pidFile)) {
+        const pid = parseInt(fs.readFileSync(pidFile, 'utf8'), 10);
+        if (Number.isFinite(pid) && isRunning(pid)) {
+          logger.step(`Stopping background Tilt process (pid ${pid})...`);
+          process.kill(pid, 'SIGTERM');
+          for (let i = 0; i < 20 && isRunning(pid); i += 1) sleepSync(250);
+        }
+        fs.rmSync(pidFile, { force: true });
+      }
+      fs.rmSync(portFile, { force: true });
+      fs.rmSync(logFile, { force: true });
+
+      run('tilt', ['down']);
+      logger.success(`"${cfg.name}" torn down. Run "localctl hosts sync" if you want to clean up its subdomain too.`);
+    });
+};

package/src/commands/exec.js

@@ -0,0 +1,15 @@
+const { loadConfig } = require('../lib/loadConfig');
+const { ensureClusterUp } = require('../lib/clusterProvision');
+const { run } = require('../lib/exec');
+
+module.exports = (program) => {
+  program
+    .command('exec [cmd...]')
+    .description('Shell into the running app\'s pod (kubectl exec) - defaults to "sh" if no command is given')
+    .action((cmd) => {
+      const cfg = loadConfig();
+      ensureClusterUp(cfg.clusterName, cfg.profile);
+      const command = cmd && cmd.length ? cmd : ['sh'];
+      run('kubectl', ['exec', '-it', `deploy/${cfg.name}`, '-n', cfg.namespace, '--', ...command]);
+    });
+};

package/src/commands/generateManifests.js

@@ -0,0 +1,12 @@
+const { loadConfig } = require('../lib/loadConfig');
+const { generateManifests } = require('../lib/manifestGen');
+
+module.exports = (program) => {
+  program
+    .command('generate-manifests')
+    .description('[internal, called by Tiltfile] Render k8s manifests for the app in the current directory to stdout')
+    .action(() => {
+      const cfg = loadConfig();
+      process.stdout.write(generateManifests(cfg));
+    });
+};

package/src/commands/hosts.js

@@ -0,0 +1,23 @@
+const { syncHosts, clearHosts, listApps } = require('../lib/hostsFile');
+const { DOMAIN } = require('../lib/constants');
+
+module.exports = (program) => {
+  const hosts = program.command('hosts').description(`Manage local hosts file entries for *.${DOMAIN} apps`);
+
+  hosts
+    .command('sync')
+    .description('Sync the hosts file with all registered app subdomains')
+    .action(() => syncHosts());
+
+  hosts
+    .command('list')
+    .description('List registered subdomains')
+    .action(() => {
+      listApps().forEach((s) => console.log(`${s}.${DOMAIN}`));
+    });
+
+  hosts
+    .command('clear')
+    .description(`[used by uninstall] Remove the entire managed *.${DOMAIN} block from the hosts file`)
+    .action(() => clearHosts());
+};

package/src/commands/logs.js

@@ -0,0 +1,45 @@
+const fs = require('fs');
+const { run } = require('../lib/exec');
+const { loadConfig } = require('../lib/loadConfig');
+const { ensureClusterUp } = require('../lib/clusterProvision');
+const { getActive, clusterNameFor } = require('../lib/profileStore');
+const { CONFIG_PATH } = require('../lib/paths');
+
+module.exports = (program) => {
+  program
+    .command('logs [name]')
+    .option('-n, --namespace <ns>', 'namespace override (only needed outside an app\'s own repo, or if it disagrees with what "localctl app status" shows)')
+    .option('-f, --follow', 'follow log output')
+    .description('Tail logs for a deployed app - run inside the app\'s repo to resolve it (and its project\'s namespace prefix) automatically, or pass a name')
+    .action((name, opts) => {
+      let targetName = name;
+      let namespace = opts.namespace;
+
+      if (!namespace) {
+        if (!targetName && fs.existsSync(CONFIG_PATH)) {
+          // Directory-resolved, same as `app status`/`up`/`down` - this is what a namespace-scoped
+          // project needs: its real namespace is "<scope>-<name>", not the bare app name a plain
+          // `-n <name>` default would guess.
+          const cfg = loadConfig();
+          ensureClusterUp(cfg.clusterName, cfg.profile);
+          targetName = cfg.name;
+          namespace = cfg.namespace;
+        } else if (targetName) {
+          // An explicit name from outside its own repo - no directory to resolve from, so this
+          // stays a best-effort guess (namespace = name) against the active project's cluster,
+          // same fallback `app status -a <name>` uses.
+          const active = getActive();
+          ensureClusterUp(clusterNameFor(active), active);
+          namespace = targetName;
+        }
+      }
+
+      if (!targetName) {
+        throw new Error('Run this from inside an app repo, or pass a name (localctl app logs <name>).');
+      }
+
+      const args = ['logs', `deploy/${targetName}`, '-n', namespace];
+      if (opts.follow) args.push('-f');
+      run('kubectl', args);
+    });
+};

package/src/commands/new.js

@@ -0,0 +1,55 @@
+const fs = require('fs');
+const path = require('path');
+const { askAll } = require('../lib/prompt');
+const logger = require('../lib/logger');
+
+module.exports = (program) => {
+  program
+    .command('new')
+    .description('Scaffold .local/config.json and a Tiltfile in the current app repo')
+    .action(async () => {
+      const cwd = process.cwd();
+      const localDir = path.join(cwd, '.local');
+      const configPath = path.join(localDir, 'config.json');
+
+      if (fs.existsSync(configPath)) {
+        logger.warn('.local/config.json already exists, aborting.');
+        return;
+      }
+
+      const defaultName = path.basename(cwd).toLowerCase().replace(/[^a-z0-9-]/g, '-');
+      const [name, portAnswer] = await askAll([
+        { text: 'App name', def: defaultName },
+        { text: 'App port', def: '3000' },
+      ]);
+
+      const port = parseInt(portAnswer, 10);
+
+      fs.mkdirSync(localDir, { recursive: true });
+
+      const config = {
+        $schema: '../../localctl/schema/app.schema.json',
+        name,
+        subdomain: name,
+        port,
+        build: { context: '.', dockerfile: 'Dockerfile' },
+        env: {},
+        replicas: 1,
+        debug: { enabled: false },
+        dependencies: [],
+        sync: [{ localPath: './src', remotePath: '/app/src' }],
+        tls: true,
+      };
+      fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+
+      const tiltTemplatePath = path.join(__dirname, '..', '..', 'templates', 'Tiltfile.tmpl');
+      const tiltTemplate = fs.readFileSync(tiltTemplatePath, 'utf8');
+      const tiltfilePath = path.join(cwd, 'Tiltfile');
+      if (!fs.existsSync(tiltfilePath)) {
+        fs.writeFileSync(tiltfilePath, tiltTemplate);
+      }
+
+      logger.success(`Created .local/config.json and Tiltfile for "${name}".`);
+      logger.info('Edit .local/config.json (env, dependencies, debug), then run "localctl app up".');
+    });
+};

package/src/commands/profiles.js

@@ -0,0 +1,180 @@
+const fs = require('fs');
+const path = require('path');
+const { run, getFreePort } = require('../lib/exec');
+const { provisionCluster, teardownCluster, clusterExists } = require('../lib/clusterProvision');
+const { enableClusterAddon } = require('../lib/clusterAddons');
+const {
+  getProfile, upsertProfile, listProfiles, getActive, setActive, mainProjectFor, childrenOf,
+} = require('../lib/profileStore');
+const { DEFAULT_HTTP_PORT, DEFAULT_HTTPS_PORT, REGISTRY_HOST_PORT } = require('../lib/constants');
+const { makePrompter } = require('../lib/prompt');
+const ui = require('../lib/ui');
+const logger = require('../lib/logger');
+
+// Tears down every OTHER Main project's cluster that's currently up - used when switching to (or
+// creating) an `exclusive` Main project, since two clusters bound to the same host :80/:443 can't
+// run at once anyway.
+function teardownOtherMains(exceptMainName) {
+  Object.entries(listProfiles()).forEach(([name, def]) => {
+    if (def.isolation === 'cluster' && name !== exceptMainName && clusterExists(def.cluster)) {
+      logger.step(`Tearing down "${name}"'s cluster (exclusive project switch)...`);
+      teardownCluster(def.cluster);
+    }
+  });
+}
+
+function bringUpMain(mainDef) {
+  provisionCluster({
+    clusterName: mainDef.cluster,
+    httpPort: mainDef.httpPort || DEFAULT_HTTP_PORT,
+    httpsPort: mainDef.httpsPort || DEFAULT_HTTPS_PORT,
+    registryPort: mainDef.registryPort || REGISTRY_HOST_PORT,
+  });
+}
+
+async function newProfile(name) {
+  if (getProfile(name)) {
+    logger.warn(`"${name}" is already registered - this will overwrite its definition (any cluster it already owns is left running as-is).`);
+  }
+
+  const { ask, close } = makePrompter();
+  try {
+    const kindAns = await ask('Own cluster (Main project), or share an existing project\'s cluster (namespace-scoped)? [cluster/namespace]', 'cluster');
+    const namespaceScoped = kindAns.trim().toLowerCase().startsWith('n');
+
+    if (namespaceScoped) {
+      const mains = Object.entries(listProfiles()).filter(([, d]) => d.isolation === 'cluster').map(([n]) => n);
+      const parent = await ask(`Parent Main project (${mains.join(', ')})`, getActive());
+      const parentDef = getProfile(parent);
+      if (!parentDef || parentDef.isolation !== 'cluster') {
+        throw new Error(`"${parent}" isn't a registered Main project. Run "localctl profiles list".`);
+      }
+      const namespacePrefix = await ask('Namespace/subdomain prefix for this project\'s apps', name);
+      upsertProfile(name, { isolation: 'namespace', parent, namespace: namespacePrefix });
+      logger.success(`Registered "${name}", namespace-scoped under "${parent}" (apps get a "${namespacePrefix}-" prefix).`);
+
+      if (!clusterExists(parentDef.cluster)) {
+        logger.warn(`Parent project "${parent}"'s cluster isn't up yet - run "localctl profiles switch ${parent}" before deploying here.`);
+      } else {
+        run('kubectl', ['config', 'use-context', `k3d-${parentDef.cluster}`], { stdio: 'ignore' });
+      }
+    } else {
+      const exclusiveAns = await ask('Tear down other Main projects\' clusters whenever you switch to this one? [Y/n]', 'y');
+      const exclusive = !/^n(o)?$/i.test(exclusiveAns);
+      const def = { isolation: 'cluster', cluster: `local-dev-${name}`, exclusive };
+      if (!exclusive) {
+        // Two clusters can't both bind host :80/:443 - a non-exclusive (concurrent-with-others)
+        // Main project gets its own free ports instead, at the cost of URLs needing a :port suffix.
+        def.httpPort = await getFreePort();
+        def.httpsPort = await getFreePort();
+        def.registryPort = await getFreePort();
+        logger.info(`Assigned its own ports (won't collide with an exclusive project's :80/:443): http ${def.httpPort}, https ${def.httpsPort}, registry ${def.registryPort}.`);
+      }
+      upsertProfile(name, def);
+      logger.success(`Registered Main project "${name}" (cluster "${def.cluster}").`);
+
+      if (exclusive) teardownOtherMains(name);
+      logger.step(`Bringing up "${name}"'s cluster...`);
+      bringUpMain(def);
+
+      const addonAns = await ask('Cluster-wide addons to enable here now, comma-separated (blank for none)', '');
+      addonAns.split(',').map((s) => s.trim()).filter(Boolean).forEach((addonName) => {
+        logger.step(`Enabling addon "${addonName}"...`);
+        enableClusterAddon(addonName);
+      });
+    }
+
+    setActive(name);
+
+    const localDir = path.join(process.cwd(), '.local');
+    fs.mkdirSync(localDir, { recursive: true });
+    fs.writeFileSync(path.join(localDir, 'project.json'), `${JSON.stringify({ profile: name }, null, 2)}\n`);
+    logger.success(`Wrote .local/project.json here - every app under ${process.cwd()} now belongs to "${name}" unless a subfolder overrides it.`);
+  } finally {
+    close();
+  }
+}
+
+function switchProfile(name) {
+  const target = getProfile(name);
+  if (!target) {
+    throw new Error(`Unknown profile "${name}". Run "localctl profiles list", or "localctl profiles new ${name}" to create it.`);
+  }
+
+  const { name: mainName, def: mainDef } = mainProjectFor(name);
+  if (mainDef.exclusive) teardownOtherMains(mainName);
+
+  if (!clusterExists(mainDef.cluster)) {
+    logger.step(`Bringing up "${mainName}"'s cluster...`);
+    bringUpMain(mainDef);
+  } else {
+    run('kubectl', ['config', 'use-context', `k3d-${mainDef.cluster}`], { stdio: 'ignore' });
+  }
+
+  setActive(name);
+  logger.success(`Switched to "${name}"${name !== mainName ? ` (namespace-scoped under "${mainName}")` : ''}.`);
+}
+
+function listProfilesCmd() {
+  const profiles = listProfiles();
+  const active = getActive();
+
+  Object.entries(profiles)
+    .filter(([, def]) => def.isolation === 'cluster')
+    .forEach(([name, def]) => {
+      const up = clusterExists(def.cluster);
+      const marker = name === active ? ui.ok('*') : ' ';
+      const portsNote = def.exclusive ? '' : ` http:${def.httpPort} https:${def.httpsPort}`;
+      console.log(
+        `${marker} ${ui.bold(name)}  [cluster: ${def.cluster}, ${up ? ui.ok('up') : ui.dim('down')}, ` +
+        `${def.exclusive ? 'exclusive' : 'concurrent'}${portsNote}]`,
+      );
+      childrenOf(name).forEach((child) => {
+        const childMarker = child === active ? ui.ok('*') : ' ';
+        const childDef = profiles[child];
+        console.log(`  ${childMarker} ${child}  [namespace: ${childDef.namespace || child}-*]`);
+      });
+    });
+}
+
+function statusCmd() {
+  const active = getActive();
+  const def = getProfile(active);
+  const { name: mainName, def: mainDef } = mainProjectFor(active);
+
+  console.log(ui.bold(active));
+  console.log(`  isolation: ${def.isolation}`);
+  if (def.isolation === 'namespace') {
+    console.log(`  parent:    ${def.parent}`);
+    console.log(`  namespace: ${def.namespace || active}-*`);
+  }
+  console.log(`  cluster:   ${mainDef.cluster} (${clusterExists(mainDef.cluster) ? ui.ok('up') : ui.dim('down')})`);
+  if (!mainDef.exclusive) {
+    console.log(`  ports:     http ${mainDef.httpPort} / https ${mainDef.httpsPort} / registry ${mainDef.registryPort}`);
+  }
+  console.log(`  exclusive: ${mainDef.exclusive ? 'yes - switching away tears this cluster down' : 'no - can run alongside other projects'}`);
+}
+
+module.exports = (program) => {
+  const profiles = program.command('profiles').description('Manage projects: isolated clusters or namespace-scoped slices of one');
+
+  profiles
+    .command('new <name>')
+    .description('Create a project - its own cluster, or namespace-scoped under an existing one - and mark the current directory as belonging to it')
+    .action(newProfile);
+
+  profiles
+    .command('list')
+    .description('List every project this machine knows about, nested under its Main (cluster) project')
+    .action(listProfilesCmd);
+
+  profiles
+    .command('switch <name>')
+    .description('Switch the active project - brings its cluster up if needed, applies its exclusive-teardown setting')
+    .action(switchProfile);
+
+  profiles
+    .command('status')
+    .description('Show the currently active project')
+    .action(statusCmd);
+};

package/src/commands/prune.js

@@ -0,0 +1,49 @@
+const { loadConfig } = require('../lib/loadConfig');
+const { ensureClusterUp } = require('../lib/clusterProvision');
+const { run, capture } = require('../lib/exec');
+const { getList } = require('../lib/workloadReadiness');
+const { confirm } = require('../lib/prompt');
+const logger = require('../lib/logger');
+
+module.exports = (program) => {
+  program
+    .command('prune')
+    .option('-y, --yes', 'skip the confirmation prompt')
+    .description('Permanently delete an already-torn-down app\'s leftover data (dependency PVCs, secrets) - "app down" deliberately leaves these alone')
+    .action(async (opts) => {
+      const cfg = loadConfig();
+      ensureClusterUp(cfg.clusterName, cfg.profile);
+
+      if (capture('kubectl', ['get', 'deployment', cfg.name, '-n', cfg.namespace]).status === 0) {
+        throw new Error(`"${cfg.name}" is still deployed - run "localctl app down" first, then "localctl app prune" to also wipe its data.`);
+      }
+      if (capture('kubectl', ['get', 'namespace', cfg.namespace]).status !== 0) {
+        logger.info(`Nothing to prune - namespace "${cfg.namespace}" doesn't exist.`);
+        return;
+      }
+
+      const pvcs = getList(['get', 'pvc', '-n', cfg.namespace]);
+      const secrets = getList(['get', 'secret', '-n', cfg.namespace]).filter((s) => s.type !== 'kubernetes.io/service-account-token');
+      if (pvcs.length === 0 && secrets.length === 0) {
+        logger.info(`Nothing left to prune in "${cfg.namespace}".`);
+        return;
+      }
+
+      console.log(`This will permanently delete everything left in namespace "${cfg.namespace}":`);
+      pvcs.forEach((p) => console.log(`  - PersistentVolumeClaim/${p.metadata.name} (data loss)`));
+      secrets.forEach((s) => console.log(`  - Secret/${s.metadata.name}`));
+      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;
+        }
+      }
+
+      run('kubectl', ['delete', 'namespace', cfg.namespace]);
+      logger.success(`Namespace "${cfg.namespace}" and everything in it deleted.`);
+    });
+};

package/src/commands/registryInfo.js

@@ -0,0 +1,18 @@
+const { loadConfig } = require('../lib/loadConfig');
+const { portsFor, mainProjectFor } = require('../lib/profileStore');
+const { registryNameFor } = require('../lib/clusterProvision');
+
+module.exports = (program) => {
+  program
+    .command('registry-info')
+    .description('[internal, called by Tiltfile] Print this app\'s registry push/pull addresses as JSON')
+    .action(() => {
+      const cfg = loadConfig();
+      const { registryPort } = portsFor(cfg.profile);
+      const { def } = mainProjectFor(cfg.profile);
+      process.stdout.write(JSON.stringify({
+        pushHost: `localhost:${registryPort}`,
+        clusterHost: `${registryNameFor(def.cluster)}:5000`,
+      }));
+    });
+};

package/src/commands/reload.js

@@ -0,0 +1,44 @@
+const fs = require('fs');
+const { CONFIG_PATH, runFiles } = require('../lib/paths');
+const { run, isRunning } = require('../lib/exec');
+const logger = require('../lib/logger');
+
+function resolveAppName(opts) {
+  if (opts.app) return opts.app;
+  if (fs.existsSync(CONFIG_PATH)) {
+    try {
+      return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8')).name;
+    } catch (e) {
+      // fall through
+    }
+  }
+  return null;
+}
+
+module.exports = (program) => {
+  program
+    .command('reload')
+    .option('-a, --app <name>', 'reload a specific app by name, regardless of the current directory')
+    .description('Force an immediate rebuild/redeploy of a running background dev loop, without waiting on a file change')
+    .action((opts) => {
+      const name = resolveAppName(opts);
+      if (!name) {
+        throw new Error('Run this from inside an app repo, or pass -a <name>.');
+      }
+
+      const { pidFile, portFile } = runFiles(name);
+      if (!fs.existsSync(pidFile) || !fs.existsSync(portFile)) {
+        throw new Error(`No background dev loop tracked for "${name}". Run "localctl app up" first (reload only works in detached mode, not "-f/--foreground").`);
+      }
+
+      const pid = parseInt(fs.readFileSync(pidFile, 'utf8'), 10);
+      if (!Number.isFinite(pid) || !isRunning(pid)) {
+        throw new Error(`"${name}"'s dev loop isn't running. Run "localctl app up" to start it.`);
+      }
+
+      const port = fs.readFileSync(portFile, 'utf8').trim();
+      logger.step(`Triggering an immediate rebuild/redeploy for "${name}"...`);
+      run('tilt', ['trigger', '--port', port, name]);
+      logger.success(`"${name}" reload triggered - check "localctl app logs ${name} -f" for progress.`);
+    });
+};

package/src/commands/secrets.js

@@ -0,0 +1,75 @@
+const { loadConfig } = require('../lib/loadConfig');
+const { ensureClusterUp } = require('../lib/clusterProvision');
+const { setSecret, unsetSecret, listKeys, readAll } = require('../lib/appSecrets');
+const { promptHidden } = require('../lib/prompt');
+const ui = require('../lib/ui');
+const logger = require('../lib/logger');
+
+module.exports = (program) => {
+  const secrets = program.command('secrets').description('Manage this app\'s own secrets (API keys, tokens - not addon-generated credentials)');
+
+  secrets
+    .command('set <key> [value]')
+    .description('Set a secret value (prompts, hidden, if not given) - stored as a real k8s Secret, never in .local/config.json')
+    .action(async (key, value) => {
+      const cfg = loadConfig();
+      ensureClusterUp(cfg.clusterName, cfg.profile);
+      if (!cfg.secrets.includes(key)) {
+        logger.warn(`"${key}" isn't listed in .local/config.json's "secrets" array - it won't be injected into the app until you add it there too.`);
+      }
+      const finalValue = value || (await promptHidden(`Value for ${key}`));
+      if (!finalValue) throw new Error('No value given.');
+      setSecret(cfg, key, finalValue);
+      logger.success(`Set "${key}". Run "localctl app up"/"localctl app reload" to pick it up.`);
+    });
+
+  secrets
+    .command('unset <key>')
+    .description('Remove a secret value')
+    .action((key) => {
+      const cfg = loadConfig();
+      ensureClusterUp(cfg.clusterName, cfg.profile);
+      const removed = unsetSecret(cfg, key);
+      if (removed) logger.success(`Removed "${key}".`);
+      else logger.info(`"${key}" wasn't set.`);
+    });
+
+  secrets
+    .command('list')
+    .description('List which secret keys are set (not their values)')
+    .action(() => {
+      const cfg = loadConfig();
+      ensureClusterUp(cfg.clusterName, cfg.profile);
+      const set = new Set(listKeys(cfg));
+      if (cfg.secrets.length === 0 && set.size === 0) {
+        logger.info('No secrets declared or set for this app.');
+        return;
+      }
+      const rows = [...new Set([...cfg.secrets, ...set])].map((key) => [
+        key,
+        set.has(key) ? ui.ok('set') : ui.warn('missing'),
+        cfg.secrets.includes(key) ? '' : ui.dim('(not in config.json)'),
+      ]);
+      ui.printTable(['KEY', 'STATUS', ''], rows);
+    });
+
+  secrets
+    .command('show [key]')
+    .description('Reveal actual secret value(s) - use with care, prints them to your terminal')
+    .action((key) => {
+      const cfg = loadConfig();
+      ensureClusterUp(cfg.clusterName, cfg.profile);
+      const data = readAll(cfg);
+      if (key) {
+        if (!(key in data)) throw new Error(`"${key}" isn't set. Run "localctl app secrets set ${key}".`);
+        console.log(data[key]);
+        return;
+      }
+      if (Object.keys(data).length === 0) {
+        logger.info('No secrets set for this app.');
+        return;
+      }
+      logger.warn('Revealing real secret values - avoid leaving these in your terminal scrollback/screen share.');
+      Object.entries(data).forEach(([k, v]) => console.log(`${k}=${v}`));
+    });
+};