turnout-cli 0.2.2 → 0.4.0

package/README.md

@@ -1,12 +1,164 @@
-# turnout-cli
+<p align="center"><img src="https://github.com/lacodda/turnout/raw/main/assets/banner.svg" alt="turnout - a developer's switchyard" width="720"></p>
 
-npm distribution of [turnout](https://github.com/lacodda/turnout) - a developer's switchyard: point local apps at any backend stand, keep servers and secrets at hand, build and deploy from any directory.
+> A developer's switchyard: point local apps at any backend stand, keep servers and secrets at hand, build and deploy - from any directory.
+
+<p align="center">
+  <a href="https://crates.io/crates/turnout"><img src="https://img.shields.io/crates/v/turnout?style=flat-square" alt="crates.io"></a>
+  <a href="https://www.npmjs.com/package/turnout-cli"><img src="https://img.shields.io/npm/v/turnout-cli?style=flat-square" alt="npm"></a>
+  <a href="https://github.com/lacodda/turnout/actions"><img src="https://img.shields.io/github/actions/workflow/status/lacodda/turnout/ci.yml?style=flat-square" alt="CI"></a>
+  <a href="https://github.com/lacodda/turnout/blob/main/LICENSE"><img src="https://img.shields.io/github/license/lacodda/turnout?style=flat-square" alt="License"></a>
+</p>
+
+## Why
+
+Working against several backend stands scatters the day: you `cd` into a folder to start a project, edit `.env` files across repositories to switch a stand, dig through notes for a password, and keep deploy paths in your head.
+
+turnout keeps all of it in one place and works from any directory.
+
+## A day in the life
+
+Point an app at a stand:
+
+```console
+$ turnout use web staging
+'web' now uses 'staging'.
+The running gateway picks this up automatically.
+Stand check: https://staging.example.com responded with 200 OK.
+```
+
+Nothing in the project changed - the app still talks to `localhost`, and the [gateway](https://lacodda.github.io/turnout/concepts/gateway/) routes it to the stand you picked. Your session survives the switch, because cookies are kept per app **and** stand.
+
+Start working, from wherever you happen to be:
+
+```console
+$ cd ~/dev/web/src/components
+$ turnout dev
+[web] pnpm dev
+```
+
+Move the whole contour at once when the frontend and the API must agree:
+
+```console
+$ turnout use contour prod-eu
+Group 'contour' now uses 'prod-eu':
+  web -> prod-eu
+  api -> prod-eu
+```
+
+Forgot a name? Leave it out and pick from a list that shows where things point:
+
+```console
+$ turnout use
+? Switch ›
+❯ contour   group: web, api
+  api       -> staging
+  web       -> staging
+```
+
+Ship it:
+
+```console
+$ turnout deploy web -s prod-eu -b
+[web] pnpm build
+✓ Connected to deploy@prod-eu.example.com:22
+✓ Backup 20260809-011500.tar.gz created in /var/www/web.backups
+================>          2.02 MiB/3.11 MiB · 1.81 MiB/s · eta 1s  assets/index-b3f0a1.js
+Uploaded 142 files (3.11 MiB) to prod-eu:/var/www/web
+✓ Ran: systemctl restart web
+Deploy of 'web' to 'prod-eu' finished.
+```
+
+Every long flag has a short form, and nothing runs silently: the upload reports throughput and an ETA, and the steps that talk to the server say so while they wait.
+
+And see what has been going on:
+
+```console
+$ turnout status
+turnout 0.4.0
+Data directory: ~/.local/share/lacodda/turnout
+Apps:    2 (api, web)
+Servers: 2 (prod-eu, staging)
+Group:   contour (web, api)
+Access:  saved for prod-eu
+Bindings:
+  api -> staging
+  web -> prod-eu
+Gateway: running (pid 24180; web:7100, api:7101)
+Recent:
+  2026-08-09T01:15:02Z  deploy         web -> prod-eu (142 files)
+  2026-08-09T01:12:44Z  use            web -> prod-eu
+```
+
+## What you get
+
+- **A dev gateway.** Apps always talk to `localhost`; turnout forwards to the selected stand over HTTP or HTTPS (self-signed certificates allowed per server), rewrites redirects, proxies WebSockets, and keeps a cookie jar per app+stand pair so switching does not log you out.
+- **Secrets in the OS keyring** - Windows Credential Manager, macOS Keychain, Linux Secret Service. Copy a password to the clipboard with one command; nothing lands in a config file, and `status` only ever reports *that* a credential exists.
+- **Commands from any directory.** `dev`, `build`, `test`, `lint` and any custom command run in the right project folder. Commands are taken from your actual `package.json` scripts, so a project whose dev script is `serve` still answers to `turnout dev`.
+- **Deploy over SSH/SFTP** - build, upload, restart, with remote backup and restore when a release goes wrong.
+- **Groups.** Bind a whole contour to one stand with a single `use`.
+- **Nothing to memorize.** Leave a name out and pick it from a list; in bash, Tab completes app, server and group names from your own catalogs. The short alias `tn` is installed alongside.
+- **An action journal.** Every state change appends one JSON line - what happened and to which entities, never secrets or output. `tail`, `grep` and `jq` work on it directly.
+
+## Install
+
+**One-line installers.** Windows (PowerShell):
+
+```powershell
+irm https://raw.githubusercontent.com/lacodda/turnout/main/tools/install.ps1 | iex
+```
+
+macOS / Linux:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/lacodda/turnout/main/tools/install.sh | sh
+```
+
+**With npm:**
 
 ```bash
 npm i -g turnout-cli
-turnout setup
 ```
 
-The package downloads the prebuilt binary for your platform (Windows x86_64, Linux x86_64, macOS arm64) from GitHub Releases on install. On other platforms use `cargo install turnout`.
+**With cargo:**
+
+```bash
+cargo install turnout
+```
+
+**Binary releases** - grab the archive for your platform from [Releases](https://github.com/lacodda/turnout/releases/latest) (Windows x86_64, Linux x86_64, macOS arm64), unpack and put `turnout` on your `PATH`.
+
+The installers and the npm package also register the short alias `tn` (skipped if the name is already taken; `TURNOUT_NO_ALIAS=1` opts out). `cargo install` gives you `turnout` only.
+
+## Quick start
+
+```bash
+turnout setup                  # first-run wizard: creates the data directory
+turnout app add                # register a project (detects its commands)
+turnout server add             # register a stand
+turnout use                    # bind one to the other
+turnout gateway start          # route traffic through the gateway
+```
+
+Data lives in the platform user data directory (e.g. `%LOCALAPPDATA%\lacodda\turnout` on Windows); set `TURNOUT_DATA_DIR` to override.
+
+Full command reference and concepts: **[lacodda.github.io/turnout](https://lacodda.github.io/turnout/)**.
+
+## Status
+
+Everything above works today. What is next:
+
+- [ ] **Updates and portability** - update notice, `self-update`, `export` / `import` for moving to another machine
+- [ ] **Credentials and paths as their own entities** - one login reused across servers, a remote directory declared once, and named builds so a deploy stays a single word
+- [ ] **Background runs** - `dev --detach`, `ps`, `logs`, `stop`, OS notifications
+- [ ] **Observability** - gateway request log, `doctor`, `report` for handing context to an assistant
+- [ ] **Deploy consists** - atomic deploy and rollback across a group of apps
+
+Released versions and what landed in each: [CHANGELOG on the Releases page](https://github.com/lacodda/turnout/releases).
+
+## Documentation
+
+The documentation site (Astro Starlight) lives in [`docs/`](https://github.com/lacodda/turnout/tree/main/docs); architecture decision records are in [`docs/adr/`](https://github.com/lacodda/turnout/tree/main/docs/adr).
+
+## License
 
-Documentation: https://lacodda.github.io/turnout/
+MIT (c) [Kirill Lakhtachev](https://lacodda.com)

package/download.js

@@ -0,0 +1,88 @@
+// Downloads the turnout binary matching this package version from GitHub Releases.
+// Shared by install.js (postinstall, where lifecycle scripts are allowed) and
+// run.js (first-run fallback: npm v12 skips install scripts by default).
+const fs = require("fs");
+const https = require("https");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const pkg = require("./package.json");
+const REPO = "lacodda/turnout";
+// The wrapper can be patched independently of the Rust binary: an explicit
+// turnout.binary field pins the release tag, otherwise it follows the version.
+const TAG = (pkg.turnout && pkg.turnout.binary) || `v${pkg.version}`;
+
+const TARGETS = {
+  "win32-x64": ["x86_64-pc-windows-msvc", "zip"],
+  "linux-x64": ["x86_64-unknown-linux-gnu", "tar.gz"],
+  "darwin-arm64": ["aarch64-apple-darwin", "tar.gz"],
+};
+
+const exe = process.platform === "win32" ? "turnout.exe" : "turnout";
+const exePath = path.join(__dirname, exe);
+
+function download(url, file, redirects, done) {
+  if (redirects > 5) return done(new Error("too many redirects"));
+  https
+    .get(url, { headers: { "user-agent": "turnout-cli" } }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        res.resume();
+        return download(res.headers.location, file, redirects + 1, done);
+      }
+      if (res.statusCode !== 200) {
+        res.resume();
+        return done(new Error(`HTTP ${res.statusCode} for ${url}`));
+      }
+      const out = fs.createWriteStream(file);
+      res.pipe(out);
+      out.on("finish", () => out.close(done));
+      out.on("error", done);
+    })
+    .on("error", done);
+}
+
+function install(done) {
+  const key = `${process.platform}-${process.arch}`;
+  const entry = TARGETS[key];
+  if (!entry) {
+    console.error(`turnout-cli: no prebuilt binary for ${key}; install with: cargo install turnout`);
+    process.exit(1);
+  }
+  const [target, ext] = entry;
+  const name = `turnout-${TAG}-${target}`;
+  const url = `https://github.com/${REPO}/releases/download/${TAG}/${name}.${ext}`;
+  const archive = path.join(__dirname, `archive.${ext}`);
+
+  console.log(`turnout-cli: downloading ${url}`);
+  download(url, archive, 0, (err) => {
+    if (err) {
+      console.error(`turnout-cli: download failed: ${err.message}`);
+      process.exit(1);
+    }
+    // Extraction must not depend on which tar happens to be first in PATH
+    // (Git Bash ships a GNU tar that cannot read zip): zip goes through
+    // PowerShell's Expand-Archive, tar.gz through tar on Unix systems.
+    const result =
+      ext === "zip"
+        ? spawnSync(
+            "powershell.exe",
+            ["-NoProfile", "-NonInteractive", "-Command", "Expand-Archive -LiteralPath 'archive.zip' -DestinationPath . -Force"],
+            { cwd: __dirname, stdio: "inherit" },
+          )
+        : spawnSync("tar", ["-xzf", `archive.${ext}`], { cwd: __dirname, stdio: "inherit" });
+    if (result.status !== 0) {
+      console.error("turnout-cli: cannot extract the archive");
+      process.exit(1);
+    }
+    fs.renameSync(path.join(__dirname, name, exe), exePath);
+    fs.rmSync(path.join(__dirname, name), { recursive: true, force: true });
+    fs.rmSync(archive, { force: true });
+    if (process.platform !== "win32") {
+      fs.chmodSync(exePath, 0o755);
+    }
+    console.log(`turnout-cli: installed turnout ${TAG}`);
+    done();
+  });
+}
+
+module.exports = { install, exePath };

package/install.js

@@ -1,79 +1,4 @@
-// Downloads the turnout binary matching this package version from GitHub Releases.
-const fs = require("fs");
-const https = require("https");
-const path = require("path");
-const { spawnSync } = require("child_process");
-
-const pkg = require("./package.json");
-const REPO = "lacodda/turnout";
-// The wrapper can be patched independently of the Rust binary: an explicit
-// turnout.binary field pins the release tag, otherwise it follows the version.
-const TAG = (pkg.turnout && pkg.turnout.binary) || `v${pkg.version}`;
-
-const TARGETS = {
-  "win32-x64": ["x86_64-pc-windows-msvc", "zip"],
-  "linux-x64": ["x86_64-unknown-linux-gnu", "tar.gz"],
-  "darwin-arm64": ["aarch64-apple-darwin", "tar.gz"],
-};
-
-const key = `${process.platform}-${process.arch}`;
-const entry = TARGETS[key];
-if (!entry) {
-  console.error(`turnout-cli: no prebuilt binary for ${key}; install with: cargo install turnout`);
-  process.exit(1);
-}
-const [target, ext] = entry;
-const name = `turnout-${TAG}-${target}`;
-const url = `https://github.com/${REPO}/releases/download/${TAG}/${name}.${ext}`;
-const exe = process.platform === "win32" ? "turnout.exe" : "turnout";
-const archive = path.join(__dirname, `archive.${ext}`);
-
-function download(url, file, redirects, done) {
-  if (redirects > 5) return done(new Error("too many redirects"));
-  https
-    .get(url, { headers: { "user-agent": "turnout-cli" } }, (res) => {
-      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-        res.resume();
-        return download(res.headers.location, file, redirects + 1, done);
-      }
-      if (res.statusCode !== 200) {
-        res.resume();
-        return done(new Error(`HTTP ${res.statusCode} for ${url}`));
-      }
-      const out = fs.createWriteStream(file);
-      res.pipe(out);
-      out.on("finish", () => out.close(done));
-      out.on("error", done);
-    })
-    .on("error", done);
-}
-
-console.log(`turnout-cli: downloading ${url}`);
-download(url, archive, 0, (err) => {
-  if (err) {
-    console.error(`turnout-cli: download failed: ${err.message}`);
-    process.exit(1);
-  }
-  // Extraction must not depend on which tar happens to be first in PATH
-  // (Git Bash ships a GNU tar that cannot read zip): zip goes through
-  // PowerShell's Expand-Archive, tar.gz through tar on Unix systems.
-  const result =
-    ext === "zip"
-      ? spawnSync(
-          "powershell.exe",
-          ["-NoProfile", "-NonInteractive", "-Command", "Expand-Archive -LiteralPath 'archive.zip' -DestinationPath . -Force"],
-          { cwd: __dirname, stdio: "inherit" },
-        )
-      : spawnSync("tar", ["-xzf", `archive.${ext}`], { cwd: __dirname, stdio: "inherit" });
-  if (result.status !== 0) {
-    console.error("turnout-cli: cannot extract the archive");
-    process.exit(1);
-  }
-  fs.renameSync(path.join(__dirname, name, exe), path.join(__dirname, exe));
-  fs.rmSync(path.join(__dirname, name), { recursive: true, force: true });
-  fs.rmSync(archive, { force: true });
-  if (process.platform !== "win32") {
-    fs.chmodSync(path.join(__dirname, exe), 0o755);
-  }
-  console.log(`turnout-cli: installed turnout ${TAG}`);
-});
+// Postinstall entry: pre-downloads the binary where lifecycle scripts are
+// allowed. On npm v12+ this script is skipped by default and run.js downloads
+// the binary on first launch instead.
+require("./download").install(() => {});

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "turnout-cli",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "turnout": {
-    "binary": "v0.2.2"
+    "binary": "v0.4.0"
   },
   "description": "A developer's switchyard: point local apps at any backend stand, keep servers and secrets at hand, build and deploy from any directory",
   "license": "MIT",
@@ -14,9 +14,10 @@
   },
   "keywords": ["cli", "proxy", "gateway", "deploy", "dev-environment", "stands"],
   "bin": {
-    "turnout": "run.js"
+    "turnout": "run.js",
+    "tn": "run.js"
   },
-  "files": ["install.js", "run.js"],
+  "files": ["download.js", "install.js", "run.js"],
   "scripts": {
     "postinstall": "node install.js"
   },

package/run.js

@@ -1,12 +1,18 @@
 #!/usr/bin/env node
-// Thin launcher: forwards everything to the downloaded turnout binary.
-const path = require("path");
+// Thin launcher: forwards everything to the turnout binary, downloading it on
+// first run when the postinstall script was skipped (npm v12 default).
+const fs = require("fs");
 const { spawnSync } = require("child_process");
+const { install, exePath } = require("./download");
 
-const exe = path.join(__dirname, process.platform === "win32" ? "turnout.exe" : "turnout");
-if (!require("fs").existsSync(exe)) {
-  console.error("turnout-cli: binary missing - reinstall the package (npm i -g turnout-cli)");
-  process.exit(1);
+function exec() {
+  const result = spawnSync(exePath, process.argv.slice(2), { stdio: "inherit" });
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+if (fs.existsSync(exePath)) {
+  exec();
+} else {
+  console.error("turnout-cli: binary not present yet - downloading it now");
+  install(exec);
 }
-const result = spawnSync(exe, process.argv.slice(2), { stdio: "inherit" });
-process.exit(result.status === null ? 1 : result.status);