@tilewise/workbench-client 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 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,6 +174,12 @@ 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.
@@ -184,28 +190,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/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,7 @@ 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/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 +17,17 @@ 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`.
+ * 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).
  */
 export declare function workbenchLocal(options?: {
     base?: string;

package/dist/vite/workbenchLocal.js

@@ -9,6 +9,7 @@ import { environment } from './environment.js';
 import { sendResponse, toRequest } from './fetchBridge.js';
 import { defaultBranch, gitIn } from './git.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 +59,7 @@ 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/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 +72,46 @@ 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`.
+ * 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).
  */
 export function workbenchLocal(options = {}) {
     let root = process.cwd();
     let git = gitIn(root);
+    let top = null;
     let server = null;
-    const api = options.api
+    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 +120,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 +177,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));
         }
@@ -203,6 +238,7 @@ export function workbenchLocal(options = {}) {
         configResolved(config) {
             root = config.root;
             git = gitIn(root);
+            top = null;
         },
         configureServer(devServer) {
             server = devServer;
@@ -216,12 +252,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);
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tilewise/workbench-client",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Connects a React prototype to the workbench's viewer: its screens, its controls and the protocol between them.",
   "license": "MIT",
   "repository": {