@jbrowse/cli 4.3.0 → 5.0.0-beta.2

package/dist/commands/make-pif/pif-generator.js

@@ -1,55 +1,261 @@
-import { spawn } from 'child_process';
-import path from 'path';
-import { flipCigar, parseCigar, swapIndelCigar } from "./cigar-utils.js";
-import { createWriteWithBackpressure, getReadline, getStdReadline, } from "./file-utils.js";
-export async function createPIF(filename, stream) {
-    const rl1 = filename ? getReadline(filename) : getStdReadline();
-    const writeWithBackpressure = createWriteWithBackpressure(stream);
-    // Process the file line by line with backpressure handling
-    try {
-        for await (const line of rl1) {
-            const [c1, l1, s1, e1, strand, c2, l2, s2, e2, ...rest] = line.split('\t');
-            // Write the first line and handle backpressure
-            await writeWithBackpressure(`${[`t${c2}`, l2, s2, e2, strand, c1, l1, s1, e1, ...rest].join('\t')}\n`);
-            const cigarIdx = rest.findIndex(f => f.startsWith('cg:Z'));
-            const CIGAR = rest[cigarIdx];
-            if (CIGAR) {
-                rest[cigarIdx] = `cg:Z:${strand === '-'
-                    ? flipCigar(parseCigar(CIGAR.slice(5))).join('')
-                    : swapIndelCigar(CIGAR.slice(5))}`;
+import { spawn } from 'node:child_process';
+import { createReadStream } from 'node:fs';
+import path from 'node:path';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { createGunzip } from 'node:zlib';
+import { coarsenCigar, csToCigar, flipCigar, flipCoarseCigar, swapCoarseCigar, swapIndelCigar, } from '@jbrowse/cigar-utils';
+// Default gap (bp) of the coarse tier's coarse CIGAR: how far a straight line
+// across one of its runs may be from the alignment's real path. Indels longer
+// than half of it keep their letter; shorter ones fold into the runs. 10kb
+// matches the adapter's default coarseBpPerPxThreshold, so at the zoom where the
+// tier is served the bound is ~1px and a folded indel was sub-pixel anyway.
+export const DEFAULT_COARSE_GAP = 10_000;
+/**
+ * The one meta line a PIF carries, sorted first by the C-locale sort and kept
+ * by tabix as a header. It states the format generation, the tiers written,
+ * the coarse tier's accuracy bound (`--coarse`), and whether every input row
+ * had a CIGAR — the facts a reader cannot recover from the rows.
+ */
+export function pifHeader(coarseGap, stats) {
+    const cigars = stats.cigarRows === 0
+        ? 'none'
+        : stats.cigarRows === stats.rows && stats.unboundedRows === 0
+            ? 'all'
+            : 'some';
+    const tiers = coarseGap === undefined ? 'fine' : 'fine,coarse';
+    const bound = coarseGap === undefined ? '' : `\tcoarse:i:${coarseGap}`;
+    return `#pif\tversion:i:1\ttiers:Z:${tiers}${bound}\tcigars:Z:${cigars}\n`;
+}
+function panSNSample(refName) {
+    const i = refName.indexOf('#');
+    return i === -1 ? undefined : refName.slice(0, i);
+}
+function addPanSNPair(stats, c1, c2) {
+    const a = panSNSample(c1);
+    const b = panSNSample(c2);
+    if (a !== undefined) {
+        stats.samples.add(a);
+    }
+    if (b !== undefined) {
+        stats.samples.add(b);
+    }
+    if (a !== undefined && b !== undefined && a !== b) {
+        stats.pairs.add(a < b ? `${a}\u0000${b}` : `${b}\u0000${a}`);
+    }
+}
+/**
+ * The sample pairs a complete all-vs-all would state but this file does not.
+ * Empty for a pairwise PAF (no PanSN names) and for a genuinely complete file.
+ */
+export function missingPairs({ samples, pairs }) {
+    const sorted = [...samples].sort();
+    const out = [];
+    for (let i = 0; i < sorted.length; i++) {
+        for (let j = i + 1; j < sorted.length; j++) {
+            const a = sorted[i];
+            const b = sorted[j];
+            if (!pairs.has(`${a}\u0000${b}`)) {
+                out.push([a, b]);
             }
-            // Write the second line and handle backpressure
-            await writeWithBackpressure(`${[`q${c1}`, l1, s1, e1, strand, c2, l2, s2, e2, ...rest].join('\t')}\n`);
         }
     }
-    catch (error) {
-        console.error('Error processing PAF file:', error);
-        throw error;
+    return out;
+}
+// The coarse row's `cr:Z:` value, or nothing, and whether withholding it left
+// the row making a claim it cannot keep.
+//
+// `ops` is nothing when the row has no CIGAR, when the fold is a single run
+// (the coordinate columns already say it all), and when the walk does not close
+// on the row's own far corner — clipping ops, a hand-made cg, a cs whose spans
+// don't add up — since the columns are what the fine tier draws and the coarse
+// row must not disagree with them. A fold of several runs with no kept indel is
+// still written: the runs are where a lopsided cluster of small indels bends
+// the path, which a straight ribbon across the row would miss by up to the
+// whole cluster.
+//
+// `unbounded` separates the last of those from the rest. The first two leave a
+// tagless row a reader may take as one run within `--coarse`, and it is one; a
+// walk that misses its own corner leaves a row that reads the same way and is
+// not, so the header has to stop saying `cigars:Z:all` on its account.
+function coarseFold({ cigar, coarseGap, ownLen, mateLen, }) {
+    const coarse = cigar === undefined ? undefined : coarsenCigar(cigar, coarseGap);
+    const closed = coarse !== undefined &&
+        coarse.ownLen === ownLen &&
+        coarse.mateLen === mateLen;
+    return {
+        ops: closed && (coarse.gapCount > 0 || coarse.opCount > 1)
+            ? coarse.ops
+            : undefined,
+        unbounded: cigar !== undefined && !closed,
+    };
+}
+// A PIF row carries exactly ONE alignment string — `cg:Z:`, in the orientation
+// of the perspective it is indexed under. A minimap2 `cs:Z:` is folded into that
+// CIGAR and never emitted, for two reasons:
+//
+//  - `cs` has its own orientation, and reorienting it means reversing op order
+//    AND reverse-complementing the spelled-out bases. Keeping an unflipped `cs`
+//    beside a flipped `cg` is silently wrong rather than merely lossy:
+//    `SyntenyFeature.forEachMismatch` prefers `cs`, so a row from
+//    `minimap2 -c --cs` (which emits both tags) drew every indel with reversed
+//    sense from the query perspective.
+//  - `csToCigar` yields `=`/`X`, so folding a `cs` in is strictly MORE
+//    informative than minimap2's own M-style `cg` — which is why `cs` wins when
+//    a row carries both. The substituted base letters are the only thing lost;
+//    mismatch positions survive as `X`.
+//
+// Returns the rewritten optional-tag list and where the surviving alignment
+// string sits in it (-1 when the row carries none).
+function foldCsIntoCg(tags) {
+    const csIdx = tags.findIndex(f => f.startsWith('cs:Z'));
+    if (csIdx === -1) {
+        return { tags, cigarIdx: tags.findIndex(f => f.startsWith('cg:Z')) };
+    }
+    const folded = `cg:Z:${csToCigar(tags[csIdx].slice(5))}`;
+    const rewritten = tags.flatMap((f, i) => i === csIdx ? [folded] : f.startsWith('cg:Z') ? [] : [f]);
+    return { tags: rewritten, cigarIdx: rewritten.indexOf(folded) };
+}
+function pifRow(fields) {
+    return `${fields.join('\t')}\n`;
+}
+function processLine(rawLine, coarseGap, stats) {
+    const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine;
+    if (line.startsWith('#')) {
+        return '';
+    }
+    const parts = line.split('\t');
+    // A valid PAF row has 12 mandatory columns; anything shorter (blank, or
+    // truncated) would produce NaN coords, so skip it rather than emit garbage.
+    if (parts.length < 12) {
+        stats.skipped++;
+        return '';
+    }
+    stats.rows++;
+    // rest[0]=num_matches, rest[1]=block_len, rest[2]=mapq, rest[3+]=optional tags
+    const [c1, l1, s1, e1, strand, c2, l2, s2, e2, ...rest] = parts;
+    addPanSNPair(stats, c1, c2);
+    // an incoming cr:Z: (a PIF turned back into PAF, or a tool that adopted the
+    // tag) is dropped from both tiers: the fine tier never carries one, and the
+    // coarse tier writes its own below
+    const { tags, cigarIdx } = foldCsIntoCg(rest.filter(f => !f.startsWith('cr:Z:')));
+    const cigar = cigarIdx === -1 ? undefined : tags[cigarIdx].slice(5);
+    if (cigar !== undefined) {
+        stats.cigarRows++;
+    }
+    // the t-row keeps the CIGAR as PAF spelled it (target perspective); the q-row
+    // re-orients it for the query perspective it is indexed under
+    const queryTags = cigar === undefined
+        ? tags
+        : tags.map((f, i) => i === cigarIdx
+            ? `cg:Z:${strand === '-' ? flipCigar(cigar) : swapIndelCigar(cigar)}`
+            : f);
+    const fineRows = pifRow([`t${c2}`, l2, s2, e2, strand, c1, l1, s1, e1, ...tags]) +
+        pifRow([`q${c1}`, l1, s1, e1, strand, c2, l2, s2, e2, ...queryTags]);
+    if (coarseGap === undefined) {
+        return fineRows;
     }
-    finally {
-        rl1.close();
+    // the coarse row is the fine row with its CIGAR replaced by the fold and
+    // every other column and tag verbatim, so a click and the identity coloring
+    // read the same on both tiers
+    const coarse = cigarIdx === -1 ? tags : tags.filter((_, i) => i !== cigarIdx);
+    // the T row's own axis is the target, as the PAF CIGAR is written; the Q row
+    // re-orients it for the query, the way the fine tier's cg is
+    const { ops: cr, unbounded } = coarseFold({
+        cigar,
+        coarseGap,
+        ownLen: +e2 - +s2,
+        mateLen: +e1 - +s1,
+    });
+    if (unbounded) {
+        stats.unboundedRows++;
     }
+    const tCr = cr === undefined ? [] : [`cr:Z:${cr}`];
+    const qCr = cr === undefined
+        ? []
+        : [`cr:Z:${strand === '-' ? flipCoarseCigar(cr) : swapCoarseCigar(cr)}`];
+    return (fineRows +
+        pifRow([`T${c2}`, l2, s2, e2, strand, c1, l1, s1, e1, ...coarse, ...tCr]) +
+        pifRow([`Q${c1}`, l1, s1, e1, strand, c2, l2, s2, e2, ...coarse, ...qCr]));
+}
+function makePifTransform(coarseGap, stats) {
+    let tail = '';
+    return new Transform({
+        transform(chunk, _enc, callback) {
+            const data = tail + chunk.toString('utf8');
+            const lastNl = data.lastIndexOf('\n');
+            if (lastNl === -1) {
+                tail = data;
+                callback();
+                return;
+            }
+            tail = data.slice(lastNl + 1);
+            callback(null, data
+                .slice(0, lastNl)
+                .split('\n')
+                .filter(Boolean)
+                .map(l => processLine(l, coarseGap, stats))
+                .join(''));
+        },
+        flush(callback) {
+            // the header goes out last and sorts first: the counts it states are
+            // only known once every row has been seen, and `#` precedes every tier
+            // letter in the C locale
+            callback(null, (tail ? processLine(tail, coarseGap, stats) : '') +
+                pifHeader(coarseGap, stats));
+        },
+    });
 }
-export function spawnSortProcess(outputFile, useCsi) {
-    // Use a more portable approach to avoid E2BIG errors
-    const sortCmd = `sort -t"\`printf '\\t'\`" -k1,1 -k3,3n`;
-    const bgzipCommand = `bgzip > "${outputFile}"`;
-    const tabixCommand = `tabix ${useCsi ? '-C ' : ''}-s1 -b3 -e4 -0 "${outputFile}"`;
-    const fullCommand = `${sortCmd} | ${bgzipCommand}; ${tabixCommand}`;
-    const minimalEnv = {
-        ...process.env,
-        LC_ALL: 'C',
+// resolves to what the pass observed: the PanSN samples (empty for a pairwise
+// PAF), so the caller can suggest the right adapter and assembly names, and the
+// row/skip counts so it can warn on a file that was not PAF at all
+export async function createPIF(filename, stream, coarseGap) {
+    const stats = {
+        samples: new Set(),
+        pairs: new Set(),
+        rows: 0,
+        cigarRows: 0,
+        unboundedRows: 0,
+        skipped: 0,
     };
-    return spawn('sh', ['-c', fullCommand], {
-        env: minimalEnv,
+    const transform = makePifTransform(coarseGap, stats);
+    if (filename) {
+        const source = createReadStream(filename);
+        await (/\.b?gz$/i.test(filename)
+            ? pipeline(source, createGunzip(), transform, stream)
+            : pipeline(source, transform, stream));
+    }
+    else {
+        await pipeline(process.stdin, transform, stream);
+    }
+    return stats;
+}
+// bgzip is the only stage of this pipeline that cannot use more than one core on
+// its own: sort parallelizes itself and tabix is I/O bound. 4 is enough to take
+// compression off the critical path on the files this command is pointed at
+// without claiming a whole machine.
+export const DEFAULT_BGZIP_THREADS = 4;
+export function spawnSortProcess(outputFile, useCsi, threads = DEFAULT_BGZIP_THREADS) {
+    // -s: tabix wants the rows ordered by (refName, start) and by nothing else,
+    // so the whole-line comparison a non-stable sort falls back to on a tie is
+    // comparing multi-kb CIGARs to pick an order no reader can observe
+    const sortCmd = `sort -s -t"\`printf '\\t'\`" -k1,1 -k3,3n`;
+    const bgzipCommand = `bgzip -@ ${threads} > "$1"`;
+    const tabixCommand = `tabix ${useCsi ? '-C ' : ''}-s1 -b3 -e4 -0 "$1"`;
+    // `&&` (not `;`) so a bgzip failure aborts before tabix runs and propagates
+    // as the pipeline's exit code. The output path is passed as the shell's "$1"
+    // positional rather than interpolated into the command string, so a path
+    // with shell metacharacters (`"`, `$(...)`, backticks) can't break out and
+    // execute — same technique as sort-utils.ts. useCsi is a fixed literal, and
+    // the caller has already checked threads is a positive integer.
+    const fullCommand = `${sortCmd} | ${bgzipCommand} && ${tabixCommand}`;
+    return spawn('sh', ['-c', fullCommand, 'sh', outputFile], {
+        env: { ...process.env, LC_ALL: 'C' },
         stdio: ['pipe', process.stdout, process.stderr],
     });
 }
 export function getOutputFilename(file, out) {
-    return out || `${path.basename(file || 'output', '.paf')}.pif.gz`;
-}
-export async function waitForProcessClose(child) {
-    return new Promise(resolve => {
-        child.on('close', resolve);
-    });
+    // strip .paf or .paf.gz so a gzipped input doesn't yield input.paf.gz.pif.gz
+    const base = path.basename(file || 'output').replace(/\.paf(\.gz)?$/i, '');
+    return out || `${base}.pif.gz`;
 }

package/dist/commands/process-utils.js

@@ -1,10 +1,21 @@
 export async function waitForProcessClose(child) {
     return new Promise((resolve, reject) => {
-        child.on('close', code => {
-            resolve(code);
+        child.on('close', (code, signal) => {
+            resolve({ code, signal });
         });
         child.on('error', err => {
             reject(err);
         });
     });
 }
+// A downstream consumer closing the pipe early — `jbrowse sort-bed big.bed |
+// head` — is that consumer's choice, not a failure of ours. `sh` reports a
+// pipeline member's death by SIGPIPE as 128+13 rather than propagating the
+// signal, so both spellings have to be recognized.
+export function diedOfSigpipe({ code, signal }) {
+    return signal === 'SIGPIPE' || code === 128 + 13;
+}
+// for an error message: the exit code, or the signal when the child was killed
+export function describeExit({ code, signal }) {
+    return code === null ? `signal ${signal}` : `code ${code}`;
+}

package/dist/commands/remove-track.js

@@ -1,5 +1,5 @@
-import { parseArgs } from 'util';
-import { printHelp, readJsonFile, resolveConfigPath, writeJsonFile, } from "../utils.js";
+import { parseArgs } from 'node:util';
+import { printHelp, readConfigFile, requirePositional, resolveConfigPath, writeJsonFile, } from '../utils.js';
 export async function run(args) {
     const options = {
         help: {
@@ -21,30 +21,37 @@ export async function run(args) {
         allowPositionals: true,
     });
     const description = 'Remove a track configuration from a JBrowse 2 configuration. Be aware that this can cause crashes in saved sessions that refer to this track!';
-    const examples = ['$ jbrowse remove-track trackId'];
+    const usage = 'jbrowse remove-track <trackId> [options]';
+    const examples = [
+        '# remove a track from the config.json in the current directory',
+        '$ jbrowse remove-track my_track_id',
+        '',
+        '# remove a track from a config.json in a specific installation directory',
+        '$ jbrowse remove-track my_track_id --out /path/to/jb2/',
+        '',
+        '# remove a track from a specific config file',
+        '$ jbrowse remove-track my_track_id --target /path/to/jb2/config.json',
+    ];
     if (flags.help) {
         printHelp({
             description,
             examples,
-            usage: 'jbrowse remove-track <trackId> [options]',
+            usage,
             options,
         });
         return;
     }
     const trackId = positionals[0];
-    if (!trackId) {
-        throw new Error('Missing required argument: trackId\nUsage: jbrowse remove-track <trackId> [options]');
-    }
+    requirePositional(trackId, 'trackId', usage);
     const target = await resolveConfigPath(flags.target, flags.out);
-    const config = await readJsonFile(target);
-    const originalLength = config.tracks?.length || 0;
-    config.tracks = config.tracks?.filter(({ trackId: id }) => id !== trackId);
-    const newLength = config.tracks?.length || 0;
-    if (originalLength === newLength) {
+    const config = await readConfigFile(target);
+    const tracks = config.tracks ?? [];
+    const remaining = tracks.filter(track => track.trackId !== trackId);
+    if (remaining.length === tracks.length) {
         console.log(`No track found with trackId: ${trackId}`);
     }
     else {
-        await writeJsonFile(target, config);
+        await writeJsonFile(target, { ...config, tracks: remaining });
         console.log(`Removed track with trackId: ${trackId} from ${target}`);
     }
 }

package/dist/commands/set-default-session.js

@@ -1,7 +1,5 @@
-import { promises as fsPromises } from 'fs';
-import { parseArgs } from 'util';
-import parseJSON from 'json-parse-better-errors';
-import { printHelp, readJsonFile, resolveConfigPath, writeJsonFile, } from "../utils.js";
+import { parseArgs } from 'node:util';
+import { isRecord, printHelp, readConfigFile, readJsonFile, resolveConfigPath, writeJsonFile, } from '../utils.js';
 const description = 'Set a default session with views and tracks';
 const examples = [
     '# set default session for the config.json in your current directory',
@@ -10,20 +8,28 @@ const examples = [
     '# make session.json the defaultSession on the specified target config.json file',
     '$ jbrowse set-default-session --target /path/to/jb2/installation/config.json --session session.json',
     '',
-    '# print current default session',
-    '$ jbrowse set-default-session --currentSession # Prints out current default session',
+    '# override the name stored in the session file',
+    '$ jbrowse set-default-session --session session.json --name "My default view"',
+    '',
+    '# pipe a session in from another program',
+    `$ jq '.defaultSession' other/config.json | jbrowse set-default-session --session -`,
+    '',
+    '# print the current default session',
+    '$ jbrowse set-default-session --currentSession',
+    '',
+    '# remove the existing default session',
+    '$ jbrowse set-default-session --delete',
 ];
 const options = {
     session: {
         type: 'string',
         short: 's',
-        description: 'set path to a file containing session in json format (required, unless using delete/currentSession flags)',
+        description: 'set path to a file containing session in json format, or "-" to read it from stdin (required, unless using delete/currentSession flags)',
     },
     name: {
         type: 'string',
         short: 'n',
-        description: 'Give a name for the default session',
-        default: 'New Default Session',
+        description: 'Give a name for the default session (overrides any name in the session file; defaults to "New Default Session")',
     },
     currentSession: {
         type: 'boolean',
@@ -47,14 +53,14 @@ export async function run(args) {
         printHelp({
             description,
             examples,
-            usage: 'jbrowse add-track <track> [options]',
+            usage: 'jbrowse set-default-session [options]',
             options,
         });
         return;
     }
-    const { session, currentSession, delete: deleteDefaultSession } = runFlags;
+    const { session, name, currentSession, delete: deleteDefaultSession, } = runFlags;
     const target = await resolveConfigPath(runFlags.target, runFlags.out);
-    const configContents = await readJsonFile(target);
+    const configContents = await readConfigFile(target);
     if (deleteDefaultSession) {
         configContents.defaultSession = undefined;
         await writeJsonFile(target, configContents);
@@ -65,30 +71,28 @@ export async function run(args) {
     else if (!session) {
         throw new Error('Please provide a --session file');
     }
-    else if (session) {
+    else {
+        const fileSession = await readDefaultSessionFile(session);
         await writeJsonFile(target, {
             ...configContents,
-            defaultSession: await readDefaultSessionFile(session),
+            // precedence: explicit --name > the session file's own name > fallback
+            defaultSession: {
+                name: 'New Default Session',
+                ...fileSession,
+                ...(name !== undefined ? { name } : {}),
+            },
         });
     }
 }
 async function readDefaultSessionFile(defaultSessionFile) {
-    let defaultSessionJson;
-    try {
-        defaultSessionJson = await fsPromises.readFile(defaultSessionFile, {
-            encoding: 'utf8',
-        });
-    }
-    catch (error) {
-        throw new Error('Could not read the provided file');
-    }
-    try {
-        const session = parseJSON(defaultSessionJson);
-        // return top-level "session" if it exists, such as in files created by
-        // "File -> Export session"
-        return session.session || session;
-    }
-    catch (error) {
-        throw new Error('Could not parse the given default session file');
+    const contents = await readJsonFile(defaultSessionFile);
+    // unwrap the top-level "session" if it exists, such as in files created by
+    // "File -> Export session"
+    const session = contents.session ?? contents;
+    // spreading a string or an array here silently wrote a defaultSession of
+    // numeric keys, so say what is wrong with the file instead
+    if (!isRecord(session)) {
+        throw new Error(`${defaultSessionFile} does not contain a session object${contents.session === undefined ? '' : ' under its "session" key'}`);
     }
+    return session;
 }

package/dist/commands/shared/config-operations.js

@@ -1,14 +1,10 @@
-import { debug, writeJsonFile } from "../../utils.js";
-/**
- * Generic function to find and update or add an item to a config array
- * Returns the updated config and whether an item was overwritten
- */
-export function findAndUpdateOrAdd({ items, newItem, idField, getId, allowOverwrite, itemType, }) {
+import { debug, writeJsonFile } from '../../utils.js';
+export function findAndUpdateOrAdd({ items, newItem, idField, getId, force, itemType, }) {
     const newId = getId(newItem);
     const idx = items.findIndex(item => getId(item) === newId);
     if (idx !== -1) {
         debug(`Found existing ${itemType} ${newId} in configuration`);
-        if (allowOverwrite) {
+        if (force) {
             debug(`Overwriting ${itemType} ${newId} in configuration`);
             const updatedItems = [...items];
             updatedItems[idx] = newItem;
@@ -22,9 +18,6 @@ export function findAndUpdateOrAdd({ items, newItem, idField, getId, allowOverwr
         return { updatedItems: [...items, newItem], wasOverwritten: false };
     }
 }
-/**
- * Saves a config file and reports the result to the user
- */
 export async function saveConfigAndReport({ config, target, itemType, itemName, itemId, wasOverwritten, }) {
     debug(`Writing configuration to file ${target}`);
     await writeJsonFile(target, config);

package/dist/commands/shared/density.js

@@ -0,0 +1,12 @@
+/**
+ * Where the density sidecar for a data file lives: `<file>.density.bw`, with a
+ * `.gz`/`.bgz` stripped first so `genes.gff3.gz` yields `genes.gff3.density.bw`
+ * rather than a name carrying the compression of a file it is not compressed
+ * like.
+ *
+ * One rule, two commands: `make-density` writes here by default and `add-track`
+ * probes here, so a sidecar built with no `--out` is the one the track picks up.
+ */
+export function densitySidecarPath(file) {
+    return `${file.replace(/\.b?gz$/i, '')}.density.bw`;
+}

package/dist/commands/shared/sort-utils.js

@@ -1,7 +1,11 @@
-import { spawn } from 'child_process';
-import tmp from 'tmp';
+import { spawn } from 'node:child_process';
+import { parseArgs } from 'node:util';
+import { fileSync } from 'tmp';
+import { printHelp } from '../../utils.js';
+import { describeExit, diedOfSigpipe, waitForProcessClose, } from '../process-utils.js';
+import { validateFileArgument, validateRequiredCommands } from './validators.js';
 export const BED_CONFIG = {
-    description: 'Helper utility to sort BED files for tabix. Moves all lines starting with # to the top of the file, and sort by refname and start position using unix utilities sort and grep',
+    description: 'Sort a BED file for tabix. It is `sort -k1,1 -k2,2n` with LC_ALL=C and a tab separator, plus every line starting with # kept at the top rather than sorted into the data. Takes a file, or the same data on stdin',
     examples: [
         '# sort bed and pipe to bgzip',
         '$ jbrowse sort-bed input.bed | bgzip > sorted.bed.gz',
@@ -13,7 +17,7 @@ export const BED_CONFIG = {
     fileType: 'bed',
 };
 export const GFF_CONFIG = {
-    description: 'Helper utility to sort GFF files for tabix. Moves all lines starting with # to the top of the file, and sort by refname and start position using unix utilities sort and grep',
+    description: 'Sort a GFF or GTF for tabix — the two share a refname/start column layout. It is `sort -k1,1 -k4,4n` with LC_ALL=C and a tab separator, plus every line starting with # kept at the top rather than sorted into the data. Takes a file, or the same data on stdin',
     examples: [
         '# sort gff and pipe to bgzip',
         '$ jbrowse sort-gff input.gff | bgzip > sorted.gff.gz',
@@ -21,6 +25,10 @@ export const GFF_CONFIG = {
         '',
         '# sort gff from stdin',
         '$ cat input.gff | jbrowse sort-gff | bgzip > sorted.gff.gz',
+        '',
+        '# also works on GTF',
+        '$ jbrowse sort-gff input.gtf | bgzip > sorted.gtf.gz',
+        '$ tabix -p gff sorted.gtf.gz',
     ],
     sortColumn: 4,
     fileType: 'gff',
@@ -31,20 +39,69 @@ function getMinimalEnvironment() {
         LC_ALL: 'C',
     };
 }
+// The file path is passed to the shell as the positional argument "$1" rather
+// than interpolated into the command string, so a path containing shell
+// metacharacters (`"`, `$(...)`, backticks) cannot break out and execute. Only
+// sortColumn, an integer from the BED/GFF configs, is interpolated.
+function sortPipeline(sortColumn) {
+    return `grep "^#" "$1"; grep -v "^#" "$1" | sort -t"\`printf '\\t'\`" -k1,1 -k${sortColumn},${sortColumn}n`;
+}
 function createSortCommandForStdin(sortColumn) {
-    const tmpFile = tmp.fileSync({ prefix: 'jbrowse-sort' }).name;
-    const sortCmd = `sort -t"\`printf '\\t'\`" -k1,1 -k${sortColumn},${sortColumn}n`;
-    return `cat > ${tmpFile} && (grep "^#" ${tmpFile}; grep -v "^#" ${tmpFile} | ${sortCmd}) && rm -f ${tmpFile}`;
+    // discardDescriptor: we only want the path — the shell below opens the file
+    // itself, so tmp's own handle would just be a descriptor left open for the
+    // life of the process
+    const tmpFile = fileSync({
+        prefix: 'jbrowse-sort',
+        discardDescriptor: true,
+    }).name;
+    // trap on EXIT removes the temp file whether or not the sort pipeline
+    // succeeds (a bare `&& rm` leaks the file when the pipeline fails)
+    return {
+        command: `trap 'rm -f "$1"' EXIT; cat > "$1" && (${sortPipeline(sortColumn)})`,
+        pathArg: tmpFile,
+    };
 }
 function createSortCommandForFile(file, sortColumn) {
-    return `(grep "^#" "${file}"; grep -v "^#" "${file}" | sort -t"\`printf '\\t'\`" -k1,1 -k${sortColumn},${sortColumn}n)`;
+    return { command: `(${sortPipeline(sortColumn)})`, pathArg: file };
 }
 export function spawnSortProcess(file, sortColumn) {
-    const command = file
+    const { command, pathArg } = file
         ? createSortCommandForFile(file, sortColumn)
         : createSortCommandForStdin(sortColumn);
-    return spawn('sh', ['-c', command], {
+    // 'sh' becomes $0, pathArg becomes $1 inside the command
+    return spawn('sh', ['-c', command, 'sh', pathArg], {
         env: getMinimalEnvironment(),
         stdio: 'inherit',
     });
 }
+export async function runSort(config, commandName, args) {
+    const options = { help: { type: 'boolean', short: 'h' } };
+    const { values: flags, positionals } = parseArgs({
+        args,
+        options,
+        allowPositionals: true,
+    });
+    if (flags.help) {
+        printHelp({
+            description: config.description,
+            examples: config.examples,
+            usage: `jbrowse ${commandName} [file] [options]`,
+            options,
+        });
+        return;
+    }
+    const file = positionals[0];
+    validateFileArgument(file, commandName, config.fileType);
+    validateRequiredCommands(['sh', 'sort', 'grep']);
+    const child = spawnSortProcess(file, config.sortColumn);
+    const exit = await waitForProcessClose(child);
+    // These commands exist to be piped (`jbrowse sort-bed in.bed | bgzip > …`), so
+    // a consumer that stops reading early — `| head`, `| grep -q` — must not be
+    // reported as a sort failure. It used to exit 1 with "exited with code 141".
+    if (diedOfSigpipe(exit)) {
+        return;
+    }
+    if (exit.code !== 0) {
+        throw new Error(`Sort process exited with ${describeExit(exit)}`);
+    }
+}