@tilewise/workbench-client 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.2.0 · 2026-11-10 17:08 +04:00
+
+- feat(workbench-client)!: serve the dev server over https by default, for Safari (4219956)
+  - Serve https with a certificate for localhost from Vite's own @vitejs/plugin-basic-ssl, one for every project on the computer, kept in
+  - Add the https option and WORKBENCH_HTTPS (1 or 0) to choose, keeping an app's own server.https, and http under Vitest
+  - Log how to trust the certificate on a Mac and on Windows at each start
+  - Link the viewer to the dev server's https address
+  - Describe https in the README
+  - BREAKING CHANGE: the dev server answers on https://localhost:<port> instead of http://localhost:<port>; set https: false or WORKBENCH_HTTPS=0 to keep http
+- fix(workbench-client): leave out HTTP/2 pseudo-headers when asking a fake API (a326e03)
+  - Skip :method, :path and the other pseudo-headers a request over HTTP/2 carries, which fetch refuses, so a dev server on https answers /api
+  - Leave out keep-alive, upgrade and proxy-connection from a fake API's answer, which HTTP/2 refuses
+  - Test a request as HTTP/2 hands it over
+- feat(workbench-client): hand the dev server's token to the viewer's origin at /connect (0ab508c)
+  - Add GET /__workbench/connect, which answers { token, repo } to a request from an allowed origin (WORKBENCH_URL or a viewer on localhost) and nothing
+  - Read the repository's owner/name in one helper, for the link and /connect
+  - Test that only the viewer's origin gets the token
+  - Describe connecting in the README
+
+## 0.1.2 · 2026-11-07 06:11 +04:00
+
+- feat(workbench-client): read the fake API from workbench.json (25e1ad9)
+  - Answer `/api` from the fake API that `viewers.proto.api` in the repository's `workbench.json` declares, from `viewers.proto.folder`, when `workbenchLocal()` is given no `api` option; the option still wins
+  - Read `workbench.json` on each request, so an edit to it counts without restarting Vite
+  - Build each other commit with the fake API its own `workbench.json` declares, else the checkout's
+  - Serve the checkout's setup at `GET /__workbench/setup`, for a workbench without the GitHub App
+  - Describe `workbench.json` in the README's local builds, workspace and fake API sections
+
 ## 0.1.1 · 2026-11-06 01:07 +04:00
 
 - feat(workbench-client): build apps in a workspace folder and answer each build's fake API (fc6dba7)

package/README.md

@@ -174,9 +174,42 @@ git-ignored `.builds/<sha>/`, and checks a branch out, refused while
 anything is uncommitted. Builds are served under `/__workbench/b/<sha>/`, so
 the app's router takes `basepath: import.meta.env.BASE_URL`.
 
+It also reads `workbench.json`, at the repository's top, where the
+repository declares its setup: the fake API comes from it (below), and
+`/__workbench/setup` hands the checkout's to the viewer, as `{ name, viewers }`
+(404 without the file, 422 when it isn't a setup), for a workbench that can't
+read it from GitHub.
+
 Only the viewer may ask: from its origin (`WORKBENCH_URL`, or a viewer on
-localhost) with the token in the link the dev server logs. `pnpm dev` opens
-that link; without `WORKBENCH_URL` the dev server opens no viewer.
+localhost) with the dev server's token. The viewer has it from the link the
+dev server logs, which `pnpm dev` opens, or by connecting to the dev server's
+port: `/__workbench/connect` hands the token, and the repository it serves,
+to a page of those origins alone, as the browser names a page's origin and
+no site can claim another's. Without `WORKBENCH_URL` the dev server opens no
+viewer, and only a viewer on localhost can connect.
+
+### https
+
+The dev server serves https, so Safari can use Local too. Safari blocks a
+secure page, as the viewer is, from reaching `http://localhost`, which
+Chrome and Firefox allow. The certificate comes from Vite's own
+[`@vitejs/plugin-basic-ssl`](https://github.com/vitejs/vite-plugin-basic-ssl).
+It is made for localhost, one for every project on the computer, and kept in
+`~/.workbench/https` for 825 days, Apple's limit.
+
+Each computer trusts it once, as the dev server's log says at each start:
+
+- **Mac** (Safari, and Chrome with it): open `https://localhost:5173` in
+  Safari, choose *Show Details* › *visit this website*, and enter your
+  password.
+- **Windows** (Chrome and Edge):
+  `certutil -user -addstore TrustedPeople "%USERPROFILE%\.workbench\https\localhost.crt"`.
+  TrustedPeople trusts this certificate alone, never one it signs.
+
+`https: false` in the options, or `WORKBENCH_HTTPS=0`, serves http.
+`WORKBENCH_HTTPS=1` serves https whatever the options say. An app that sets
+its own `server.https` keeps it. Under Vitest it is http, unless `https` is
+set.
 
 ### An app in a workspace
 
@@ -184,28 +217,51 @@ The app may live in a folder of a pnpm workspace, such as `apps/app/`, with
 its dev server's root there. Each commit is built from that folder, or from
 the top for a commit from before the app moved there. A workspace commit
 installs its own packages (`pnpm install --frozen-lockfile --prefer-offline`),
-so its packages link to that commit's, never the checkout's.
+so its packages link to that commit's, never the checkout's. The folder is
+the dev server's root, whatever `workbench.json` says, and a local build
+installs and builds as above, without Proto's `install` and `build`.
 
 ### A fake API
 
-```ts
-workbenchLocal({ base: 'develop', api: { entry: '../fake-api/src/index.ts' } });
+Declare it in `workbench.json`, at the repository's top, as Proto's `api`:
+
+```json
+{
+  "name": "Aitems",
+  "viewers": {
+    "proto": { "folder": "apps/app", "api": "../fake-api/src/index.ts" }
+  }
+}
 ```
 
-`entry` is the fake API's module, from the app's folder. Its default export
-is a fetch handler: a function from `Request` to `Response`, or an object
-with `fetch`, as a Hono app is. `path` is where the app asks it, `/api` unless
-set. The handler is asked without that path, so `/api/bags/b1` reaches it as
-`/bags/b1`.
-
-- **Live:** the dev server answers it at `path`, from its source. Vite loads
-  it again when it changes.
-- **Builds:** each build bundles its commit's fake API, with every package
-  inside it, into `.builds/<sha>/__api/`, and answers it under the build, at
-  `/__workbench/b/<sha>/api/…`. An old build asks the API it was built with,
-  whatever the checkout's has become. The app asks
-  `` `${import.meta.env.BASE_URL}api/…` ``, which is right in both.
+`api` is the fake API's module, from Proto's `folder`: the app's folder from
+the top, or the top when it is `''` or left out. Its default export is a
+fetch handler: a function from `Request` to `Response`, or an object with
+`fetch`, as a Hono app is. The app asks it at `/api`, and the handler is
+asked without that path, so `/api/bags/b1` reaches it as `/bags/b1`. With no
+file, a file that isn't a setup, or no `api` in it, there is no fake API and
+`/api` is the app's own.
+
+- **Live:** the dev server answers it at `/api`, from its source. Vite loads
+  it again when it changes, and the file is read on each request, so
+  declaring the API or moving it needs no restart.
+- **Builds:** each build bundles the fake API its commit's own
+  `workbench.json` declares (the checkout's, for a commit with no file of its
+  own), with every package inside it, into `.builds/<sha>/__api/`, and
+  answers it under the build, at `/__workbench/b/<sha>/api/…`. An old build
+  asks the API it was built with, whatever the checkout's has become. The app
+  asks `` `${import.meta.env.BASE_URL}api/…` ``, which is right in both.
 - Each build's API runs in a worker of its own: loaded on its first request
   and stopped after 30 minutes with nothing asked, so a visit's data lasts
   until then. The worker gets no environment variables, and the bundle
   itself is never served.
+
+The `api` option overrides the file, for Live and for a commit with no file
+of its own:
+
+```ts
+workbenchLocal({ base: 'develop', api: { entry: '../fake-api/src/index.ts', path: '/api' } });
+```
+
+`entry` is the module from the app's folder, the dev server's root; `path` is
+where the app asks it, `/api` unless set.

package/dist/vite/builds.d.ts

@@ -8,9 +8,10 @@ export interface Build {
     /** The end of the log, when it failed. */
     error?: string;
 }
-/** A fake API beside the app: its module, from the app's folder, and where the app asks it. */
+/** A fake API beside the app: where its module is, and where the app asks it. */
 export interface ApiOption {
-    entry: string;
+    /** Its module in a tree of the repository: `top` is the tree's top, `app` the app's folder in it. */
+    entry: (top: string, app: string) => string;
     path: string;
 }
 /** A build's own fake API: its bundle, and where the build asks it. */
@@ -30,14 +31,15 @@ export declare function lockOf(dir: string): Promise<{
  *
  * The app may live in a folder of the repository, such as a pnpm workspace's
  * `apps/app/`: each commit is built from that folder, or from the top for a
- * commit from before the app moved there. With `api`, a commit that has the
- * fake API is bundled too, into `.builds/<sha>/__api/`, so its build asks its
- * own API, whatever the checkout's API has become since.
+ * commit from before the app moved there. A commit's fake API is bundled too,
+ * into `.builds/<sha>/__api/`, so its build asks its own API, whatever the
+ * checkout's API has become since: the one the commit's own `workbench.json`
+ * declares, else `api`, the checkout's, when the commit has it.
  */
 export declare function createBuilds(options: {
     root: () => string;
     git: Git;
-    api?: () => ApiOption | null;
+    api?: () => Promise<ApiOption | null>;
 }): {
     apiOf: (sha: string) => Promise<BuiltApi | null>;
     buildOf: (sha: string) => Promise<Build>;

package/dist/vite/builds.js

@@ -2,11 +2,12 @@ import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { appendFile, lstat, mkdir, readdir, readFile, rename, rm, rmdir, symlink, unlink, writeFile, } from 'node:fs/promises';
 import { createRequire } from 'node:module';
-import { dirname, join, relative, resolve } from 'node:path';
+import { dirname, join, relative } from 'node:path';
 import { appFolder } from './appFolder.js';
 import { bundleApi } from './bundleApi.js';
 import { buildEnvironment } from './environment.js';
 import { isWorkspace } from './isWorkspace.js';
+import { setupApi } from './setup.js';
 /** The Vite this plugin runs in, for a commit that has none of its own installed. */
 const ownVite = () => {
     return join(dirname(createRequire(import.meta.url).resolve('vite/package.json')), 'bin', 'vite.js');
@@ -29,9 +30,10 @@ export async function lockOf(dir) {
  *
  * The app may live in a folder of the repository, such as a pnpm workspace's
  * `apps/app/`: each commit is built from that folder, or from the top for a
- * commit from before the app moved there. With `api`, a commit that has the
- * fake API is bundled too, into `.builds/<sha>/__api/`, so its build asks its
- * own API, whatever the checkout's API has become since.
+ * commit from before the app moved there. A commit's fake API is bundled too,
+ * into `.builds/<sha>/__api/`, so its build asks its own API, whatever the
+ * checkout's API has become since: the one the commit's own `workbench.json`
+ * declares, else `api`, the checkout's, when the commit has it.
  */
 export function createBuilds(options) {
     const states = new Map();
@@ -180,10 +182,11 @@ export function createBuilds(options) {
                 '--emptyOutDir',
             ];
             await step(sha, log, process.execPath, args, app, 'vite build');
-            // Its own fake API, when the commit has one inside the worktree.
-            const api = options.api?.() ?? null;
+            // Its own fake API, when the commit has one inside the worktree: the one its own
+            // workbench.json declares, else the checkout's.
+            const api = (await setupApi(work)) ?? (await options.api?.()) ?? null;
             let built = null;
-            const entry = api ? resolve(app, api.entry) : null;
+            const entry = api ? api.entry(work, app) : null;
             if (api && entry && !relative(work, entry).startsWith('..')) {
                 const file = await bundleApi((more, cwd) => step(sha, log, process.execPath, [vite, ...more], cwd, 'API bundle'), app, entry, join(temporary, '__api'));
                 built = file ? { file: `__api/${file}`, path: api.path } : null;

package/dist/vite/environment.d.ts

@@ -4,6 +4,10 @@ export declare const environment: {
     viewerUrl: string | null;
     /** The package script that started the dev server: only `dev` opens the viewer. */
     script: string | null;
+    /** WORKBENCH_HTTPS: `1` serves https, `0` http; unset leaves it to the option. */
+    https: boolean | null;
+    /** Run by Vitest, whose servers are never opened in a browser. */
+    vitest: boolean;
 };
 /** What a build's install and bundle run with: this environment, as CI. */
 export declare const buildEnvironment: () => NodeJS.ProcessEnv;

package/dist/vite/environment.js

@@ -1,10 +1,15 @@
 const viewer = process.env['WORKBENCH_URL']?.replace(/\/$/, '');
+const https = process.env['WORKBENCH_HTTPS'];
 /** Every setting the local builds service reads from the environment. */
 export const environment = {
     /** The viewer's address. Without it, the dev server opens no viewer. */
     viewerUrl: viewer === undefined || viewer === '' ? null : viewer,
     /** The package script that started the dev server: only `dev` opens the viewer. */
     script: process.env['npm_lifecycle_event'] ?? null,
+    /** WORKBENCH_HTTPS: `1` serves https, `0` http; unset leaves it to the option. */
+    https: https === '1' ? true : https === '0' ? false : null,
+    /** Run by Vitest, whose servers are never opened in a browser. */
+    vitest: !!process.env['VITEST'],
 };
 /** What a build's install and bundle run with: this environment, as CI. */
 export const buildEnvironment = () => ({ ...process.env, CI: '1' });

package/dist/vite/fetchBridge.d.ts

@@ -1,7 +1,9 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 /**
  * A Node request as a fetch `Request` for a fake API, at `path`: the part of
- * the address after the API's mount, with its query.
+ * the address after the API's mount, with its query. HTTP/2's pseudo-headers
+ * (`:method`, `:path`…), which the https dev server's requests carry, are
+ * no headers to fetch, so they are left out.
  */
 export declare function toRequest(request: IncomingMessage, path: string): Promise<Request>;
 /** Writes a fake API's fetch `Response` to a Node response. */

package/dist/vite/fetchBridge.js

@@ -1,5 +1,12 @@
-/** Headers Node works out for itself, from what it sends. */
-const COMPUTED = new Set(['content-length', 'transfer-encoding', 'connection']);
+/** Headers Node works out for itself, from what it sends, and that HTTP/2 refuses. */
+const COMPUTED = new Set([
+    'content-length',
+    'transfer-encoding',
+    'connection',
+    'keep-alive',
+    'upgrade',
+    'proxy-connection',
+]);
 const bodyOf = (request) => {
     return new Promise((resolve, reject) => {
         const chunks = [];
@@ -10,13 +17,15 @@ const bodyOf = (request) => {
 };
 /**
  * A Node request as a fetch `Request` for a fake API, at `path`: the part of
- * the address after the API's mount, with its query.
+ * the address after the API's mount, with its query. HTTP/2's pseudo-headers
+ * (`:method`, `:path`…), which the https dev server's requests carry, are
+ * no headers to fetch, so they are left out.
  */
 export async function toRequest(request, path) {
     const method = request.method ?? 'GET';
     const headers = new Headers();
     for (const [name, value] of Object.entries(request.headers)) {
-        if (value === undefined) {
+        if (value === undefined || name.startsWith(':')) {
             continue;
         }
         for (const each of Array.isArray(value) ? value : [value]) {

package/dist/vite/git.d.ts

@@ -5,3 +5,5 @@ export declare function gitIn(root: string): Git;
 export declare const refExists: (git: Git, ref: string) => Promise<boolean>;
 /** The repository's default branch, as its remote has it, or `main`. */
 export declare function defaultBranch(git: Git): Promise<string>;
+/** The repository on GitHub, as `owner/name`, from its `origin` remote; null for any other. */
+export declare function repositoryOf(git: Git): Promise<string | null>;

package/dist/vite/git.js

@@ -16,3 +16,8 @@ export async function defaultBranch(git) {
     const head = await git('symbolic-ref', '--short', 'refs/remotes/origin/HEAD').catch(() => '');
     return head.trim().replace(/^origin\//, '') || 'main';
 }
+/** The repository on GitHub, as `owner/name`, from its `origin` remote; null for any other. */
+export async function repositoryOf(git) {
+    const remote = await git('remote', 'get-url', 'origin').catch(() => '');
+    return /github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?\s*$/.exec(remote)?.[1] ?? null;
+}

package/dist/vite/https.d.ts

@@ -0,0 +1,17 @@
+export interface Certificate {
+    /** The key and the certificate, as Vite's `server.https` takes them. */
+    pem: string;
+    /** The certificate alone, the file a browser is told to trust. */
+    file: string;
+}
+/**
+ * The dev server's certificate for localhost, made by Vite's own basic-ssl.
+ * One for every project on this computer, kept in `~/.workbench/https` for
+ * 825 days, so a browser trusts it once. `folder` is for tests.
+ */
+export declare function localhostCertificate(folder?: string): Promise<Certificate>;
+/**
+ * How to trust the certificate, once per computer, for the dev server's log
+ * at each start: whether this computer trusts it can't be told from here.
+ */
+export declare function trustSteps(file: string, port: number): string[];

package/dist/vite/https.js

@@ -0,0 +1,34 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { getCertificate } from '@vitejs/plugin-basic-ssl';
+/** Apple's longest lifetime for a certificate its browsers trust. */
+const DAYS = 825;
+const CERTIFICATE = /-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----/;
+/**
+ * The dev server's certificate for localhost, made by Vite's own basic-ssl.
+ * One for every project on this computer, kept in `~/.workbench/https` for
+ * 825 days, so a browser trusts it once. `folder` is for tests.
+ */
+export async function localhostCertificate(folder = join(homedir(), '.workbench', 'https')) {
+    const pem = await getCertificate(folder, 'localhost', [], DAYS);
+    const file = join(folder, 'localhost.crt');
+    const certificate = CERTIFICATE.exec(pem)?.[0] ?? '';
+    const kept = await readFile(file, 'utf8').catch(() => '');
+    if (kept.trim() !== certificate) {
+        await mkdir(folder, { recursive: true });
+        await writeFile(file, `${certificate}\n`);
+    }
+    return { pem, file };
+}
+/**
+ * How to trust the certificate, once per computer, for the dev server's log
+ * at each start: whether this computer trusts it can't be told from here.
+ */
+export function trustSteps(file, port) {
+    return [
+        'HTTPS: trust its certificate once on this computer, if you haven’t yet.',
+        `  Mac: open https://localhost:${port} in Safari, choose Show Details › visit this website, and enter your password`,
+        `  Windows: certutil -user -addstore TrustedPeople "${file}"`,
+    ];
+}

package/dist/vite/setup.d.ts

@@ -0,0 +1,38 @@
+/** What a repository says about itself in `workbench.json` at its top. */
+export interface Setup {
+    /** '' when the file gives none. */
+    name: string;
+    /** In the file's order, each with its string settings. */
+    viewers: {
+        name: string;
+        options: Record<string, string>;
+    }[];
+}
+/**
+ * The `workbench.json` at `top`, read as the workbench reads it: an object,
+ * whose `viewers` is an object of viewers, each named in lower case and with
+ * an object of settings, of which only strings are kept, cut to 500
+ * characters. `missing` without the file, `invalid` when it isn't JSON or
+ * isn't a setup. Read each time, so an edit to it counts at once.
+ *
+ * ```json
+ * { "name": "Aitems", "viewers": { "proto": { "folder": "apps/app", "api": "../fake-api/src/index.ts" } } }
+ * ```
+ */
+export declare function readSetup(top: string): Promise<{
+    state: 'read';
+    setup: Setup;
+} | {
+    state: 'missing' | 'invalid';
+}>;
+/**
+ * The fake API the `workbench.json` at `top` declares: Proto's `api`, its
+ * module from Proto's `folder` ('' or none for the top), answered at `/api`.
+ * `entry` places that module in any tree of the repository, this one or a
+ * build's worktree. Null when the file is missing or no setup, or declares no
+ * fake API.
+ */
+export declare function setupApi(top: string): Promise<{
+    entry: (tree: string) => string;
+    path: string;
+} | null>;

package/dist/vite/setup.js

@@ -0,0 +1,65 @@
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+/** An object, as JSON has it: not null, not an array. */
+const isObject = (value) => {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+/**
+ * The `workbench.json` at `top`, read as the workbench reads it: an object,
+ * whose `viewers` is an object of viewers, each named in lower case and with
+ * an object of settings, of which only strings are kept, cut to 500
+ * characters. `missing` without the file, `invalid` when it isn't JSON or
+ * isn't a setup. Read each time, so an edit to it counts at once.
+ *
+ * ```json
+ * { "name": "Aitems", "viewers": { "proto": { "folder": "apps/app", "api": "../fake-api/src/index.ts" } } }
+ * ```
+ */
+export async function readSetup(top) {
+    let text;
+    try {
+        text = await readFile(join(top, 'workbench.json'), 'utf8');
+    }
+    catch {
+        return { state: 'missing' };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return { state: 'invalid' };
+    }
+    if (!isObject(raw) || (raw['viewers'] !== undefined && !isObject(raw['viewers']))) {
+        return { state: 'invalid' };
+    }
+    const name = typeof raw['name'] === 'string' ? raw['name'].trim().slice(0, 80) : '';
+    const viewers = [];
+    for (const [viewer, settings] of Object.entries(isObject(raw['viewers']) ? raw['viewers'] : {})) {
+        if (!/^[a-z][a-z0-9-]*$/.test(viewer) || !isObject(settings)) {
+            return { state: 'invalid' };
+        }
+        const options = {};
+        for (const [key, value] of Object.entries(settings)) {
+            if (typeof value === 'string') {
+                options[key] = value.slice(0, 500);
+            }
+        }
+        viewers.push({ name: viewer, options });
+    }
+    return { state: 'read', setup: { name, viewers } };
+}
+/**
+ * The fake API the `workbench.json` at `top` declares: Proto's `api`, its
+ * module from Proto's `folder` ('' or none for the top), answered at `/api`.
+ * `entry` places that module in any tree of the repository, this one or a
+ * build's worktree. Null when the file is missing or no setup, or declares no
+ * fake API.
+ */
+export async function setupApi(top) {
+    const read = await readSetup(top);
+    const proto = read.state === 'read' ? read.setup.viewers.find((viewer) => viewer.name === 'proto') : null;
+    const api = proto?.options['api']?.trim() ?? '';
+    const folder = proto?.options['folder']?.trim() ?? '';
+    return api === '' ? null : { entry: (tree) => resolve(tree, folder, api), path: '/api' };
+}

package/dist/vite/workbenchLocal.d.ts

@@ -4,6 +4,8 @@ import type { Plugin } from 'vite';
  * also answers the deployed viewer. It lists this machine's branches and
  * commits, builds any commit, and checks a branch out.
  *
+ *   GET  /__workbench/connect            { token, repo }: the token, for an allowed origin, which needs none
+ *   GET  /__workbench/setup              the checkout's workbench.json: { name, viewers }; 404 none, 422 no setup
  *   GET  /__workbench/versions           branches, tags, what is checked out, changed files
  *   GET  /__workbench/commits?ref=<ref>  that ref's history, newest first, each with its build
  *   POST /__workbench/builds/<sha>       build it; asked again, says how it stands (?retry after a failure)
@@ -16,12 +18,29 @@ import type { Plugin } from 'vite';
  * default branch unless set. Builds are served without the token, as a frame
  * can't send a header. Without WORKBENCH_URL, the dev server opens no viewer.
  *
- * `api` is a fake API beside the app: `entry`, its module from the app's
- * folder, whose default export is a fetch handler, and `path`, where the app
- * asks it (`/api` unless set). The dev server answers it there for Live, from
- * its source; each build bundles that commit's and answers it under the
- * build, at `/__workbench/b/<sha>/api/…`. Either way the handler is asked
- * without the path, so `/api/bags/b1` reaches it as `/bags/b1`.
+ * The viewer has the token from the link the dev server logs, or asks
+ * `/connect` for it from its own page. Only a page of an allowed origin gets
+ * it: the browser names the page's origin, and no site can claim another's. A
+ * request that names none, as a page's request to its own origin, gets none.
+ *
+ * A fake API beside the app is declared in `workbench.json` at the
+ * repository's top, as Proto's `api`: its module from Proto's `folder`, whose
+ * default export is a fetch handler, asked at `/api`. The dev server answers
+ * it there for Live, from its source, reading the file on each request; each
+ * build bundles the one its commit declares (the checkout's, for a commit with
+ * no file of its own) and answers it under the build, at
+ * `/__workbench/b/<sha>/api/…`. Either way the handler is asked without the
+ * path, so `/api/bags/b1` reaches it as `/bags/b1`.
+ *
+ * The `api` option overrides the file: `entry`, the module from the app's
+ * folder, and `path`, where the app asks it (`/api` unless set).
+ *
+ * The dev server serves https, so Safari, which blocks a secure page from
+ * reaching `http://localhost`, can use it too. Its certificate is Vite's own
+ * basic-ssl's, one for every project on this computer, which a browser
+ * trusts once (https.ts). `https: false`, or WORKBENCH_HTTPS=0, serves http;
+ * WORKBENCH_HTTPS=1 serves https whatever the option says. Under Vitest it is
+ * http unless `https` is set, and an app's own `server.https` is left as is.
  */
 export declare function workbenchLocal(options?: {
     base?: string;
@@ -29,4 +48,5 @@ export declare function workbenchLocal(options?: {
         entry: string;
         path?: string;
     };
+    https?: boolean;
 }): Plugin;

package/dist/vite/workbenchLocal.js

@@ -7,8 +7,10 @@ import { createBuilds } from './builds.js';
 import { checkout } from './checkout.js';
 import { environment } from './environment.js';
 import { sendResponse, toRequest } from './fetchBridge.js';
-import { defaultBranch, gitIn } from './git.js';
+import { defaultBranch, gitIn, repositoryOf } from './git.js';
+import { localhostCertificate, trustSteps } from './https.js';
 import { sendJson, serveBuild } from './serveBuild.js';
+import { readSetup, setupApi } from './setup.js';
 import { commits, versions } from './versions.js';
 const PREFIX = '/__workbench';
 const SHA = /^[0-9a-f]{7,40}$/;
@@ -58,6 +60,8 @@ function open(url) {
  * also answers the deployed viewer. It lists this machine's branches and
  * commits, builds any commit, and checks a branch out.
  *
+ *   GET  /__workbench/connect            { token, repo }: the token, for an allowed origin, which needs none
+ *   GET  /__workbench/setup              the checkout's workbench.json: { name, viewers }; 404 none, 422 no setup
  *   GET  /__workbench/versions           branches, tags, what is checked out, changed files
  *   GET  /__workbench/commits?ref=<ref>  that ref's history, newest first, each with its build
  *   POST /__workbench/builds/<sha>       build it; asked again, says how it stands (?retry after a failure)
@@ -70,27 +74,60 @@ function open(url) {
  * default branch unless set. Builds are served without the token, as a frame
  * can't send a header. Without WORKBENCH_URL, the dev server opens no viewer.
  *
- * `api` is a fake API beside the app: `entry`, its module from the app's
- * folder, whose default export is a fetch handler, and `path`, where the app
- * asks it (`/api` unless set). The dev server answers it there for Live, from
- * its source; each build bundles that commit's and answers it under the
- * build, at `/__workbench/b/<sha>/api/…`. Either way the handler is asked
- * without the path, so `/api/bags/b1` reaches it as `/bags/b1`.
+ * The viewer has the token from the link the dev server logs, or asks
+ * `/connect` for it from its own page. Only a page of an allowed origin gets
+ * it: the browser names the page's origin, and no site can claim another's. A
+ * request that names none, as a page's request to its own origin, gets none.
+ *
+ * A fake API beside the app is declared in `workbench.json` at the
+ * repository's top, as Proto's `api`: its module from Proto's `folder`, whose
+ * default export is a fetch handler, asked at `/api`. The dev server answers
+ * it there for Live, from its source, reading the file on each request; each
+ * build bundles the one its commit declares (the checkout's, for a commit with
+ * no file of its own) and answers it under the build, at
+ * `/__workbench/b/<sha>/api/…`. Either way the handler is asked without the
+ * path, so `/api/bags/b1` reaches it as `/bags/b1`.
+ *
+ * The `api` option overrides the file: `entry`, the module from the app's
+ * folder, and `path`, where the app asks it (`/api` unless set).
+ *
+ * The dev server serves https, so Safari, which blocks a secure page from
+ * reaching `http://localhost`, can use it too. Its certificate is Vite's own
+ * basic-ssl's, one for every project on this computer, which a browser
+ * trusts once (https.ts). `https: false`, or WORKBENCH_HTTPS=0, serves http;
+ * WORKBENCH_HTTPS=1 serves https whatever the option says. Under Vitest it is
+ * http unless `https` is set, and an app's own `server.https` is left as is.
  */
 export function workbenchLocal(options = {}) {
     let root = process.cwd();
     let git = gitIn(root);
+    let top = null;
     let server = null;
-    const api = options.api
+    let certificate = null;
+    const https = environment.https ?? options.https ?? !environment.vitest;
+    const given = options.api;
+    const option = given
         ? {
-            entry: options.api.entry,
-            path: `/${(options.api.path ?? '/api').replace(/^\/+|\/+$/g, '')}`,
+            entry: (_top, app) => resolve(app, given.entry),
+            path: `/${(given.path ?? '/api').replace(/^\/+|\/+$/g, '')}`,
         }
         : null;
+    /** The repository's top, where workbench.json is; null outside a repository. */
+    const topOf = () => {
+        return (top ??= git('rev-parse', '--show-toplevel').then((output) => output.trim() || null, () => null));
+    };
+    /** The checkout's fake API: the option, else the one its workbench.json declares now. */
+    const currentApi = async () => {
+        if (option) {
+            return option;
+        }
+        const at = await topOf();
+        return at === null ? null : setupApi(at);
+    };
     const builds = createBuilds({
         root: () => root,
         git: (...args) => git(...args),
-        api: () => api,
+        api: currentApi,
     });
     const workers = createApiWorkers();
     const base = async () => options.base ?? (await defaultBranch(git));
@@ -99,6 +136,16 @@ export function workbenchLocal(options = {}) {
         if (request.method === 'GET' && path === '/versions') {
             return sendJson(response, 200, await versions(git, await base(), builds.buildOf));
         }
+        if (request.method === 'GET' && path === '/setup') {
+            const at = await topOf();
+            const read = at === null ? { state: 'missing' } : await readSetup(at);
+            if (read.state === 'read') {
+                return sendJson(response, 200, read.setup);
+            }
+            return read.state === 'missing'
+                ? sendJson(response, 404, { error: 'No workbench.json' })
+                : sendJson(response, 422, { error: "workbench.json isn't a setup" });
+        }
         if (request.method === 'GET' && path === '/commits') {
             const ref = url.searchParams.get('ref') ?? 'HEAD';
             if (!REF.test(ref)) {
@@ -146,13 +193,17 @@ export function workbenchLocal(options = {}) {
         }
         return true;
     }
-    /** The fake API for Live, from its source: Vite loads it again when it changes. */
-    async function answerLiveApi(request, response) {
+    /**
+     * The fake API for Live, from its source: Vite loads it again when it
+     * changes. Without one, the path is the app's, as if this were not here.
+     */
+    async function answerLiveApi(request, response, next) {
         try {
+            const api = await currentApi();
             if (!api || !server) {
-                return sendJson(response, 404, { error: 'No fake API' });
+                return next();
             }
-            const module = await server.ssrLoadModule(resolve(root, api.entry));
+            const module = await server.ssrLoadModule(api.entry((await topOf()) ?? root, root));
             const asked = await toRequest(request, request.url ?? '/');
             await sendResponse(response, await apiFetchOf(module)(asked));
         }
@@ -183,6 +234,9 @@ export function workbenchLocal(options = {}) {
             response.statusCode = 204;
             return response.end();
         }
+        if (request.method === 'GET' && url.pathname === '/connect' && allowed(origin)) {
+            return sendJson(response, 200, { token, repo: await repositoryOf(git) });
+        }
         if (!allowed(origin) || request.headers['x-workbench-token'] !== token) {
             return sendJson(response, 403, {
                 error: 'Only the viewer, with the token from the dev server',
@@ -198,11 +252,19 @@ export function workbenchLocal(options = {}) {
     return {
         name: 'workbench-local',
         apply: 'serve',
-        // Builds and their worktrees are no part of the app: never watch or reload for them.
-        config: () => ({ server: { watch: { ignored: ['**/.builds/**'] } } }),
+        async config(config) {
+            // Builds and their worktrees are no part of the app: never watch or reload for them.
+            const ignored = { watch: { ignored: ['**/.builds/**'] } };
+            if (!https || config.server?.https) {
+                return { server: ignored };
+            }
+            certificate = await localhostCertificate();
+            return { server: { ...ignored, https: { key: certificate.pem, cert: certificate.pem } } };
+        },
         configResolved(config) {
             root = config.root;
             git = gitIn(root);
+            top = null;
         },
         configureServer(devServer) {
             server = devServer;
@@ -216,12 +278,11 @@ export function workbenchLocal(options = {}) {
             if (ours) {
                 stack.unshift(ours);
             }
-            // Before Vite's own middleware, which would answer the path with the app's page.
-            if (api) {
-                devServer.middlewares.use(api.path, (request, response) => {
-                    void answerLiveApi(request, response);
-                });
-            }
+            // Before Vite's own middleware, which would answer the path with the app's page. Always
+            // there without the option, so declaring the API in workbench.json needs no restart.
+            devServer.middlewares.use(option?.path ?? '/api', (request, response, next) => {
+                void answerLiveApi(request, response, next);
+            });
             devServer.httpServer?.once('listening', () => {
                 void announce(devServer);
             });
@@ -231,16 +292,20 @@ export function workbenchLocal(options = {}) {
         },
     };
     async function announce(devServer) {
+        const address = devServer.httpServer?.address();
+        const port = typeof address === 'object' && address ? address.port : 5173;
+        // How to trust the certificate, once, before the viewer is opened on it.
+        if (certificate) {
+            devServer.config.logger.info(`\n  ${trustSteps(certificate.file, port).join('\n  ')}`);
+        }
         if (!environment.viewerUrl) {
             devServer.config.logger.info('\n  Viewer: set WORKBENCH_URL to its address to open it\n');
             return;
         }
-        const address = devServer.httpServer?.address();
-        const port = typeof address === 'object' && address ? address.port : 5173;
         // The repository, as owner/name: the viewer opens its project from it.
-        const remote = await git('remote', 'get-url', 'origin').catch(() => '');
-        const repository = /github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?\s*$/.exec(remote)?.[1];
-        const local = encodeURIComponent(`http://localhost:${port}`);
+        const repository = await repositoryOf(git);
+        const scheme = devServer.config.server.https ? 'https' : 'http';
+        const local = encodeURIComponent(`${scheme}://localhost:${port}`);
         const url = `${environment.viewerUrl}/?src=local&v=live#local=${local}&token=${token}${repository ? `&repo=${encodeURIComponent(repository)}` : ''}`;
         devServer.config.logger.info(`\n  Viewer: ${url}\n`);
         // `pnpm dev` opens it; any other script is the app alone.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tilewise/workbench-client",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Connects a React prototype to the workbench's viewer: its screens, its controls and the protocol between them.",
   "license": "MIT",
   "repository": {
@@ -54,6 +54,7 @@
     "vitest": "^4.1.11"
   },
   "dependencies": {
+    "@vitejs/plugin-basic-ssl": "^2.3.0",
     "modern-screenshot": "^4.7.0"
   },
   "scripts": {