@skillcdn/console 0.1.6 → 0.1.8

package/src/cli/help.ts

@@ -0,0 +1,326 @@
+import {
+  MAX_AGENT_LENGTH,
+  MAX_ARTIFACTS_PER_RUN,
+  MAX_BODY_LENGTH,
+  MAX_DOCUMENT_LENGTH,
+  MAX_DOCUMENT_PATH_LENGTH,
+  MAX_FILE_BYTES,
+  MAX_FILES_PER_DOCUMENT,
+  MAX_LINK_LABEL_LENGTH,
+  MAX_OPTION_LABEL_LENGTH,
+  MAX_OPTIONS,
+  MAX_QUESTION_LENGTH,
+  MAX_REPORTS_PER_RUN,
+  MAX_SUMMARY_LENGTH,
+  MAX_TITLE_LENGTH,
+  MAX_VERSIONS_PER_DOCUMENT,
+  MIN_OPTIONS,
+} from "../limits.js";
+
+// What the command says about itself: for an agent that meets it for the first time, and for a
+// person. One table for every command, from which the usage and each command's help are made:
+// the overview says what each command does, and a command's own help adds the limits the
+// console holds it to and the refusals it may meet, so that an agent learns them before it
+// runs into them.
+
+export interface CommandHelp {
+  /** The command and its arguments, after `console`. */
+  readonly usage: string;
+  /** What it does, in a sentence. */
+  readonly about: string;
+  /** What the console holds the arguments to. */
+  readonly limits?: readonly string[];
+  /** What the console may refuse, by code, and what to do then. */
+  readonly refusals?: readonly string[];
+}
+
+/** The refusals any command may meet, said once in the overview. */
+const COMMON_REFUSALS = [
+  "auth.required: the token is not one the console knows, any more or at all; a person signs the command in again",
+  "request.invalid: what was sent is over a limit or malformed; the message names the field",
+  "network: the console could not be reached at its address",
+];
+
+const RUN_REFUSALS = [
+  "run.not_yours: the run is another person's",
+  "run.over: the run has ended already",
+];
+
+const MARKDOWN = `Markdown, up to ${MAX_BODY_LENGTH} characters`;
+
+const DOCUMENT_PATH = `a path of lowercase letters, digits and hyphens, with slashes between its folders (guides/onboarding), up to ${MAX_DOCUMENT_PATH_LENGTH} characters; it does not change once written`;
+const DOCUMENT_REFUSALS = ["document.not_found: no page has that path in this project"];
+
+export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
+  login: {
+    usage: "login --url <origin> [--agent <name>] [--token-stdin]",
+    about:
+      "Connects this agent to the console: shows an address and a code, which a person opens signed in, names the agent and approves; the command then receives a token of its own and keeps it, with the console's address, in your home directory, never showing it. An agent running the command relays the address and the code to its person and waits. --agent says what the agent calls itself. --token-stdin reads a token made by hand from standard input instead, for a script or a job.",
+    refusals: [
+      "connect.not_found: the code was not approved in time, or the person said it was not theirs; run login again",
+      "the console does not know the token given: make one on the Agents page and try again",
+    ],
+  },
+  logout: {
+    usage: "logout",
+    about:
+      "Forgets the address and the token kept here. The token itself is removed on the Agents page.",
+  },
+  whoami: {
+    usage: "whoami",
+    about:
+      "Who the token acts as, which console it is for, and which project this directory works in.",
+  },
+  projects: {
+    usage: "projects",
+    about:
+      "The projects you may work in: each with its key, its name, what you are in it, and what waits in it. Every command on the board works in one project.",
+  },
+  use: {
+    usage: "use <key>",
+    about:
+      "Says which project this directory works in: writes .skillcdn-console.json here, which the commands read from this directory or one above it, and which is meant to be committed. --project <key> on any command, or CONSOLE_PROJECT in the environment, wins over it.",
+    refusals: ["project.not_found: no project has the key, or it is not yours to see"],
+  },
+  tasks: {
+    usage: "tasks [--state <state>]",
+    about:
+      "The tasks on the board, newest first: number, state, priority, title, who owns and works on each, and what waits on it. States: idea, ready, in_progress, in_review, done, dropped.",
+  },
+  task: {
+    usage:
+      "task <number|id>  |  task new <title> [--body <markdown>|--file <path>] [--state <state>] [--priority <priority>]",
+    about:
+      "One task in full, with the decisions about it and the runs on it; or a new task written down (priorities: low, normal, high, urgent).",
+    limits: [`title: one line, up to ${MAX_TITLE_LENGTH} characters`, `body: ${MARKDOWN}`],
+    refusals: ["task.not_found: no task has that number or id"],
+  },
+  skills: {
+    usage: "skills",
+    about:
+      "The organization's skills, as SkillCDN serves them at the console's address: each with its description and the URI you load it by through your own SkillCDN connection. --json adds the page of each, for a person.",
+  },
+  take: {
+    usage: "take <number|id> [--agent <name>]",
+    about:
+      "Takes a task: a run begins, and the task is in progress and the person's. One agent at a time per task. --agent is what people see at work; left out, it is what the person called the token.",
+    limits: [`agent: one line, up to ${MAX_AGENT_LENGTH} characters`],
+    refusals: [
+      "task.not_found: no task has that number or id",
+      "run.task_taken: a run is open on the task already; console runs --open --mine shows whether it is yours",
+      "run.task_closed: the task is done or dropped",
+    ],
+  },
+  report: {
+    usage: "report <markdown>  |  report --file <path>  |  report -",
+    about:
+      "Says how the work goes, in Markdown: what was found, what was done, what is next. A milestone at a time, not every step. With - the report is read from standard input.",
+    limits: [
+      `the report: ${MARKDOWN}, not blank`,
+      `at most ${MAX_REPORTS_PER_RUN} reports on one run`,
+    ],
+    refusals: [...RUN_REFUSALS, "run.too_many_reports: the run carries as many as one may"],
+  },
+  "hand-in": {
+    usage: "hand-in <https url | file path> [--label <words>]",
+    about:
+      "Hands in what was made: a link (a branch, a pull request, a document, a page), or a file from this machine, which the console keeps and shows on the task.",
+    limits: [
+      "a link: https only",
+      `a file: up to ${MAX_FILE_BYTES} bytes, not empty; it is called by its name, without the path`,
+      `label: one line, up to ${MAX_LINK_LABEL_LENGTH} characters`,
+      `at most ${MAX_ARTIFACTS_PER_RUN} links and files on one run`,
+    ],
+    refusals: [
+      ...RUN_REFUSALS,
+      "run.too_many_artifacts: the run carries as many as one may",
+      "request.too_large: the file is over the limit",
+    ],
+  },
+  ask: {
+    usage:
+      'ask "<question>" --option "<label>" --option "<label>" [...] [--body <markdown>|--file <path>] [--wait <seconds>]',
+    about:
+      "Raises a decision a person must make: the question, the options to choose from, and what they need to know. The run waits for the answer. The command waits 60 seconds for it unless --wait says otherwise, and exits with 3 if it is still to come: keep waiting with `console decision <id> --wait 100`, within what your shell gives one command, and go on meanwhile only with work that does not depend on the answer. The decision's id is printed as soon as it is raised.",
+    limits: [
+      `question: one line, up to ${MAX_QUESTION_LENGTH} characters`,
+      `options: ${MIN_OPTIONS} to ${MAX_OPTIONS}, each one line up to ${MAX_OPTION_LABEL_LENGTH} characters`,
+      `body: ${MARKDOWN}`,
+    ],
+    refusals: ["decision.invalid_run: the run is not yours, or is over"],
+  },
+  decision: {
+    usage: "decision <id> [--wait <seconds>]  |  decision <id> --outcome <markdown>|--file <path>",
+    about:
+      "One decision, with its context, its options, its answer and what followed. With --wait, holds on for the answer that long, and exits with 3 if it is still to come. With --outcome, writes down what followed the decision, so that it reads as a record.",
+    limits: [`outcome: ${MARKDOWN}`],
+    refusals: ["decision.not_found: no decision has that id"],
+  },
+  decisions: {
+    usage: "decisions [--open]",
+    about: "The decisions on the board, the waiting first; --open keeps only those.",
+  },
+  finish: {
+    usage: 'finish [--summary "<markdown>"|--file <path>]',
+    about:
+      "Ends the run: the work is done and handed in, and the task goes up for review. The summary says what was done and what is left; the result itself goes in a last report before, which may be much longer.",
+    limits: [`summary: ${`Markdown, up to ${MAX_SUMMARY_LENGTH} characters`}`],
+    refusals: RUN_REFUSALS,
+  },
+  fail: {
+    usage: 'fail [--summary "<markdown>"|--file <path>]',
+    about: "Ends the run: the work could not be done. The summary says why, and what is left.",
+    limits: [`summary: Markdown, up to ${MAX_SUMMARY_LENGTH} characters`],
+    refusals: RUN_REFUSALS,
+  },
+  abandon: {
+    usage: 'abandon [<run id>] [--summary "<markdown>"]',
+    about:
+      "Leaves a run; the task stays as it is. A person gives up this way on a run of theirs that will not come back.",
+    limits: [`summary: Markdown, up to ${MAX_SUMMARY_LENGTH} characters`],
+    refusals: RUN_REFUSALS,
+  },
+  runs: {
+    usage: "runs [--task <number|id>] [--open] [--mine]",
+    about:
+      "The runs, newest first: agents at work and what they did. --mine keeps those begun with this token.",
+  },
+  run: {
+    usage: "run <id>",
+    about: "One run in full: its reports, what it handed in, what it waits for, how it ended.",
+    refusals: ["run.not_found: no run has that id"],
+  },
+  docs: {
+    usage: "docs [<folder>] [--search <words>] [--archived]",
+    about:
+      "The pages of the project's documents: those in a folder, with the folders in it (the root when none is named), or those found by words in their title or body. Archived pages are left out unless --archived.",
+  },
+  doc: {
+    usage: "doc <path> [--version <n>|--versions]",
+    about:
+      "One page in full: its title, its body in Markdown, what it links to, what refers to it (pages, tasks, decisions), and its files. --versions lists its versions, who wrote each and when; --version <n> prints one as it was.",
+    refusals: [...DOCUMENT_REFUSALS, "document.version_not_found: the page has no such version"],
+  },
+  write: {
+    usage: 'write <path> [--title "<title>"] --body <markdown>|--file <path> [--base <version>]',
+    about:
+      "Writes a page: the first version at a new path, or a new version of the page there. A link in the body whose destination is a page's path (guides/onboarding) refers to that page, and the page says what refers to it. Without --title the page keeps its title. With --base, the write is refused if the page has moved on since that version.",
+    limits: [
+      `path: ${DOCUMENT_PATH}`,
+      `title: one line, up to ${MAX_TITLE_LENGTH} characters`,
+      `body: Markdown, up to ${MAX_DOCUMENT_LENGTH} characters`,
+      `at most ${MAX_VERSIONS_PER_DOCUMENT} versions of one page`,
+    ],
+    refusals: [
+      "document.invalid_path: the path is not one",
+      "document.conflict: the page has moved on since --base; read it again",
+      "document.archived: the page is archived; restore it first",
+      "document.too_many_versions: the page carries as many versions as one may; write a new page",
+    ],
+  },
+  attach: {
+    usage: "attach <path> <file> [--label <words>]",
+    about:
+      "Attaches a file from this machine to a page: the console keeps it, and the page shows it.",
+    limits: [
+      `a file: up to ${MAX_FILE_BYTES} bytes, not empty; it is called by its name, without the path`,
+      `at most ${MAX_FILES_PER_DOCUMENT} files on one page`,
+    ],
+    refusals: [
+      ...DOCUMENT_REFUSALS,
+      "document.archived: the page is archived; restore it first",
+      "document.too_many_files: the page carries as many files as one may",
+      "request.too_large: the file is over the limit",
+    ],
+  },
+  archive: {
+    usage: "archive <path>",
+    about:
+      "Puts a page away: out of the folders and the search, still readable at its path, not written to until restored. Nothing is deleted.",
+    refusals: DOCUMENT_REFUSALS,
+  },
+  restore: {
+    usage: "restore <path>",
+    about: "Brings an archived page back.",
+    refusals: DOCUMENT_REFUSALS,
+  },
+  serve: {
+    usage: "serve [<dir>] [--port <n>]",
+    about:
+      "For a person: serves a console of your own from this machine, for you. The build in <dir> (its index.html and files) is served at http://127.0.0.1:11197/, and everything under /api/ is carried to the console you are signed in to with your token, which the pages never see. Without a directory only the API is served there, for a development server to send its /api/ requests to. The loopback only; a request from another site's page is refused. Stop it with Ctrl+C.",
+    refusals: ["not a build to serve: the directory holds no index.html"],
+  },
+};
+
+/** The first lines of the usage, with the version of the command when it is known. */
+const preamble = (version: string | undefined): string =>
+  `console${version === undefined ? "" : ` ${version}`}: the board of your organization's work with AI agents, from the command line.
+You act as the person whose token you hold; everything you send is shown to people as text.
+
+Usage: console <command> [arguments] [--json] [--url <origin>] [--project <key>]
+`;
+
+const CLOSING = `Options everywhere: --json answers with the console's own JSON; --url names another console;
+--project names the project to work in, over CONSOLE_PROJECT and over what console use kept here.
+Commands on a run (report, hand-in, ask, finish, fail) act on your one open run in the project;
+with several open, say which with --run <id>. A Markdown body given as - is read from standard input.
+console help <command> says what each command takes, the limits the console holds it to, and
+what it may refuse. console --version says which version of the command this is.
+
+Exit codes: 0 done; 1 the console refused, or could not be reached (the reason is on stderr);
+2 the command was not understood; 3 the decision still waits for a person.
+What the console refuses is printed as its code and its words. Everywhere:
+${COMMON_REFUSALS.map((refusal) => `  ${refusal}`).join("\n")}
+
+Credentials: CONSOLE_URL and CONSOLE_TOKEN in the environment, else what login kept in
+$XDG_CONFIG_HOME/skillcdn-console/credentials.json (~/.config when XDG_CONFIG_HOME is unset).
+`;
+
+const SECTIONS: readonly { readonly title: string; readonly commands: readonly string[] }[] = [
+  {
+    title: "Signing in, once, as a person, and the project to work in",
+    commands: ["login", "logout", "whoami", "projects", "use"],
+  },
+  {
+    title: "The board",
+    commands: ["tasks", "task", "decisions", "decision", "runs", "run", "skills"],
+  },
+  { title: "Working", commands: ["take", "report", "hand-in", "ask", "finish", "fail", "abandon"] },
+  {
+    title: "The documents: the project's pages of Markdown, in folders, by path",
+    commands: ["docs", "doc", "write", "attach", "archive", "restore"],
+  },
+];
+
+/** The whole usage, as `console help` prints it, naming the version when it is known. */
+export function usage(version?: string): string {
+  const parts = [preamble(version)];
+  for (const section of SECTIONS) {
+    parts.push(`${section.title}`);
+    for (const name of section.commands) {
+      const help = COMMAND_HELP[name];
+      if (help !== undefined) {
+        parts.push(`  console ${help.usage}\n      ${help.about}`);
+      }
+    }
+    parts.push("");
+  }
+  parts.push(CLOSING);
+  return parts.join("\n");
+}
+
+/** What `console help <command>` prints, or nothing for a command that is not one. */
+export function helpFor(name: string): string | undefined {
+  const help = COMMAND_HELP[name];
+  if (help === undefined) {
+    return undefined;
+  }
+  const parts = [`console ${help.usage}`, "", help.about];
+  if (help.limits !== undefined) {
+    parts.push("", "Limits:", ...help.limits.map((limit) => `  ${limit}`));
+  }
+  if (help.refusals !== undefined) {
+    parts.push("", "Refusals:", ...help.refusals.map((refusal) => `  ${refusal}`));
+  }
+  return `${parts.join("\n")}\n`;
+}

package/src/cli/main.ts

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { hostname } from "node:os";
+import process from "node:process";
+import * as z from "zod/mini";
+import { runCli } from "./cli.js";
+import { createFileStore, defaultConfigDir } from "./credentials.js";
+import { createDirectoryStore } from "./directory.js";
+import { listenOn } from "./serve.js";
+import { readBytesAt, readFileAt, readStdin } from "./terminal.js";
+
+// The `console` command: the only place the command reads the process. Everything it does is in
+// cli.ts, which takes what it needs and is what the tests run.
+
+/** The version of the package this file runs from: its own manifest, two levels above dist/cli. */
+const manifest = z
+  .object({ version: z.string() })
+  .safeParse(createRequire(import.meta.url)("../../package.json"));
+
+process.exitCode = await runCli(process.argv.slice(2), {
+  env: process.env,
+  stdout: (text) => {
+    process.stdout.write(text);
+  },
+  stderr: (text) => {
+    process.stderr.write(text);
+  },
+  fetch: (input, init) => fetch(input, init),
+  readStdin,
+  hostname: hostname(),
+  readFile: readFileAt,
+  readBytes: readBytesAt,
+  store: createFileStore(defaultConfigDir(process.env)),
+  directory: createDirectoryStore(process.cwd()),
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  now: () => Date.now(),
+  version: manifest.success ? manifest.data.version : undefined,
+  listen: listenOn,
+});

package/src/cli/serve.ts

@@ -0,0 +1,276 @@
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import type { ReadableStream as NodeReadableStream } from "node:stream/web";
+import type { FetchLike } from "../client.js";
+import type { WebRoot } from "../web.js";
+
+// A console of a person's own, served from their machine (ADR-0014): the files of a build, and
+// everything under /api/ carried to the organization's console with the token the command
+// keeps. The page and the API share one origin on the loopback, so the page needs no token and
+// the organization's console no allowance: it sees a token's requests, as it sees the command's.
+
+/** Where the command listens when nothing is said: next to the api role's 11199 and the dev UI's 11198. */
+export const DEFAULT_SERVE_PORT = 11197;
+
+/** The one address the command listens on. */
+export const LOOPBACK = "127.0.0.1";
+
+export interface ServeOptions {
+  /** The origin of the organization's console, where the API is. */
+  readonly upstream: string;
+  /** The token the requests are carried with: the person's standing, never given to the page. */
+  readonly token: string;
+  readonly fetch: FetchLike;
+  /** The port the command listens on: what a request's host must name. */
+  readonly port: number;
+  /** The build to serve, or none: then only the API is here, for a development server to send it to. */
+  readonly web?: WebRoot | undefined;
+}
+
+export type ServeHandler = (request: Request) => Promise<Response>;
+
+/** Headers that belong to one connection and never travel over the next. */
+const HOP_BY_HOP: ReadonlySet<string> = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "proxy-connection",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+]);
+
+/**
+ * What of the browser's request does not go to the console: the loopback's host, anything of a
+ * session (the token is the credential), what names the page's origin (a token's request needs
+ * none), and the encodings the browser takes, since what comes back is passed on decoded.
+ */
+const NOT_FORWARDED: ReadonlySet<string> = new Set([
+  "host",
+  "cookie",
+  "authorization",
+  "origin",
+  "referer",
+  "accept-encoding",
+]);
+
+/** What of the console's answer does not go to the browser: a cookie would be the loopback's, and the body arrives decoded. */
+const NOT_ANSWERED: ReadonlySet<string> = new Set([
+  "set-cookie",
+  "content-encoding",
+  "content-length",
+]);
+
+const json = (status: number, code: string, message: string): Response =>
+  new Response(JSON.stringify({ error: { code, message } }), {
+    status,
+    headers: { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" },
+  });
+
+const plain = (status: number, message: string): Response =>
+  new Response(`${message}\n`, {
+    status,
+    headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" },
+  });
+
+/**
+ * Whether a request to the API comes from the console's own page, or from no page at all.
+ * Browsers say which site a request comes from, and one from another site is that site's
+ * request made with the person's standing: refused. A browser too old to say names the page's
+ * origin on a request that changes something, which is compared instead. A request that says
+ * nothing of either is not a browser's.
+ */
+function fromOwnPage(request: Request, origin: string): boolean {
+  const site = request.headers.get("sec-fetch-site");
+  if (site !== null) {
+    return site === "same-origin" || site === "none";
+  }
+  const from = request.headers.get("origin");
+  return from === null || from === origin;
+}
+
+async function forward(
+  request: Request,
+  url: URL,
+  upstream: string,
+  options: ServeOptions,
+): Promise<Response> {
+  const headers = new Headers();
+  request.headers.forEach((value, name) => {
+    if (!HOP_BY_HOP.has(name) && !NOT_FORWARDED.has(name) && !name.startsWith("sec-")) {
+      headers.set(name, value);
+    }
+  });
+  headers.set("authorization", `Bearer ${options.token}`);
+  headers.set("accept-encoding", "identity");
+  const withBody = request.method !== "GET" && request.method !== "HEAD";
+  let answer: Response;
+  try {
+    answer = await options.fetch(`${upstream}${url.pathname}${url.search}`, {
+      method: request.method,
+      headers,
+      body: withBody ? request.body : undefined,
+      redirect: "manual",
+      signal: request.signal,
+      // A streamed body has to be declared as such.
+      ...(withBody ? { duplex: "half" } : {}),
+    } as RequestInit);
+  } catch {
+    return json(502, "network", "The console could not be reached.");
+  }
+  const out = new Headers();
+  answer.headers.forEach((value, name) => {
+    if (!HOP_BY_HOP.has(name) && !NOT_ANSWERED.has(name)) {
+      out.set(name, value);
+    }
+  });
+  return new Response(answer.body, { status: answer.status, headers: out });
+}
+
+/**
+ * What the command answers: the API carried to the console with the token, for the page's own
+ * requests; the build's files and its page for everything else, when there is a build; and
+ * nothing to a request whose host is not this loopback, which is a page elsewhere whose name
+ * was made to resolve here.
+ */
+export function createServeHandler(options: ServeOptions): ServeHandler {
+  const hosts = new Set([
+    `${LOOPBACK}:${options.port}`,
+    `localhost:${options.port}`,
+    `[::1]:${options.port}`,
+  ]);
+  const upstream = new URL(options.upstream).origin;
+  return async (request) => {
+    const url = new URL(request.url);
+    if (!hosts.has(url.host)) {
+      return plain(421, "This address is not the console's.");
+    }
+    if (url.pathname === "/api" || url.pathname.startsWith("/api/")) {
+      if (!fromOwnPage(request, `http://${url.host}`)) {
+        return json(
+          403,
+          "auth.forbidden_origin",
+          "This request must come from the console's own pages.",
+        );
+      }
+      return forward(request, url, upstream, options);
+    }
+    if (options.web !== undefined) {
+      const answer = await options.web.respond(request);
+      if (answer !== undefined) {
+        return answer;
+      }
+    }
+    return plain(
+      404,
+      options.web === undefined
+        ? "Nothing is served here but the API, under /api/."
+        : "Nothing here.",
+    );
+  };
+}
+
+export interface Listening {
+  /** Where the command listens, for a person to open. */
+  readonly url: string;
+  /** Settled once the listener has closed. */
+  readonly closed: Promise<void>;
+  close(): Promise<void>;
+}
+
+/** How the command listens: given the port it was bound, the handler to answer with. */
+export type Listen = (
+  handlerFor: (port: number) => ServeHandler,
+  port: number,
+) => Promise<Listening>;
+
+async function answer(
+  handler: ServeHandler,
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<void> {
+  // A browser that goes away takes its request with it, a stream of events included.
+  const controller = new AbortController();
+  res.on("close", () => {
+    if (!res.writableFinished) {
+      controller.abort();
+    }
+  });
+  const method = req.method ?? "GET";
+  const withBody = method !== "GET" && method !== "HEAD";
+  let request: Request;
+  try {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers)) {
+      if (Array.isArray(value)) {
+        for (const each of value) {
+          headers.append(name, each);
+        }
+      } else if (value !== undefined) {
+        headers.set(name, value);
+      }
+    }
+    request = new Request(`http://${req.headers.host ?? LOOPBACK}${req.url ?? "/"}`, {
+      method,
+      headers,
+      body: withBody ? (Readable.toWeb(req) as unknown as ReadableStream) : undefined,
+      signal: controller.signal,
+      ...(withBody ? { duplex: "half" } : {}),
+    } as RequestInit);
+  } catch {
+    res.writeHead(400, { "content-type": "text/plain; charset=utf-8" });
+    res.end("The request was not understood.\n");
+    return;
+  }
+  let response: Response;
+  try {
+    response = await handler(request);
+  } catch {
+    response = plain(500, "Something went wrong.");
+  }
+  res.statusCode = response.status;
+  response.headers.forEach((value, name) => {
+    res.setHeader(name, value);
+  });
+  if (response.body === null || method === "HEAD") {
+    res.end();
+    return;
+  }
+  try {
+    await pipeline(Readable.fromWeb(response.body as unknown as NodeReadableStream), res);
+  } catch {
+    // The browser went away before the answer ended: nothing is owed to it.
+    res.destroy();
+  }
+}
+
+/** Listens on the loopback, and only there, and answers every request through the handler. */
+export const listenOn: Listen = (handlerFor, port) =>
+  new Promise((resolve, reject) => {
+    let handler: ServeHandler | undefined;
+    const server = createServer((req, res) => {
+      void answer(handler ?? (() => Promise.resolve(plain(503, "Not ready."))), req, res);
+    });
+    server.once("error", reject);
+    server.listen(port, LOOPBACK, () => {
+      server.off("error", reject);
+      const address = server.address();
+      const bound = typeof address === "object" && address !== null ? address.port : port;
+      handler = handlerFor(bound);
+      const closed = new Promise<void>((done) => {
+        server.once("close", () => done());
+      });
+      resolve({
+        url: `http://${LOOPBACK}:${bound}/`,
+        closed,
+        close: () =>
+          new Promise<void>((done, fail) => {
+            server.closeAllConnections();
+            server.close((error) => (error === undefined ? done() : fail(error)));
+          }),
+      });
+    });
+  });

package/src/cli/terminal.ts

@@ -0,0 +1,28 @@
+import { readFile } from "node:fs/promises";
+import process from "node:process";
+
+// The terminal's side of the command: what is read from it. Nothing here is reached by tests,
+// which hand the command readers of their own.
+
+/** All of standard input, once it ends. */
+export function readStdin(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let content = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk: string) => {
+      content += chunk;
+    });
+    process.stdin.on("end", () => resolve(content));
+    process.stdin.on("error", reject);
+  });
+}
+
+/** A file named on the command line, as text. */
+export function readFileAt(path: string): Promise<string> {
+  return readFile(path, "utf8");
+}
+
+/** A file named on the command line, as bytes: what is handed in. */
+export function readBytesAt(path: string): Promise<Uint8Array> {
+  return readFile(path);
+}