@jbrowse/cli 4.3.0 → 5.0.0-beta.10

package/dist/commands/add-track-utils/track-config.js

@@ -1,42 +1,83 @@
-import path from 'path';
-import parseJSON from 'json-parse-better-errors';
-import { isURL } from "../../types/common.js";
-const SYNTENY_ADAPTERS = new Set([
-    'PAFAdapter',
-    'PairwiseIndexedPAFAdapter',
-    'DeltaAdapter',
-    'ChainAdapter',
-    'MashMapAdapter',
-    'MCScanAnchorsAdapter',
-    'MCScanSimpleAnchorsAdapter',
-]);
+import path from 'node:path';
+import { isURL } from '../../types/common.js';
+import { parseCommaSeparatedString } from '../../utils.js';
+import { displayDefaultsForTrackType } from '../validate/displayDefaultKeys.js';
+import { suggest } from '../validate/suggest.js';
+import { syntenyAdapterTypes } from './adapter-utils.js';
+import { parseJsonFlag } from './validators.js';
 export function mapLocationForFiles(p, load, subDir) {
     return !p || isURL(p) || load === 'inPlace'
         ? p
         : path.join(subDir || '', path.basename(p));
 }
-export function buildTrackConfig({ location, trackType, trackId, name, assemblyNames, category, description, config, adapter, configContents, }) {
-    const configObj = config ? parseJSON(config) : {};
-    const finalTrackId = trackId || path.basename(location, path.extname(location));
-    const finalName = name || finalTrackId;
-    const finalAssemblyNames = assemblyNames || configContents.assemblies?.[0]?.name || '';
-    const trackConfig = {
+export function buildTrackConfig({ trackType, trackId, name, assemblyNames, category, description, configObj = {}, adapter, }) {
+    return {
         type: trackType,
-        trackId: finalTrackId,
-        name: finalName,
+        trackId,
+        name,
         adapter,
-        category: category?.split(',').map(c => c.trim()),
-        assemblyNames: finalAssemblyNames.split(',').map(a => a.trim()),
+        category: category ? parseCommaSeparatedString(category) : undefined,
+        assemblyNames: parseCommaSeparatedString(assemblyNames),
         description,
         ...configObj,
     };
-    return trackConfig;
+}
+// Fold the --color / --height convenience flags and any --displayDefaults JSON
+// into one displayDefaults object, layered over a displayDefaults already
+// present in --config. Precedence: --config < --displayDefaults < typed flags,
+// so the most specific flag a user reaches for wins. Returns undefined when
+// nothing was supplied, so the track omits displayDefaults entirely.
+//
+// Takes `trackType` so it can refuse a key none of that track's displays
+// declares: expandTrackConfigShorthand drops an unmatched key with a console
+// warning, and the command otherwise wrote the dead setting and exited 0.
+export function mergeDisplayDefaults({ configObj, color, height, displayDefaults, trackType, }) {
+    const fromJson = displayDefaults
+        ? parseJsonFlag(displayDefaults, '--displayDefaults')
+        : {};
+    const typed = {};
+    if (color !== undefined) {
+        typed.color = color;
+    }
+    if (height !== undefined) {
+        const asNumber = Number(height);
+        typed.height = Number.isNaN(asNumber) ? height : asNumber;
+    }
+    const existing = (configObj?.displayDefaults ?? {});
+    const merged = { ...existing, ...fromJson, ...typed };
+    if (Object.keys(merged).length === 0) {
+        return undefined;
+    }
+    checkDisplayDefaultKeys(merged, trackType);
+    return merged;
+}
+// An unknown track type accepts everything: it is a plugin's, and this manifest
+// is only the core plugins'.
+//
+// The message names the display where the track offers exactly one, and the
+// track otherwise: the keys checked are the union over its displays, so
+// naming one of several would send the reader to look in the wrong place.
+function checkDisplayDefaultKeys(merged, trackType) {
+    const { displayTypes, keys } = displayDefaultsForTrackType(trackType);
+    if (keys.length === 0) {
+        return;
+    }
+    const unknown = Object.keys(merged).filter(key => !keys.includes(key));
+    if (unknown.length > 0) {
+        const declarer = displayTypes.length === 1 ? displayTypes[0] : `any ${trackType} display`;
+        throw new Error(unknown
+            .map(key => {
+            const hit = suggest(key, keys);
+            return `"${key}" is not a setting ${declarer} declares${hit ? `, did you mean "${hit}"?` : ''}`;
+        })
+            .join('\n'));
+    }
 }
 export function addSyntenyAssemblyNames(adapter, assemblyNames) {
-    if (SYNTENY_ADAPTERS.has(adapter.type)) {
+    if (syntenyAdapterTypes.has(adapter.type)) {
         return {
             ...adapter,
-            assemblyNames: assemblyNames?.split(',').map(a => a.trim()),
+            assemblyNames: parseCommaSeparatedString(assemblyNames),
         };
     }
     return adapter;

package/dist/commands/add-track-utils/validators.js

@@ -1,9 +1,19 @@
-import fs from 'fs';
-import path from 'path';
-import { isURL } from "../../types/common.js";
+import { isURL } from '../../types/common.js';
+import { parseCommaSeparatedString } from '../../utils.js';
+export function parseJsonFlag(value, flagName) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw new Error(`${flagName} is not valid JSON: ${value}`);
+    }
+}
+export function parseConfigFlag(config) {
+    return parseJsonFlag(config, '--config');
+}
 export function validateLoadOption(load) {
     if (load && !['copy', 'symlink', 'move', 'inPlace'].includes(load)) {
-        throw new Error('Error: --load must be one of: copy, symlink, move, inPlace');
+        throw new Error('--load must be one of: copy, symlink, move, inPlace');
     }
 }
 export function validateTrackArg(track) {
@@ -21,6 +31,17 @@ export function validateLoadAndLocation(location, load) {
         copy/move/symlink/inPlace (inPlace for no file operations)`);
     }
 }
+// --multiwig follows the same local-file rule as a single track: local sources
+// need a --load mode, a pure-URL set must omit it. hasLocalSource is true when
+// any comma/JSON string source is a local path.
+export function validateMultiWiggleLoad(hasLocalSource, load) {
+    if (hasLocalSource && !load) {
+        throw new Error('--load is required when --multiwig includes local files (copy/move/symlink/inPlace)');
+    }
+    if (!hasLocalSource && load) {
+        throw new Error('The --load flag is used for local files only, but every --multiwig source is a URL');
+    }
+}
 export function validateAdapterType(adapterType) {
     if (adapterType === 'UNKNOWN') {
         throw new Error('Track type is not recognized');
@@ -37,21 +58,16 @@ export function validateAssemblies(configContents, assemblyNames) {
         throw new Error('Too many assemblies, cannot default to one. Please specify the assembly with the --assemblyNames flag');
     }
 }
-export function validateTrackId(configContents, trackId, force, overwrite) {
-    if (!configContents.tracks) {
-        configContents.tracks = [];
-    }
-    const idx = configContents.tracks.findIndex(c => c.trackId === trackId);
-    if (idx !== -1 && !force && !overwrite) {
-        throw new Error(`Cannot add track with id ${trackId}, a track with that id already exists (use --force to override)`);
-    }
-    return idx;
-}
-export function createTargetDirectory(configDir, subDir) {
-    if (subDir) {
-        const dir = path.join(configDir, subDir);
-        if (!fs.existsSync(dir)) {
-            fs.mkdirSync(dir);
-        }
+// warn (don't throw) when a --assemblyNames entry matches no assembly in the
+// config: a typo or reversed query,target usually means this, but referencing an
+// assembly to be added later is legitimate, so it stays a soft warning
+export function warnUnknownAssemblyNames(configContents, assemblyNames) {
+    const known = new Set(configContents.assemblies?.flatMap(a => [a.name, ...(a.aliases ?? [])]) ??
+        []);
+    const missing = parseCommaSeparatedString(assemblyNames).filter(name => !known.has(name));
+    if (missing.length) {
+        console.warn(`Warning: assembly name(s) not found in config: ${missing.join(', ')}. ` +
+            `Available: ${[...known].join(', ')}. ` +
+            'Check for a typo or reversed query,target order; the track will not display until a matching assembly exists.');
     }
 }

package/dist/commands/add-track.js

@@ -1,10 +1,12 @@
-import path from 'path';
-import { parseArgs } from 'util';
-import { printHelp, resolveConfigPath } from "../utils.js";
-import { guessAdapter } from "./add-track-utils/adapter-utils.js";
-import { addSyntenyAssemblyNames, mapLocationForFiles, } from "./add-track-utils/track-config.js";
-import { createTargetDirectory, validateAdapterType, validateAssemblies, validateLoadAndLocation, validateLoadOption, validateTrackArg, } from "./add-track-utils/validators.js";
-import { addTrackToConfig, buildTrackParams, createTrackConfiguration, loadTrackConfig, processTrackFiles, saveTrackConfigAndReport, } from "./track-utils.js";
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { printHelp, readConfigFile, resolveConfigPath } from '../utils.js';
+import { guessTrack, guessTrackType, makeLocationProtocol, withDensityAdapter, } from './add-track-utils/adapter-utils.js';
+import { loadFiles } from './add-track-utils/file-operations.js';
+import { buildMultiWiggle } from './add-track-utils/multiwig.js';
+import { addSyntenyAssemblyNames, buildTrackConfig, mapLocationForFiles, mergeDisplayDefaults, } from './add-track-utils/track-config.js';
+import { parseConfigFlag, validateAdapterType, validateAssemblies, validateLoadAndLocation, validateLoadOption, validateMultiWiggleLoad, validateTrackArg, warnUnknownAssemblyNames, } from './add-track-utils/validators.js';
+import { findAndUpdateOrAdd, saveConfigAndReport, } from './shared/config-operations.js';
 export async function run(args) {
     const options = {
         help: {
@@ -16,6 +18,10 @@ export async function run(args) {
             short: 't',
             description: 'Type of track, by default inferred from track file',
         },
+        adapterType: {
+            type: 'string',
+            description: 'Adapter type, by default inferred from track file',
+        },
         name: {
             type: 'string',
             short: 'n',
@@ -33,7 +39,7 @@ export async function run(args) {
         assemblyNames: {
             type: 'string',
             short: 'a',
-            description: 'Assembly name or names for track as comma separated string',
+            description: 'Assembly name or names for track as comma separated string. For pairwise synteny tracks the order is query,target (reverse of minimap2/nucmer argument order); for the multi-genome PAF adapters (MultiGenomePAFAdapter/MultiGenomeIndexedPAFAdapter) list every assembly the file covers, in any order',
         },
         category: {
             type: 'string',
@@ -43,6 +49,22 @@ export async function run(args) {
             type: 'string',
             description: 'Any extra config settings to add to a track',
         },
+        color: {
+            type: 'string',
+            description: 'Track color: a plain CSS color or a jexl callback. Merged into displayDefaults',
+        },
+        height: {
+            type: 'string',
+            description: 'Track display height in pixels. Merged into displayDefaults',
+        },
+        displayDefaults: {
+            type: 'string',
+            description: 'Inline JSON merged into the track displayDefaults (labels, mouseover, filter, etc.)',
+        },
+        multiwig: {
+            type: 'string',
+            description: 'Build a MultiQuantitativeTrack from several BigWigs (in place of the positional track arg): a comma-separated list of BigWig files/URLs, or a .json file holding an array of BigWig locations or subadapter objects, each with its own name/color',
+        },
         target: {
             type: 'string',
             description: 'Path to config file in JB2 installation to write out to',
@@ -62,20 +84,13 @@ export async function run(args) {
         load: {
             type: 'string',
             short: 'l',
-            description: 'How to manage the track (copy, symlink, move, inPlace)',
-        },
-        skipCheck: {
-            type: 'boolean',
-            description: 'Skip check for whether file or URL exists',
-        },
-        overwrite: {
-            type: 'boolean',
-            description: 'Overwrites existing track if it shares the same trackId',
+            description: 'How to manage the track file relative to config.json. Required for local files, omit for URLs',
+            choices: ['copy', 'symlink', 'move', 'inPlace'],
         },
         force: {
             type: 'boolean',
             short: 'f',
-            description: 'Equivalent to --skipCheck --overwrite',
+            description: 'Overwrite existing track and any existing files',
         },
         protocol: {
             type: 'string',
@@ -89,6 +104,10 @@ export async function run(args) {
             type: 'string',
             description: 'Used only for mcscan anchors/simpleAnchors types',
         },
+        density: {
+            type: 'string',
+            description: "Path or URL of a features-per-bin bigWig (jbrowse make-density) to attach as the adapter's densityAdapter. A local <file>.density.bw beside the track file is attached without this flag",
+        },
     };
     const { values: flags, positionals } = parseArgs({
         args,
@@ -96,6 +115,40 @@ export async function run(args) {
         allowPositionals: true,
     });
     const description = 'Add a track to a JBrowse 2 configuration';
+    const notes = '--load controls how the data file is placed relative to config.json: ' +
+        'copy, move, or symlink it into the install directory, or inPlace to ' +
+        'reference a pre-staged local file where it already sits. Omit --load ' +
+        'entirely for URLs. For a local file the matching index is whichever ' +
+        'conventional spelling is actually beside it — <file>.bai/.crai/.tbi, a ' +
+        '<file>.csi, or the reads.bai form Picard writes beside reads.bam. A URL ' +
+        'cannot be checked, so it gets <file>.bai/.tbi; pass --indexFile for ' +
+        'anything else.\n\n' +
+        '--config takes inline JSON (not a file path) that is merged into the ' +
+        'generated track config, so you can set fields the dedicated flags do not ' +
+        'cover, e.g. --config \'{"metadata":{"skipTextIndex":true}}\' to exclude ' +
+        'the track from jbrowse text-index.\n\n' +
+        '--color and --height set the two most common appearance settings without ' +
+        'writing JSON. Wrap the value in single quotes and use double quotes inside ' +
+        'a jexl callback so nothing needs escaping, e.g. ' +
+        '--color \'jexl:feature.strand==1?"blue":"red"\'. --displayDefaults takes ' +
+        'inline JSON for any other appearance setting (labels, mouseover, ' +
+        'filter).\n\n' +
+        '--multiwig bundles several BigWigs into one MultiQuantitativeTrack, in ' +
+        'place of the positional track argument: pass a comma-separated list of ' +
+        'BigWig files/URLs, or a .json file with an array of BigWig locations or ' +
+        'subadapter objects (each carrying its own name/color/group). With --load, ' +
+        'local list entries are copied like any other track file.\n\n' +
+        '--density attaches a features-per-bin bigWig (jbrowse make-density) as the ' +
+        "adapter's densityAdapter, the band a display draws where the region is too " +
+        'large to fetch features. A local <file>.density.bw beside the track file is ' +
+        'attached without the flag; a URL cannot be probed, so a remote sidecar needs ' +
+        'it. The adapters carrying the slot are BamAdapter, CramAdapter, ' +
+        'HtsgetBamAdapter, Gff3TabixAdapter, GtfTabixAdapter, BedTabixAdapter, ' +
+        'BigBedAdapter, VcfTabixAdapter and SplitVcfTabixAdapter.\n\n' +
+        'For pairwise synteny adapters (PAF/Delta/Chain) --assemblyNames is ' +
+        'query,target — the reverse of the minimap2/nucmer input order. For the ' +
+        'multi-genome PAF adapters (MultiGenomePAFAdapter, MultiGenomeIndexedPAFAdapter) it is ' +
+        'instead the full list of assemblies the file covers, in any order.';
     const examples = [
         '# copy /path/to/my.bam and /path/to/my.bam.bai to current directory and adds track to config.json',
         '$ jbrowse add-track /path/to/my.bam --load copy',
@@ -114,72 +167,157 @@ export async function run(args) {
         '',
         '# --load inPlace adds a track without doing file operations',
         '$ jbrowse add-track /url/relative/path.bam --load inPlace',
+        '',
+        '# color a track by strand and set its height (no escaping: single-quote the value, double-quote inside the jexl)',
+        `$ jbrowse add-track genes.gff3.gz --load copy --color 'jexl:feature.strand==1?"blue":"red"' --height 200`,
+        '',
+        '# bundle several BigWigs into one MultiQuantitativeTrack (no positional track arg)',
+        '$ jbrowse add-track --multiwig a.bw,b.bw,c.bw --load copy --name "Coverage"',
+        '',
+        '# ...or from a sources.json carrying per-row name/color for each BigWig',
+        '$ jbrowse add-track --multiwig sources.json --name "CATlas ATAC"',
+        '',
+        '# attach a remote density sidecar (a local genes.gff3.density.bw needs no flag)',
+        '$ jbrowse add-track https://mywebsite.com/genes.gff3.gz --density https://mywebsite.com/genes.gff3.density.bw',
     ];
     if (flags.help) {
         printHelp({
             description,
             examples,
+            notes,
             usage: 'jbrowse add-track <track> [options]',
             options,
         });
         return;
     }
     validateLoadOption(flags.load);
-    const track = positionals[0];
-    validateTrackArg(track);
-    const { config, force, overwrite, category, description: trackDescription, load, subDir = '', target, protocol = 'uri', out, indexFile: index, bed1, bed2, } = flags;
+    const { config, force, category, description: trackDescription, load, subDir = '', target, protocol = 'uri', out, indexFile: index, bed1, bed2, adapterType, multiwig, } = flags;
+    const location = positionals[0];
+    if (multiwig && location) {
+        throw new Error('Pass either a positional track file or --multiwig, not both');
+    }
+    const wrap = makeLocationProtocol(protocol);
+    const mapLocation = (p) => wrap(mapLocationForFiles(p, load, subDir));
+    // build the adapter (and the set of files to load) up front, so the track-arg
+    // and load validation runs before we touch the config on disk
+    const { adapter: builtAdapter, files, trackType, trackId, } = multiwig
+        ? buildMultiWiggleTrack({
+            sources: multiwig,
+            mapLocation,
+            load,
+            trackType: flags.trackType,
+            trackId: flags.trackId,
+        })
+        : buildFileTrack({
+            location,
+            index,
+            bed1,
+            bed2,
+            adapterType,
+            assemblyNames: flags.assemblyNames,
+            mapLocation,
+            load,
+            trackType: flags.trackType,
+            trackId: flags.trackId,
+        });
+    const { adapter, file: densityFile } = withDensityAdapter({
+        adapter: builtAdapter,
+        location,
+        density: flags.density,
+        makeLocation: mapLocation,
+    });
+    if (densityFile !== undefined && !load) {
+        throw new Error(`--density names a local file (${densityFile}); pass --load to say how it is placed beside the config`);
+    }
+    const baseConfigObj = config ? parseConfigFlag(config) : undefined;
+    const displayDefaults = mergeDisplayDefaults({
+        configObj: baseConfigObj,
+        color: flags.color,
+        height: flags.height,
+        displayDefaults: flags.displayDefaults,
+        trackType,
+    });
+    const configObj = displayDefaults
+        ? { ...baseConfigObj, displayDefaults }
+        : baseConfigObj;
     const targetConfigPath = await resolveConfigPath(target, out);
     const configDir = path.dirname(targetConfigPath);
-    createTargetDirectory(configDir, subDir);
-    const location = track;
-    const mapLoc = (p) => mapLocationForFiles(p, load, subDir);
-    let adapter = guessAdapter({
-        protocol,
-        location: mapLoc(location),
-        index: index ? mapLoc(index) : undefined,
-        bed1: bed1 ? mapLoc(bed1) : undefined,
-        bed2: bed2 ? mapLoc(bed2) : undefined,
-    });
-    adapter = addSyntenyAssemblyNames(adapter, flags.assemblyNames);
-    validateLoadAndLocation(location, load);
-    validateAdapterType(adapter.type);
-    const configContents = await loadTrackConfig(targetConfigPath);
+    const configContents = await readConfigFile(targetConfigPath);
     validateAssemblies(configContents, flags.assemblyNames);
-    const trackParams = buildTrackParams({
-        flags,
-        location,
+    const name = flags.name || trackId;
+    const assemblyNames = flags.assemblyNames || configContents.assemblies?.[0]?.name || '';
+    warnUnknownAssemblyNames(configContents, assemblyNames);
+    const trackConfig = buildTrackConfig({
+        trackType,
+        trackId,
+        name,
+        assemblyNames,
+        category,
+        description: trackDescription,
+        configObj,
         adapter,
-        configContents,
     });
-    const trackConfig = createTrackConfiguration({
-        location,
-        trackParams,
-        flags: { category, description: trackDescription, config },
-        adapter,
-        configContents,
+    const { updatedItems: tracks, wasOverwritten } = findAndUpdateOrAdd({
+        items: configContents.tracks ?? [],
+        newItem: trackConfig,
+        idField: 'trackId',
+        getId: item => item.trackId,
+        force: force ?? false,
+        itemType: 'track',
     });
-    const { updatedConfig, wasOverwritten } = addTrackToConfig({
-        configContents,
-        trackConfig,
-        trackId: trackParams.trackId,
+    const updatedConfig = { ...configContents, tracks };
+    await loadFiles({
+        files: [...files, densityFile],
+        destDir: configDir,
+        mode: load,
+        subDir,
         force,
-        overwrite,
     });
-    await processTrackFiles({
+    await saveConfigAndReport({
+        config: updatedConfig,
+        target: targetConfigPath,
+        itemType: 'track',
+        itemName: name,
+        itemId: trackId,
+        wasOverwritten,
+    });
+}
+// --multiwig: bundle several BigWigs into one MultiQuantitativeTrack
+function buildMultiWiggleTrack({ sources, mapLocation, load, trackType, trackId, }) {
+    const { adapter, files } = buildMultiWiggle({ sources, mapLocation });
+    validateMultiWiggleLoad(files.length > 0, load);
+    return {
+        adapter,
+        files,
+        trackType: trackType || 'MultiQuantitativeTrack',
+        trackId: trackId || multiWiggleTrackId(sources),
+    };
+}
+// the usual path: one positional data file, adapter guessed from its extension
+function buildFileTrack({ location, index, bed1, bed2, adapterType, assemblyNames, mapLocation, load, trackType, trackId, }) {
+    validateTrackArg(location);
+    validateLoadAndLocation(location, load);
+    const { adapter: guessedAdapter, files } = guessTrack({
         location,
         index,
         bed1,
         bed2,
-        load,
-        configDir,
-        subDir,
-        force,
-    });
-    await saveTrackConfigAndReport({
-        config: updatedConfig,
-        targetConfigPath,
-        name: trackParams.name,
-        trackId: trackParams.trackId,
-        wasOverwritten,
+        adapterType,
+        mapLocation,
     });
+    const adapter = addSyntenyAssemblyNames(guessedAdapter, assemblyNames);
+    validateAdapterType(adapter.type);
+    return {
+        adapter,
+        files,
+        trackType: trackType || guessTrackType(adapter.type, location),
+        trackId: trackId || path.basename(location, path.extname(location)),
+    };
+}
+// a .json sources file names the track after itself (sources.json -> sources); a
+// bare comma list has no filename to borrow, so it falls back to 'multiwiggle'
+function multiWiggleTrackId(sources) {
+    return sources.toLowerCase().endsWith('.json')
+        ? path.basename(sources, path.extname(sources))
+        : 'multiwiggle';
 }

package/dist/commands/admin-server/index.js

@@ -1,11 +1,7 @@
-import fs from 'fs';
-import os from 'os';
-import path from 'path';
-import { parseArgs } from 'util';
-import cors from 'cors';
-import express from 'express';
-import { generateKey, parsePort, setupConfigFile, setupRoutes, startServer, } from "./utils.js";
-import { debug, printHelp } from "../../utils.js";
+import http from 'node:http';
+import { parseArgs } from 'node:util';
+import { printHelp } from '../../utils.js';
+import { createRequestHandler, generateKey, parseByteLimit, parsePort, setupConfigFile, startServer, } from './utils.js';
 export async function run(args) {
     const options = {
         help: {
@@ -17,6 +13,11 @@ export async function run(args) {
             short: 'p',
             description: 'Specified port to start the server on (default: 9090)',
         },
+        host: {
+            type: 'string',
+            description: 'Interface to bind to (default: 127.0.0.1). Use 0.0.0.0 to accept ' +
+                'connections from other machines',
+        },
         root: {
             type: 'string',
             description: 'Path to the root of the JB2 installation',
@@ -32,63 +33,51 @@ export async function run(args) {
         allowPositionals: true,
     });
     const description = 'Start up a small admin server for JBrowse configuration';
-    const examples = ['$ jbrowse admin-server', '$ jbrowse admin-server -p 8888'];
+    const examples = [
+        '# start the admin server for the JBrowse install in the current directory',
+        '$ jbrowse admin-server',
+        '',
+        '# start on a specific port',
+        '$ jbrowse admin-server -p 8888',
+        '',
+        '# point at a specific JBrowse installation directory',
+        '$ jbrowse admin-server --root /path/to/jb2/',
+        '',
+        '# raise the body size limit for very large config updates',
+        '$ jbrowse admin-server --bodySizeLimit 100mb',
+        '',
+        '# accept connections from other machines on the network',
+        '$ jbrowse admin-server --host 0.0.0.0',
+    ];
+    const notes = 'The admin-server lets a browser session write changes back to ' +
+        'config.json on disk, authorized by a one-time key printed in the ' +
+        'startup URL. It binds to 127.0.0.1 so only this machine can reach it. ' +
+        'The key gates the config routes, but the rest of the JBrowse directory ' +
+        'is served unauthenticated, so widen --host only on a trusted network.';
     if (flags.help) {
         printHelp({
             description,
             examples,
+            notes,
             usage: 'jbrowse admin-server [options]',
             options,
         });
         return;
     }
-    const { root, bodySizeLimit = '25mb' } = flags;
+    const { root, host, bodySizeLimit = '25mb' } = flags;
     const { outFile, baseDir } = await setupConfigFile({ root });
-    // Parse and validate port
     const port = parsePort({ portStr: flags.port });
-    // Set up the Express server
-    // const { app, key, keyPath, serverRef } = setupServer({
-    //   baseDir,
-    //   outFile,
-    //   bodySizeLimit,
-    // })
-    const app = express();
-    // Configure middleware
-    app.use(express.static(baseDir));
-    app.use(cors());
-    app.use(express.json({ limit: bodySizeLimit }));
-    // Add error handling middleware
-    app.use((err, _req, res, next) => {
-        if (err) {
-            console.error('Server error:', err);
-            res.status(500).setHeader('Content-Type', 'text/plain');
-            res.send('Internal Server Error');
-        }
-        else {
-            next();
-        }
-    });
-    // Generate admin key and store it
+    // the key lives only in this process and in the startup URL printed below. It
+    // used to also be written to os.tmpdir()/jbrowse-admin-<key>, which nothing
+    // ever read and which published the key in a filename any local user can list
     const key = generateKey();
-    const keyPath = path.join(os.tmpdir(), `jbrowse-admin-${key}`);
-    try {
-        fs.writeFileSync(keyPath, key);
-        debug(`Admin key stored at ${keyPath}`);
-    }
-    catch (error) {
-        console.error(`Failed to write admin key to ${keyPath}:`, error instanceof Error ? error.message : error);
-        // Continue anyway, as this is not critical
-    }
-    // Create server reference for shutdown route
     const serverRef = { current: null };
-    // Set up routes
-    setupRoutes({
-        app,
+    const server = http.createServer(createRequestHandler({
         baseDir,
         outFile,
         key,
         serverRef,
-    });
-    // Start the server and set up shutdown handlers
-    startServer({ app, port, key, outFile, keyPath, serverRef });
+        bodySizeLimit: parseByteLimit(bodySizeLimit),
+    }));
+    startServer({ server, port, host, key, outFile, serverRef });
 }