@wildo-ai/application-creation-workbench 1.1.5

package/LICENSE

@@ -0,0 +1,34 @@
+Copyright (c) 2026 P2C Consulting, s.à r.l.-S
+RCS Luxembourg B307591
+6C, Porte de France, L-4360 Esch-sur-Alzette, Luxembourg
+
+All rights reserved.
+
+This software and its accompanying materials (the "Software") are the
+confidential and proprietary property of P2C Consulting, s.à r.l.-S (the
+"Licensor"). The Software is made available for viewing only. No licence,
+right, or permission of any kind is granted by its publication or by its
+availability on any package registry or source repository.
+
+Without the Licensor's prior written permission, you may not use, copy,
+reproduce, modify, adapt, translate, merge, publish, distribute, sublicense,
+sell, host, or create derivative works of the Software, in whole or in part,
+nor use it to provide a service to any third party.
+
+Publication of the Software in any public registry is for distribution to
+authorised recipients and for technical evaluation of its packaging only. It
+does not place the Software in the public domain, does not constitute an open
+source release, and does not waive any right of the Licensor.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Third-party components distributed with the Software remain governed by their
+own licences.
+
+Contact: P2C Consulting, s.à r.l.-S, 6C, Porte de France, L-4360
+Esch-sur-Alzette, Luxembourg.

package/bin/companion-proxy.d.mts

@@ -0,0 +1,10 @@
+/** Types for `companion-proxy.mjs` — see that file for what each export is for. */
+export declare const COMPANION_UNAVAILABLE_ENVELOPE: Readonly<{ type: 'NETWORK'; severity: 'high'; message: 'network'; customMessage: 'network' }>;
+export declare const COMPANION_UNAVAILABLE_HEADERS: Readonly<Record<string, string>>;
+export declare function isCompanionAwayError(error: unknown): boolean;
+export declare function companionUnavailableBody(input: { companionUrl: string; path: string | null; reason: string }): string;
+export declare function createCompanionOutageReporter(input: {
+  companionUrl: string;
+  report: (line: string) => void;
+  now?: () => number;
+}): { away: (path: string | undefined) => void; answered: () => void };

package/bin/companion-proxy.mjs

@@ -0,0 +1,92 @@
+/**
+ * How the workbench talks to the companion when the companion is AWAY — shared by the two servers that
+ * put the workbench in front of it:
+ *
+ * - `vite.config.ts`, the dev server (framework developers, workbench source);
+ * - `wildo-workbench-serve.mjs`, the built bundle's server (application creators, published package).
+ *
+ * Both answer on the workbench's own origin and forward `/api` and `/health` to the companion, so both
+ * meet the same two facts: a companion that is not listening must read as the server being away (503,
+ * the engine's NETWORK envelope), never as an internal failure (a 500 the client classifies HIGH); and
+ * a respawn is ONE outage with a start and an end, not one log line per refused request.
+ *
+ * Plain Node ESM with no dependencies on purpose: the production server runs this file straight out of
+ * `node_modules`, with nothing built and nothing else installed.
+ */
+
+/**
+ * The engine error envelope `AbstractController.jsonError` writes, spelled here rather than imported:
+ * these values are `ErrorType.NETWORK`, `ErrorSeverity.HIGH` and `ErrorCustomMessageReference.NETWORK`
+ * from `@wildo-ai/saas-models`, and this module must stay a dependency-free leaf. A change there is a
+ * change here.
+ */
+// semantic-literal-boundary: the engine error envelope, written by a Node-side leaf that must not import the models package
+export const COMPANION_UNAVAILABLE_ENVELOPE = Object.freeze({ type: 'NETWORK', severity: 'high', message: 'network', customMessage: 'network' });
+
+/**
+ * The two connection failures that mean "the companion is away", as opposed to "the companion failed".
+ *
+ * `ECONNREFUSED` — nothing is listening (restarting, stopped, or another application's port).
+ * `ECONNRESET` — the companion went away mid-request, which is what a supervised respawn does to every
+ * request in flight at the moment it stops. Both end the moment the new process binds.
+ */
+const COMPANION_AWAY_ERROR_CODES = new Set(['ECONNREFUSED', 'ECONNRESET']);
+
+/** @param {unknown} error */
+export function isCompanionAwayError(error) {
+  const code = /** @type {{ code?: unknown } | null} */ (error)?.code;
+  return typeof code === 'string' && COMPANION_AWAY_ERROR_CODES.has(code);
+}
+
+/**
+ * The 503 body for a request the companion could not answer.
+ *
+ * @param {{ companionUrl: string; path: string | null; reason: string }} input
+ */
+export function companionUnavailableBody({ companionUrl, path, reason }) {
+  return JSON.stringify({
+    error: {
+      ...COMPANION_UNAVAILABLE_ENVELOPE,
+      timestamp: new Date().toISOString(),
+      details: { companionUrl, path, reason },
+    },
+  });
+}
+
+/** Headers of that 503: JSON, and a hint to retry shortly — a respawn takes seconds. */
+export const COMPANION_UNAVAILABLE_HEADERS = Object.freeze({ 'Content-Type': 'application/json', 'Retry-After': '2' });
+
+/**
+ * Reports a companion outage as TWO lines — when it starts and when it ends — instead of one per request.
+ *
+ * Every framework recompile respawns the companion, and the same edit reloads the workbench page, so the
+ * reload's whole label fan-out (one request per 30 keys) lands on a companion that is not listening yet.
+ * The outage is keyed on the moment the companion stops answering and cleared by the first response that
+ * comes back, so the recovery line says how long it was away and how many requests were answered 503.
+ *
+ * @param {{ companionUrl: string; report: (line: string) => void; now?: () => number }} input
+ * @returns {{ away: (path: string | undefined) => void; answered: () => void }}
+ */
+export function createCompanionOutageReporter({ companionUrl, report, now = Date.now }) {
+  /** @type {number | null} */
+  let outageStartedAt = null;
+  let unansweredRequests = 0;
+  return {
+    away(path) {
+      unansweredRequests += 1;
+      if (outageStartedAt !== null) return;
+      outageStartedAt = now();
+      report(
+        `[workbench proxy] the companion at ${companionUrl} is not answering (first: ${path ?? '(no url)'}) — it is restarting,`
+        + ' not running, or belongs to a different application. Answering 503 until it is back; further refusals are counted, not printed.',
+      );
+    },
+    answered() {
+      if (outageStartedAt === null) return;
+      const seconds = ((now() - outageStartedAt) / 1000).toFixed(1);
+      report(`[workbench proxy] the companion at ${companionUrl} is answering again after ${seconds}s; ${unansweredRequests} request(s) were answered 503 meanwhile.`);
+      outageStartedAt = null;
+      unansweredRequests = 0;
+    },
+  };
+}

package/bin/wildo-workbench-serve.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * `wildo-workbench-serve --companion <url> [--port <n>]` — serve the built application-creation
+ * workbench in front of one application's companion. Started by the application's workbench drop
+ * (`.wildo-saas/application-creation-workbench`, written by `wildo init` / `wildo update` for an
+ * application creator), which `wildo local dev` runs with the rest of the stack.
+ *
+ * Flags rather than environment variables so the drop's `dev` script is one portable command line on
+ * every shell, Windows `cmd.exe` included. `WILDO_COMPANION_URL` / `WILDO_WORKBENCH_PORT` are still
+ * honoured, for starting it by hand the way the dev server is.
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createWorkbenchServer, WORKBENCH_PORT_OFFSET_FROM_COMPANION } from './workbench-server.mjs';
+
+function flag(name) {
+  const index = process.argv.indexOf(`--${name}`);
+  if (index !== -1) return process.argv[index + 1];
+  const inline = process.argv.find((argument) => argument.startsWith(`--${name}=`));
+  return inline === undefined ? undefined : inline.slice(name.length + 3);
+}
+
+const companionUrl = flag('companion') ?? process.env.WILDO_COMPANION_URL;
+if (!companionUrl) {
+  console.error('[workbench] No companion to front: pass --companion http://localhost:<companion port> (or set WILDO_COMPANION_URL).');
+  process.exit(1);
+}
+let parsedCompanion;
+try {
+  parsedCompanion = new URL(companionUrl);
+} catch {
+  console.error(`[workbench] --companion ${companionUrl} is not a URL.`);
+  process.exit(1);
+}
+const portArgument = flag('port') ?? process.env.WILDO_WORKBENCH_PORT;
+if (!portArgument && parsedCompanion.port === '') {
+  // `new URL('http://localhost').port` is '' — deriving from it would bind port 1.
+  console.error(`[workbench] --companion ${companionUrl} names no port, so the workbench port cannot be derived; include the port or pass --port.`);
+  process.exit(1);
+}
+// The companion admits the workbench at exactly one origin, companion port + 1; see workbench-server.mjs.
+const port = portArgument ? Number(portArgument) : Number(parsedCompanion.port) + WORKBENCH_PORT_OFFSET_FROM_COMPANION;
+if (!Number.isInteger(port) || port <= 0) {
+  console.error(`[workbench] Cannot derive a port from ${companionUrl}; pass --port.`);
+  process.exit(1);
+}
+
+const distDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'dist');
+if (!existsSync(join(distDir, 'index.html'))) {
+  console.error(`[workbench] No built workbench at ${distDir}. This package ships its bundle; reinstall it (\`wildo update\`).`);
+  process.exit(1);
+}
+
+const server = createWorkbenchServer({ distDir, companionUrl });
+server.on('error', (error) => {
+  if (error.code === 'EADDRINUSE') {
+    console.error(`[workbench] Port ${port} is already in use — another workbench, or another application's stack, holds it.`);
+    console.error('[workbench] THE WORKBENCH WILL NOT BE AVAILABLE for this stack. Everything else starts normally.');
+  } else {
+    console.error(`[workbench] ${error.message}`);
+  }
+  process.exit(1);
+});
+// `localhost`, as the dev server binds: the origin the companion admits is http://localhost:<port>.
+server.listen(port, 'localhost', () => {
+  console.info(`[workbench] http://localhost:${port} — proxying /api and /health -> ${companionUrl}`);
+});
+
+for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+  process.on(signal, () => {
+    server.close();
+    server.closeAllConnections();
+    process.exit(0);
+  });
+}

package/bin/workbench-server.d.mts

@@ -0,0 +1,9 @@
+/** Types for `workbench-server.mjs` — see that file for the design. */
+import type { IncomingHttpHeaders, Server } from 'node:http';
+
+export declare const COMPANION_PROXIED_PREFIXES: readonly string[];
+export declare const WORKBENCH_PORT_OFFSET_FROM_COMPANION: number;
+export declare function isCompanionPath(pathname: string): boolean;
+export declare function forwardableHeaders(headers: IncomingHttpHeaders): Record<string, string | string[]>;
+export declare function resolveStaticFile(distDir: string, pathname: string): string | null;
+export declare function createWorkbenchServer(input: { distDir: string; companionUrl: string; log?: (line: string) => void }): Server;

package/bin/workbench-server.mjs

@@ -0,0 +1,225 @@
+/**
+ * The server that puts a BUILT workbench in front of an application's companion — what an application
+ * creator runs, where a framework developer runs the Vite dev server over the workbench source.
+ *
+ * It does exactly what `vite.config.ts`'s dev proxy does, because both halves of that design are load-
+ * bearing and neither is a dev convenience:
+ *
+ * - **One origin.** The page and its API calls share the workbench's own origin, and `/api` + `/health`
+ *   are forwarded to the companion. The companion's CORS list is derived from the APPLICATION's frontend
+ *   URLs; teaching it about a framework tool's origin was rejected (see `vite.config.ts`).
+ * - **`Origin` forwarded untouched.** The companion admits the workbench at exactly one origin —
+ *   `companion port + 1`, registered as the workbench endpoint — so this server must listen THERE and
+ *   must not rewrite the header. Only `Host` is rewritten, as Vite's `changeOrigin` does.
+ *
+ * And what a dev server does not have to: responses are STREAMED (the coding-session frames are
+ * Server-Sent Events, which a buffering proxy would hold until the stream ended), an upstream request
+ * is aborted when its client goes away, and hashed assets are cached while `index.html` never is, so a
+ * `wildo update` is picked up on the next reload.
+ *
+ * Plain Node ESM with no dependencies, run straight from `node_modules`.
+ */
+import { createReadStream, existsSync, statSync } from 'node:fs';
+import { createServer, request as httpRequest } from 'node:http';
+import { pipeline } from 'node:stream';
+import { request as httpsRequest } from 'node:https';
+import { extname, join, normalize, resolve, sep } from 'node:path';
+import {
+  companionUnavailableBody,
+  COMPANION_UNAVAILABLE_HEADERS,
+  createCompanionOutageReporter,
+  isCompanionAwayError,
+} from './companion-proxy.mjs';
+
+/** Path prefixes the companion answers. Everything else is the workbench bundle. */
+export const COMPANION_PROXIED_PREFIXES = Object.freeze(['/api', '/health']);
+
+/** The workbench's port sits one above its companion's (`WORKBENCH_PORT_OFFSET_FROM_COMPANION`). */
+export const WORKBENCH_PORT_OFFSET_FROM_COMPANION = 1;
+
+const CONTENT_TYPES = Object.freeze({
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.txt': 'text/plain; charset=utf-8',
+  '.wasm': 'application/wasm',
+  '.lottie': 'application/zip',
+});
+
+/**
+ * Connection-specific fields this proxy never forwards: `Connection` itself, plus the fields RFC 9110
+ * says an intermediary SHOULD remove whether or not `Connection` names them. The fields a `Connection`
+ * header DOES name are removed as well, per message (`forwardableHeaders`) — that half is a MUST.
+ * spec-cite: RFC 9110 §7.6.1 (Connection) — the SHOULD list is Proxy-Connection, Keep-Alive, TE, Transfer-Encoding, Upgrade.
+ */
+const CONNECTION_SPECIFIC_HEADERS = new Set(['connection', 'proxy-connection', 'keep-alive', 'te', 'transfer-encoding', 'upgrade']);
+
+/**
+ * The headers of one message minus its connection-specific fields: the fixed set above and every
+ * field its own `Connection` header names.
+ *
+ * @param {import('node:http').IncomingHttpHeaders} headers
+ * @returns {Record<string, string | string[]>}
+ */
+export function forwardableHeaders(headers) {
+  const named = new Set(
+    String(headers.connection ?? '')
+      .split(',')
+      .map((option) => option.trim().toLowerCase())
+      .filter(Boolean),
+  );
+  /** @type {Record<string, string | string[]>} */
+  const kept = {};
+  for (const [name, value] of Object.entries(headers)) {
+    if (value !== undefined && !CONNECTION_SPECIFIC_HEADERS.has(name) && !named.has(name)) kept[name] = value;
+  }
+  return kept;
+}
+
+/**
+ * @param {string} pathname
+ */
+export function isCompanionPath(pathname) {
+  return COMPANION_PROXIED_PREFIXES.some((prefix) => pathname === prefix || pathname.startsWith(`${prefix}/`));
+}
+
+/**
+ * The file a GET for `pathname` serves: the file itself when it exists inside `distDir`, `index.html`
+ * for an extension-less path (a client-side route), and `null` otherwise — including any path that
+ * would resolve outside `distDir`.
+ *
+ * @param {string} distDir
+ * @param {string} pathname
+ * @returns {string | null}
+ */
+export function resolveStaticFile(distDir, pathname) {
+  let decoded;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    return null;
+  }
+  const root = resolve(distDir);
+  const candidate = resolve(root, `.${normalize(`/${decoded}`)}`);
+  if (candidate !== root && !candidate.startsWith(`${root}${sep}`)) return null;
+  if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+  if (extname(decoded) === '') return join(root, 'index.html');
+  return null;
+}
+
+/**
+ * @param {{ distDir: string; companionUrl: string; log?: (line: string) => void }} input
+ * @returns {import('node:http').Server}
+ */
+export function createWorkbenchServer({ distDir, companionUrl, log = (line) => console.warn(line) }) {
+  const companion = new URL(companionUrl);
+  const forward = companion.protocol === 'https:' ? httpsRequest : httpRequest;
+  const outage = createCompanionOutageReporter({ companionUrl, report: log });
+
+  return createServer((request, response) => {
+    const url = new URL(request.url ?? '/', 'http://workbench.invalid');
+
+    if (isCompanionPath(url.pathname)) {
+      const headers = forwardableHeaders(request.headers);
+      headers.host = companion.host;
+      /*
+       * Set when the CLIENT goes away (a closed tab, an EventSource reconnect). Destroying the upstream
+       * then raises ECONNRESET on it — which, unflagged, reads exactly like the companion going away and
+       * logged a false outage against a healthy companion (measured, 2026-09-24 review).
+       */
+      let clientGone = false;
+      /*
+       * Set when the COMPANION's response dies mid-stream. `pipeline` then destroys the client response
+       * itself, and that close must not be mistaken for the client leaving — which would silence the
+       * outage report for the very interruption it describes.
+       */
+      let upstreamInterrupted = false;
+      const upstream = forward(
+        {
+          protocol: companion.protocol,
+          hostname: companion.hostname,
+          port: companion.port,
+          method: request.method,
+          path: `${url.pathname}${url.search}`,
+          headers,
+        },
+        (upstreamResponse) => {
+          outage.answered();
+          response.writeHead(upstreamResponse.statusCode ?? 502, forwardableHeaders(upstreamResponse.headers));
+          // Flush the headers now, so a Server-Sent Events stream opens before its first frame.
+          response.flushHeaders();
+          upstreamResponse.on('aborted', () => { upstreamInterrupted = true; });
+          upstreamResponse.on('error', () => { upstreamInterrupted = true; });
+          /*
+           * `pipeline`, not `pipe`: when the companion drops its socket MID-STREAM — a respawn during a
+           * Server-Sent Events stream — `pipe` never ends the browser's side, so its EventSource waited on a
+           * connection that would never deliver again and never reconnected (probe, 2026-09-24 review).
+           * `pipeline` destroys the client response too, the browser sees the close, and EventSource
+           * reconnects — to a 503 until the companion is back, then to the stream.
+           */
+          pipeline(upstreamResponse, response, (error) => {
+            if (!error || clientGone) return;
+            if (isCompanionAwayError(error)) outage.away(request.url);
+            else log(`[workbench proxy] ${request.url ?? '(no url)'} <- ${companionUrl} interrupted: ${error.message}`);
+          });
+        },
+      );
+      upstream.on('error', (error) => {
+        if (clientGone) return;
+        if (isCompanionAwayError(error)) outage.away(request.url);
+        else log(`[workbench proxy] ${request.url ?? '(no url)'} -> ${companionUrl} FAILED: ${error.message}`);
+        if (response.headersSent || response.writableEnded) {
+          response.destroy();
+          return;
+        }
+        response.writeHead(503, { ...COMPANION_UNAVAILABLE_HEADERS });
+        response.end(companionUnavailableBody({ companionUrl, path: request.url ?? null, reason: /** @type {NodeJS.ErrnoException} */ (error).code ?? error.message }));
+      });
+      // A client that goes away (a closed tab, an EventSource reconnect) must not leave the upstream open.
+      response.on('close', () => {
+        if (response.writableFinished || upstreamInterrupted) return;
+        clientGone = true;
+        upstream.destroy();
+      });
+      request.pipe(upstream);
+      return;
+    }
+
+    if (request.method !== 'GET' && request.method !== 'HEAD') {
+      response.writeHead(405, { Allow: 'GET, HEAD' });
+      response.end();
+      return;
+    }
+    const file = resolveStaticFile(distDir, url.pathname);
+    if (file === null || !existsSync(file)) {
+      response.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+      response.end('Not found');
+      return;
+    }
+    const isIndex = file.endsWith(`${sep}index.html`);
+    response.writeHead(200, {
+      'Content-Type': CONTENT_TYPES[/** @type {keyof typeof CONTENT_TYPES} */ (extname(file).toLowerCase())] ?? 'application/octet-stream',
+      // Vite fingerprints everything under assets/; the entry document must always be re-read, so a
+      // `wildo update` reaches the browser on the next reload.
+      'Cache-Control': isIndex ? 'no-cache' : url.pathname.startsWith('/assets/') ? 'public, max-age=31536000, immutable' : 'no-cache',
+    });
+    if (request.method === 'HEAD') {
+      response.end();
+      return;
+    }
+    createReadStream(file).pipe(response);
+  });
+}