@design.estate/wcctools 6.1.0 → 7.0.0

package/ts/classes.devserver.ts

@@ -2,17 +2,35 @@ import * as plugins from './plugins.js';
 import * as paths from './paths.js';
 import { commitinfo } from './00_commitinfo_data.js';
 import { WccDevApi } from './classes.devapi.js';
+import { WccHostPolicy, defaultListenHost, formatUrlHost } from './classes.hostpolicy.js';
+import { WccCaptureService } from './capture/index.js';
 import { loadShellContent, shellPathPrefix } from './shellcontent.js';
 
 export interface IWccDevServerOptions {
   /** Port to listen on; overrides the tswatch configuration. 0 picks a free port. */
   port?: number;
+  /**
+   * The project directory: its tswatch configuration, package.json and catalog are served, and
+   * tswatch bundles and watches in it (default: `process.cwd()` when the server is constructed).
+   */
+  cwd?: string;
+  /**
+   * The interface address to listen on (default `127.0.0.1`, this machine only). `0.0.0.0` or
+   * `::` listen on every interface; the machine's interface addresses are then allowed hosts.
+   */
+  host?: string;
+  /** Further hostnames or addresses the server answers, besides localhost and the listen address. */
+  allowedHosts?: readonly string[];
 }
 
 export interface IWccDevServerAddress {
   port: number;
   /** The shell's address. */
   url: string;
+  /** The interface address the server listens on. */
+  host: string;
+  /** The hostnames the server answers; requests for any other Host are refused. */
+  allowedHosts: string[];
 }
 
 /** tswatch's default port and serve directory, used when the configuration names none. */
@@ -25,87 +43,187 @@ const securityHeaders: plugins.typedserver.ISecurityHeaders = {
   crossOriginEmbedderPolicy: 'require-corp',
 };
 
+/** Every surface takes every hostname: the server-wide Host admission refuses the ones it does not serve. */
 const acceptAnyHostname = () => true;
 
 /**
- * `wcctools dev`: bundles the catalog of the current project with tswatch, as its
- * `@git.zone/tswatch` configuration (or the `element` preset) describes, and serves on one port:
+ * `wcctools dev`: bundles the catalog of a project with tswatch, as its `@git.zone/tswatch`
+ * configuration (or the `element` preset) describes, and serves on one port:
  *
  * - the shell on `/wcctools/` (`/` redirects there) and its routes `/wcctools-route/...`,
- * - the typed API on `/wcctools/typedrequest`,
+ * - the typed API on `/wcctools/typedrequest`, including the bundles' status,
  * - the catalog's preview document and bundle from the tswatch serve directory on every other
- *   path, with live reload that reloads only the preview document.
+ *   path, with live reload that reloads only the preview document,
+ * - captures of single demos in a headless browser (`capture`, also on the typed API).
+ *
+ * It listens on loopback unless told otherwise and admits requests as its `WccHostPolicy`
+ * describes: only the hosts it serves, and state-changing requests and WebSockets only from its
+ * own origin.
  *
- * tswatch resolves its paths against the process's working directory, so the server serves the
- * project the process runs in.
+ * The server owns no process lifecycle: while it runs, a process shutdown through smartexit's
+ * `ProcessLifecycle` stops it. The entry point installs that lifecycle with
+ * `getShutdownTimeoutMs()`.
  */
 export class WccDevServer {
   /** The typed API on `/wcctools/typedrequest`; register further handlers before `start()`. */
   public readonly api = new WccDevApi();
-  private tsWatch: plugins.tswatch.TsWatch | null = null;
+  /** Screenshots and interaction captures of the served catalog; available while the server runs. */
+  public readonly capture: WccCaptureService;
+  /** Who may talk to the server: the hosts it answers and the origin of its requests. */
+  public readonly hostPolicy: WccHostPolicy;
+  /** The project directory everything resolves against. */
+  public readonly cwd: string;
+  /** The project's tswatch configuration, or the `element` preset; read once, on construction. */
+  private readonly config: plugins.tswatch.ITswatchConfig;
+  /** Bundling and watching stay tswatch's; its own server stays off. */
+  private readonly tsWatch: plugins.tswatch.TsWatch;
   private typedServer: plugins.typedserver.TypedServer | null = null;
-  private readonly smartExit = new plugins.smartexit.SmartExit({ silent: true });
+  /** Stops the server on a process shutdown; registered by start(), released by stop(). */
+  private smartExit: plugins.smartexit.SmartExit | null = null;
+  private unsubscribeBundleEvents: (() => void) | null = null;
+  private running = false;
+  private starting: Promise<IWccDevServerAddress> | null = null;
+  private stopping: Promise<void> | null = null;
 
   constructor(private readonly options: IWccDevServerOptions = {}) {
-    this.smartExit.addCleanupFunction(() => this.stop());
+    this.cwd = plugins.path.resolve(options.cwd ?? process.cwd());
+    const configHandler = new plugins.tswatch.ConfigHandler(this.cwd);
+    this.config = configHandler.loadConfig() ?? this.getElementPreset(configHandler);
+    this.tsWatch = new plugins.tswatch.TsWatch({ ...this.config, server: { enabled: false } }, { cwd: this.cwd });
+    this.hostPolicy = new WccHostPolicy({ listenHost: options.host ?? defaultListenHost, allowedHosts: options.allowedHosts });
+    this.capture = new WccCaptureService(this.api.bundleStatus);
+    this.capture.addTypedHandlers(this.api.typedrouter);
   }
 
+  /**
+   * The shutdown deadline the server needs, tswatch's: the entry point installs smartexit's
+   * `ProcessLifecycle` with it, so every watcher command keeps its full grace period.
+   */
+  public getShutdownTimeoutMs(): number {
+    return this.tsWatch.getShutdownTimeoutMs();
+  }
+
+  /**
+   * Bundles the catalog, starts the watchers and serves. Refused while the server runs or stops;
+   * the server starts again after stop().
+   */
   public async start(): Promise<IWccDevServerAddress> {
-    if (this.typedServer) {
-      throw new Error('wcctools: the dev server is already started.');
+    if (this.running || this.stopping) {
+      throw new Error('wcctools: the dev server is already started or still stopping.');
+    }
+    this.running = true;
+    // A process shutdown stops the server from here on, also while it is still starting
+    const smartExit = new plugins.smartexit.SmartExit({ silent: true });
+    smartExit.addCleanupFunction(() => this.stop());
+    this.smartExit = smartExit;
+    const starting = this.startServing();
+    this.starting = starting;
+    try {
+      const address = await starting;
+      if (this.stopping) {
+        throw new Error('wcctools: the dev server was stopped while starting.');
+      }
+      return address;
+    } catch (error) {
+      // A start that failed halfway releases what it opened
+      await this.stop();
+      throw error;
+    } finally {
+      if (this.starting === starting) {
+        this.starting = null;
+      }
+    }
+  }
+
+  /**
+   * Stops the server and tswatch's bundling and watching, and releases everything start()
+   * registered. A stop during start() waits for the start to settle first; concurrent and
+   * repeated calls share one stop.
+   */
+  public stop(): Promise<void> {
+    this.stopping ??= this.release().finally(() => {
+      this.stopping = null;
+    });
+    return this.stopping;
+  }
+
+  private async release(): Promise<void> {
+    await this.starting?.catch(() => undefined);
+    const smartExit = this.smartExit;
+    const typedServer = this.typedServer;
+    const unsubscribeBundleEvents = this.unsubscribeBundleEvents;
+    this.smartExit = null;
+    this.typedServer = null;
+    this.unsubscribeBundleEvents = null;
+    smartExit?.deregister();
+    // Status requests waiting for a change are refused now, so none holds the server's stop, and
+    // requests until the server stops listening are refused too: the shell backs off
+    this.api.bundleStatus.close();
+    try {
+      // Captures end and the capture browser closes before the server stops answering its pages
+      await this.capture.close();
+      await typedServer?.stop();
+    } finally {
+      this.hostPolicy.setPort(null);
+      try {
+        await this.tsWatch.stop();
+      } finally {
+        unsubscribeBundleEvents?.();
+        this.running = false;
+      }
     }
-    const cwd = process.cwd();
-    const configHandler = new plugins.tswatch.ConfigHandler(cwd);
-    const config = configHandler.loadConfig() ?? configHandler.getPreset('element');
-    const serveDir = plugins.path.resolve(cwd, config.server?.serveDir ?? defaultServeDir);
-    const port = this.options.port ?? config.server?.port ?? defaultPort;
+  }
+
+  private async startServing(): Promise<IWccDevServerAddress> {
+    const serveDir = plugins.path.resolve(this.cwd, this.config.server?.serveDir ?? defaultServeDir);
+    const port = this.options.port ?? this.config.server?.port ?? defaultPort;
 
     // The preview surface watches the serve directory, which must exist before the first bundle
     await plugins.fs.mkdir(serveDir, { recursive: true });
     this.api.setServerInfo({
       wcctoolsVersion: commitinfo.version,
-      projectName: await this.readProjectName(cwd),
+      projectName: await this.readProjectName(),
     });
+    const surfaces = [await this.createShellSurface(), this.createPreviewSurface(serveDir)];
     const typedServer = new plugins.typedserver.TypedServer({
       cors: false,
       port,
-      surfaces: [
-        await this.createShellSurface(),
-        this.createPreviewSurface(serveDir),
-      ],
+      listenHostname: this.hostPolicy.listenHost,
+      // Requests and WebSocket upgrades for a Host the server does not serve are refused
+      requestAdmission: this.hostPolicy.admitHost,
+      websocketAdmission: this.hostPolicy.admitHost,
+      surfaces,
     });
     this.typedServer = typedServer;
 
-    // Bundling and watching stay tswatch's; its own server stays off
-    this.tsWatch = new plugins.tswatch.TsWatch({ ...config, server: { enabled: false } });
-    try {
-      await this.tsWatch.start();
-      await typedServer.start();
-    } catch (error) {
-      await this.stop();
-      throw error;
-    }
+    this.api.bundleStatus.open();
+    const bundleStatus = this.api.bundleStatus;
+    this.unsubscribeBundleEvents = this.tsWatch.onBundleEvent((eventArg) => bundleStatus.record(eventArg));
+    // The initial bundles run here; a failed one is reported in the bundle status
+    await this.tsWatch.start();
+    await typedServer.start();
     const boundPort = typedServer.listeningPort ?? port;
-    return { port: boundPort, url: `http://localhost:${boundPort}${shellPathPrefix}/` };
+    this.hostPolicy.setPort(boundPort);
+    this.capture.open(`http://${formatUrlHost(this.hostPolicy.getLocalHost())}:${boundPort}`);
+    return {
+      port: boundPort,
+      url: `http://${formatUrlHost(this.hostPolicy.getDisplayHost())}:${boundPort}${shellPathPrefix}/`,
+      host: this.hostPolicy.listenHost,
+      allowedHosts: [...this.hostPolicy.allowedHostnames],
+    };
   }
 
-  /** Stops the server, then tswatch's bundling and watching. */
-  public async stop(): Promise<void> {
-    const typedServer = this.typedServer;
-    const tsWatch = this.tsWatch;
-    this.typedServer = null;
-    this.tsWatch = null;
-    this.smartExit.deregister();
-    await typedServer?.stop();
-    await tsWatch?.stop();
+  private getElementPreset(configHandlerArg: plugins.tswatch.ConfigHandler): plugins.tswatch.ITswatchConfig {
+    const preset = configHandlerArg.getPreset('element');
+    if (!preset) {
+      throw new Error('wcctools: tswatch provides no `element` preset.');
+    }
+    return preset;
   }
 
   /**
-   * The shell: the prebuilt shell bundle and the typed API.
-   *
-   * Seam for side-effecting APIs (assistant, capture, standards fixes): before any handler with
-   * side effects is registered here, add a `websocketAdmission`/`requestAdmission` that accepts
-   * only the shell's own origin, and keep surface mode's strict authority validation.
+   * The shell: the prebuilt shell bundle and the typed API, whose requests (captures among them)
+   * are admitted only from the server's own origin.
    */
   private async createShellSurface(): Promise<plugins.typedserver.ITypedServerSurface> {
     return {
@@ -118,6 +236,8 @@ export class WccDevServer {
       spaFallback: true,
       httpTypedRouter: this.api.typedrouter,
       typedRequestPath: `${shellPathPrefix}/typedrequest`,
+      requestAdmission: this.hostPolicy.admitRequestOrigin,
+      websocketAdmission: this.hostPolicy.admitWebsocketOrigin,
       noCache: true,
       securityHeaders,
     };
@@ -141,8 +261,10 @@ export class WccDevServer {
       watch: true,
       // Lets the reload client get pushed changes instead of polling
       websocketTypedRouter: new plugins.typedrequest.TypedRouter(),
-      // As tswatch serves catalogs
-      cors: true,
+      requestAdmission: this.hostPolicy.admitRequestOrigin,
+      websocketAdmission: this.hostPolicy.admitWebsocketOrigin,
+      // Shell and preview share one origin, so no other origin may read the catalog
+      cors: false,
       httpHandler: async (contextArg) => {
         if (contextArg.path === '/' && (contextArg.method === 'GET' || contextArg.method === 'HEAD')) {
           return new Response(null, { status: 302, headers: { Location: `${shellPathPrefix}/` } });
@@ -154,8 +276,8 @@ export class WccDevServer {
     };
   }
 
-  private async readProjectName(cwdArg: string): Promise<string> {
-    const packageJson = JSON.parse(await plugins.fs.readFile(plugins.path.join(cwdArg, 'package.json'), 'utf8')) as { name?: string };
-    return packageJson.name ?? plugins.path.basename(cwdArg);
+  private async readProjectName(): Promise<string> {
+    const packageJson = JSON.parse(await plugins.fs.readFile(plugins.path.join(this.cwd, 'package.json'), 'utf8')) as { name?: string };
+    return packageJson.name ?? plugins.path.basename(this.cwd);
   }
 }

package/ts/classes.hostpolicy.ts

@@ -0,0 +1,201 @@
+import * as plugins from './plugins.js';
+
+type TRequestContext = plugins.typedserver.IRequestContext;
+type TAdmissionResult = plugins.typedserver.TRequestAdmissionResult;
+
+/** The interface address `wcctools dev` listens on unless told otherwise. */
+export const defaultListenHost = '127.0.0.1';
+
+/** The hostnames every dev server answers: the loopback names. */
+const loopbackHostnames = ['localhost', '127.0.0.1', '::1'];
+
+const wildcardHosts = new Set(['0.0.0.0', '::']);
+
+/** Methods that never change state, which the Origin check leaves to the Host check alone. */
+const safeMethods = new Set(['GET', 'HEAD', 'OPTIONS']);
+
+/** Canonical form of a hostname: lower case, IPv6 without brackets, no trailing dot. */
+export const normalizeHostname = (hostnameArg: string): string => {
+  let hostname = hostnameArg.trim().toLowerCase();
+  if (hostname.startsWith('[') && hostname.endsWith(']')) {
+    hostname = hostname.slice(1, -1);
+  }
+  if (hostname.endsWith('.') && hostname.length > 1) {
+    hostname = hostname.slice(0, -1);
+  }
+  return hostname;
+};
+
+/** Whether the address is the wildcard address of all interfaces. */
+export const isWildcardHost = (hostArg: string): boolean => wildcardHosts.has(normalizeHostname(hostArg));
+
+/** Whether a peer address is a loopback address (IPv4, IPv6 or IPv4-mapped IPv6). */
+export const isLoopbackAddress = (addressArg: string): boolean => {
+  const address = normalizeHostname(addressArg);
+  return address === '::1' || address.startsWith('127.') || address.startsWith('::ffff:127.');
+};
+
+/** A hostname as it appears in a URL: IPv6 addresses in brackets. */
+export const formatUrlHost = (hostnameArg: string): string => {
+  return hostnameArg.includes(':') ? `[${hostnameArg}]` : hostnameArg;
+};
+
+/** An invalid `--host` or `--allowed-host` value. */
+export class WccHostPolicyError extends Error {
+  constructor(messageArg: string) {
+    super(messageArg);
+    this.name = 'WccHostPolicyError';
+  }
+}
+
+export interface IWccHostPolicyOptions {
+  /** The interface address the server listens on. */
+  listenHost: string;
+  /** Further hostnames or addresses the server answers (`--allowed-host`). */
+  allowedHosts?: readonly string[];
+}
+
+/**
+ * Who may talk to a `wcctools dev` server. The server listens on loopback unless told otherwise
+ * and answers only the hostnames it serves: the loopback names, the address it listens on, the
+ * machine's interface addresses when it listens on all of them, and the hosts allowed explicitly.
+ * Every other Host is refused, which defeats DNS rebinding. Requests that can change state
+ * (any method but GET, HEAD and OPTIONS) and WebSocket connections are further admitted only from
+ * the server's own origin, so other web pages cannot drive the API; a request without an Origin
+ * is admitted only from a loopback peer (local tools, such as the CLI and tests).
+ */
+export class WccHostPolicy {
+  /** The canonical hostnames the server answers. */
+  public readonly allowedHostnames: ReadonlySet<string>;
+  public readonly listenHost: string;
+  private port: number | null = null;
+
+  constructor(optionsArg: IWccHostPolicyOptions) {
+    this.listenHost = WccHostPolicy.parseHost(optionsArg.listenHost);
+    const hostnames = new Set(loopbackHostnames);
+    if (isWildcardHost(this.listenHost)) {
+      for (const address of WccHostPolicy.getInterfaceAddresses()) {
+        hostnames.add(address);
+      }
+    } else {
+      hostnames.add(this.listenHost);
+    }
+    for (const host of optionsArg.allowedHosts ?? []) {
+      hostnames.add(WccHostPolicy.parseHost(host));
+    }
+    this.allowedHostnames = hostnames;
+  }
+
+  /** A hostname or address, as a URL would carry it; anything else is refused. */
+  private static parseHost(hostArg: string): string {
+    const hostname = normalizeHostname(hostArg);
+    let parsed: string | null = null;
+    try {
+      parsed = normalizeHostname(new URL(`http://${formatUrlHost(hostname)}/`).hostname);
+    } catch {
+      parsed = null;
+    }
+    if (!hostname || parsed !== hostname) {
+      throw new WccHostPolicyError(`wcctools: "${hostArg}" is not a hostname or address.`);
+    }
+    return hostname;
+  }
+
+  /** Every address of the machine's network interfaces. */
+  private static getInterfaceAddresses(): string[] {
+    const addresses: string[] = [];
+    for (const interfaceAddresses of Object.values(plugins.os.networkInterfaces())) {
+      for (const interfaceAddress of interfaceAddresses ?? []) {
+        addresses.push(normalizeHostname(interfaceAddress.address));
+      }
+    }
+    return addresses;
+  }
+
+  /** The port the server listens on, once it does: origins are compared against it. */
+  public setPort(portArg: number | null) {
+    this.port = portArg;
+  }
+
+  /**
+   * The host the server's own tools reach it on: the loopback address when it listens on all
+   * interfaces or on loopback, otherwise the address it listens on.
+   */
+  public getLocalHost(): string {
+    if (isWildcardHost(this.listenHost) || isLoopbackAddress(this.listenHost)) {
+      return '127.0.0.1';
+    }
+    return this.listenHost;
+  }
+
+  /** The host shown to the user: `localhost` for a loopback or all-interface server. */
+  public getDisplayHost(): string {
+    if (isWildcardHost(this.listenHost) || isLoopbackAddress(this.listenHost) || this.listenHost === 'localhost') {
+      return 'localhost';
+    }
+    return this.listenHost;
+  }
+
+  /** Server-wide HTTP and WebSocket admission: the Host must be one the server answers. */
+  public readonly admitHost = (contextArg: TRequestContext): TAdmissionResult => {
+    const hostname = normalizeHostname(contextArg.url.hostname);
+    if (this.allowedHostnames.has(hostname)) {
+      return true;
+    }
+    return this.refuse(
+      `wcctools: the dev server does not answer the host "${hostname}". Open it on localhost, or restart it with --allowed-host ${hostname}.`,
+    );
+  };
+
+  /** Surface HTTP admission: a request that can change state must come from the server's origin. */
+  public readonly admitRequestOrigin = (contextArg: TRequestContext): TAdmissionResult => {
+    if (safeMethods.has(contextArg.method)) {
+      return true;
+    }
+    return this.admitOrigin(contextArg);
+  };
+
+  /** Surface WebSocket admission: a connection must come from the server's origin. */
+  public readonly admitWebsocketOrigin = (contextArg: TRequestContext): TAdmissionResult => {
+    return this.admitOrigin(contextArg);
+  };
+
+  /** Whether an Origin header names this server: http, an allowed host and the server's port. */
+  public isOwnOrigin(originArg: string): boolean {
+    if (this.port === null) {
+      return false;
+    }
+    let origin: URL;
+    try {
+      origin = new URL(originArg);
+    } catch {
+      return false;
+    }
+    const port = origin.port === '' ? 80 : Number(origin.port);
+    return origin.protocol === 'http:'
+      && port === this.port
+      && this.allowedHostnames.has(normalizeHostname(origin.hostname));
+  }
+
+  private admitOrigin(contextArg: TRequestContext): TAdmissionResult {
+    const origin = contextArg.headers.get('origin');
+    if (origin === null) {
+      const peer = contextArg.connectionInfo?.remoteAddr ?? 'unknown';
+      if (isLoopbackAddress(peer)) {
+        return true;
+      }
+      return this.refuse('wcctools: requests without an Origin are admitted only from this machine.');
+    }
+    if (this.isOwnOrigin(origin)) {
+      return true;
+    }
+    return this.refuse(`wcctools: requests from the origin "${origin}" are not admitted.`);
+  }
+
+  private refuse(messageArg: string): Response {
+    return new Response(`${messageArg}\n`, {
+      status: 403,
+      headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+    });
+  }
+}

package/ts/cli.screenshot.ts

@@ -0,0 +1,95 @@
+import * as plugins from './plugins.js';
+import { WccDevServer } from './classes.devserver.js';
+import { WccCaptureRequestError, captureViewportWidths, resolveScreenshotRequest } from './capture/index.js';
+
+/** Reads `<item>` or `<section>/<item>`. */
+const parseSubject = (argsArg: readonly string[], demoArg: number | undefined): plugins.interfaces.IWccCaptureSubject => {
+  if (argsArg.length !== 1 || argsArg[0].trim() === '') {
+    throw new WccCaptureRequestError('wcctools screenshot: name one catalog entry, as <item> or <section>/<item>.');
+  }
+  const [subject] = argsArg;
+  const slash = subject.indexOf('/');
+  const named: plugins.interfaces.IWccCaptureSubject = slash === -1
+    ? { itemName: subject }
+    : { sectionName: subject.slice(0, slash), itemName: subject.slice(slash + 1) };
+  return demoArg === undefined ? named : { ...named, demoIndex: demoArg };
+};
+
+/** Reads a named viewport or a width in pixels. */
+const parseViewport = (valueArg: string | undefined): plugins.interfaces.TWccCaptureViewport | undefined => {
+  if (valueArg === undefined) {
+    return undefined;
+  }
+  if (Object.hasOwn(captureViewportWidths, valueArg)) {
+    return valueArg as plugins.interfaces.TWccCaptureViewportPreset;
+  }
+  if (/^\d+$/.test(valueArg)) {
+    return Number(valueArg);
+  }
+  throw new WccCaptureRequestError(
+    `wcctools screenshot: --viewport must be one of ${Object.keys(captureViewportWidths).join(', ')} or a width in pixels.`,
+  );
+};
+
+/** The image format the output file's extension names. */
+const formatForFile = (fileArg: string): 'png' | 'jpeg' => {
+  const extension = plugins.path.extname(fileArg).toLowerCase();
+  if (extension === '.png') {
+    return 'png';
+  }
+  if (extension === '.jpg' || extension === '.jpeg') {
+    return 'jpeg';
+  }
+  throw new WccCaptureRequestError('wcctools screenshot: --out must name a .png, .jpg or .jpeg file.');
+};
+
+/**
+ * `wcctools screenshot`: bundles the catalog of the working directory, serves it on a free
+ * loopback port, screenshots one demo in a headless browser, writes the image and stops.
+ */
+export const registerScreenshotCommand = (out: plugins.smartconsole.SmartConsole): void => {
+  out.cli.command({
+    name: 'screenshot',
+    description: 'Screenshot one demo of the catalog in a headless browser: wcctools screenshot <item | section/item> --out <file.png>',
+    options: {
+      out: { type: 'string', required: true, description: 'The image file to write; .png, .jpg or .jpeg' },
+      demo: { type: 'number', description: 'The demo to render, counted from 0 as in the shell URL (default 0)' },
+      viewport: { type: 'string', description: `The width: ${Object.entries(captureViewportWidths).map(([nameArg, widthArg]) => `${nameArg} (${widthArg})`).join(', ')} or pixels (default desktop)` },
+      height: { type: 'number', description: 'The height of the preview window in pixels (default 800)' },
+      theme: { type: 'string', description: 'dark or bright (default dark)' },
+      framing: { type: 'string', description: 'element, viewport or fullpage (default element; fullpage for pages)' },
+      scale: { type: 'number', description: 'Device pixel ratio, 1 or 2 (default 1)' },
+      quality: { type: 'number', description: 'JPEG quality from 1 to 100 (default 80)' },
+    },
+  }, async ({ args, options }) => {
+    const format = formatForFile(options.out);
+    const request: plugins.interfaces.IWccScreenshotRequest = {
+      subject: parseSubject(args, options.demo),
+      viewport: parseViewport(options.viewport),
+      height: options.height,
+      theme: options.theme as plugins.interfaces.TWccTheme | undefined,
+      framing: options.framing as plugins.interfaces.TWccCaptureFraming | undefined,
+      scale: options.scale as 1 | 2 | undefined,
+      format,
+      quality: options.quality,
+    };
+    // Invalid options are refused before anything is bundled
+    resolveScreenshotRequest(request);
+    const outFile = plugins.path.resolve(options.out);
+    const devServer = new WccDevServer({ port: 0, cwd: process.cwd() });
+    // As for `wcctools dev`: SIGINT and SIGTERM stop the server and the capture browser once
+    plugins.smartexit.ProcessLifecycle.install({ shutdownTimeoutMs: devServer.getShutdownTimeoutMs() });
+    let result: plugins.interfaces.IWccScreenshotResult;
+    try {
+      await devServer.start();
+      result = await devServer.capture.captureScreenshot(request);
+    } finally {
+      await devServer.stop();
+    }
+    await plugins.fs.writeFile(outFile, Buffer.from(result.image.dataBase64, 'base64'));
+    const { selection, image } = result;
+    await out.log(
+      `wcctools screenshot: wrote ${outFile} (${selection.sectionName}/${selection.itemName} demo ${selection.demoIndex}, ${result.framing}, ${image.width}×${image.height}${result.truncated ? ', cut at the maximum height' : ''})`,
+    );
+  });
+};

package/ts/cli.ts

@@ -1,6 +1,9 @@
 import * as plugins from './plugins.js';
 import { commitinfo } from './00_commitinfo_data.js';
 import { WccDevServer } from './classes.devserver.js';
+import { WccHostPolicyError } from './classes.hostpolicy.js';
+import { WccCaptureRequestError } from './capture/index.js';
+import { registerScreenshotCommand } from './cli.screenshot.js';
 import { StandardConfigError, StandardUsageError, registerStandardCommands } from './standards/index.js';
 
 /**
@@ -21,13 +24,34 @@ export const registerCommands = (out: plugins.smartconsole.SmartConsole): void =
         type: 'number',
         description: 'Port to listen on (0 picks a free port); overrides the tswatch configuration',
       },
+      host: {
+        type: 'string',
+        description: 'Interface address to listen on (default 127.0.0.1, this machine only; 0.0.0.0 for every interface)',
+      },
+      allowedHost: {
+        type: 'strings',
+        description: 'A further hostname or address the server answers, besides localhost and the listen address (repeatable)',
+      },
     },
   }, async ({ options }) => {
-    const devServer = new WccDevServer({ port: options.port });
+    const devServer = new WccDevServer({
+      port: options.port,
+      cwd: process.cwd(),
+      host: options.host,
+      allowedHosts: options.allowedHost,
+    });
+    // The entry point owns process signals: SIGINT and SIGTERM run every registered cleanup, the
+    // dev server's stop among them, once within tswatch's shutdown deadline, then exit.
+    plugins.smartexit.ProcessLifecycle.install({ shutdownTimeoutMs: devServer.getShutdownTimeoutMs() });
     const address = await devServer.start();
     await out.log(`wcctools dev: ${address.url}`);
+    if (address.host !== '127.0.0.1' && address.host !== '::1' && address.host !== 'localhost') {
+      await out.log(`wcctools dev: listening on ${address.host}, answering the hosts ${address.allowedHosts.join(', ')}`);
+    }
   });
 
+  registerScreenshotCommand(out);
+
   registerStandardCommands(out);
 
   out.cli.default({}, async () => {
@@ -45,7 +69,9 @@ export const runCli = async () => {
     // Configuration and usage errors exit with 2, every other failure with 1.
     const usageError = error instanceof plugins.smartconsole.CliUsageError
       || error instanceof StandardConfigError
-      || error instanceof StandardUsageError;
+      || error instanceof StandardUsageError
+      || error instanceof WccCaptureRequestError
+      || error instanceof WccHostPolicyError;
     process.exitCode = usageError ? 2 : 1;
   } finally {
     await out.dispose();

package/ts/index.ts

@@ -1,3 +1 @@
 export { runCli } from './cli.js';
-export { WccDevServer, type IWccDevServerOptions, type IWccDevServerAddress } from './classes.devserver.js';
-export { WccDevApi } from './classes.devapi.js';