@aloud/runner 0.2.3 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aloud/runner",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "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

@@ -8,7 +8,8 @@
  */
 import { createInterface } from "node:readline/promises";
 import { spawn } from "node:child_process";
-import { accessSync, constants, existsSync, readFileSync, unlinkSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { accessSync, constants, existsSync, openSync, readFileSync, unlinkSync } from "node:fs";
 import { hostname } from "node:os";
 import { delimiter, dirname, join } from "node:path";
 import { normaliseHosts } from "@aloud/core";
@@ -22,7 +23,7 @@ import {
   type Credentials,
 } from "./config/credentials";
 import { policyFrom, type LocalPolicy } from "./config/policy";
-import { clearRunning, readRunning, runningPath, writeRunning } from "./config/running";
+import { clearRunning, readRunning, runningPath, writeRunning, type RunningState } from "./config/running";
 import { RUNNER_VERSION } from "./version";
 import { RunnerClient } from "./protocol/client";
 import { installChromium, preflight } from "./preflight";
@@ -210,6 +211,7 @@ async function setup(): Promise<number> {
   const installed = onPath("aloud");
   const latest = await latestVersion();
   const stale = latest !== null && latest !== RUNNER_VERSION;
+  const signedIn = await signedInState(credentials);
 
   const out = (line = "") => process.stdout.write(line + "\n");
 
@@ -218,27 +220,56 @@ async function setup(): Promise<number> {
   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(
+    `  signed in      ${
+      signedIn.state === "ok"
+        ? signedIn.name
+        : signedIn.state === "revoked"
+          ? `no. The saved token for ${credentials?.runnerName ?? "this machine"} was revoked`
+          : signedIn.state === "unreachable"
+            ? `cannot tell, ${signedIn.server} did not answer`
+            : "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[] = [];
+  // Each step is a command plus the lines that qualify it. Only the command gets a number, or a
+  // continuation reads as a step of its own, and an agent following "step 2" ends up pasting a URL
+  // into a shell.
+  // A person in a terminal gets setup done, not a list of things to go and do. An agent, which has
+  // no terminal, gets the list. Same command, and the difference is who can answer a prompt.
+  if (process.stdin.isTTY) return interactiveSetup({ installed, stale, latest, signedIn, running, credentials });
+
+  const steps: string[][] = [];
   if (!installed) {
-    steps.push("npm install -g @aloud/runner");
+    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`);
+    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 (signedIn.state === "revoked") {
+    steps.push([
+      `Create a new token at ${credentials?.server ?? DEFAULT_SERVER}/app/settings/runners`,
+      "The saved one was revoked and cannot be reused.",
+    ]);
+  }
+  if (signedIn.state === "none" || signedIn.state === "revoked") {
+    steps.push([
+      "aloud login",
+      "Needs a terminal. If you are an agent, hand this step to the person: they run it",
+      "themselves and paste the token at the prompt. Do not ask them to paste it to you.",
+    ]);
   }
   if (!running) {
-    steps.push("aloud start    # in a background shell. It never exits.");
+    steps.push(["aloud start", "In a background shell. It never exits, so do not block on it."]);
+  }
+
+  if (steps.length === 0 && signedIn.state === "unreachable") {
+    out(`Cannot reach ${signedIn.server}, so there is nothing useful to say about what is left.`);
+    out("Check the connection and run this again.");
+    out();
+    return 1;
   }
 
   if (steps.length === 0) {
@@ -249,8 +280,12 @@ async function setup(): Promise<number> {
 
   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`);
+  for (const [index, [command, ...notes]] of steps.entries()) {
+    out(`  ${index + 1}. ${command}`);
+    for (const note of notes) out(`     ${note}`);
+  }
+  out(`  ${steps.length + 1}. aloud status`);
+  out("     Exits non-zero until all of the above are true.");
   out();
   out("Rules, if you are an agent doing this:");
   out();
@@ -277,6 +312,149 @@ async function setup(): Promise<number> {
   return 1;
 }
 
+
+
+/**
+ * Setup, performed rather than described.
+ *
+ * Everything here is a question first. Installing globally, writing a credential and starting a
+ * long-lived process are all things someone should agree to on their own machine, and the printed
+ * version of this command exists for the case where nobody can be asked.
+ */
+async function interactiveSetup(state: {
+  installed: boolean;
+  stale: boolean;
+  latest: string | null;
+  signedIn: { state: string };
+  running: RunningState | null;
+  credentials: Credentials | null;
+}): Promise<number> {
+  const out = (line = "") => process.stdout.write(line + "\n");
+  const server = state.credentials?.server ?? DEFAULT_SERVER;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+  try {
+    if (!state.installed || state.stale) {
+      const what = state.installed ? `Update to ${state.latest}` : "Install it globally";
+      if (await confirm(rl, `${what} with npm?`)) {
+        const ok = await run("npm", ["install", "-g", "@aloud/runner@latest"], out);
+        if (!ok) {
+          out("");
+          out("That install did not work. If it asked for permissions, do not use sudo:");
+          out("npm's global prefix belongs to you or it does not, and sudo papers over the wrong one.");
+          return 1;
+        }
+      }
+    }
+
+    if (state.signedIn.state !== "ok") {
+      out("");
+      if (state.signedIn.state === "revoked") {
+        out(`The token saved here was revoked, so this machine needs a new one.`);
+      }
+      out(`Create a token at ${server}/app/settings/runners`);
+      out("It is shown once. Copy it, then paste it below.");
+      out("");
+      const token = (await rl.question("Token: ")).trim();
+      rl.close();
+      const code = await login(["--token", token, "--server", server]);
+      if (code !== 0) return code;
+    } else {
+      rl.close();
+    }
+
+    if (!state.running) {
+      const second = createInterface({ input: process.stdin, output: process.stdout });
+      const start = await confirm(second, "Start the runner now, in the background?");
+      second.close();
+      if (!start) {
+        out("");
+        out("Start it when you are ready, and leave it running:  aloud start");
+        return 1;
+      }
+      return startDetached(out);
+    }
+
+    out("");
+    out("Set up. This machine is waiting for studies.");
+    out("");
+    return 0;
+  } finally {
+    rl.close();
+  }
+}
+
+/** Yes unless clearly refused: the answer to every question here is the reason they ran this. */
+async function confirm(rl: ReturnType<typeof createInterface>, question: string): Promise<boolean> {
+  const answer = (await rl.question(`${question} [Y/n] `)).trim().toLowerCase();
+  return answer === "" || answer === "y" || answer === "yes";
+}
+
+/** Runs a command, showing its output, because an install that says nothing looks like a hang. */
+async function run(command: string, args: readonly string[], out: (line?: string) => void): Promise<boolean> {
+  out("");
+  out(`  ${command} ${args.join(" ")}`);
+  return new Promise((resolve) => {
+    const child = spawn(command, [...args], { stdio: ["ignore", "pipe", "pipe"] });
+    child.stdout?.on("data", (chunk: Buffer) => out("  " + chunk.toString("utf8").trimEnd()));
+    child.stderr?.on("data", (chunk: Buffer) => out("  " + chunk.toString("utf8").trimEnd()));
+    child.on("error", () => resolve(false));
+    child.on("close", (code: number | null) => resolve(code === 0));
+  });
+}
+
+/**
+ * Starts the runner and lets go of it, so closing this terminal does not stop the machine.
+ *
+ * Output goes to a file rather than nowhere, because the first start downloads Chromium and a
+ * silent five minutes is indistinguishable from a hang.
+ */
+async function startDetached(out: (line?: string) => void): Promise<number> {
+  const log = join(dirname(credentialsPath()), "runner.log");
+  await mkdir(dirname(log), { recursive: true, mode: 0o700 });
+  const handle = openSync(log, "a");
+  const child = spawn(process.execPath, [process.argv[1] ?? "", "start"], {
+    detached: true,
+    stdio: ["ignore", handle, handle],
+  });
+  child.unref();
+
+  out("");
+  out(`Started in the background, pid ${child.pid}.`);
+  out(`  Output      ${log}`);
+  out("  Check it    aloud status");
+  out(`  Stop it     kill ${child.pid}`);
+  out("");
+  out("The first start downloads Chromium, about 350 MB, once. Studies will wait until it is done.");
+  out("");
+  return 0;
+}
+
+/**
+ * Whether the saved credential still works, asked of the server rather than assumed from the file.
+ *
+ * A credentials file proves a token was written here once, not that it is still good. Revoking a
+ * machine from the web app leaves the file exactly as it was, so reporting "signed in" from its
+ * presence sent an agent off to `aloud start`, which died on its first poll with a 401 and no
+ * explanation of what to do. This is the same endpoint `login` checks a token against.
+ */
+async function signedInState(
+  credentials: Credentials | null,
+): Promise<{ state: "none" } | { state: "ok"; name: string } | { state: "revoked" } | { state: "unreachable"; server: string }> {
+  if (!credentials) return { state: "none" };
+  try {
+    const response = await fetch(new URL("api/runner/me", credentials.server + "/"), {
+      headers: { authorization: `Bearer ${credentials.token}` },
+      signal: AbortSignal.timeout(5_000),
+    });
+    if (response.status === 401 || response.status === 403) return { state: "revoked" };
+    if (!response.ok) return { state: "unreachable", server: credentials.server };
+    return { state: "ok", name: credentials.runnerName };
+  } catch {
+    return { state: "unreachable", server: credentials.server };
+  }
+}
+
 /**
  * Where npm would put a global install, and whether it can be written to.
  *

package/src/run/execute.ts

@@ -336,8 +336,24 @@ function failureFrom(outcome: RunOutcome): string | null {
   return null;
 }
 
-function describeOutcome(result: { status: string; selfReportedOutcome?: string | null; selfReportedReason?: string | null }): string {
+/**
+ * The one line the person watching their own machine sees when a participant stops.
+ *
+ * The cap cases are named rather than folded into "finished", which is what they used to read as.
+ * A session the runtime cut off produced truncated evidence, and MONETIZATION treats that as a
+ * platform failure rather than a delivery, so the operator watching it happen should be told that
+ * plainly instead of being shown a word that means the opposite.
+ */
+function describeOutcome(result: {
+  status: string;
+  endReason?: string | null;
+  selfReportedOutcome?: string | null;
+  selfReportedReason?: string | null;
+}): string {
   if (result.status === "error") return "the browser stopped unexpectedly";
+  if (result.endReason === "cap_actions") return "ran out of actions before finishing";
+  if (result.endReason === "cap_elapsed") return "ran out of time before finishing";
+  if (result.endReason === "cap_tokens") return "ran out of its token budget before finishing";
   if (result.selfReportedOutcome === "success") return "reached the goal";
   if (result.selfReportedOutcome === "abandoned") return result.selfReportedReason ?? "gave up";
   return result.selfReportedOutcome ?? "finished";

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.3";
+export const RUNNER_VERSION = "0.2.5";
 
 /** The header the server reads it from. */
 export const RUNNER_VERSION_HEADER = "x-aloud-runner-version";