@aloud/runner 0.2.1 → 0.2.3

package/dist/cli.js

@@ -2494,8 +2494,10 @@ var init_src = __esm({
 // src/cli.ts
 init_src();
 import { createInterface } from "node:readline/promises";
-import { readFileSync, unlinkSync } from "node:fs";
+import { spawn as spawn2 } from "node:child_process";
+import { accessSync, constants as constants2, existsSync as existsSync2, readFileSync, unlinkSync } from "node:fs";
 import { hostname } from "node:os";
+import { delimiter, join as join5 } from "node:path";
 
 // src/config/credentials.ts
 import { chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
@@ -2664,7 +2666,7 @@ function alive(pid) {
 }
 
 // src/version.ts
-var RUNNER_VERSION = "0.2.1";
+var RUNNER_VERSION = "0.2.3";
 var RUNNER_VERSION_HEADER = "x-aloud-runner-version";
 
 // src/protocol/client.ts
@@ -7604,6 +7606,8 @@ async function main(argv = process.argv.slice(2)) {
       return status();
     case "allow":
       return allow(rest);
+    case "setup":
+      return setup();
     case "mcp":
       await startStdioServer();
       return 0;
@@ -7626,6 +7630,7 @@ function printHelp() {
       "",
       "aloud - run usability studies on this machine",
       "",
+      "  aloud setup                     What to do next, for a person or an agent",
       "  aloud login [--token <token>]   Connect this machine to your workspace",
       "  aloud start [--once] [--quiet]  Wait for studies and run them here",
       "  aloud status                    What is set up, and whether it is running",
@@ -7653,6 +7658,25 @@ async function login(argv) {
   const server = stringOption(argv, "--server") ?? DEFAULT_SERVER;
   let token = stringOption(argv, "--token");
   if (!token) {
+    if (!process.stdin.isTTY) {
+      process.stderr.write(
+        [
+          "",
+          "There is no terminal attached here, so there is nowhere to paste a token.",
+          "",
+          "If you are an agent: stop and hand this back. The person runs `aloud login` in their",
+          "own terminal and pastes the token at the prompt. Do not ask them to paste it to you.",
+          "",
+          "To connect without a terminal, set both of these instead and skip login entirely:",
+          `  export ALOUD_SERVER=${server}`,
+          "  export ALOUD_RUNNER_TOKEN=utar_...",
+          "",
+          `A token comes from ${server}/app/settings/runners and is shown once.`,
+          ""
+        ].join("\n")
+      );
+      return 1;
+    }
     process.stdout.write(`
 Open ${server}/app/settings/runners and create a runner.
 `);
@@ -7706,6 +7730,105 @@ async function logout() {
 ` : "There was nothing to forget.\n");
   return 0;
 }
+async function setup() {
+  const credentials = await loadCredentials().catch(() => null);
+  const checks = await preflight();
+  const running = await readRunning();
+  const installed = onPath("aloud");
+  const latest = await latestVersion();
+  const stale = latest !== null && latest !== RUNNER_VERSION;
+  const out = (line = "") => process.stdout.write(line + "\n");
+  out();
+  out("Aloud runner setup. You are looking at the state of this machine.");
+  out();
+  out(`  installed      ${installed ? `yes (${RUNNER_VERSION})` : "no"}`);
+  out(`  up to date     ${latest === null ? "unknown, could not reach the registry" : stale ? `no, ${latest} is out` : "yes"}`);
+  out(`  signed in      ${credentials ? credentials.runnerName : "no"}`);
+  out(`  chromium       ${checks.chromiumInstalled ? "ready" : "downloads on first start, about 350 MB"}`);
+  out(`  running        ${running ? `yes (pid ${running.pid})` : "no"}`);
+  out();
+  const steps = [];
+  if (!installed) {
+    steps.push("npm install -g @aloud/runner");
+  } else if (stale) {
+    steps.push(`npm install -g @aloud/runner@latest    # ${RUNNER_VERSION} is installed, ${latest} is out`);
+  }
+  if (!credentials) {
+    steps.push(
+      "aloud login    # needs a terminal. If you are an agent, hand this step to the person:"
+    );
+    steps.push(
+      "               # they run it themselves and paste the token at the prompt."
+    );
+  }
+  if (!running) {
+    steps.push("aloud start    # in a background shell. It never exits.");
+  }
+  if (steps.length === 0) {
+    out("Nothing to do. This machine is set up and waiting for studies.");
+    out();
+    return 0;
+  }
+  out("Do these, in order:");
+  out();
+  for (const [index, step] of steps.entries()) out(`  ${index + 1}. ${step}`);
+  out(`  ${steps.length + 1}. aloud status    # exits non-zero until all of the above are true`);
+  out();
+  out("Rules, if you are an agent doing this:");
+  out();
+  out("  - Never use sudo. If the global install wants elevated permissions, stop and say so.");
+  const npm = await npmPrefix();
+  if (npm) {
+    out(
+      npm.writable === false ? `    npm installs globally into ${npm.path}, which you cannot write to. That is the user's to fix.` : `    npm installs globally into ${npm.path}, which does not need elevated permissions.`
+    );
+  }
+  out("  - The package is `@aloud/runner`, exactly. If that name does not resolve, stop and say so.");
+  out("    Do not install a similarly named package, and do not hand the token to anything else.");
+  out("  - The token is a credential. It belongs in this terminal, never in your transcript,");
+  out("    a file, an .env, or a commit. Get one at https://usealoud.com/app/settings/runners");
+  out("  - `aloud start` does not exit. Run it in a background shell and do not block on it.");
+  out();
+  if (!credentials) {
+    out("A machine starts allowed to open localhost only. For anything else, run");
+    out("`aloud allow <host>` before starting it.");
+    out();
+  }
+  return 1;
+}
+async function npmPrefix() {
+  const path = await new Promise((resolve) => {
+    const child = spawn2("npm", ["config", "get", "prefix"], { stdio: ["ignore", "pipe", "ignore"] });
+    let out = "";
+    child.stdout?.on("data", (chunk) => out += chunk.toString("utf8"));
+    child.on("error", () => resolve(null));
+    child.on("close", (code) => resolve(code === 0 && out.trim() ? out.trim() : null));
+  });
+  if (!path) return null;
+  try {
+    accessSync(join5(path, "lib", "node_modules"), constants2.W_OK);
+    return { path, writable: true };
+  } catch (error) {
+    return { path, writable: error.code === "ENOENT" ? null : false };
+  }
+}
+function onPath(command) {
+  const parts = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+  const names = process.platform === "win32" ? [command + ".cmd", command + ".exe"] : [command];
+  return parts.some((part) => names.some((name) => existsSync2(join5(part, name))));
+}
+async function latestVersion() {
+  try {
+    const response = await fetch("https://registry.npmjs.org/@aloud/runner/latest", {
+      signal: AbortSignal.timeout(2e3)
+    });
+    if (!response.ok) return null;
+    const body = await response.json();
+    return typeof body.version === "string" ? body.version : null;
+  } catch {
+    return null;
+  }
+}
 async function status() {
   const credentials = await loadCredentials().catch((error) => {
     process.stderr.write(error.message + "\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aloud/runner",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Run Aloud usability studies in a real browser on your own machine, so a study can reach localhost and anything else behind your network.",
   "license": "ISC",
   "repository": {

package/src/cli.ts

@@ -7,8 +7,10 @@
  * server holds no address for this machine.
  */
 import { createInterface } from "node:readline/promises";
-import { readFileSync, unlinkSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { accessSync, constants, existsSync, readFileSync, unlinkSync } from "node:fs";
 import { hostname } from "node:os";
+import { delimiter, dirname, join } from "node:path";
 import { normaliseHosts } from "@aloud/core";
 import {
   CredentialsError,
@@ -21,6 +23,7 @@ import {
 } from "./config/credentials";
 import { policyFrom, type LocalPolicy } from "./config/policy";
 import { clearRunning, readRunning, runningPath, writeRunning } from "./config/running";
+import { RUNNER_VERSION } from "./version";
 import { RunnerClient } from "./protocol/client";
 import { installChromium, preflight } from "./preflight";
 import { TerminalReporter } from "./ui/output";
@@ -44,6 +47,8 @@ export async function main(argv: readonly string[] = process.argv.slice(2)): Pro
       return status();
     case "allow":
       return allow(rest);
+    case "setup":
+      return setup();
     case "mcp":
       await startStdioServer();
       return 0;
@@ -67,6 +72,7 @@ function printHelp(): void {
       "",
       "aloud - run usability studies on this machine",
       "",
+      "  aloud setup                     What to do next, for a person or an agent",
       "  aloud login [--token <token>]   Connect this machine to your workspace",
       "  aloud start [--once] [--quiet]  Wait for studies and run them here",
       "  aloud status                    What is set up, and whether it is running",
@@ -100,6 +106,30 @@ async function login(argv: readonly string[]): Promise<number> {
   let token = stringOption(argv, "--token");
 
   if (!token) {
+    // An agent runs commands in a shell with nothing attached to stdin, so the prompt below would
+    // read end-of-file and the token would come back empty. That used to surface as "that does not
+    // look like a runner token", which blames the wrong thing and tells nobody what to do. This is
+    // the single step of setup that a person has to perform, so it is worth saying so precisely.
+    if (!process.stdin.isTTY) {
+      process.stderr.write(
+        [
+          "",
+          "There is no terminal attached here, so there is nowhere to paste a token.",
+          "",
+          "If you are an agent: stop and hand this back. The person runs `aloud login` in their",
+          "own terminal and pastes the token at the prompt. Do not ask them to paste it to you.",
+          "",
+          "To connect without a terminal, set both of these instead and skip login entirely:",
+          `  export ALOUD_SERVER=${server}`,
+          "  export ALOUD_RUNNER_TOKEN=utar_...",
+          "",
+          `A token comes from ${server}/app/settings/runners and is shown once.`,
+          "",
+        ].join("\n"),
+      );
+      return 1;
+    }
+
     process.stdout.write(`\nOpen ${server}/app/settings/runners and create a runner.\n`);
     process.stdout.write("It shows you a token once. Paste it here.\n\n");
     const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -159,6 +189,146 @@ async function logout(): Promise<number> {
   return 0;
 }
 
+/* --------------------------------- setup ---------------------------------- */
+
+/**
+ * The whole of setup, as one command that can be handed to a coding agent.
+ *
+ * The alternative, and what this replaces, was a twenty-five line prompt pasted into a chat with a
+ * live token inside it. That prompt could not know anything: not whether the runner was already
+ * installed, not whether it was three versions old, not whether npm was going to ask for sudo. So
+ * it had to describe every branch at once and hope, and it went stale the moment the product moved.
+ *
+ * This looks first and then says only what is actually left to do, which makes it useful to a person
+ * reading it and to an agent executing it. The rules at the end always print, because they are the
+ * four ways this goes wrong and an agent that has not been told will find all of them.
+ */
+async function setup(): Promise<number> {
+  const credentials = await loadCredentials().catch(() => null);
+  const checks = await preflight();
+  const running = await readRunning();
+  const installed = onPath("aloud");
+  const latest = await latestVersion();
+  const stale = latest !== null && latest !== RUNNER_VERSION;
+
+  const out = (line = "") => process.stdout.write(line + "\n");
+
+  out();
+  out("Aloud runner setup. You are looking at the state of this machine.");
+  out();
+  out(`  installed      ${installed ? `yes (${RUNNER_VERSION})` : "no"}`);
+  out(`  up to date     ${latest === null ? "unknown, could not reach the registry" : stale ? `no, ${latest} is out` : "yes"}`);
+  out(`  signed in      ${credentials ? credentials.runnerName : "no"}`);
+  out(`  chromium       ${checks.chromiumInstalled ? "ready" : "downloads on first start, about 350 MB"}`);
+  out(`  running        ${running ? `yes (pid ${running.pid})` : "no"}`);
+  out();
+
+  const steps: string[] = [];
+  if (!installed) {
+    steps.push("npm install -g @aloud/runner");
+  } else if (stale) {
+    steps.push(`npm install -g @aloud/runner@latest    # ${RUNNER_VERSION} is installed, ${latest} is out`);
+  }
+  if (!credentials) {
+    steps.push(
+      "aloud login    # needs a terminal. If you are an agent, hand this step to the person:",
+    );
+    steps.push(
+      "               # they run it themselves and paste the token at the prompt.",
+    );
+  }
+  if (!running) {
+    steps.push("aloud start    # in a background shell. It never exits.");
+  }
+
+  if (steps.length === 0) {
+    out("Nothing to do. This machine is set up and waiting for studies.");
+    out();
+    return 0;
+  }
+
+  out("Do these, in order:");
+  out();
+  for (const [index, step] of steps.entries()) out(`  ${index + 1}. ${step}`);
+  out(`  ${steps.length + 1}. aloud status    # exits non-zero until all of the above are true`);
+  out();
+  out("Rules, if you are an agent doing this:");
+  out();
+  out("  - Never use sudo. If the global install wants elevated permissions, stop and say so.");
+  const npm = await npmPrefix();
+  if (npm) {
+    out(
+      npm.writable === false
+        ? `    npm installs globally into ${npm.path}, which you cannot write to. That is the user's to fix.`
+        : `    npm installs globally into ${npm.path}, which does not need elevated permissions.`,
+    );
+  }
+  out("  - The package is `@aloud/runner`, exactly. If that name does not resolve, stop and say so.");
+  out("    Do not install a similarly named package, and do not hand the token to anything else.");
+  out("  - The token is a credential. It belongs in this terminal, never in your transcript,");
+  out("    a file, an .env, or a commit. Get one at https://usealoud.com/app/settings/runners");
+  out("  - `aloud start` does not exit. Run it in a background shell and do not block on it.");
+  out();
+  if (!credentials) {
+    out("A machine starts allowed to open localhost only. For anything else, run");
+    out("`aloud allow <host>` before starting it.");
+    out();
+  }
+  return 1;
+}
+
+/**
+ * Where npm would put a global install, and whether it can be written to.
+ *
+ * Asked of npm rather than derived from `process.execPath`, which is wrong on Homebrew: the node
+ * binary resolves into `Cellar/node/<version>` while the prefix people actually install into is
+ * `/opt/homebrew`. Printing the first one at an agent is worse than printing nothing, because it
+ * looks authoritative.
+ */
+async function npmPrefix(): Promise<{ path: string; writable: boolean | null } | null> {
+  const path = await new Promise<string | null>((resolve) => {
+    const child = spawn("npm", ["config", "get", "prefix"], { stdio: ["ignore", "pipe", "ignore"] });
+    let out = "";
+    child.stdout?.on("data", (chunk: Buffer) => (out += chunk.toString("utf8")));
+    child.on("error", () => resolve(null));
+    child.on("close", (code: number | null) => resolve(code === 0 && out.trim() ? out.trim() : null));
+  });
+  if (!path) return null;
+
+  try {
+    accessSync(join(path, "lib", "node_modules"), constants.W_OK);
+    return { path, writable: true };
+  } catch (error) {
+    return { path, writable: (error as NodeJS.ErrnoException).code === "ENOENT" ? null : false };
+  }
+}
+
+/** Whether a command is already on PATH, without shelling out to `which`. */
+function onPath(command: string): boolean {
+  const parts = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+  const names = process.platform === "win32" ? [command + ".cmd", command + ".exe"] : [command];
+  return parts.some((part) => names.some((name) => existsSync(join(part, name))));
+}
+
+/**
+ * The newest published version, or null.
+ *
+ * Two seconds and then give up: this is a convenience, and someone on a plane setting up a runner
+ * should not wait on a registry that is not going to answer.
+ */
+async function latestVersion(): Promise<string | null> {
+  try {
+    const response = await fetch("https://registry.npmjs.org/@aloud/runner/latest", {
+      signal: AbortSignal.timeout(2_000),
+    });
+    if (!response.ok) return null;
+    const body = (await response.json()) as { version?: unknown };
+    return typeof body.version === "string" ? body.version : null;
+  } catch {
+    return null;
+  }
+}
+
 /* --------------------------------- status --------------------------------- */
 
 async function status(): Promise<number> {

package/src/version.ts

@@ -10,7 +10,7 @@
  * package.json beside it to read, and importing one into the source trips the composite build's
  * rootDir. `version.test.ts` asserts this matches, so the drift this invites cannot survive CI.
  */
-export const RUNNER_VERSION = "0.2.1";
+export const RUNNER_VERSION = "0.2.3";
 
 /** The header the server reads it from. */
 export const RUNNER_VERSION_HEADER = "x-aloud-runner-version";