@localctl/cli 0.2.0 → 0.4.0

package/assets/manifests/namespace-addons.yaml

@@ -1,4 +1,4 @@
-apiVersion: v1
-kind: Namespace
-metadata:
-  name: observability
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: observability

package/assets/manifests/tls-store.yaml

@@ -1,8 +1,8 @@
-apiVersion: traefik.io/v1alpha1
-kind: TLSStore
-metadata:
-  name: default
-  namespace: kube-system
-spec:
-  defaultCertificate:
-    secretName: local-dev-tls
+apiVersion: traefik.io/v1alpha1
+kind: TLSStore
+metadata:
+  name: default
+  namespace: kube-system
+spec:
+  defaultCertificate:
+    secretName: local-dev-tls

package/bin/localctl.js

@@ -1,2 +1,2 @@
-#!/usr/bin/env node
-require('../src/index.js');
+#!/usr/bin/env node
+require('../src/index.js');

package/package.json

@@ -1,54 +1,61 @@
-{
-  "name": "@localctl/cli",
-  "version": "0.2.0",
-  "description": "localctl - local Kubernetes dev platform CLI",
-  "keywords": [
-    "kubernetes",
-    "k3d",
-    "tilt",
-    "local-development",
-    "cli",
-    "devtools"
-  ],
-  "homepage": "https://psilvmoreira.github.io/localctl/",
-  "bugs": {
-    "url": "https://github.com/psilvmoreira/localctl/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/psilvmoreira/localctl.git",
-    "directory": "cli"
-  },
-  "author": "Pedro Moreira",
-  "license": "MIT",
-  "bin": {
-    "localctl": "bin/localctl.js"
-  },
-  "main": "src/index.js",
-  "files": [
-    "bin/",
-    "src/",
-    "templates/",
-    "assets/",
-    "schema/"
-  ],
-  "scripts": {
-    "sync-assets": "node scripts/sync-assets.js",
-    "prepack": "node scripts/sync-assets.js",
-    "test": "node scripts/smoke-test.js",
-    "test:pack": "node scripts/pack-test.js"
-  },
-  "dependencies": {
-    "chalk": "^4.1.2",
-    "commander": "^11.1.0",
-    "js-yaml": "^4.1.0",
-    "zod": "^3.23.8"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public",
-    "provenance": true
-  }
-}
+{
+  "name": "@localctl/cli",
+  "version": "0.4.0",
+  "description": "localctl - local Kubernetes dev platform CLI",
+  "keywords": [
+    "kubernetes",
+    "k3d",
+    "tilt",
+    "local-development",
+    "cli",
+    "devtools"
+  ],
+  "homepage": "https://psilvmoreira.github.io/localctl/",
+  "bugs": {
+    "url": "https://github.com/psilvmoreira/localctl/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/psilvmoreira/localctl.git",
+    "directory": "cli"
+  },
+  "author": "Pedro Moreira",
+  "license": "MIT",
+  "bin": {
+    "localctl": "bin/localctl.js"
+  },
+  "main": "src/index.js",
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "assets/",
+    "schema/"
+  ],
+  "scripts": {
+    "sync-assets": "node scripts/sync-assets.js",
+    "prepack": "node scripts/sync-assets.js",
+    "test": "node scripts/smoke-test.js",
+    "test:pack": "node scripts/pack-test.js"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "js-yaml": "^4.1.0",
+    "zod": "^3.23.8"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "localctl": {
+    "containerEngines": {
+      "podman": "tested",
+      "docker": "experimental",
+      "rancher-desktop": "experimental"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/src/commands/addons.js

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

@@ -1,43 +1,44 @@
-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.`);
-    });
-};
+const { commandExists, capture } = require('../lib/exec');
+const { detectEngine, warnIfExperimental } = 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) warnIfExperimental(detected.engine);
+      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

@@ -1,35 +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.`);
-    });
-};
+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

@@ -1,15 +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]);
-    });
-};
+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

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

@@ -1,23 +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());
-};
+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

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