@jbrowse/cli 4.3.0 → 5.0.0-beta.2

package/dist/commands/add-connection.js

@@ -1,29 +1,26 @@
-import path from 'path';
-import { parseArgs } from 'util';
-import parseJSON from 'json-parse-better-errors';
-import fetch from "../cliFetch.js";
-import { debug, printHelp, readJsonFile, resolveConfigPath, writeJsonFile, } from "../utils.js";
-async function resolveURL(location, check = true) {
-    let locationUrl;
+import { parseArgs } from 'node:util';
+import { debug, parseCommaSeparatedString, printHelp, readConfigFile, requirePositional, resolveConfigPath, } from '../utils.js';
+import { parseConfigFlag } from './add-track-utils/validators.js';
+import { findAndUpdateOrAdd, saveConfigAndReport, } from './shared/config-operations.js';
+function resolveURL(location) {
     try {
-        locationUrl = new URL(location);
+        return new URL(location);
     }
     catch (error) {
-        throw new Error(`The location ${location} provided is not a valid URL`);
-    }
-    if (check) {
-        const response = await fetch(`${locationUrl}`, { method: 'HEAD' });
-        if (!response.ok) {
-            throw new Error(`HTTP ${response.status} fetching ${locationUrl}`);
-        }
+        throw new Error(`The location ${location} provided is not a valid URL`, {
+            cause: error,
+        });
     }
-    return locationUrl.href;
 }
+// a hub.txt filename and a jbrowse/data path are the two conventions we can
+// recognize. Both are read off the URL's path rather than the whole href, so a
+// query string can't fake one and a host that happens to be named hub.txt can't
+// be mistaken for a hub file.
 function determineConnectionType(url) {
-    if (path.basename(url) === 'hub.txt') {
+    if (url.pathname.endsWith('/hub.txt')) {
         return 'UCSCTrackHubConnection';
     }
-    if (url.includes('jbrowse/data')) {
+    if (url.pathname.includes('jbrowse/data')) {
         return 'JBrowse1Connection';
     }
     return 'custom';
@@ -66,18 +63,10 @@ export async function run(args) {
             type: 'string',
             description: 'Synonym for target',
         },
-        skipCheck: {
-            type: 'boolean',
-            description: "Don't check whether the data directory URL exists",
-        },
-        overwrite: {
-            type: 'boolean',
-            description: 'Overwrites any existing connections if same connection id',
-        },
         force: {
             type: 'boolean',
             short: 'f',
-            description: 'Equivalent to --skipCheck --overwrite',
+            description: 'Overwrite existing connection if one with the same id exists',
         },
     };
     const { values: flags, positionals } = parseArgs({
@@ -86,81 +75,86 @@ export async function run(args) {
         allowPositionals: true,
     });
     const description = 'Add a connection to a JBrowse 2 configuration';
+    const usage = 'jbrowse add-connection <connectionUrlOrPath> [options]';
     const examples = [
-        '$ jbrowse add-connection http://mysite.com/jbrowse/data/ -a hg19',
-        '$ jbrowse add-connection http://mysite.com/jbrowse/custom_data_folder/ --type JBrowse1Connection -a hg38',
-        '$ jbrowse add-connection http://mysite.com/path/to/hub.txt',
-        '$ jbrowse add-connection http://mysite.com/path/to/custom_hub_name.txt --type UCSCTrackHubConnection',
-        `$ jbrowse add-connection http://mysite.com/path/to/custom --type custom --config '{"uri":{"url":"https://mysite.com/path/to/custom"}, "locationType": "UriLocation"}' -a hg19`,
+        '# add a JBrowse 1 data directory connection (type inferred from the jbrowse/data path)',
+        '$ jbrowse add-connection https://mysite.com/jbrowse/data/ -a hg19',
+        '',
+        '# force the JBrowse1Connection type for a non-standard data folder path',
+        '$ jbrowse add-connection https://mysite.com/jbrowse/custom_data_folder/ --type JBrowse1Connection -a hg38',
+        '',
+        '# add a UCSC track hub (type inferred from the hub.txt filename)',
+        '$ jbrowse add-connection https://mysite.com/path/to/hub.txt',
+        '',
+        '# force the UCSCTrackHubConnection type for a hub file not named hub.txt',
+        '$ jbrowse add-connection https://mysite.com/path/to/custom_hub_name.txt --type UCSCTrackHubConnection',
+        '',
+        '# add a custom connection type with extra config',
+        `$ jbrowse add-connection https://mysite.com/path/to/custom --type custom --config '{"uri":{"url":"https://mysite.com/path/to/custom"}, "locationType": "UriLocation"}' -a hg19`,
+        '',
+        '# set an explicit id/name and write to a specific config file',
         '$ jbrowse add-connection https://mysite.com/path/to/hub.txt --connectionId newId --name newName --target /path/to/jb2/installation/config.json',
     ];
     if (flags.help) {
         printHelp({
             description,
             examples,
-            usage: 'jbrowse add-connection <connectionUrlOrPath> [options]',
+            usage,
             options,
         });
         return;
     }
     const connectionUrlOrPath = positionals[0];
-    if (!connectionUrlOrPath) {
-        throw new Error('Missing required argument: connectionUrlOrPath\nUsage: jbrowse add-connection <connectionUrlOrPath> [options]');
-    }
+    requirePositional(connectionUrlOrPath, 'connectionUrlOrPath', usage);
+    const { assemblyNames, type, name, config, connectionId, force } = flags;
+    const configObj = config ? parseConfigFlag(config) : undefined;
     const target = await resolveConfigPath(flags.target, flags.out);
-    const { assemblyNames, type, name, config, connectionId, skipCheck, force } = flags;
-    const url = await resolveURL(connectionUrlOrPath, !(skipCheck || force));
-    const configContents = await readJsonFile(target);
+    const url = resolveURL(connectionUrlOrPath);
+    const configContents = await readConfigFile(target);
     debug(`Using config file ${target}`);
     if (!configContents.assemblies?.length) {
         throw new Error('No assemblies found. Please add one before adding connections');
     }
     const configType = type || determineConnectionType(url);
     const id = connectionId ||
-        [configType, assemblyNames, Date.now()].filter(f => !!f).join('-');
+        [configType, assemblyNames, Date.now()].filter(Boolean).join('-');
+    // each known connection type stores the URL under its own location slot; a
+    // custom type carries no location, so its --config must supply one
+    const locationField = {
+        UCSCTrackHubConnection: 'hubTxtLocation',
+        JBrowse1Connection: 'dataDirLocation',
+    }[configType];
+    // a JBrowse 1 connection serves exactly one assembly, so it falls back to the
+    // config's first (the assemblies list is known non-empty by here)
+    const defaultAssemblyNames = configType === 'JBrowse1Connection'
+        ? [configContents.assemblies[0].name]
+        : undefined;
     const connectionConfig = {
         type: configType,
         name: name || id,
-        ...(configType === 'UCSCTrackHubConnection'
-            ? {
-                hubTxtLocation: {
-                    uri: url,
-                    locationType: 'UriLocation',
-                },
-            }
-            : {}),
-        ...(configType === 'JBrowse1Connection'
-            ? {
-                dataDirLocation: {
-                    uri: url,
-                    locationType: 'UriLocation',
-                },
-            }
-            : {}),
+        ...(locationField && {
+            [locationField]: { uri: url.href, locationType: 'UriLocation' },
+        }),
         connectionId: id,
         assemblyNames: assemblyNames
-            ? assemblyNames.split(',')
-            : type === 'JBrowse1Connection'
-                ? [configContents.assemblies[0]?.name]
-                : undefined,
-        ...(config ? parseJSON(config) : {}),
+            ? parseCommaSeparatedString(assemblyNames)
+            : defaultAssemblyNames,
+        ...configObj,
     };
-    if (!configContents.connections) {
-        configContents.connections = [];
-    }
-    const idx = configContents.connections.findIndex(c => c.connectionId === connectionId);
-    if (idx !== -1) {
-        if (force || flags.overwrite) {
-            configContents.connections[idx] = connectionConfig;
-        }
-        else {
-            throw new Error(`Cannot add connection with id ${connectionId}, a connection with that id already exists.\nUse --overwrite if you would like to replace the existing connection`);
-        }
-    }
-    else {
-        configContents.connections.push(connectionConfig);
-    }
-    debug(`Writing configuration to file ${target}`);
-    await writeJsonFile(target, configContents);
-    console.log(`${idx !== -1 ? 'Overwrote' : 'Added'} connection "${name || id}" ${idx !== -1 ? 'in' : 'to'} ${target}`);
+    const { updatedItems: connections, wasOverwritten } = findAndUpdateOrAdd({
+        items: configContents.connections ?? [],
+        newItem: connectionConfig,
+        idField: 'connectionId',
+        getId: item => item.connectionId,
+        force: force ?? false,
+        itemType: 'connection',
+    });
+    await saveConfigAndReport({
+        config: { ...configContents, connections },
+        target,
+        itemType: 'connection',
+        itemName: name || id,
+        itemId: id,
+        wasOverwritten,
+    });
 }

package/dist/commands/add-track-json.js

@@ -1,6 +1,6 @@
-import { parseArgs } from 'util';
-import { debug, printHelp, readInlineOrFileJson, readJsonFile, resolveConfigPath, } from "../utils.js";
-import { findAndUpdateOrAdd, saveConfigAndReport, } from "./shared/config-operations.js";
+import { parseArgs } from 'node:util';
+import { debug, printHelp, readInlineOrFileJson, readConfigFile, requirePositional, resolveConfigPath, } from '../utils.js';
+import { findAndUpdateOrAdd, saveConfigAndReport, } from './shared/config-operations.js';
 export async function run(args) {
     const options = {
         help: {
@@ -27,38 +27,50 @@ export async function run(args) {
         allowPositionals: true,
     });
     const description = 'Add a track configuration directly from a JSON hunk to the JBrowse 2 configuration';
+    const usage = 'jbrowse add-track-json <track> [options]';
+    const notes = 'The track argument is a JSON file, inline JSON, or "-" to read the JSON ' +
+        'from stdin, so a track config can be generated and piped straight in.';
     const examples = [
+        '# add a track from a JSON file',
         '$ jbrowse add-track-json track.json',
+        '',
+        '# update an existing track (matched by trackId) with new JSON contents',
         '$ jbrowse add-track-json track.json --update',
+        '',
+        '# pass the track config inline instead of via a file',
+        `$ jbrowse add-track-json '{"type":"FeatureTrack","trackId":"genes","assemblyNames":["hg38"],"adapter":{"type":"Gff3TabixAdapter","gffGzLocation":{"uri":"genes.gff.gz"}}}'`,
+        '',
+        '# pipe the track config in from another program',
+        `$ jq '.tracks[0]' other/config.json | jbrowse add-track-json -`,
+        '',
+        '# write to a config.json in a specific installation directory',
+        '$ jbrowse add-track-json track.json --out /path/to/jb2/',
     ];
     if (flags.help) {
         printHelp({
             description,
             examples,
-            usage: 'jbrowse add-track-json <track> [options]',
+            notes,
+            usage,
             options,
         });
         return;
     }
     const track = positionals[0];
-    if (!track) {
-        throw new Error('Missing required argument: track\nUsage: jbrowse add-track-json <track> [options]');
-    }
+    requirePositional(track, 'track', usage);
     const target = await resolveConfigPath(flags.target, flags.out);
     debug(`Sequence location is: ${track}`);
     const { update } = flags;
-    const config = await readJsonFile(target);
+    const config = await readConfigFile(target);
     debug(`Found existing config file ${target}`);
     const trackConfig = await readInlineOrFileJson(track);
-    if (!config.tracks) {
-        config.tracks = [];
-    }
+    config.tracks ??= [];
     const { updatedItems, wasOverwritten } = findAndUpdateOrAdd({
         items: config.tracks,
         newItem: trackConfig,
         idField: 'trackId',
         getId: item => item.trackId,
-        allowOverwrite: update ?? false,
+        force: update ?? false,
         itemType: 'track',
     });
     config.tracks = updatedItems;