@data-fair/dev-server 2.4.1 → 2.5.1

package/README.md

@@ -7,6 +7,74 @@ A development server for optimal development experience of data-fair application
 See [data-fair-charts](https://github.com/koumoul-dev/data-fair-charts/blob/master/package.json) for an example with nuxt.
 See [data-fair-minimal](https://github.com/koumoul-dev/data-fair-minimal/blob/master/package.json) for an example with a simple http server.
 
+## Ports de développement
+
+`df-dev-env` génère un `.env` git-ignoré portant trois ports libres consécutifs,
+tirés dans 20000–29999, pour que plusieurs applications tournent en parallèle :
+
+```
+APP_PORT=24730          # le serveur de dev de l'application (Vite)
+DEV_SERVER_PORT=24731   # df-dev-server
+E2E_PORT=24732          # le webServer de Playwright
+APP_PATH=/app/          # chemin sous lequel l'application est servie
+```
+
+Le fichier est généré une fois, au premier `npm run dev`, puis laissé tel quel.
+`df-dev-env --force` retire de nouveaux ports en cas de collision, en
+conservant l'`APP_PATH` déjà choisi : le remède à une collision de ports ne
+doit pas replacer en silence sous `/app/` une application servie à la racine.
+`--app-path` explicite prime sur la valeur conservée.
+
+Un `.env` déjà présent est laissé intact — mais `df-dev-env` prévient quand ce
+silence n'est pas ce qu'on attendait : quand le fichier ne porte pas `APP_PORT`
+(un `.env` écrit pour une autre raison, qui ne recevrait donc aucun port), et
+quand un `--app-path` explicite diffère de celui déjà stocké.
+
+`df-dev-server` lit ce `.env` (`dotenv`) : `DEV_SERVER_PORT` fixe son port, et
+`app.url` est dérivée de `APP_PORT` + `APP_PATH`. `APP_URL` reste prioritaire
+pour une application qui n'est pas servie sur `localhost`.
+
+`npm run dev-test-app-minimal` relit `.env` lui-même (via `dotenv-cli`) pour
+faire écouter `http-server` sur le bon `APP_PORT`, mais ne peut pas agir sur
+`APP_PATH` : ce script et le processus `df-dev-server` déjà démarré ne
+partagent rien d'autre que le fichier `.env`, écrit une seule fois par
+`df-dev-env` avec `/app/` par défaut. Pour tester `test-apps/minimal` (servie
+à la racine) il faut régénérer `.env` avant de lancer le dev-server :
+`node src/dev-env.js --force --app-path=`.
+
+## Configurations et pièces jointes distantes
+
+Le bouton « Copier une configuration distante » liste les applications qui, sur
+le data-fair distant, tournent sur l'application de base en cours de
+développement, dans la même version mineure. La recherche part du nom lu dans la
+balise `<meta name="application-name">` de l'`index.html` local et de la version
+du `package.json`.
+
+Une application de base réservée à une organisation (`privateAccess`) est
+invisible à une requête anonyme : sans elle la liste est vide, quand bien même
+les applications qui l'utilisent seraient publiques. Le paramètre
+`privateAccess` la rend visible, mais data-fair répond 401 sans
+authentification — il n'est donc envoyé que si `DATAFAIR_API_KEY` est
+renseignée. Une clé d'API se crée depuis le compte ou l'organisation sur le
+data-fair distant, et se met dans le `.env` de l'application :
+
+```
+DATAFAIR_API_KEY=xxx
+```
+
+Ce `.env` est celui que `df-dev-env` génère, et qu'il laisse intact tant qu'on
+ne passe pas `--force` — qui, lui, le réécrit entièrement et emporte la clé.
+
+La copie ramène aussi les pièces jointes de l'application distante dans
+`.dev-attachments/` (git-ignoré). Une configuration ne référence une pièce
+jointe que par son nom et reconstruit son URL à l'affichage
+(`application.href + '/attachments/' + name`) : sans les fichiers, une
+configuration de production copiée s'affiche avec toutes ses images cassées.
+Elles sont servies sous `/config/attachments/`, listées dans
+`window.APPLICATION.attachments`, et proposées par le formulaire de
+configuration comme data-fair le fait avec `context.attachments`. Un fichier
+déposé à la main dans `.dev-attachments/` est listé et servi de la même façon.
+
 ## Development
 
 Run development server :

package/config/custom-environment-variables.js

@@ -1,4 +1,10 @@
 export default {
+  port: {
+    __name: 'DEV_SERVER_PORT',
+    // __format, otherwise the config module hands over the raw string: the declared type is a
+    // number, and ajv cannot coerce it back since the config object is frozen before assertValid.
+    __format: 'json'
+  },
   dataFair: {
     url: 'DATAFAIR_URL',
     owner: {

package/config/default.js

@@ -10,7 +10,12 @@ export default {
     apiKey: null
   },
   app: {
-    url: 'http://localhost:3000',
+    // Derived from the app port so that a shifted dev setup cannot desynchronize the two.
+    // Path defaults to /app/: 27 of the 37 applications are Vite apps served under it, and
+    // this is the only value that works in a fresh clone that never ran df-dev-env. An
+    // application served at the root opts out with APP_PATH= (empty string is not nullish,
+    // so ?? keeps it). APP_URL still overrides it entirely, for apps not served on localhost.
+    url: `http://localhost:${process.env.APP_PORT ?? 3000}${process.env.APP_PATH ?? '/app/'}`,
     proxyPaths: ['/_nuxt/']
   },
   site: {

package/package.json

@@ -1,21 +1,23 @@
 {
   "name": "@data-fair/dev-server",
-  "version": "2.4.1",
+  "version": "2.5.1",
   "description": "A development server for optimal development experience of data-fair applications.",
   "main": "src/index.js",
   "bin": {
-    "df-dev-server": "src/index.js"
+    "df-dev-server": "src/index.js",
+    "df-dev-env": "src/dev-env.js"
   },
   "type": "module",
   "scripts": {
     "build": "tsc",
     "build-watch": "tsc --watch",
     "dev": "NODE_ENV=development node --watch src/index.js",
-    "dev-test-app-minimal": "http-server test-apps/minimal --port=3000 --cors --silent",
+    "dev-test-app-minimal": "dotenv -- sh -c 'http-server test-apps/minimal --port=${APP_PORT:-3000} --cors --silent'",
     "dev-test-app-vue3": "cd test-apps/vue3 && npm run dev",
     "dev-test-app-modern": "cd test-apps/modern && npm run dev",
-    "dev-zellij": "zellij --layout .zellij.kdl",
-    "prepublishOnly": "npm run lint && npm run build && npm -w ui run build",
+    "dev-zellij": "npm run build && node src/dev-env.js && dotenv -- zellij --layout .zellij.kdl",
+    "test": "node --test test/*.test.ts",
+    "prepublishOnly": "npm run lint && npm test && npm run build && npm -w ui run build",
     "lint": "eslint . && npm -w ui run lint",
     "lint-fix": "eslint --fix . && npm -w ui run lint-fix",
     "build-types": "df-build-types ."
@@ -46,6 +48,7 @@
     "@types/express": "^5.0.6",
     "@types/node": "^26.3.0",
     "@types/ws": "^8.18.1",
+    "dotenv-cli": "^11.0.0",
     "eslint": "^9.39.5",
     "eslint-plugin-vue": "^10.10.0",
     "eslint-plugin-vuetify": "^2.7.2",

package/src/app.js

@@ -1,6 +1,8 @@
 // Express app for TaxMan own API and UI
 import config from './config.js';
 import uiConfig from './ui-config.js';
+import { localizeConfig } from './localize.js';
+import { ATTACHMENTS_DIR, attachmentPath, copyAttachments, listAttachments } from './attachments.js';
 import { WebSocket, WebSocketServer } from 'ws';
 import { createServer } from 'node:http';
 import express from 'express';
@@ -14,7 +16,7 @@ import { isElementNode, createTextNode, createElement, appendChild } from '@pars
 import escapeStringRegexp from 'escape-string-regexp';
 import eventPromise from '@data-fair/lib-utils/event-promise.js';
 import { createSpaMiddleware } from '@data-fair/lib-express/serve-spa.js';
-import { resolve } from 'node:path';
+import { join, resolve } from 'node:path';
 const debug = debugModule('df-dev-server');
 const app = express();
 const server = createServer(app);
@@ -91,7 +93,7 @@ app.get('/config', (req, res, next) => {
 // exact same data as the application receives in window.APPLICATION
 app.get('/config/enriched', async (req, res) => {
     try {
-        res.send(await refreshConfigDatasets(readDevConfig()));
+        res.send(await prepareConfig(readDevConfig()));
     }
     catch (err) {
         res.status(500).send({ error: err.message });
@@ -109,6 +111,27 @@ app.post('/config/error', (req, res) => {
     }
     res.send();
 });
+// The attachments of the application under development, read by the dev-server UI to feed the
+// `context.attachments` of the configuration form — data-fair feeds it with
+// application.attachments, and an application configuration references an attachment by name.
+app.get('/config/attachments', (req, res) => {
+    res.send(listAttachments());
+});
+// window.APPLICATION.href points at /config, so an application building an attachment url the
+// production way — application.href + '/attachments/' + name — lands here. Same path shape as
+// data-fair (applications/:id/attachments/*), same no-cache: a re-copied file shows up at once.
+app.get('/config/attachments/*attachmentPath', (req, res) => {
+    const relFilePath = join(...req.params.attachmentPath);
+    const filePath = attachmentPath(ATTACHMENTS_DIR, relFilePath);
+    if (!filePath || !existsSync(filePath)) {
+        res.status(404).send({ error: `attachment "${relFilePath}" not found in ${ATTACHMENTS_DIR}` });
+        return;
+    }
+    res.setHeader('Cache-Control', 'no-cache');
+    // served from a root, and not from the absolute path: send() refuses any path holding a
+    // hidden segment, and the attachments directory is itself a dotted one
+    res.sendFile(relFilePath, { root: resolve(ATTACHMENTS_DIR) });
+});
 // Identification of the app under development: its name is read from the
 // "application-name" meta tag of the local index.html and its version from the
 // package.json of the current directory.
@@ -135,14 +158,33 @@ const localAppInfo = async () => {
     }
     return { name, version };
 };
+// The owner the dev-server works on behalf of, in the "type:id[:department]" form the
+// data-fair api expects for its owner and privateAccess filters.
+const ownerFilter = () => {
+    const owner = config.dataFair.owner;
+    let filter = `${owner.type}:${owner.id}`;
+    if (owner.department)
+        filter += ':' + owner.department;
+    return filter;
+};
 // Fetch a resource from the remote data-fair api
 const remoteFetch = async (path) => {
+    const res = await remoteFetchRaw(path);
+    return res.json();
+};
+// Same, for an attachment: a file, never json, and never decoded as text — see the app proxy
+// below, where decoding a binary body as utf8 destroys it.
+const remoteFetchBuffer = async (path) => {
+    const res = await remoteFetchRaw(path);
+    return Buffer.from(await res.arrayBuffer());
+};
+const remoteFetchRaw = async (path) => {
     const res = await fetch(config.dataFair.url + '/api/v1' + path, {
         headers: config.dataFair.apiKey ? { 'x-apiKey': config.dataFair.apiKey } : {}
     });
     if (!res.ok)
         throw new Error(`error ${res.status} on remote data-fair: ${await res.text()}`);
-    return res.json();
+    return res;
 };
 // Short-lived cache for the dataset enrichment below, so that every preview reload does not
 // hammer the remote data-fair API. Failures are cached too: a private dataset without an api
@@ -168,14 +210,11 @@ const enrichDataset = async (dataset) => {
     }
     try {
         const fresh = await remoteFetch('/datasets/' + encodeURIComponent(dataset.id));
-        const localBase = `http://localhost:${config.port}/data-fair`;
         const data = {};
         for (const prop of INJECTED_DATASET_PROPS) {
             if (fresh[prop] !== undefined)
                 data[prop] = fresh[prop];
         }
-        if (typeof data.href === 'string')
-            data.href = data.href.replace(config.dataFair.url, localBase);
         data.userPermissions = fresh.userPermissions ?? [];
         datasetsCache.set(dataset.id, { data, fetchedAt: Date.now() });
         return { ...dataset, ...data };
@@ -188,12 +227,15 @@ const enrichDataset = async (dataset) => {
         return dataset;
     }
 };
-const refreshConfigDatasets = async (configuration) => {
+// Enrich the datasets from the remote data-fair, then rewrite every remote origin to ours.
+// The rewrite is applied even when there is no dataset to enrich: a configuration can carry
+// remote urls anywhere (logos, links, tileserver styles), not only in datasets[].href.
+const prepareConfig = async (configuration) => {
     const datasets = configuration?.datasets?.filter((d) => !!d);
-    if (!datasets?.length)
-        return configuration;
-    const enriched = await Promise.all(datasets.map(enrichDataset));
-    return { ...configuration, datasets: enriched };
+    const enriched = datasets?.length
+        ? { ...configuration, datasets: await Promise.all(datasets.map(enrichDataset)) }
+        : configuration;
+    return localizeConfig(enriched, new URL(config.dataFair.url).origin, `http://localhost:${config.port}`);
 };
 // read the .dev-config.json file of the app under development
 const readDevConfig = () => existsSync('.dev-config.json') ? JSON.parse(readFileSync('.dev-config.json', 'utf8')) : {};
@@ -337,9 +379,20 @@ app.get('/configurations', async (req, res) => {
         return;
     }
     response.minorVersion = minorVersion(version);
+    // a base application restricted to an organization is invisible to an anonymous request, and
+    // without it the listing below finds nothing at all — the applications are then never reached,
+    // however public they are. privateAccess is what makes it visible, and data-fair answers 401
+    // to it without credentials, so it is only sent when an api key is configured.
+    response.authenticated = !!config.dataFair.apiKey;
     try {
-        const baseApps = await remoteFetch('/base-applications?applicationName=' + encodeURIComponent(name) + '&size=1000&count=false');
+        let baseAppsQuery = '/base-applications?applicationName=' + encodeURIComponent(name) + '&size=1000&count=false';
+        if (response.authenticated)
+            baseAppsQuery += '&privateAccess=' + encodeURIComponent(ownerFilter());
+        const baseApps = await remoteFetch(baseAppsQuery);
         const matchingBaseApps = (baseApps.results ?? []).filter((b) => typeof b.version === 'string' && minorVersion(b.version) === response.minorVersion);
+        // told apart from "the base application exists but carries no application": the UI has no
+        // other way to explain an empty list, and a missing api key is by far the likeliest cause
+        response.baseAppFound = matchingBaseApps.length > 0;
         response.results = [];
         for (const baseApp of matchingBaseApps) {
             const applications = await remoteFetch('/applications?base-application=' + encodeURIComponent(baseApp.url) + '&size=1000&count=false&select=id,title,owner');
@@ -354,14 +407,23 @@ app.get('/configurations', async (req, res) => {
         res.status(500).send({ ...response, error: err.message });
     }
 });
-// copy a configuration from the remote data-fair, replacing all references to the
-// remote origin by the local one so that data goes through the local proxies
+// copy a configuration from the remote data-fair, keeping its remote origins so that
+// .dev-config.json stays portable — see localize.ts
 app.get('/configurations/:id', async (req, res) => {
+    const id = encodeURIComponent(req.params.id);
     try {
-        const configuration = await remoteFetch('/applications/' + encodeURIComponent(req.params.id) + '/configuration');
-        const remoteOrigin = new URL(config.dataFair.url).origin;
-        const localOrigin = `http://localhost:${config.port}`;
-        res.send(JSON.parse(JSON.stringify(configuration).replaceAll(remoteOrigin, localOrigin)));
+        // Sent as-is, with its remote origins: the UI stores this straight into .dev-config.json,
+        // which must stay portable. Origins are rewritten on the read path, in prepareConfig.
+        const configuration = await remoteFetch('/applications/' + id + '/configuration');
+        // The attachments come along: a configuration references them by name only, so without the
+        // files a copied production configuration renders with every image broken. Fetched from the
+        // application itself rather than from the configuration, which never lists them.
+        const application = await remoteFetch('/applications/' + id + '?select=attachments');
+        const attachments = await copyAttachments(application.attachments ?? [], (name) => remoteFetchBuffer('/applications/' + id + '/attachments/' + encodeURIComponent(name)));
+        if (attachments.failed.length) {
+            console.warn('[dev-server] failed to copy attachments ' + attachments.failed.join(', ') + ', images referencing them will be broken');
+        }
+        res.send({ configuration, attachments });
     }
     catch (err) {
         res.status(500).send({ error: err.message });
@@ -407,7 +469,7 @@ app.use('/app', createProxyMiddleware({
                     let output = rawBody.toString();
                     if (output.includes('%APPLICATION%')) {
                         try {
-                            configuration = await refreshConfigDatasets(configuration);
+                            configuration = await prepareConfig(configuration);
                         }
                         catch (err) {
                             console.warn('[dev-server] failed to enrich configuration datasets', err);
@@ -419,6 +481,8 @@ app.use('/app', createProxyMiddleware({
                             configuration,
                             exposedUrl: `http://localhost:${config.port}/app`,
                             href: `http://localhost:${config.port}/config`,
+                            // data-fair serializes the whole application document, attachments included
+                            attachments: listAttachments(),
                             apiUrl: `http://localhost:${config.port}/data-fair/api/v1`,
                             wsUrl: `ws://localhost:${config.port}/data-fair`,
                             owner: config.dataFair && config.dataFair.owner

package/src/attachments.d.ts

@@ -0,0 +1,19 @@
+export declare const ATTACHMENTS_DIR = ".dev-attachments";
+export type Attachment = {
+    name: string;
+    title: string;
+    size: number;
+    mimetype: string;
+    updatedAt: string;
+};
+export declare const listAttachments: (dir?: string) => Attachment[];
+export declare const attachmentPath: (dir: string, name: string) => string | undefined;
+export type CopyAttachmentsResult = {
+    copied: string[];
+    failed: string[];
+};
+export declare const copyAttachments: (attachments: {
+    name?: string;
+    title?: string;
+    mimetype?: string;
+}[], fetchAttachment: (name: string) => Promise<Buffer>, dir?: string) => Promise<CopyAttachmentsResult>;

package/src/attachments.js

@@ -0,0 +1,125 @@
+// Attachments of the application under development.
+//
+// data-fair lets an application carry attached files: they are listed in the application
+// object (window.APPLICATION.attachments), offered by the configuration form through the
+// `context.attachments` of vjsf, and served under <application.href>/attachments/<name>.
+// An application configuration therefore stores an attachment by name only — see the
+// attachmentImage pattern used by app-eco-watt and friends — and rebuilds its url at
+// render time. We mirror that whole contract locally, with the files sitting in a
+// git-ignored directory, so an image referenced by a copied production configuration
+// displays in dev exactly as it does in production.
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { extname, join, resolve, sep } from 'node:path';
+export const ATTACHMENTS_DIR = '.dev-attachments';
+// Titles are metadata of the remote application, nothing on disk holds them. They are kept
+// beside the files, in a dotfile: hidden entries are excluded from the listing below, so the
+// sidecar can never be mistaken for an attachment.
+const METADATA_FILE = '.metadata.json';
+// Enough to cover what an application attaches (images, and the occasional document). An
+// unknown extension falls back to the mimetype the remote data-fair reported, then to the
+// generic binary type — never to a guess that a browser would act upon.
+const MIME_TYPES = {
+    '.avif': 'image/avif',
+    '.csv': 'text/csv',
+    '.gif': 'image/gif',
+    '.ico': 'image/vnd.microsoft.icon',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.json': 'application/json',
+    '.pdf': 'application/pdf',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml',
+    '.txt': 'text/plain',
+    '.webp': 'image/webp'
+};
+const readMetadata = (dir) => {
+    const path = join(dir, METADATA_FILE);
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (!Array.isArray(parsed))
+            return {};
+        return Object.fromEntries(parsed.filter(a => a?.name).map(a => [a.name, a]));
+    }
+    catch (err) {
+        // a hand-edited or truncated sidecar must not take the whole listing down with it:
+        // the files themselves are the source of truth, the metadata only decorates them
+        return {};
+    }
+};
+// The directory is the source of truth, not the sidecar: an image a developer drops in by
+// hand is listed just like one copied from a remote application, and a file deleted by hand
+// disappears. Size and date come from the file, since the local file is what is served.
+export const listAttachments = (dir = ATTACHMENTS_DIR) => {
+    if (!existsSync(dir))
+        return [];
+    const metadata = readMetadata(dir);
+    return readdirSync(dir, { withFileTypes: true })
+        .filter(entry => entry.isFile() && !entry.name.startsWith('.'))
+        .map(entry => {
+        const stats = statSync(join(dir, entry.name));
+        const known = metadata[entry.name];
+        return {
+            name: entry.name,
+            title: known?.title ?? entry.name,
+            size: stats.size,
+            mimetype: MIME_TYPES[extname(entry.name).toLowerCase()] ?? known?.mimetype ?? 'application/octet-stream',
+            updatedAt: stats.mtime.toISOString()
+        };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+};
+// The requested name reaches us from an application configuration copied from a remote
+// data-fair, so it is never to be trusted: resolve it and refuse anything that lands outside
+// the attachments directory. undefined means "no such attachment", never "here is /etc/passwd".
+export const attachmentPath = (dir, name) => {
+    if (!name)
+        return undefined;
+    const dirPath = resolve(dir);
+    const filePath = resolve(dirPath, name);
+    if (!filePath.startsWith(dirPath + sep))
+        return undefined;
+    return filePath;
+};
+// Replace the whole local attachments directory with the attachments of a remote application.
+// Replace, and not merge: copying a configuration replaces the current one entirely, so leaving
+// behind the images of the previously copied application would only produce a directory whose
+// content matches no configuration at all.
+//
+// Everything is downloaded before anything is written, then the directory is swapped in one
+// rename: an interrupted or partly failing copy — a private file with no api key, a network
+// hiccup — never leaves a half-written directory behind, and what did download is kept. A copy
+// where nothing downloads does empty the directory, which is the point: the configuration it
+// came with is being applied all the same, and its images are genuinely missing.
+export const copyAttachments = async (attachments, fetchAttachment, dir = ATTACHMENTS_DIR) => {
+    const result = { copied: [], failed: [] };
+    const downloaded = [];
+    for (const attachment of attachments ?? []) {
+        // a name with a path separator would write outside the directory, and data-fair has no
+        // reason to send one: skip it rather than sanitize a name the configuration still refers to
+        if (!attachment?.name || attachmentPath(dir, attachment.name) === undefined) {
+            if (attachment?.name)
+                result.failed.push(attachment.name);
+            continue;
+        }
+        try {
+            downloaded.push({ attachment: { ...attachment, name: attachment.name }, body: await fetchAttachment(attachment.name) });
+        }
+        catch (err) {
+            result.failed.push(attachment.name);
+        }
+    }
+    // written aside then swapped in, so an interrupted copy leaves the previous directory intact
+    const tmpDir = dir + '.tmp';
+    rmSync(tmpDir, { recursive: true, force: true });
+    mkdirSync(tmpDir, { recursive: true });
+    for (const { attachment, body } of downloaded) {
+        writeFileSync(join(tmpDir, attachment.name), body);
+        result.copied.push(attachment.name);
+    }
+    writeFileSync(join(tmpDir, METADATA_FILE), JSON.stringify(downloaded.map(d => d.attachment), null, 2));
+    rmSync(dir, { recursive: true, force: true });
+    renameSync(tmpDir, dir);
+    return result;
+};

package/src/dev-env.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/src/dev-env.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { parseArgs } from 'node:util';
+import { MIN_BASE, MAX_BASE, renderEnv, findBase, readEnvVar } from './env-file.js';
+const { values } = parseArgs({
+    options: {
+        force: { type: 'boolean', default: false },
+        // No default value: an absent --app-path must stay distinguishable from an explicit one, so
+        // that --force can redraw the ports without resetting a path the developer chose.
+        'app-path': { type: 'string' }
+    }
+});
+const existing = existsSync('.env') ? readFileSync('.env', 'utf8') : undefined;
+const storedAppPath = existing === undefined ? undefined : readEnvVar(existing, 'APP_PATH');
+if (existing !== undefined && !values.force) {
+    // An existing .env is left untouched — but say so when leaving it untouched is not what the
+    // caller expected, rather than letting the application start on the wrong port or path.
+    if (readEnvVar(existing, 'APP_PORT') === undefined) {
+        console.warn('.env existe déjà mais ne porte pas APP_PORT : y ajouter les lignes de port à la main, ou df-dev-env --force');
+    }
+    else if (values['app-path'] !== undefined && values['app-path'] !== storedAppPath) {
+        console.warn(`.env existe déjà avec APP_PATH=${storedAppPath} : --app-path=${values['app-path']} est ignoré, df-dev-env --force pour l'appliquer`);
+    }
+    process.exit(0);
+}
+const isFree = (port) => new Promise(resolve => {
+    const server = createServer();
+    server.once('error', () => { resolve(false); });
+    server.once('listening', () => { server.close(() => { resolve(true); }); });
+    server.listen(port, '127.0.0.1');
+});
+const draw = () => MIN_BASE + Math.floor(Math.random() * (MAX_BASE - MIN_BASE + 1));
+// --force is the documented remedy for a port collision: it must not silently move an
+// application served at the root back under /app/ along the way.
+const appPath = values['app-path'] ?? storedAppPath ?? '/app/';
+const base = await findBase(isFree, draw);
+writeFileSync('.env', renderEnv(base, appPath));
+console.log(`.env généré — app ${base}, dev-server ${base + 1}, e2e ${base + 2}, chemin ${appPath || '/ (racine)'}`);

package/src/env-file.d.ts

@@ -0,0 +1,5 @@
+export declare const MIN_BASE = 20000;
+export declare const MAX_BASE = 29997;
+export declare const renderEnv: (base: number, appPath: string) => string;
+export declare const readEnvVar: (content: string, name: string) => string | undefined;
+export declare const findBase: (isFree: (port: number) => Promise<boolean>, draw: () => number, attempts?: number) => Promise<number>;

package/src/env-file.js

@@ -0,0 +1,28 @@
+// Development ports live below the kernel ephemeral range (32768-60999 on Linux), where a port
+// can already be held by an outgoing connection, and above the 191xx block used by the
+// data-fair docker compose.
+export const MIN_BASE = 20000;
+// The base takes three consecutive ports, so it may not go past 29999.
+export const MAX_BASE = 29997;
+export const renderEnv = (base, appPath) => `# généré par df-dev-env — ne pas commiter
+APP_PORT=${base}
+DEV_SERVER_PORT=${base + 1}
+E2E_PORT=${base + 2}
+APP_PATH=${appPath}
+`;
+// Reads one variable out of an already written .env. Used to tell a .env that carries our ports
+// from one written for another purpose, and to keep the APP_PATH a developer chose when --force
+// redraws the ports. Deliberately naive: the file we read is the one we wrote.
+export const readEnvVar = (content, name) => {
+    const line = content.split('\n').find(l => l.startsWith(name + '='));
+    return line === undefined ? undefined : line.slice(name.length + 1).trim();
+};
+export const findBase = async (isFree, draw, attempts = 10) => {
+    for (let i = 0; i < attempts; i++) {
+        const base = draw();
+        const free = await Promise.all([base, base + 1, base + 2].map(isFree));
+        if (free.every(Boolean))
+            return base;
+    }
+    throw new Error(`no free port range found after ${attempts} attempts`);
+};

package/src/localize.d.ts

@@ -0,0 +1 @@
+export declare const localizeConfig: <T>(configuration: T, remoteOrigin: string, localOrigin: string) => T;

package/src/localize.js

@@ -0,0 +1,16 @@
+// Configurations are stored with their remote (koumoul.com) origins so that .dev-config.json
+// stays portable across developers, machines and regenerated ports. Origins are rewritten here,
+// on the read path, on the way to the application — never on the write path.
+// Paths the dev-server re-exposes under its own origin.
+const PROXIED_PATHS = ['/data-fair', '/simple-directory', '/tileserver'];
+// Transition rewrite: .dev-config.json files written before this change carry a hardcoded
+// http://localhost:5888 origin. Only rewrite one when it stands on a path we actually proxy,
+// and only when that path is complete — a deliberate http://localhost:8080/data-fair-lookalike
+// typed by a developer must survive untouched.
+const legacyLocalOrigin = new RegExp(`http://localhost:\\d+(?=(?:${PROXIED_PATHS.join('|')})(?:/|"))`, 'g');
+export const localizeConfig = (configuration, remoteOrigin, localOrigin) => {
+    const json = JSON.stringify(configuration);
+    if (json === undefined)
+        return configuration;
+    return JSON.parse(json.replaceAll(remoteOrigin, localOrigin).replace(legacyLocalOrigin, localOrigin));
+};