@localctl/cli 0.4.0 → 0.4.2

package/README.md

@@ -75,17 +75,19 @@ JSON file per app.
 |---|---|
 | **macOS** or **Windows** | Windows commands run in PowerShell. |
 | **Node.js 18+** | Needed to install the CLI from npm. |
-| **Container engine** | [Podman Desktop](https://podman-desktop.io/), running. See [supported container engines](#supported-container-engines). |
+| **Container engine** | [Podman Desktop](https://podman-desktop.io/) (or Docker Desktop / Rancher Desktop), running. See [supported container engines](#supported-container-engines). |
 | **Homebrew** or **winget** | Used once by `localctl setup` to install missing tools. |
 
 `localctl setup` installs `k3d`, `kubectl`, `tilt`, `mkcert` and `helm` for you if they're missing.
+On Windows, Tilt isn't on winget, so it's downloaded from its GitHub release into
+`~.localctl	ools` and added to your user PATH.
 
 ### Supported container engines
 
 | Engine | Status |
 |---|---|
 | [Podman Desktop](https://podman-desktop.io/) | ✅ Tested |
-| [Docker Desktop](https://www.docker.com/products/docker-desktop/) | 🧪 Experimental — not yet tested |
+| [Docker Desktop](https://www.docker.com/products/docker-desktop/) | 🧪 Experimental — setup and app deploy verified on Windows |
 | [Rancher Desktop](https://rancherdesktop.io/) | 🧪 Experimental — not yet tested |
 
 Experimental engines are detected and should work, since k3d only needs a Docker-compatible API,
@@ -106,7 +108,9 @@ the local image registry, trusts the `*.local.test` certificate, and updates you
 is idempotent: run it again any time to repair your environment.
 
 You'll see up to two one-time prompts during setup: **mkcert** asking to trust its local
-certificate authority, and **sudo/Administrator** to write the `*.local.test` hosts entries.
+certificate authority, and **admin rights** to write the `*.local.test` hosts entries (your
+`sudo` password on macOS, a UAC prompt on Windows). Approve both: without the hosts entries, apps
+run but their addresses don't resolve.
 
 **Pre-releases** are published under the `beta` tag: `npm install -g @localctl/cli@beta`.
 
@@ -120,7 +124,8 @@ Update available: 0.2.0 -> 0.3.0
 Run npm install -g @localctl/cli to update.
 ```
 
-Update with `npm install -g @localctl/cli`. The check never slows a command down, is skipped in
+Update with `npm install -g @localctl/cli`. On a pre-release you're also told about newer
+versions on your own channel (e.g. `beta`). The check never slows a command down, is skipped in
 CI, and can be turned off with `LOCALCTL_NO_UPDATE_CHECK=1`.
 
 <details>
@@ -204,6 +209,16 @@ localctl app down
 
 This removes only that app. The shared cluster keeps running for everything else.
 
+<details>
+<summary><b>App is ready but <code>https://&lt;app&gt;.local.test</code> doesn't open?</b></summary>
+
+If `localctl app status` shows `1/1` but the browser can't reach the address, the hosts file
+entry is missing: the `sudo` or UAC prompt was declined or missed. Run `localctl hosts sync` and
+approve the prompt. More cases, with cause and fix:
+[**Troubleshooting**](https://psilvmoreira.github.io/localctl/troubleshooting/).
+
+</details>
+
 > **Tip:** no app of your own yet? Clone the repo and try a ready-made example:
 > [`node-app`](https://github.com/psilvmoreira/localctl/tree/master/examples/node-app) (Node.js + Postgres),
 > [`python-app`](https://github.com/psilvmoreira/localctl/tree/master/examples/python-app) (Python + Redis), or
@@ -211,7 +226,8 @@ This removes only that app. The shared cluster keeps running for everything else
 
 ## Commands
 
-Run `localctl <command> --help` for every option.
+Run `localctl <command> --help` for every option, or see the full
+[**CLI reference**](https://psilvmoreira.github.io/localctl/cli-reference/).
 
 <details open>
 <summary><b>Machine setup</b></summary>
@@ -220,7 +236,7 @@ Run `localctl <command> --help` for every option.
 |---|---|
 | `localctl setup` | Install or repair the infrastructure: container engine, cluster, TLS, hosts. Idempotent. |
 | `localctl doctor` | Health check of the active project's environment. |
-| `localctl hosts sync` / `list` | Manage the `*.local.test` entries in your hosts file. |
+| `localctl hosts sync` / `list` | Write or list the `*.local.test` entries in your hosts file. Asks for admin rights when needed. |
 | `localctl uninstall [-y]` | Remove every cluster, registry, hosts entry, certificate and state file `localctl` created. |
 
 </details>
@@ -235,7 +251,7 @@ Run `localctl <command> --help` for every option.
 | `localctl app down` | Stop the dev loop and remove the app. Keeps its data. |
 | `localctl app reload [-a <name>]` | Force a rebuild and redeploy without waiting for a file change. |
 | `localctl app status [-a <name>] [-A]` | One app's detail inside its repository, or a table of every app. |
-| `localctl app logs <name> [-f]` | Show or follow an app's logs. |
+| `localctl app logs [name] [-f]` | Show or follow an app's logs. Inside its repository the name is optional. |
 | `localctl app exec [cmd...]` | Open a shell (default `sh`) in the app's pod. |
 | `localctl app prune [-y]` | Delete leftover data (volumes, secrets) of apps already taken down. |
 | `localctl app secrets set <KEY> [value]` | Store a secret as a Kubernetes Secret, never in `config.json`. |
@@ -318,11 +334,13 @@ The full documentation lives at **[psilvmoreira.github.io/localctl](https://psil
 |---|---|
 | [Getting started](https://psilvmoreira.github.io/localctl/getting-started/) | Install and first deploy, step by step |
 | [Architecture](https://psilvmoreira.github.io/localctl/architecture/) | Every component, why it was chosen, multi-project support |
+| [CLI commands](https://psilvmoreira.github.io/localctl/cli-reference/) | Every command and option |
 | [Config schema](https://psilvmoreira.github.io/localctl/config-schema/) | Every `.local/config.json` field |
 | [Debugging](https://psilvmoreira.github.io/localctl/debugging/) | Attach a debugger in Node, Python, Go, Java and .NET |
 | [Adding tools](https://psilvmoreira.github.io/localctl/adding-tools/) | Write your own per-app or cluster-wide addon |
 | [Troubleshooting](https://psilvmoreira.github.io/localctl/troubleshooting/) | Known issues, with cause and fix |
 | [Uninstalling](https://psilvmoreira.github.io/localctl/uninstalling/) | Full teardown reference |
+| [Contributing](https://psilvmoreira.github.io/localctl/contributing/) | Local setup, tests, pull requests, dependency policy, docs site |
 | [Releasing](https://psilvmoreira.github.io/localctl/releasing/) | How versions are cut and published |
 
 ## Releases and versioning
@@ -333,15 +351,21 @@ The full documentation lives at **[psilvmoreira.github.io/localctl](https://psil
   with notes and the package tarball.
 - Versions follow [Semantic Versioning](https://semver.org). Before `1.0.0`, minor versions may
   contain breaking changes.
-- npm releases are published from GitHub Actions with
+- Every pull request shows a **release preview**: the version that merging it would publish,
+  including any unreleased commits already on `master`.
+- npm releases are published from GitHub Actions through
+  [trusted publishing](https://docs.npmjs.com/trusted-publishers) (no npm tokens) with
   [provenance](https://docs.npmjs.com/generating-provenance-statements). The npm package page links
   each version to the exact commit and workflow run that built it.
+- Dependencies and GitHub Actions are kept up to date by Dependabot, with every action pinned to a
+  commit SHA.
 
 ## Contributing
 
-Issues and pull requests are welcome.
+Issues and pull requests are welcome. The full guide (constraints, dependency policy, working on
+the docs site) is in [**Contributing**](https://psilvmoreira.github.io/localctl/contributing/).
 
-1. Fork the repository and create a branch.
+1. Fork the repository and create a branch from an up-to-date `master`.
 2. Make your change and run the tests:
    ```sh
    cd cli
@@ -350,15 +374,19 @@ Issues and pull requests are welcome.
    npm run test:pack   # the published package installs and runs
    ```
 3. Open a pull request with a [Conventional Commits](https://www.conventionalcommits.org/) title.
-   The title decides the next version:
+   PRs are squash-merged, so the title decides the next version. GitHub pre-fills it from the
+   branch name, which fails the title check: edit it.
 
    | Title | Release |
    |---|---|
-   | `fix: ...` | Patch (`0.2.0` → `0.2.1`) |
-   | `feat: ...` | Minor (`0.2.1` → `0.3.0`) |
-   | `feat!: ...` | Major (`0.3.0` → `1.0.0`) |
+   | `fix: ...`, `perf: ...` | Patch (`0.4.0` → `0.4.1`) |
+   | `feat: ...` | Minor (`0.4.1` → `0.5.0`) |
+   | `feat!: ...` | Major (`0.5.0` → `1.0.0`) |
    | `docs:` `chore:` `ci:` `refactor:` `test:` | No release |
 
+4. Check the **release preview** on the `pr-title` check and wait for every check to pass
+   (title, tests on Linux/macOS/Windows × Node 18/22, docs build, non-empty diff).
+
 <details>
 <summary><b>Repository layout</b></summary>
 
@@ -374,8 +402,10 @@ localctl/
 ├── cluster/manifests/   cluster-level manifests (TLS store, addon namespace)
 ├── schema/              JSON Schema for .local/config.json
 ├── examples/            ready-to-run sample apps
-├── docs/                documentation site (MkDocs Material, deployed to GitHub Pages)
-└── bin/                 bootstrap and uninstall scripts for source installs
+├── docs/                documentation pages (MkDocs Material, deployed to GitHub Pages)
+├── overrides/           docs site template overrides (landing page)
+├── bin/                 bootstrap and uninstall scripts for source installs
+└── .github/             CI, release and docs workflows, Dependabot config
 ```
 
 </details>
@@ -388,8 +418,10 @@ npm uninstall -g @localctl/cli  # the CLI itself
 ```
 
 `localctl uninstall` asks for confirmation (skip with `-y`) and is safe to re-run. It leaves the
-shared tools (`k3d`, `kubectl`, `tilt`, `mkcert`, `node`) and mkcert's root CA installed, since
-other projects may use them. It prints the exact commands to remove them too. Installed from
+shared tools (`k3d`, `kubectl`, `tilt`, `mkcert`, `helm`, `node`) and mkcert's root CA installed,
+since other projects may use them. It prints the exact commands to remove them for your OS
+(`brew uninstall ...` on macOS; `winget uninstall ...` plus the `~.localctl	ools` folder for
+Tilt on Windows). Installed from
 source with the bootstrap script? Use `./bin/uninstall.sh` or `./bin/uninstall.ps1` instead.
 Details: [**Uninstalling**](https://psilvmoreira.github.io/localctl/uninstalling/).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localctl/cli",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "localctl - local Kubernetes dev platform CLI",
   "keywords": [
     "kubernetes",

package/src/commands/uninstall.js

@@ -91,7 +91,12 @@ async function uninstall(opts) {
   logger.success('Uninstall complete.');
   console.log('');
   console.log('Left in place (remove yourself if you want them gone too):');
-  console.log('  brew uninstall k3d kubectl tilt mkcert node   # only if nothing else needs them');
+  if (process.platform === 'win32') {
+    console.log('  winget uninstall k3d.k3d Kubernetes.kubectl FiloSottile.mkcert Helm.Helm   # only if nothing else needs them');
+    console.log('  Remove-Item -Recurse -Force ~\\.localctl\\tools   # tilt, if localctl installed it');
+  } else {
+    console.log('  brew uninstall k3d kubectl tilt mkcert helm   # only if nothing else needs them');
+  }
   console.log("  mkcert -uninstall   # removes the root CA from trust stores - affects EVERY");
   console.log('                      # mkcert-issued cert on this machine, not just *.local.test');
 }

package/src/index.js

@@ -2,6 +2,9 @@ const { Command } = require('commander');
 const { version } = require('../package.json');
 
 require('./lib/updateCheck').start(version);
+// Tools localctl downloaded itself (e.g. tilt on Windows) work even in a terminal opened before
+// they were added to the user's PATH.
+require('./lib/toolInstall').addToolsDirToPath();
 
 const program = new Command();
 program

package/src/lib/clusterProvision.js

@@ -4,7 +4,7 @@ const path = require('path');
 const yaml = require('js-yaml');
 const { run, capture, sleepSync, commandExists } = require('./exec');
 const { detectEngine, warnIfExperimental } = require('./engine');
-const { installIfMissing } = require('./toolInstall');
+const { installIfMissing, installTiltWindows } = require('./toolInstall');
 const { ensureInsecureRegistry } = require('./podman');
 const { DOMAIN } = require('./constants');
 const logger = require('./logger');
@@ -49,9 +49,9 @@ function provisionCluster({ clusterName, httpPort, httpsPort, registryPort }) {
     ensureInsecureRegistry(registryPort);
   }
 
-  installIfMissing('k3d', 'k3d', 'k3d-io.k3d');
+  installIfMissing('k3d', 'k3d', 'k3d.k3d');
   installIfMissing('kubectl', 'kubernetes-cli', 'Kubernetes.kubectl');
-  installIfMissing('tilt', 'tilt', 'Tilt.dev.tilt');
+  installIfMissing('tilt', 'tilt', installTiltWindows);
   installIfMissing('mkcert', 'mkcert', 'FiloSottile.mkcert');
   installIfMissing('helm', 'helm', 'Helm.Helm');
 

package/src/lib/hostsFile.js

@@ -24,6 +24,20 @@ function listApps() {
   return Object.keys(registry);
 }
 
+// The Windows counterpart of `sudo cp`: copies src over the hosts file from an elevated
+// PowerShell, which raises a UAC prompt. Returns false if the prompt is declined or the copy
+// fails. The inner command goes through -EncodedCommand so paths need no nested quoting.
+function copyElevatedWindows(src) {
+  const quote = (s) => `'${s.replace(/'/g, "''")}'`;
+  const inner = `Copy-Item -LiteralPath ${quote(src)} -Destination ${quote(HOSTS_PATH)} -Force`;
+  const encoded = Buffer.from(inner, 'utf16le').toString('base64');
+  const res = spawnSync('powershell', [
+    '-NoProfile', '-NonInteractive', '-Command',
+    `Start-Process powershell -Verb RunAs -Wait -WindowStyle Hidden -ArgumentList '-NoProfile','-NonInteractive','-EncodedCommand','${encoded}'`,
+  ], { stdio: 'ignore' });
+  return res.status === 0;
+}
+
 function writeHosts(next, current) {
   if (next === current) {
     logger.info('Hosts file already up to date.');
@@ -38,8 +52,13 @@ function writeHosts(next, current) {
     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`);
+      logger.warn('Need Administrator rights to update the hosts file. Approve the Windows prompt to continue.');
+      if (copyElevatedWindows(tmp) && fs.readFileSync(HOSTS_PATH, 'utf8') === next) {
+        logger.success(`Updated ${HOSTS_PATH}`);
+      } else {
+        logger.warn('Hosts file not updated, so *.local.test addresses won\'t resolve. 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' });

package/src/lib/toolInstall.js

@@ -1,7 +1,72 @@
+const fs = require('fs');
+const path = require('path');
 const { commandExists, run } = require('./exec');
 const logger = require('./logger');
+const { HOME_STATE_DIR } = require('./paths');
 
-// macId: Homebrew formula name. winId: winget package id.
+// Tools that have no package-manager package on a platform get downloaded here instead. The
+// directory is added to the user's PATH for new terminals, and to this process's PATH by
+// addToolsDirToPath() on every run, so the current terminal needs no restart.
+const TOOLS_DIR = path.join(HOME_STATE_DIR, 'tools');
+
+function prependToPath(dir) {
+  if (!fs.existsSync(dir)) return;
+  const entries = (process.env.PATH || '').split(path.delimiter);
+  if (!entries.includes(dir)) process.env.PATH = [dir, ...entries].join(path.delimiter);
+}
+
+function addToolsDirToPath() {
+  prependToPath(TOOLS_DIR);
+}
+
+// winget puts portable packages (k3d, kubectl, helm, mkcert) behind links in this directory and
+// adds it to PATH for new terminals only. Adding it here lets the rest of `localctl setup` use a
+// tool winget just installed.
+function addWingetLinksToPath() {
+  if (process.env.LOCALAPPDATA) prependToPath(path.join(process.env.LOCALAPPDATA, 'Microsoft', 'WinGet', 'Links'));
+}
+
+function powershell(script) {
+  run('powershell', ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', script]);
+}
+
+// Tilt isn't published to winget. Same steps as Tilt's own install.ps1 (latest release zip from
+// GitHub), but into TOOLS_DIR and with the directory added to the user's PATH, which install.ps1
+// leaves to you.
+function installTiltWindows() {
+  logger.step('Installing tilt from its GitHub release (not available on winget)...');
+  powershell(`
+    $ErrorActionPreference = 'Stop'
+    $ProgressPreference = 'SilentlyContinue'
+    $dir = '${TOOLS_DIR.replace(/'/g, "''")}'
+    $version = (Invoke-RestMethod 'https://api.github.com/repos/tilt-dev/tilt/releases/latest').tag_name.TrimStart('v')
+    $url = "https://github.com/tilt-dev/tilt/releases/download/v$version/tilt.$version.windows.x86_64.zip"
+    $tmp = Join-Path $env:TEMP "localctl-tilt-$version"
+    if (Test-Path $tmp) { Remove-Item -Recurse -Force $tmp }
+    New-Item -ItemType Directory -Force -Path $tmp, $dir | Out-Null
+    Write-Host "Downloading $url"
+    Invoke-WebRequest $url -OutFile "$tmp\\tilt.zip"
+    Expand-Archive "$tmp\\tilt.zip" -DestinationPath $tmp
+    Move-Item -Force "$tmp\\tilt.exe" "$dir\\tilt.exe"
+    Remove-Item -Recurse -Force $tmp
+    # Raw registry value, so entries like %USERPROFILE%\\bin stay unexpanded (REG_EXPAND_SZ).
+    $key = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true)
+    $userPath = [string]$key.GetValue('Path', '', 'DoNotExpandEnvironmentNames')
+    if ((($userPath -split ';') | Where-Object { $_ -eq $dir }).Count -eq 0) {
+      $key.SetValue('Path', (($userPath.TrimEnd(';'), $dir) -join ';').TrimStart(';'), 'ExpandString')
+      # Setting any user variable through .NET broadcasts WM_SETTINGCHANGE, so terminals opened
+      # from now on pick up the new PATH without signing out.
+      [Environment]::SetEnvironmentVariable('LOCALCTL_PATH_REFRESH', '1', 'User')
+      [Environment]::SetEnvironmentVariable('LOCALCTL_PATH_REFRESH', $null, 'User')
+    }
+    $key.Close()
+  `);
+  addToolsDirToPath();
+  logger.success(`tilt installed in ${TOOLS_DIR} (added to your PATH for new terminals)`);
+}
+
+// macId: Homebrew formula name. winId: winget package id, or a function that installs the tool
+// when winget doesn't have it.
 function installIfMissing(bin, macId, winId) {
   if (commandExists(bin)) {
     logger.success(`${bin} already installed`);
@@ -14,6 +79,10 @@ function installIfMissing(bin, macId, winId) {
     logger.step(`Installing ${macId} via brew...`);
     run('brew', ['install', macId]);
   } else if (process.platform === 'win32') {
+    if (typeof winId === 'function') {
+      winId();
+      return;
+    }
     if (!commandExists('winget')) {
       throw new Error('winget is required to install missing tools (ships with modern Windows / App Installer).');
     }
@@ -22,9 +91,10 @@ function installIfMissing(bin, macId, winId) {
       'install', '--id', winId, '-e', '--source', 'winget',
       '--accept-package-agreements', '--accept-source-agreements',
     ]);
+    addWingetLinksToPath();
   } else {
     throw new Error(`"${bin}" is missing and automatic install isn't supported on this platform. Install it manually.`);
   }
 }
 
-module.exports = { installIfMissing };
+module.exports = { installIfMissing, installTiltWindows, addToolsDirToPath, TOOLS_DIR };