permaura 1.3.26 → 1.3.28

package/bin/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// permaura — the dead-easy way to run the Permaura gateway.
+// permaura: the dead-easy way to run the Permaura gateway.
 //   npx -y permaura start                 # install-or-upgrade, run, print URL + token
 //   npx -y permaura start --pair PGW-XXXX # …and connect it to your permaura.com account
 //   npx -y permaura status                # …or any other permaura command, against a running one
@@ -11,7 +11,7 @@
 // newer binary when one ships (skip with --no-upgrade / PERMAURA_NO_UPGRADE=1).
 //
 // This is a launcher, not a second CLI. Everything but the install/upgrade half is handed to the
-// binary verbatim, so there is exactly one implementation of every command — including `--pair`,
+// binary verbatim, so there is exactly one implementation of every command, including `--pair`,
 // which the binary performs itself once it is up.
 import os from "node:os";
 import fs from "node:fs";
@@ -58,7 +58,7 @@ const warn = (s) => console.log(`${C.yellow("!")} ${s}`);
 /**
  * The binary's own subcommands. The launcher keeps the list so a typo costs nothing: a mistyped
  * command is rejected here, before anything downloads a binary or binds a port. It is the same list
- * the binary's clap definition carries, and the two drift only when a command is added — at which
+ * the binary's clap definition carries, and the two drift only when a command is added, at which
  * point the worst case is that the new one has to be run through the installed binary directly.
  */
 const KNOWN = new Set([
@@ -90,7 +90,7 @@ const VALUE_FLAGS = new Set(["--url", "--token"]);
  * people arrive by and wrong for the other one that installs this file: `npm i -g permaura` puts the
  * launcher on PATH, and telling someone to reach it through npx then sends them back out to the
  * registry to fetch a copy of what they are already running. It is not in the docs, but it is the
- * reflex for anything published on npm, and it works — so the help has to know.
+ * reflex for anything published on npm, and it works, so the help has to know.
  *
  * npx runs the package out of its own cache (`~/.npm/_npx/<hash>/node_modules/permaura/bin/cli.mjs`),
  * so the path this module was loaded from is the answer; nothing else needs to be probed or asked.
@@ -98,7 +98,7 @@ const VALUE_FLAGS = new Set(["--url", "--token"]);
  * reader on PATH gets a command that works, and an npx user gets one their shell will tell them
  * about immediately.
  *
- * The `curl | sh` route never reaches here at all — it installs the Rust binary, whose own clap help
+ * The `curl | sh` route never reaches here at all: it installs the Rust binary, whose own clap help
  * has said `permaura <command>` throughout.
  */
 function invocation() {
@@ -106,7 +106,7 @@ function invocation() {
   return self.includes(`${path.sep}_npx${path.sep}`) ? "npx -y permaura" : "permaura";
 }
 
-const usage = (me = invocation()) => `permaura — the dead-easy way to run the Permaura gateway.
+const usage = (me = invocation()) => `permaura: the dead-easy way to run the Permaura gateway.
 
 Usage:
   ${me} start                  install-or-upgrade, run, print URL + token
@@ -116,7 +116,7 @@ Usage:
   ${me} --version               print the launcher + installed-binary versions
   ${me} --help                  print this
 
-Commands (${[...KNOWN].sort().join(", ")}) are the binary's own — run
+Commands (${[...KNOWN].sort().join(", ")}) are the binary's own: run
 \`${me} help <command>\` for one of them.
 
 Launcher options:
@@ -138,7 +138,7 @@ Environment:
  *
  * NO arguments prints help and starts nothing. A multi-command tool that boots a long-running server
  * when invoked bare is a surprise, and this is the first command most people type. An unrecognised
- * subcommand is an ERROR for the same reason it always was — `--help`, and every typo, used to
+ * subcommand is an ERROR for the same reason it always was: `--help`, and every typo, used to
  * silently boot a gateway and bind a port.
  *
  * Everything else is forwarded to the binary untouched (minus the launcher-only flags), so the
@@ -272,7 +272,7 @@ function sha256File(p) {
  * The release signing keys this launcher accepts (Ed25519, SPKI PEM), newest first.
  *
  * Why this matters: `asset.sha256` comes from the SAME manifest as `asset.url`. That is integrity
- * against a corrupted download, not authenticity — anyone who can change the manifest changes both
+ * against a corrupted download, not authenticity: anyone who can change the manifest changes both
  * numbers and the checksum cheerfully confirms their binary. Only a signature made by a key we pinned
  * out-of-band says "Permaura built this".
  *
@@ -280,7 +280,7 @@ function sha256File(p) {
  * gateway binary is, so whatever is pinned here sits on people's machines until they think to run
  * `npm update -g permaura`. With one key, rotating it breaks every one of those installs at once, and
  * the break is unrecoverable from the client side: the thing that would carry the new key is itself
- * signed with it. A set gives rotation an overlap window — see RELEASING.md, but the shape is: add
+ * signed with it. A set gives rotation an overlap window. See RELEASING.md, but the shape is: add
  * the next key here, ship, wait, and only then sign with it.
  *
  * MUST stay in step with the other three pin sites, or an install verifies on one surface and fails on
@@ -315,7 +315,7 @@ const REQUIRE_SIGNATURE = RELEASE_PUBKEY_PEMS.length > 0;
  * parse.
  *
  * Returns true when verified, false when no key is configured (nothing to verify against), and throws
- * when a key IS configured and the signature is missing or bad — that is an attack, not a hiccup.
+ * when a key IS configured and the signature is missing or bad: that is an attack, not a hiccup.
  */
 async function verifyManifestSignature(rawManifest, sigUrl) {
   if (!REQUIRE_SIGNATURE) return false;
@@ -344,13 +344,13 @@ async function ensureBinary({ noUpgrade, force }) {
   const key = platformKey();
   if (!key) {
     throw new Error(
-      `unsupported platform ${process.platform}/${process.arch} — prebuilt gateways cover macOS, Linux and Windows on arm64/x64. https://permaura.com/docs`,
+      `unsupported platform ${process.platform}/${process.arch}: prebuilt gateways cover macOS, Linux and Windows on arm64/x64. https://permaura.com/docs`,
     );
   }
   fs.mkdirSync(path.join(DIR, "bin"), { recursive: true });
 
   // Sweep binaries parked by a previous rename-aside upgrade (D9 cleanup-on-start; no-op when no
-  // live binary exists — a lone .old may be the only working copy after a failed swap).
+  // live binary exists: a lone .old may be the only working copy after a failed swap).
   sweepOldBinaries(BIN);
 
   const have = installedVersion();
@@ -368,7 +368,7 @@ async function ensureBinary({ noUpgrade, force }) {
       throw new Error(`bad manifest JSON: ${e.message}`);
     }
   } catch (e) {
-    // A signature failure is never "the network was flaky" — it must not fall back to a cached binary
+    // A signature failure is never "the network was flaky": it must not fall back to a cached binary
     // and carry on as though nothing happened.
     if (REQUIRE_SIGNATURE && /signature|signed|release key/i.test(e.message)) throw e;
     if (haveBinary && !force) {
@@ -379,7 +379,7 @@ async function ensureBinary({ noUpgrade, force }) {
   }
   if (!REQUIRE_SIGNATURE) {
     warn(
-      "This build cannot verify that the gateway binary came from Permaura — no release key is pinned yet. The download is checksummed, but a checksum from an unsigned manifest only proves the file arrived intact, not who made it.",
+      "This build cannot verify that the gateway binary came from Permaura: no release key is pinned yet. The download is checksummed, but a checksum from an unsigned manifest only proves the file arrived intact, not who made it.",
     );
   }
 
@@ -427,14 +427,14 @@ async function ensureBinary({ noUpgrade, force }) {
 
   fs.chmodSync(tmp, 0o755);
   // Rename-aside swap (the rustup pattern, D9): park the current binary at `.old`, move the verified
-  // download into place, restore the parked copy if that fails — a runnable binary exists at BIN on
+  // download into place, restore the parked copy if that fails: a runnable binary exists at BIN on
   // every exit path. A gateway already running the old inode keeps working on every platform; the
   // sweep above collects parked files on a later run.
   swapBinaryIntoPlace(BIN, tmp);
   // Quarantine is macOS's own "you didn't make this" flag, so stripping it from an artifact we could
   // not authenticate throws away the last check standing. Once a release key is pinned this only runs
   // for a signature-verified binary; until then it must still run, because the gateway binary is not
-  // notarized and Gatekeeper would otherwise refuse to execute it at all — removing the strip today
+  // notarized and Gatekeeper would otherwise refuse to execute it at all: removing the strip today
   // would simply break every macOS install. Un-gating it is part of the signing work, not separate
   // from it (see HANDBACK, § H-04).
   if (process.platform === "darwin" && (manifestVerified || !REQUIRE_SIGNATURE)) {
@@ -450,7 +450,7 @@ async function ensureBinary({ noUpgrade, force }) {
 
 /**
  * The operator bearer for this install: an explicit PERMAURA_TOKEN, else the one the gateway minted
- * into `operator.token` on clean bootstrap. Returns null when neither exists — a gateway initialised
+ * into `operator.token` on clean bootstrap. Returns null when neither exists: a gateway initialised
  * by an older build has a bearer we can't read, and inventing a shared one is exactly the hole this
  * closes. Callers degrade to manual pairing instead.
  */
@@ -488,7 +488,7 @@ async function waitHealthz(addr, tries = 20) {
 /**
  * Best-effort graceful stop: `POST /v1/shutdown` (operator-authed, loopback-only) asks the gateway to
  * drain in-flight requests and exit on its own. Resolves true on 202. Falls through to the caller's
- * hard kill on any failure — e.g. a clean (non-seeded) gateway where the demo token isn't valid.
+ * hard kill on any failure, e.g. a clean (non-seeded) gateway where the demo token isn't valid.
  */
 function postShutdown(addr, token) {
   return new Promise((resolve) => {
@@ -533,7 +533,7 @@ async function main() {
 
   if (!cmd) {
     if (forward.length) {
-      // Arguments but no command — a mistyped flag. It must not fall through to the bare-invocation
+      // Arguments but no command: a mistyped flag. It must not fall through to the bare-invocation
       // help and exit 0, and it certainly must not start anything.
       console.error(`${C.red("✗")} unknown argument${forward.length > 1 ? "s" : ""}: ${forward.join(", ")}\n`);
       console.error(usage());
@@ -546,7 +546,7 @@ async function main() {
   }
 
   if (!KNOWN.has(cmd)) {
-    // Exit before anything binds a port or downloads a binary — a mistyped command should cost
+    // Exit before anything binds a port or downloads a binary: a mistyped command should cost
     // nothing.
     console.error(`${C.red("✗")} unknown command: ${cmd}\n`);
     console.error(usage());
@@ -598,7 +598,7 @@ async function main() {
   const token = readOperatorToken();
   const pairing = forward.some((a) => a === "--pair" || a.startsWith("--pair="));
   if (!token) {
-    // The gateway is up and healthy — only adding it to an account needs the bearer. Say so plainly
+    // The gateway is up and healthy: only adding it to an account needs the bearer. Say so plainly
     // rather than guessing at a token.
     warn(
       `This gateway was initialised by an earlier build, so its operator token isn't readable here.\n    Re-pair from Console → Settings → Gateways, or re-run with PERMAURA_TOKEN=<token> set.`,

package/bin/lib.mjs

@@ -34,7 +34,7 @@ export function assetName(key) {
 /**
  * Sweep binaries parked by a previous rename-aside upgrade (D9 cleanup-on-start). Only sweeps when
  * a live binary exists at `binPath`: after a failed swap the newest `.old` may be the only working
- * copy on disk, and it must survive until a later successful swap replaces it. Best-effort — on
+ * copy on disk, and it must survive until a later successful swap replaces it. Best-effort: on
  * Windows a still-running old gateway keeps its file locked and is collected on a later run.
  */
 export function sweepOldBinaries(binPath, fsOps = fs) {
@@ -46,7 +46,7 @@ export function sweepOldBinaries(binPath, fsOps = fs) {
       try {
         fsOps.rmSync(path.join(dir, f), { force: true });
       } catch {
-        /* locked by a running process — leave it for next time */
+        /* locked by a running process, leave it for next time */
       }
     }
   }
@@ -55,7 +55,7 @@ export function sweepOldBinaries(binPath, fsOps = fs) {
 /**
  * Rename-aside swap (D9, the rustup pattern): park the current binary at `.old` (Windows can't
  * overwrite a running executable but CAN rename it), then move the verified download into place.
- * If that final rename fails, the parked binary is restored — there is a runnable binary at
+ * If that final rename fails, the parked binary is restored: there is a runnable binary at
  * `binPath` on every exit path, success or throw.
  */
 export function swapBinaryIntoPlace(binPath, tmpPath, fsOps = fs) {
@@ -80,7 +80,7 @@ export function swapBinaryIntoPlace(binPath, tmpPath, fsOps = fs) {
       try {
         fsOps.renameSync(parkedAt, binPath);
       } catch {
-        /* restore failed — surface the original swap error below */
+        /* restore failed: surface the original swap error below */
       }
     }
     throw e;
@@ -91,7 +91,7 @@ export function swapBinaryIntoPlace(binPath, tmpPath, fsOps = fs) {
  * Compare versions by semver precedence. `<0` if a<b, `0` equal, `>0` if a>b.
  *
  * The pre-release suffix is part of the order, not noise to be discarded. It used to be dropped, so
- * `1.2.5-dev.1` compared EQUAL to the released `1.2.5` and the upgrade was never offered — a
+ * `1.2.5-dev.1` compared EQUAL to the released `1.2.5` and the upgrade was never offered: a
  * dev build of a version permanently masked that version's real release, on exactly the machines
  * most likely to be running one.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "permaura",
-  "version": "1.3.26",
+  "version": "1.3.28",
   "description": "Run the Permaura gateway with one command. Give your AI agents permission, not keys. `npm i -g permaura` then `permaura start --pair <code>` installs the gateway, starts it, and connects it to your permaura.com account.",
   "license": "Apache-2.0",
   "type": "module",