@aloud/runner 0.2.4 → 0.2.5

package/dist/cli.js

@@ -2578,9 +2578,10 @@ var init_src = __esm({
 init_src();
 import { createInterface } from "node:readline/promises";
 import { spawn as spawn2 } from "node:child_process";
-import { accessSync, constants as constants2, existsSync as existsSync2, readFileSync, unlinkSync } from "node:fs";
+import { mkdir as mkdir4 } from "node:fs/promises";
+import { accessSync, constants as constants2, existsSync as existsSync2, openSync, readFileSync, unlinkSync } from "node:fs";
 import { hostname } from "node:os";
-import { delimiter, join as join5 } from "node:path";
+import { delimiter, dirname as dirname4, join as join5 } from "node:path";
 
 // src/config/credentials.ts
 import { chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
@@ -2749,7 +2750,7 @@ function alive(pid) {
 }
 
 // src/version.ts
-var RUNNER_VERSION = "0.2.4";
+var RUNNER_VERSION = "0.2.5";
 var RUNNER_VERSION_HEADER = "x-aloud-runner-version";
 
 // src/protocol/client.ts
@@ -7292,13 +7293,13 @@ async function handleTool(context, name, input, execute) {
         }
         throw error;
       }
-      const { run, started, preflight: preflight2 } = outcome;
-      await execute?.(run.id, parsed.productId, started);
+      const { run: run2, started, preflight: preflight2 } = outcome;
+      await execute?.(run2.id, parsed.productId, started);
       return json({
-        runId: run.id,
-        resource: RESOURCE_SCHEMES.run(run.id),
-        webUrl: context.webBaseUrl ? `${context.webBaseUrl}/app/runs/${run.id}` : null,
-        status: run.status,
+        runId: run2.id,
+        resource: RESOURCE_SCHEMES.run(run2.id),
+        webUrl: context.webBaseUrl ? `${context.webBaseUrl}/app/runs/${run2.id}` : null,
+        status: run2.status,
         // SPEC FR-116: a retry with the same key reports that it found the existing run.
         alreadyRunning: !started,
         preflight: preflight2 ? summarisePreflight(preflight2) : null,
@@ -7326,8 +7327,8 @@ async function handleTool(context, name, input, execute) {
     }
     case "cancel_run": {
       const parsed = z25.object({ runId: z25.string(), reason: z25.string().optional() }).parse(input);
-      const run = await app.cancelRun(actor, { workspaceId, ...parsed });
-      return json({ runId: run.id, status: run.status });
+      const run2 = await app.cancelRun(actor, { workspaceId, ...parsed });
+      return json({ runId: run2.id, status: run2.status });
     }
     case "list_findings": {
       const parsed = RunIdInput.parse(input);
@@ -7699,7 +7700,7 @@ async function readResource(context, parsed) {
           name: study.name,
           goal: study.goal,
           status: study.status,
-          runs: runs.map((run) => ({ runId: run.id, status: run.status, resource: RESOURCE_SCHEMES.run(run.id) }))
+          runs: runs.map((run2) => ({ runId: run2.id, status: run2.status, resource: RESOURCE_SCHEMES.run(run2.id) }))
         },
         null,
         2
@@ -7955,6 +7956,7 @@ async function setup() {
   out(`  chromium       ${checks.chromiumInstalled ? "ready" : "downloads on first start, about 350 MB"}`);
   out(`  running        ${running ? `yes (pid ${running.pid})` : "no"}`);
   out();
+  if (process.stdin.isTTY) return interactiveSetup({ installed, stale, latest, signedIn, running, credentials });
   const steps = [];
   if (!installed) {
     steps.push(["npm install -g @aloud/runner"]);
@@ -8019,6 +8021,91 @@ async function setup() {
   }
   return 1;
 }
+async function interactiveSetup(state) {
+  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 start2 = await confirm(second, "Start the runner now, in the background?");
+      second.close();
+      if (!start2) {
+        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();
+  }
+}
+async function confirm(rl, question) {
+  const answer = (await rl.question(`${question} [Y/n] `)).trim().toLowerCase();
+  return answer === "" || answer === "y" || answer === "yes";
+}
+async function run(command, args, out) {
+  out("");
+  out(`  ${command} ${args.join(" ")}`);
+  return new Promise((resolve) => {
+    const child = spawn2(command, [...args], { stdio: ["ignore", "pipe", "pipe"] });
+    child.stdout?.on("data", (chunk) => out("  " + chunk.toString("utf8").trimEnd()));
+    child.stderr?.on("data", (chunk) => out("  " + chunk.toString("utf8").trimEnd()));
+    child.on("error", () => resolve(false));
+    child.on("close", (code) => resolve(code === 0));
+  });
+}
+async function startDetached(out) {
+  const log = join5(dirname4(credentialsPath()), "runner.log");
+  await mkdir4(dirname4(log), { recursive: true, mode: 448 });
+  const handle = openSync(log, "a");
+  const child = spawn2(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;
+}
 async function signedInState(credentials) {
   if (!credentials) return { state: "none" };
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aloud/runner",
-  "version": "0.2.4",
+  "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";
@@ -237,6 +238,10 @@ async function setup(): Promise<number> {
   // 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"]);
@@ -308,6 +313,123 @@ async function setup(): Promise<number> {
 }
 
 
+
+/**
+ * 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.
  *

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