tosijs-ui 1.8.0 → 1.9.0-beta.1

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 1.9.0-beta.1
+
+> **Prerelease.** The preview-host system works end to end and is in daily use, but the
+> plan it belongs to (`REMOTE-ACCESS-PLAN.md`) has two more phases. Published under the
+> `beta` dist-tag — **install with `tosijs-ui@beta`**; `latest` stays on 1.8.0.
+>
+> It's a **minor**, not a patch, despite being unfinished: it adds public API
+> (`SiteConfig.preview`), emits a new artifact into every adopter's output
+> (`/version.json`), and changes what happens when a build fails. Semver tracks the
+> shape of a change, not how done it feels.
+
+- **New: preview hosting.** `bun run deploy` rsyncs the built site to a box you control,
+  so a phone, a client, or a reviewer can see it without your dev server — or your
+  laptop — being up. The whole artifact is a few MB, so this is a copy, not a pipeline.
+  - **`preview: { host, path?, url? }`** in the site config. Only `host` is required;
+    `path` defaults to `/srv/preview/<name>`. Flag > env > config, so a one-off push
+    elsewhere doesn't need a config edit.
+  - **Dry run by default.** It runs `rsync --delete` (the remote must mirror the build,
+    stale pages must not linger), so the destructive form has to be typed: `--go`. It
+    also refuses any target that isn't an absolute path at least two levels deep.
+  - **Projects self-register.** Each deploy writes its own Caddy fragment; the server
+    glob-imports them. Adding a project touches no shared config and needs no DNS
+    change. The deploy **validates before reloading** and refuses to reload on invalid
+    config, so one bad fragment can't take down every project on the box.
+  - `deploy/Caddyfile` and `deploy/build-index.sh` are committed — server config in git
+    beats server config in someone's shell history.
+- **New: `/version.json`** in every build — `{ generator, site, commit, commitTime }`.
+  Nothing exposed which commit produced a given site before. It matters wherever a
+  deploy is a snapshot: a reviewer can otherwise report a bug you fixed this morning
+  with no way to tell from the page which of you is stale.
+  **Deliberately deterministic** — no build timestamp, no dirty flag — so a committed
+  output dir doesn't churn on every build. Git fields are omitted (never blank) when
+  git isn't available.
+- **Fix: a failed rebuild no longer destroys the site.** `buildSite()` opens with
+  `rm -rf <outputDir>`, so a build failing after that left nothing to serve — save a
+  typo, and the next refresh was a dead site. The dev server now moves the working
+  build aside first and restores it on failure, **and says so on the page**: the
+  existing floating widget (which already means "the far end has something to tell
+  you") shows the failure until a good build clears it, with detail in the console.
+  Note it survives the "tests disabled" preference — otherwise the one person who
+  turned test indicators off is the one who never learns their build is broken.
+- **New: `DEV_NO_WATCH=1`** serves the built site without watching, for automated
+  suites that want a server rather than a rebuilder.
+
 ## 1.8.0
 
 > **Read this first if you use `tosijs-ui/site`.** This release adds a **dependency-audit
@@ -47,6 +91,16 @@
   filename with a raw NUL byte, which makes macOS `grep` silently match **nothing** in that
   file (exit 1, no message) — so searching it for any symbol came back empty and the sort bug
   above was effectively unfindable. The comparator needs no delimiter; the NUL is gone.
+  - **Adopting the gate — budget for one upgrade, not one pin.** From the first real
+    adoption (`tosijs`, which went from 12 blocking advisories to zero): if the gate flags
+    **`brace-expansion`**, note that `GHSA-mh99-v99m-4gvg` marks *every* version below
+    **5.0.8** affected, so the override is mandatory — and `brace-expansion@5` breaks
+    **eslint 8**'s bundled `minimatch@3` with `expand is not a function`. In practice that
+    means **an eslint 8 → 10 migration** (flat config + typescript-eslint 8), not a one-line
+    pin. The upside is that it clears the whole `minimatch`/`js-yaml`/`flatted` cluster at
+    once — which is exactly what the advisories-per-package tally is telling you when it
+    fingers a stale toolchain. Expect "replace, don't patch" to be the right answer more
+    often than a targeted override.
 - **New: `openBrowser`** site-config option — opens the doc site on dev-server start, reusing
   an existing tab on macOS rather than piling up new ones.
 - **New: `DEV_NO_WATCH=1`** serves the built site without watching. The E2E lane used to run

package/dist/doc-browser.js

@@ -191,6 +191,10 @@ const testIndicatorStyleSpec = {
     'body:not(.tests-enabled) .doc-link::after, body:not(.tests-enabled) .test-widget': {
         display: 'none !important',
     },
+    // ...EXCEPT a far-end status (a failed build). That is not a test result, so the
+    // "show test indicators" preference must not suppress it — otherwise the one
+    // person who turned tests off is the one who never learns their build is broken.
+    'body .test-widget.-dev-status': { display: 'flex !important' },
     // Nav link dot indicators
     '.doc-link.-test-passed::after, .doc-link.-test-failed::after': {
         content: "''",
@@ -1210,8 +1214,48 @@ export function createDocBrowser(options) {
         onClick: showTestMenu,
     }, span({ part: 'label' }, 'Tests'), span({ class: 'count', part: 'count' }, '0'));
     container.appendChild(testWidget);
+    /*
+    The far end has something to tell you.
+  
+    The dev server injects `window.__tosiDevStatus` at serve time when a rebuild has
+    FAILED — see statusSnippet() in site/dev-server.ts. That is the same kind of news
+    as a failing browser test (something broke; here is what), so it uses the same
+    floating widget rather than a second overlay competing for the same corner.
+  
+    Two differences from a test run, both deliberate:
+      - it does NOT auto-fade. A passing test run is over; a broken build is a standing
+        condition you have to act on, and it stays until a good build clears it.
+      - it wins ties. If tests also failed, the build failure is the more useful thing
+        to read first — the tests probably failed BECAUSE the build did.
+  
+    Nothing is injected when the server is healthy, so this is inert in production and
+    in a normal session.
+    */
+    const devStatus = globalThis.__tosiDevStatus;
+    let devStatusShown = false;
+    if (devStatus && devStatus.ok === false) {
+        devStatusShown = true;
+        const labelEl = testWidget.querySelector('[part="label"]');
+        const countEl = testWidget.querySelector('[part="count"]');
+        if (labelEl)
+            labelEl.textContent = devStatus.label || 'Build failed';
+        if (countEl)
+            countEl.hidden = true;
+        testWidget.classList.add('-failed', '-dev-status');
+        testWidget.hidden = false;
+        testWidget.title = devStatus.detail || '';
+        // The page you are reading is the LAST GOOD build — the dev server keeps serving
+        // it rather than the wreckage of the failed one — so say so plainly in the
+        // console, where the detail is readable and copyable.
+        console.error(`[tosi] ${devStatus.label || 'Build failed'} — showing the last good build.\n` +
+            (devStatus.detail || ''));
+    }
     let testsRunning = false;
     function setTestWidgetRunning() {
+        // A broken build outranks a test run: the tests very likely failed BECAUSE the
+        // build did, so replacing "Build failed" with "Tests" would hide the cause.
+        if (devStatusShown)
+            return;
         testsRunning = true;
         testWidget.hidden = false;
         testWidget.classList.remove('-passed', '-failed');

package/dist/doc-system/site/build-stamp.d.ts

@@ -0,0 +1,23 @@
+export interface BuildStamp {
+    /** the tosijs-ui version that generated this site */
+    generator: string;
+    /** the project's name, from site config */
+    site?: string;
+    /** short commit hash the site was built from, when available */
+    commit?: string;
+    /** ISO-8601 commit timestamp, when available */
+    commitTime?: string;
+}
+/** Injectable git seam for tests. Returns '' when the command can't run. */
+export type GitReader = (args: string[]) => Promise<string>;
+/**
+ * Collect build identity. Git fields are omitted (not blank) when unavailable, so
+ * `version.json` never asserts something it doesn't know.
+ */
+export declare function gatherBuildStamp(opts?: {
+    generator: string;
+    site?: string;
+    git?: GitReader;
+}): Promise<BuildStamp>;
+/** Serialize for `/version.json` (trailing newline so the file is diff-friendly). */
+export declare function serializeBuildStamp(stamp: BuildStamp): string;

package/dist/doc-system/site/build-stamp.js

@@ -0,0 +1,65 @@
+/*
+Build identity for a generated site: `/version.json`.
+
+Answers one question — **what am I looking at?** — for any deployed copy of the site.
+Nothing in the build exposed this before: `src/version.ts` is the *library* version,
+which says nothing about which commit of the CONSUMER's project produced a given
+build.
+
+That question is easy to shrug at locally and genuinely expensive elsewhere. A static
+deploy is a snapshot, so a preview host serves whatever was last pushed to it; someone
+reviews it, reports a bug you fixed this morning, and there is no way to tell from the
+page which of you is out of date. Same for a published doc site after a partial deploy.
+
+DELIBERATELY DETERMINISTIC — no build timestamp.
+
+`docs/` is committed in this repo (and in the other tosijs-* projects), so anything
+that changes on every build shows up as a diff on every commit. A wall-clock stamp
+would churn the tree forever and train everyone to ignore it — the same nuisance the
+non-reproducible ePub already causes. Identity comes from the COMMIT instead, so
+rebuilding the same source twice produces byte-identical output. That is also the more
+useful answer: you want to know which source this is, not when someone happened to run
+a build.
+
+There is no `dirty` flag for the same reason. A build made from a dirty tree reports
+its last commit, which may not describe what was actually built — so the warning
+belongs at DEPLOY time, where a human can act on it, not baked into a committed file
+that would then be permanently wrong.
+
+Best-effort by construction: a consumer of `tosijs-ui/site` may not be in a git repo
+at all, and a build must never fail because it couldn't read git metadata.
+*/
+import { $ } from 'bun';
+const defaultGit = async (args) => {
+    try {
+        const r = await $ `git ${args}`.nothrow().quiet();
+        return r.exitCode === 0 ? r.stdout.toString().trim() : '';
+    }
+    catch {
+        return ''; // git absent, not a repo, whatever — never fatal
+    }
+};
+/**
+ * Collect build identity. Git fields are omitted (not blank) when unavailable, so
+ * `version.json` never asserts something it doesn't know.
+ */
+export async function gatherBuildStamp(opts = {
+    generator: 'unknown',
+}) {
+    const git = opts.git ?? defaultGit;
+    const stamp = { generator: opts.generator };
+    if (opts.site)
+        stamp.site = opts.site;
+    const commit = await git(['rev-parse', '--short', 'HEAD']);
+    if (commit)
+        stamp.commit = commit;
+    // %cI is the committer date, strict ISO-8601 — stable for a given commit.
+    const commitTime = await git(['log', '-1', '--format=%cI']);
+    if (commitTime)
+        stamp.commitTime = commitTime;
+    return stamp;
+}
+/** Serialize for `/version.json` (trailing newline so the file is diff-friendly). */
+export function serializeBuildStamp(stamp) {
+    return JSON.stringify(stamp, null, 2) + '\n';
+}

package/dist/doc-system/site/dev-server.d.ts

@@ -38,6 +38,24 @@ export declare function resolveLimitMb(configMb: number | undefined, envMb: stri
  * once per test page (N redundant loads in throwaway frames). An agent only ever
  * drives the top page, so nested frames never need the channel.
  */
+/**
+ * Is this request coming from THIS machine?
+ *
+ * The dev server binds every interface (`Bun.serve` with no `hostname`), which is
+ * deliberate — the mkcert dev cert covers `<host>.local` precisely so you can open the
+ * site on a phone or a second laptop. But "anyone on this network may READ the preview"
+ * and "anyone on this network may REWRITE my source files" are wildly different
+ * propositions, and the source endpoints were getting the first one's treatment.
+ *
+ * On any shared network — a café, a conference, a hotel — an unauthenticated
+ * `POST /__docstore/source` is remote code execution: it writes a file in the repo, the
+ * watcher rebuilds, and the build runs what was written. So those endpoints are
+ * loopback-only, while the site itself stays reachable from your other devices.
+ *
+ * IPv4-mapped IPv6 (`::ffff:127.0.0.1`) counts — that is how a v4 client shows up on a
+ * dual-stack listener, and missing it would lock out the local machine on some setups.
+ */
+export declare function isLoopbackAddress(address: string | undefined | null): boolean;
 export declare function haltijaLoaderSnippet(httpsPort: number): string;
 export declare function devServer(config: SiteConfig, opts?: {
     test?: boolean;

package/dist/doc-system/site/dev-server.js

@@ -8,7 +8,7 @@ headless browser through the inline doc tests and exits with their pass/fail.
 Build-time only (Bun APIs). Never import this from browser code.
 */
 import * as path from 'path';
-import { statSync } from 'fs';
+import { statSync, existsSync } from 'fs';
 import { watch } from 'chokidar';
 import { $, spawn } from 'bun';
 import { buildSite } from './orchestrator';
@@ -90,6 +90,33 @@ export function resolveLimitMb(configMb, envMb) {
  * once per test page (N redundant loads in throwaway frames). An agent only ever
  * drives the top page, so nested frames never need the channel.
  */
+/**
+ * Is this request coming from THIS machine?
+ *
+ * The dev server binds every interface (`Bun.serve` with no `hostname`), which is
+ * deliberate — the mkcert dev cert covers `<host>.local` precisely so you can open the
+ * site on a phone or a second laptop. But "anyone on this network may READ the preview"
+ * and "anyone on this network may REWRITE my source files" are wildly different
+ * propositions, and the source endpoints were getting the first one's treatment.
+ *
+ * On any shared network — a café, a conference, a hotel — an unauthenticated
+ * `POST /__docstore/source` is remote code execution: it writes a file in the repo, the
+ * watcher rebuilds, and the build runs what was written. So those endpoints are
+ * loopback-only, while the site itself stays reachable from your other devices.
+ *
+ * IPv4-mapped IPv6 (`::ffff:127.0.0.1`) counts — that is how a v4 client shows up on a
+ * dual-stack listener, and missing it would lock out the local machine on some setups.
+ */
+export function isLoopbackAddress(address) {
+    if (!address)
+        return false;
+    const a = address.trim().toLowerCase().replace(/^\[|\]$/g, '');
+    if (a === '::1' || a === 'localhost')
+        return true;
+    // ::ffff:127.0.0.1 — IPv4-mapped IPv6
+    const mapped = a.startsWith('::ffff:') ? a.slice(7) : a;
+    return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(mapped);
+}
 export function haltijaLoaderSnippet(httpsPort) {
     return (`<script>self===top&&/^localhost$|^127\\./.test(location.hostname)` +
         `&&import('https://localhost:${httpsPort}/dev.js')</script>`);
@@ -276,6 +303,13 @@ export async function devServer(config, opts = {}) {
             process.env.HALTIJA_DEV === '1' ||
             process.env.HALTIJA_DEV === 'true');
     const HALTIJA_SNIPPET = haltijaLoaderSnippet(HALTIJA_HTTPS_PORT);
+    /*
+    What the far end has to tell you. `ok: true` means nothing to report and nothing
+    is injected into served pages. A failed rebuild sets it; the next good build
+    clears it. Surfaced through the page's existing floating widget — see
+    statusSnippet() below and the `__tosiDevStatus` reader in doc-browser.ts.
+    */
+    let buildStatus = { ok: true };
     let testReportResolve;
     // Source read/write for in-browser "edit page source" (config.editableSources).
     // Local dev only — your machine, your files — so the lone guard is correctness:
@@ -342,15 +376,41 @@ export async function devServer(config, opts = {}) {
         }
         return null;
     }
-    // Serve a resolved file, injecting the haltija dev-channel loader into HTML
-    // pages when enabled. Serve-time only — the loader never touches the built
-    // output on disk, and non-HTML assets are streamed untouched.
+    /*
+    Serve-time status for the page's floating widget.
+  
+    The widget already exists and already means "the far end has something to tell
+    you" — it is how browser-test results surface. A failed rebuild is the same kind
+    of news, so it uses the same surface rather than inventing a second one.
+  
+    Injected as a plain global rather than pushed over a socket: the case that matters
+    is "the build broke and I hit refresh", and a refresh re-reads this. (When Phase 2
+    of REMOTE-ACCESS-PLAN.md adds a socket, it can update the same global live.)
+  
+    Only emitted when there IS something to say, so a healthy dev server injects
+    nothing at all.
+    */
+    function statusSnippet() {
+        if (buildStatus.ok)
+            return '';
+        const payload = JSON.stringify({
+            ok: false,
+            label: buildStatus.label,
+            detail: buildStatus.detail,
+            at: buildStatus.at,
+        });
+        return `<script>window.__tosiDevStatus=${payload}</script>`;
+    }
+    // Serve a resolved file, injecting the haltija dev-channel loader and/or a build
+    // status into HTML pages. Serve-time only — neither touches the built output on
+    // disk, and non-HTML assets are streamed untouched.
     async function respondFile(filePath) {
-        if (haltijaDev && filePath.endsWith('.html')) {
+        const extras = (haltijaDev ? HALTIJA_SNIPPET : '') + (testMode ? '' : statusSnippet());
+        if (extras && filePath.endsWith('.html')) {
             const html = await Bun.file(filePath).text();
             const injected = html.includes('</body>')
-                ? html.replace('</body>', `${HALTIJA_SNIPPET}</body>`)
-                : html + HALTIJA_SNIPPET;
+                ? html.replace('</body>', `${extras}</body>`)
+                : html + extras;
             return new Response(injected, {
                 headers: { 'Content-Type': 'text/html; charset=utf-8' },
             });
@@ -499,6 +559,63 @@ export async function devServer(config, opts = {}) {
         // network, and re-running it on every hot-reload save would add latency to the
         // edit loop and break offline dev. The audit ran once at launch (below).
         const runBuild = opts.build ?? (() => buildSite(config, { skipAudit: true }));
+        /*
+        A FAILED REBUILD MUST NOT DESTROY THE SITE YOU ARE LOOKING AT.
+    
+        `buildSite()` begins with `rm -rf <outputDir>` — it has to, since it regenerates
+        the tree — so a build that fails anywhere after that leaves an empty or partial
+        output directory. Before this, the sequence was: save a typo, the rebuild throws,
+        the error scrolls past in a terminal you may not be watching, and the next refresh
+        serves nothing. The site was gone until you noticed and fixed it, and the page
+        gave you no clue why.
+    
+        So: move the working site aside first (a rename — atomic and instant on the same
+        filesystem, and ~9MB of extra disk we will never notice), then build. On success,
+        drop the spare. On failure, put it back and record WHY, so the page keeps working
+        and the widget can say what broke.
+    
+        Deliberately wraps `runBuild`, not `buildSite`: a consumer's custom `{ build }`
+        pipeline gets the same protection without knowing about it.
+        */
+        const LAST_GOOD = `${PUBLIC}.last-good`;
+        const runBuildPreservingLastGood = async () => {
+            const hadSite = existsSync(PUBLIC);
+            if (hadSite) {
+                await $ `rm -rf ${LAST_GOOD}`.nothrow().quiet();
+                await $ `mv ${PUBLIC} ${LAST_GOOD}`.nothrow().quiet();
+            }
+            const restore = async () => {
+                if (!hadSite)
+                    return;
+                await $ `rm -rf ${PUBLIC}`.nothrow().quiet();
+                await $ `mv ${LAST_GOOD} ${PUBLIC}`.nothrow().quiet();
+            };
+            try {
+                // buildSite REPORTS failure by returning false (a blocking advisory, an
+                // output-dir overlap) and THROWS for everything else, so treat both as
+                // failure — a falsy return that we ignored would silently ship a wiped site.
+                const result = await runBuild();
+                if (result === false)
+                    throw new Error('build reported failure');
+                if (hadSite)
+                    await $ `rm -rf ${LAST_GOOD}`.nothrow().quiet();
+                if (!buildStatus.ok)
+                    console.log('✅ build recovered — serving fresh output');
+                buildStatus = { ok: true, at: Date.now() };
+            }
+            catch (error) {
+                await restore();
+                buildStatus = {
+                    ok: false,
+                    label: 'Build failed',
+                    detail: String(error instanceof Error ? error.message : error).slice(0, 2000),
+                    at: Date.now(),
+                };
+                console.error(`\n🛑 Rebuild failed — still serving the last good build.\n` +
+                    `   Fix the error above; the next successful build clears this.\n`);
+                throw error;
+            }
+        };
         // Rebuild-storm detector.
         //
         // The other way this process eats the machine is not a leak but a LOOP: if the
@@ -547,7 +664,7 @@ export async function devServer(config, opts = {}) {
             // Both look like: started again with no gap.
             const immediate = lastBuildEnd > 0 && Date.now() - lastBuildEnd < IMMEDIATE_MS;
             try {
-                await runBuild();
+                await runBuildPreservingLastGood();
             }
             catch (error) {
                 console.error('rebuild failed:', error);
@@ -627,7 +744,7 @@ export async function devServer(config, opts = {}) {
             key: Bun.file('./tls/key.pem'),
             cert: Bun.file('./tls/certificate.pem'),
         },
-        async fetch(request) {
+        async fetch(request, srv) {
             touch();
             let reqPath = new URL(request.url).pathname;
             console.log(request.method, reqPath);
@@ -647,6 +764,26 @@ export async function devServer(config, opts = {}) {
                 if (!config.editableSources) {
                     return new Response('editableSources is not enabled in this doc-site config (set editableSources: true to edit/save source in dev)', { status: 501, headers: { 'Content-Type': 'text/plain; charset=utf-8' } });
                 }
+                // LOOPBACK ONLY. Reading exposes any file in the repo; writing is remote code
+                // execution (write a file, the watcher rebuilds, the build runs it). Checked on
+                // the PEER ADDRESS, never on Origin/Host, which are attacker-supplied.
+                //
+                // There is deliberately NO override. An env var that re-enables this would have
+                // no legitimate use today — nothing authenticates in front of this server — and
+                // it is exactly the shape of guard that gets set once in a shell profile and
+                // stays off forever. Remote editing is not a flag to flip; it needs real
+                // authentication, and that is Phase 3 of REMOTE-ACCESS-PLAN.md, where the
+                // schema is the authorization boundary and a session (not a location, and not
+                // an env var) decides who may write. Until then: view remotely, edit locally.
+                const peer = srv?.requestIP?.(request)?.address;
+                if (!isLoopbackAddress(peer)) {
+                    console.warn(`⚠️  refused ${request.method} /__docstore/source from ${peer ?? 'unknown'} — ` +
+                        `source editing is local-only.`);
+                    return new Response('source editing is restricted to this machine', {
+                        status: 403,
+                        headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+                    });
+                }
                 if (request.method === 'GET')
                     return handleReadSource(request);
                 if (request.method === 'POST')

package/dist/doc-system/site/orchestrator.js

@@ -23,6 +23,8 @@ import { generateSite } from './generate-site';
 import { findOutputDirOverlap } from './output-guard';
 import { preflight } from './preflight';
 import { auditDependencies, reportAudit } from './audit-guard';
+import { gatherBuildStamp, serializeBuildStamp } from './build-stamp';
+import { version } from '../../version';
 import { tjsEditorExternal, tjsEditorLeakedAsExternal, classicScriptSyntaxErrorInChild, } from './bundle-guard';
 // Module specifiers contain regex metacharacters (`/`, `.`, `@`, …), so escape
 // before interpolating into the require-shim detector below.
@@ -627,6 +629,10 @@ export async function buildSite(config, opts = {}) {
         scriptUrl: config.scriptUrl,
         basePath: config.basePath,
     });
+    // Build identity at /version.json — "what am I looking at?" for any deployed copy.
+    // Deterministic (commit-derived, no wall clock) so a committed outputDir doesn't
+    // churn on every build. See build-stamp.ts.
+    await Bun.write(`${PUBLIC}/version.json`, serializeBuildStamp(await gatherBuildStamp({ generator: version, site: config.name })));
     // Burn the theme into a static stylesheet (separate subprocess — see
     // generate-css.ts). Resolve the sibling relative to THIS module so it works
     // both in-repo (.ts) and when shipped (compiled .js).

package/dist/doc-system/site/site-config.d.ts

@@ -291,6 +291,31 @@ export interface SiteConfig {
      * permission prompt ("<runtime> wants to control <Browser>") — approve it once.
      */
     openBrowser?: boolean | string;
+    /**
+     * Preview host for `bun bin/deploy-preview.ts` — rsync the built site to a box you
+     * control, so a phone, a client, or a reviewer can see it without your dev server
+     * (or your laptop) being up.
+     *
+     * Only `host` is required; everything else has a sensible default:
+     *
+     * ```ts
+     * preview: { host: 'root@203.0.113.10' }
+     * // → rsyncs <outputDir>/ to /srv/preview/<name>/ on that box
+     * ```
+     *
+     * The deploy is a plain `rsync --delete` of static files — the whole artifact is a
+     * few MB — so there is no pipeline, no build service, and (because static files
+     * have no write endpoint) no meaningful attack surface to design around. See
+     * REMOTE-ACCESS-PLAN.md.
+     */
+    preview?: {
+        /** ssh target, e.g. `root@203.0.113.10` or `deploy@preview.example.com` */
+        host: string;
+        /** remote directory; defaults to `/srv/preview/<name>` */
+        path?: string;
+        /** public URL, printed after a successful deploy (e.g. `https://dev.example.com`) */
+        url?: string;
+    };
     /**
      * Enable the dev-server source read/write endpoints (`/__docstore/source`) that
      * back in-browser "edit page source". Local dev only — the dev server runs on