tosijs-ui 1.7.4 → 1.9.0-beta.1

package/CHANGELOG.md

@@ -1,5 +1,137 @@
 # 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
+> gate that is ON BY DEFAULT and can fail your build** — on advisories in _your_ dependency
+> tree, not ours. That is deliberate, and there are three ways out (below). Minor, not patch,
+> precisely because `bun run build` can now exit 1 where it previously didn't.
+
+- **New: dependency-audit gate** (`src/doc-system/site/audit-guard.ts`, exported from
+  `tosijs-ui/site`). `bun audit` knows the registry advisory database; nothing in a normal
+  build ever asked it, so a high-severity advisory in a transitive dep stayed invisible until
+  someone ran it by hand. Now it's asked at the point a human is looking.
+  - **Runs synchronously in every mode** — inside `buildSite` for `bun run build` / `--test`,
+    and in `devServer` **just before it binds the port** (it throws, so the server never comes
+    up). Sub-second in practice; a gate you wait for can't be raced. **Watch rebuilds never
+    audit** — that would put a network call in your edit loop and break offline dev.
+  - **What blocks:** any advisory at or above `level` (default `high`) that isn't gated.
+    Consumer-facing and developer-facing advisories block **alike** — a dev-only dependency
+    still runs on your machine, and the escape hatch makes over-blocking cheap.
+  - **Three ways out:** `audit: { allow: [{ advisory, reason, expires }] }` to accept a risk
+    **on a deadline** (an expired or malformed gate stops suppressing, so it comes back for
+    review instead of living in an allowlist nobody re-reads); `audit: { mode: 'warn' }` to
+    report without failing; `audit: false` or `TOSIJS_AUDIT=off` to disable.
+  - **Fails open, never closed, when it can't check** — offline, registry down, `bun` too old,
+    or past its 20s timeout: it warns and proceeds. It fails **closed** only on a real finding.
+  - **Not downgraded in CI.** Unlike the machine-health preflight (a heuristic about someone's
+    local box), an advisory is deterministic and environment-independent.
+  - **Findings are grouped, sorted worst-first, and annotated** with the _nature_ of the risk
+    (`LEAK/ALTER` / `DoS-only` / `DoS?+ESCALATABLE` / `UNCLASSIFIED`), parsed from the CVSS
+    vector (3.x and 4.0) plus CWEs. Annotation only — it never changes what blocks, and it
+    fails **closed**: ~20% of real advisories carry no CVSS vector at all, and those skew
+    severe. Sub-threshold advisories are listed compactly (previously collected and never
+    shown), plus an **advisories-per-package tally** — a dependency that keeps producing them
+    is a code smell worth replacing rather than patching.
+- **Fix (issue #24, reported by a consumer): nav `order` now sorts numerically.** Section nav
+  and the generated `<!-- toc -->` built a zero-padded *string* key and compared it lexically,
+  so a fractional order silently sorted to the **end** of its section — `order: 1.5` landed
+  after `2`, `3`, … because `"01.5" > "0002"` as text. "Insert a page at N.5" reads like a
+  supported idiom and did the opposite with no warning. The same padding capped `order` at 4
+  digits (10000+ overflowed the width) and mis-sorted negatives. `pinnedSort` is now a
+  multi-key comparator (pin bucket → numeric order → title → filename), which fixes all three.
+  **Removed `navSortKey`** (the string-key builder) — it was never in a public index, but was
+  reachable via the `./*` subpath, so: technically breaking. A string key cannot express this
+  ordering, so there is no corrected version of it.
+- **`src/doc-system/nav-tree.ts` was a binary file.** The old sort key joined title and
+  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
+  `bun start`, so a file watcher stayed live for the whole suite and could `rm -rf docs/` and
+  regenerate underneath a test mid-navigation — the lane flaked against its own build system,
+  which presents as a product bug.
+- **New public API on `tosijs-ui/site`:** `auditDependencies`, `reportAudit`,
+  `resolveAuditMode`, `classifyRisk`, `groupAdvisories`, `openBrowser`, plus their types.
+  `buildSite` takes an optional second argument (`{ skipAudit }`).
+- **Fix: `bun run test-browser` no longer reports success on a failed build.** It computed the
+  build result and launched the test run regardless, so a failing build (or a blocking
+  advisory) still went green. One-shot modes now exit 1.
+- **Fix: the E2E lane can register ServiceWorkers over the dev cert.** `ignoreHTTPSErrors` is a
+  browser-_context_ option and never covered a ServiceWorker's own script fetch, so the
+  import-resolver worker failed to register and `hydration.pw.ts` caught it as a console error.
+  Chromium now launches with `--ignore-certificate-errors`.
+- **Dependency pins:** `overrides` for `flatted` (`>=3.4.2`) and `brace-expansion` (`>=5.0.8`)
+  clear live high-severity advisories. Added `.github/dependabot.yml` so advisories published
+  later against an unchanged lockfile still surface.
+- Includes the unpublished 1.7.5 (header-logo sizing) — npm goes 1.7.4 → 1.8.0.
+
+## 1.7.5
+
+- **Header logo size/spacing are now CSS-tunable** (follow-up to 1.7.4). The brand mark no
+  longer hard-wires a pixel height inline; it carries a `.logo-mark` class driven by two
+  variables — `--tosi-logo-mark-size` (default **32px**, was a fixed 40px) and
+  `--tosi-logo-mark-gap` (default 10px) — for icon, `<img>`, and inline-`<svg>` logos alike.
+  (Icon `<svg>`s take their height from `--tosi-icon-size`, set inline by `makeIcon()`, so the
+  class points that knob at the same variable rather than fighting the inline height.) Retune a
+  logo from CSS instead of editing the build.
+
 ## 1.7.4
 
 - **Configurable header logo.** A new `logo` option lets a doc site set the brand mark shown

package/dist/doc-browser.d.ts

@@ -67,7 +67,9 @@ export interface DocBrowserOptions {
      * - an image URL / path / data: URI (rendered as an `<img>`)
      * - a raw inline `<svg …>…</svg>` string
      * Omit to fall back to the tosijs-ui logo when `projectLinks.tosijs` is set,
-     * or to no mark at all otherwise.
+     * or to no mark at all otherwise. Size and spacing are CSS-tunable via
+     * `--tosi-logo-mark-size` (default 32px) and `--tosi-logo-mark-gap` (default
+     * 10px) on the `.logo-mark` element.
      */
     logo?: string;
     navSize?: number;

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: "''",
@@ -257,9 +261,9 @@ const testIndicatorStyleSpec = {
 // The brand mark shown left of the site title. `logo` (from config) may name a
 // known icon, be an inline `<svg>` string, or be an image URL; when absent we
 // keep the legacy behavior — the tosijs-ui logo iff this is a tosijs project,
-// else nothing. Sized to match the header height so hydration doesn't reflow.
-const LOGO_SIZE = 40;
-const LOGO_GAP = 10;
+// else nothing. Size and spacing are class-driven (`.logo-mark`, see
+// logoMarkStyleSpec) so a consumer retunes them with one CSS variable each,
+// rather than a hard-wired pixel value.
 // `icons` is a Proxy that returns a factory for ANY string (unknown names get a
 // placeholder glyph), so we can't ask it whether a name is real — we route by the
 // shape of the string instead: an inline `<svg>` renders as-is, a URL/path/data:
@@ -274,33 +278,44 @@ function looksLikeImageUrl(s) {
         /\.(png|jpe?g|gif|webp|avif|svg|ico)(\?.*)?$/i.test(s));
 }
 function logoMark(logo, projectLinks) {
+    let mark = null;
     if (logo) {
         if (logo.trimStart().startsWith('<')) {
-            const holder = span({
-                style: {
-                    display: 'inline-flex',
-                    height: `${LOGO_SIZE}px`,
-                    marginRight: `${LOGO_GAP}px`,
-                },
-            });
-            holder.innerHTML = logo;
-            return holder;
+            // Inline <svg>: wrap in a flex holder so `.logo-mark`'s height sizes it.
+            mark = span({ style: { display: 'inline-flex', alignItems: 'center' } });
+            mark.innerHTML = logo;
         }
-        if (looksLikeImageUrl(logo)) {
-            return img({
-                src: logo,
-                alt: '',
-                style: { height: `${LOGO_SIZE}px`, marginRight: `${LOGO_GAP}px` },
-            });
+        else if (looksLikeImageUrl(logo)) {
+            mark = img({ src: logo, alt: '' });
         }
-        return icons[logo]({
-            style: { _xinIconSize: LOGO_SIZE, marginRight: LOGO_GAP },
-        });
+        else {
+            mark = icons[logo]();
+        }
+    }
+    else if (projectLinks.tosijs) {
+        mark = icons.tosiUi();
     }
-    return projectLinks.tosijs
-        ? icons.tosiUi({ style: { _xinIconSize: LOGO_SIZE, marginRight: LOGO_GAP } })
-        : span();
+    // No mark → an empty span with NO class, so it carries no margin (the title
+    // stays flush; a flex `gap` on the header link couldn't do that).
+    if (!mark)
+        return span();
+    mark.classList.add('logo-mark');
+    return mark;
 }
+const logoMarkStyleSpec = {
+    '.logo-mark': {
+        height: 'var(--tosi-logo-mark-size, 32px)',
+        // An icon <svg> takes its height from --tosi-icon-size, set INLINE on the svg
+        // by makeIcon() — which beats a class `height` rule. Point that knob at the
+        // same variable so one --tosi-logo-mark-size drives an icon, an <img>, or an
+        // inline <svg> alike.
+        _tosiIconSize: 'var(--tosi-logo-mark-size, 32px)',
+        marginRight: 'var(--tosi-logo-mark-gap, 10px)',
+        flexShrink: '0',
+    },
+    // Inline-<svg> logos are wrapped in a flex holder; scale the embedded svg to it.
+    '.logo-mark > svg': { height: '100%', width: 'auto' },
+};
 // Monotonic per-page counter so each createDocBrowser() call gets a distinct
 // tosi() registry key (see stateKey below) and two browsers can't share state.
 let docBrowserSeq = 0;
@@ -1190,6 +1205,8 @@ export function createDocBrowser(options) {
     showDoc(currentDoc);
     // Inject test indicator styles
     StyleSheet('test-indicators', testIndicatorStyleSpec);
+    // Header brand-mark sizing (icon / <img> / inline-<svg>), one CSS var each.
+    StyleSheet('doc-logo-mark', logoMarkStyleSpec);
     // Floating widget for test status
     const testWidget = button({
         class: 'test-widget',
@@ -1197,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/nav-tree.d.ts

@@ -14,12 +14,31 @@ export interface NavNode<T extends NavDoc = NavDoc> {
     depth: number;
 }
 /**
- * Total-order sort key: pin bucket (top<none<bottom), then `order` (default
- * 500), then title, then filename. The filename tiebreak guarantees a stable
- * total order even for equal titles — required so the generated TOC blocks are
- * idempotent (no build-to-build churn).
+ * Total order: pin bucket (top<none<bottom), then `order` (NUMERIC, default 500),
+ * then title, then filename. The filename tiebreak guarantees a stable total order
+ * even for equal titles — required so the generated TOC blocks are idempotent (no
+ * build-to-build churn).
+ *
+ * This is a multi-key COMPARATOR, not a concatenated string key, and that is the
+ * whole point (issue #24, reported by a consumer). The old version built
+ * `bucket + String(order).padStart(4,'0') + title + filename` and compared it
+ * lexically, so `order` sorted as TEXT:
+ *
+ *   order 1   -> "0001"
+ *   order 2   -> "0002"
+ *   order 1.5 -> String(1.5) = "1.5" -> padStart(4,'0') = "01.5"
+ *
+ * and lexically "01.5" > "0002" (at index 1, '1' > '0'), so a doc at 1.5 sorted
+ * AFTER 2, 3, ... — last in its section. "Insert a page at N.5" reads like a
+ * supported idiom and silently did the opposite, with no warning. The same padding
+ * also capped `order` at 4 digits (10000+ overflowed the width) and mis-sorted
+ * negatives. Comparing numbers as numbers fixes all three.
+ *
+ * The old key also joined title and filename with a raw NUL byte, which made this
+ * file BINARY: macOS grep then silently matches nothing in it (exit 1, no message),
+ * so searching this file for any symbol came back empty and the padStart bug was
+ * effectively unfindable. A comparator needs no delimiter, so the NUL is gone.
  */
-export declare function navSortKey(doc: NavDoc): string;
 export declare function pinnedSort(a: NavDoc, b: NavDoc): number;
 /**
  * Build the forest of top-level nav nodes. Children are grouped under their

package/dist/doc-system/site/audit-guard.d.ts

@@ -0,0 +1,124 @@
+export type AuditSeverity = 'info' | 'low' | 'moderate' | 'high' | 'critical';
+export type AuditMode = 'fail' | 'warn' | 'off';
+/** One advisory as `bun audit --json` reports it, flattened with its package. */
+export interface AuditAdvisory {
+    package: string;
+    id: number;
+    url: string;
+    title: string;
+    severity: AuditSeverity;
+    vulnerableVersions?: string;
+    /** GHSA id parsed from `url`, e.g. 'GHSA-25h7-pfq9-p65f' (if present) */
+    ghsa?: string;
+    /** what KIND of harm this is — annotation only, never changes whether it blocks */
+    risk?: Classification;
+}
+export type RiskNature = 
+/** C or I impact — can leak or alter data / execute code */
+'compromise'
+/** availability-only — resource exhaustion, hang, crash */
+ | 'dos'
+/** no or unparseable vector, or an escalatable CWE — assume the worst */
+ | 'unknown';
+export interface Classification {
+    nature: RiskNature;
+    /** short label for the report line */
+    label: string;
+    /** what drove the call, so the reader can second-guess it */
+    basis: string;
+}
+/** Classify one advisory's nature from its CVSS vector + CWEs. Fails CLOSED. */
+export declare function classifyRisk(raw: {
+    cvss?: {
+        vectorString?: string;
+    } | null;
+    cwe?: string[] | null;
+}): Classification;
+/**
+ * A time-boxed exception. A gate suppresses a matching advisory ONLY while it is
+ * valid and unexpired — after `expires` it stops suppressing and the build fails
+ * again, which is the point: an accepted risk gets re-evaluated on a deadline
+ * rather than living forever in an allowlist nobody re-reads.
+ */
+export interface AuditGate {
+    /** GHSA id, the numeric advisory id, or a package name (package match is broad) */
+    advisory: string;
+    /** why this is temporarily allowed — required, non-empty */
+    reason: string;
+    /** YYYY-MM-DD; on/after this date the gate no longer suppresses — required */
+    expires: string;
+}
+export interface AuditConfig {
+    /** 'fail' (default) blocks the build; 'warn' reports and proceeds; 'off' skips it */
+    mode?: AuditMode;
+    /** minimum severity that blocks, default 'high' */
+    level?: AuditSeverity;
+    /** time-boxed exceptions */
+    allow?: AuditGate[];
+}
+export interface GatedFinding {
+    advisory: AuditAdvisory;
+    reason: string;
+    /** whole days until the gate expires (active gate) */
+    daysLeft?: number;
+    /** whole days since the gate expired (expired gate) */
+    daysAgo?: number;
+}
+export interface AuditResult {
+    /** did the audit actually run and parse? false => fail-open, treated as pass */
+    ran: boolean;
+    /** no blocking findings (or couldn't run) */
+    ok: boolean;
+    mode: AuditMode;
+    level: AuditSeverity;
+    /** at/above threshold and NOT suppressed — these fail the build */
+    blocking: AuditAdvisory[];
+    /** suppressed by a valid, unexpired gate */
+    gated: GatedFinding[];
+    /** matched a gate whose expiry has passed — NOT suppressed (also in `blocking`) */
+    expired: GatedFinding[];
+    /** gates that are structurally invalid (missing reason/expires) — ignored */
+    invalid: Array<{
+        gate: AuditGate;
+        problem: string;
+    }>;
+    /** valid gates that matched no current advisory — safe to delete */
+    stale: AuditGate[];
+    /** findings below the blocking threshold (reported, never blocking) */
+    belowThreshold: AuditAdvisory[];
+}
+/** Injectable subprocess seam for tests. */
+export type AuditRunner = () => Promise<string>;
+export declare const AUDIT_TIMEOUT_MS = 20000;
+/**
+ * Parse `bun audit --json` output — `{ "<pkg>": [advisory, …] }` — into a flat
+ * advisory list. Returns null when the text is not a JSON object (offline, an
+ * error dump, an incompatible bun): the caller reads null as "couldn't check".
+ */
+export declare function parseAuditJson(text: string): AuditAdvisory[] | null;
+/** Resolve the effective mode from config + the TOSIJS_AUDIT env override. */
+export declare function resolveAuditMode(config: boolean | AuditConfig | undefined): AuditMode;
+/** Test-only: forget the per-process audit memo. */
+export declare function resetAuditMemo(): void;
+/**
+ * Run `bun audit`, classify findings against the configured threshold and the
+ * time-boxed allowlist, and return a structured verdict. Never exits.
+ *
+ * Memoized per process (see above) unless `opts.runAudit` is injected.
+ */
+export declare function auditDependencies(config: boolean | AuditConfig | undefined, opts?: {
+    now?: Date;
+    runAudit?: AuditRunner;
+}): Promise<AuditResult>;
+export interface GroupedAdvisory {
+    advisory: AuditAdvisory;
+    /** every vulnerable range this advisory matched for this package */
+    ranges: string[];
+}
+export declare function groupAdvisories(advisories: AuditAdvisory[]): GroupedAdvisory[];
+/**
+ * Print the verdict. Blocking findings first (why the build is failing), then
+ * active gates, expired/invalid gates, stale gates, and — when blocking — the
+ * due-diligence footer. Returns nothing; the caller decides what to do with `ok`.
+ */
+export declare function reportAudit(result: AuditResult, label?: string): void;