@jbrowse/cli 4.2.1 → 5.0.0-beta.1

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

@@ -1,7 +1,8 @@
-import { parseArgs } from 'util';
-import { createPIF, getOutputFilename, spawnSortProcess, waitForProcessClose, } from "./pif-generator.js";
-import { printHelp } from "../../utils.js";
-import { validateFileArgument, validateRequiredCommands, } from "../shared/validators.js";
+import { parseArgs } from 'node:util';
+import { printHelp } from '../../utils.js';
+import { describeExit, waitForProcessClose } from '../process-utils.js';
+import { validateFileArgument, validateRequiredCommands, } from '../shared/validators.js';
+import { DEFAULT_COARSE_SPLIT_GAP, createPIF, getOutputFilename, missingPairs, spawnSortProcess, } from './pif-generator.js';
 export async function run(args) {
     const options = {
         help: {
@@ -16,6 +17,14 @@ export async function run(args) {
             type: 'boolean',
             description: 'Create a CSI index for the PIF file instead of TBI',
         },
+        coarse: {
+            type: 'string',
+            description: 'Minimum insertion/deletion length (bp) at which a coarse-tier row is split into multiple pieces so each row stays tight — 0 emits an unsplit coarse tier. Defaults to 10000. The no-CIGAR coarse tier (prefix T/Q) is emitted alongside the per-row CIGAR fine tier by default so whole-genome synteny views can auto-switch to it; pass --no-coarse to omit it.',
+        },
+        'no-coarse': {
+            type: 'boolean',
+            description: 'Do not emit the coarse no-CIGAR tier; write only the per-row CIGAR fine tier.',
+        },
     };
     const { values: flags, positionals } = parseArgs({
         args,
@@ -24,14 +33,30 @@ export async function run(args) {
     });
     const description = 'creates pairwise indexed PAF (PIF), with bgzip and tabix';
     const examples = [
-        '$ jbrowse make-pif input.paf # creates input.pif.gz in same directory',
+        '# creates input.pif.gz and input.pif.gz.tbi in the same directory',
+        '$ jbrowse make-pif input.paf',
+        '',
+        '# specify the output file, also creates output.pif.gz.tbi',
+        '$ jbrowse make-pif input.paf --out output.pif.gz',
+        '',
+        '# use a CSI index for assemblies with chromosomes longer than ~512 Mb',
+        '$ jbrowse make-pif input.paf --csi',
+        '',
+        '# emit an unsplit coarse tier (alongside the fine tier)',
+        '$ jbrowse make-pif input.paf --coarse 0',
         '',
-        '$ jbrowse make-pif input.paf --out output.pif.gz # specify output file, creates output.pif.gz.tbi also',
+        '# emit only the per-row CIGAR fine tier, skipping the coarse tier',
+        '$ jbrowse make-pif input.paf --no-coarse',
     ];
+    const notes = 'Use --csi for assemblies containing sequences longer than ~512 Mb. The ' +
+        'default TBI index cannot address coordinates beyond 2^29 (~536 Mb), so a ' +
+        'CSI index is required for large chromosomes (e.g. some plant and ' +
+        'amphibian genomes). Requires sh, sort, bgzip, and tabix on the PATH.';
     if (flags.help) {
         printHelp({
             description,
             examples,
+            notes,
             usage: 'jbrowse make-pif <file> [options]',
             options,
         });
@@ -39,11 +64,73 @@ export async function run(args) {
     }
     const file = positionals[0];
     validateFileArgument(file, 'make-pif', 'paf');
-    validateRequiredCommands(['sh', 'sort', 'grep', 'tabix', 'bgzip']);
-    const { out, csi = false } = flags;
+    validateRequiredCommands(['sh', 'sort', 'tabix', 'bgzip']);
+    const { out, csi = false, coarse, 'no-coarse': noCoarse = false } = flags;
     const outputFile = getOutputFilename(file, out);
+    // --no-coarse used to silently win over an explicit --coarse, so a run asking
+    // for both wrote a file with no coarse tier and said nothing about it
+    if (noCoarse && coarse !== undefined) {
+        throw new Error('--coarse and --no-coarse are mutually exclusive');
+    }
+    const coarseSplitGap = noCoarse
+        ? undefined
+        : coarse === undefined
+            ? DEFAULT_COARSE_SPLIT_GAP
+            : +coarse;
+    if (coarseSplitGap !== undefined &&
+        (!Number.isFinite(coarseSplitGap) || coarseSplitGap < 0)) {
+        throw new Error(`Invalid --coarse value: ${coarse}`);
+    }
     const child = spawnSortProcess(outputFile, csi);
-    await createPIF(file, child.stdin);
-    child.stdin.end();
-    await waitForProcessClose(child);
+    const stdin = child.stdin;
+    // end stdin even if createPIF throws, otherwise the spawned sort/index child
+    // is left running with an open stdin
+    const stats = await createPIF(file, stdin, coarseSplitGap).finally(() => {
+        stdin.end();
+    });
+    const { samples, rows, skipped } = stats;
+    // no SIGPIPE exemption here (unlike sort-gff/sort-bed): this pipeline's output
+    // is the .pif.gz file, so anything that killed it early left that file broken
+    const exit = await waitForProcessClose(child);
+    if (exit.code !== 0) {
+        throw new Error(`PIF sort/index pipeline exited with ${describeExit(exit)}`);
+    }
+    // A file that yielded nothing is almost always the wrong file, not an empty
+    // alignment: without this the command wrote a valid, indexed, empty PIF and
+    // printed the add-track suggestion for it
+    if (rows === 0) {
+        throw new Error(`No valid PAF rows found in ${file ?? 'stdin'} (${skipped} line(s) had fewer than the 12 mandatory PAF columns). Is this a PAF file?`);
+    }
+    if (skipped > 0) {
+        console.warn(`Warning: skipped ${skipped} of ${rows + skipped} line(s) with fewer than the 12 mandatory PAF columns`);
+    }
+    // An all-vs-all PAF that does not state every pair indexes perfectly well and
+    // then draws an empty synteny band for each pair the aligner never emitted,
+    // which reads as "no homology here" rather than as "never computed". This is
+    // the moment someone is looking at the file, and the census it needs was
+    // already taken on the pass above.
+    const missing = missingPairs(stats);
+    if (missing.length > 0) {
+        const shown = missing
+            .slice(0, 5)
+            .map(([a, b]) => `${a}<->${b}`)
+            .join(', ');
+        const rest = missing.length - Math.min(missing.length, 5);
+        console.warn(`Warning: this file has ${samples.size} samples but states only ` +
+            `${(samples.size * (samples.size - 1)) / 2 - missing.length} of their ` +
+            `${(samples.size * (samples.size - 1)) / 2} pairs. Synteny bands for the ` +
+            `missing pairs (${shown}${rest > 0 ? `, and ${rest} more` : ''}) will draw ` +
+            `empty. That is what a reference-anchored alignment looks like — only ` +
+            `pairs involving the reference are stated. Order the synteny rows so the ` +
+            `reference sits between the others, use a complete all-vs-all if the ` +
+            `project publishes one, or view a larger cohort as a multiple alignment ` +
+            `(MAF) rather than a stack of pairwise bands.`);
+    }
+    const indexFile = `${outputFile}.${csi ? 'csi' : 'tbi'}`;
+    const nextCommand = samples.size > 0
+        ? 'Next, add it as an all-vs-all synteny track (PanSN names detected):\n' +
+            `  jbrowse add-track ${outputFile} --adapterType AllVsAllIndexedPAFAdapter -a ${[...samples].sort().join(',')} --load copy`
+        : 'Next, add it as a synteny track (set -a to your query,target assembly names):\n' +
+            `  jbrowse add-track ${outputFile} -a query,target --load copy`;
+    console.log(`Created ${outputFile} and ${indexFile}\n\n${nextCommand}`);
 }

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

@@ -1,55 +1,289 @@
-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 { csToCigar, flipCigar, pafIdentity, swapIndelCigar, } from '@jbrowse/cigar-utils';
+import { splitCigarOnLargeGaps } from './cigar-utils.js';
+// Default split gap (bp) for the coarse tier. A row is broken into multiple
+// coarse pieces wherever a CIGAR insertion/deletion is at least this long, so
+// each coarse row's bounding box stays tight. 10kb matches the adapter's
+// default coarseBpPerPxThreshold (~1px at the zoom where the coarse tier is
+// served), so smaller gaps that would be sub-pixel there don't fragment rows.
+export const DEFAULT_COARSE_SPLIT_GAP = 10_000;
+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;
+}
+function coarsePieces({ cigar, strand, tstart, tend, qstart, qend, numMatches, blockLen, splitGap, }) {
+    const whole = { tstart, tend, qstart, qend, numMatches, blockLen };
+    const split = cigar && splitGap > 0
+        ? splitCigarOnLargeGaps({
+            cigar,
+            strand,
+            tstart,
+            tend,
+            qstart,
+            qend,
+            splitGap,
+        })
+        : undefined;
+    // The walk's reconstruction is taken only when it CLOSED on the row's own far
+    // corner (see `CigarSplit.closed`) — otherwise the columns are what the fine
+    // tier draws and the coarse row must not drift off them.
+    //
+    // Closure rather than a piece count: `segments.length < 2` read as "nothing to
+    // split on", but a large gap at either END also yields a single piece, a
+    // genuine tightening that was being thrown away for the loose box. It is the
+    // ordinary case below the default `--coarse`. The count also never noticed a
+    // MULTI-piece walk that failed to close, which is the case it was written for.
+    return split?.closed && split.segments.length > 0
+        ? split.segments.map(seg => ({
+            ...seg,
+            numMatches: blockLen > 0 ? Math.round((numMatches * seg.blockLen) / blockLen) : 0,
+        }))
+        : [whole];
+}
+// 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) };
+}
+// Coarse identity must match the fine tier exactly, or coloring jumps at the
+// zoom where the view switches tiers. So it is written off the SAME function the
+// adapters read the fine tier with (de:f: tag, then odgi's id:f:, then
+// num_matches/block_len) rather than a private copy of that chain — a copy is
+// what previously skipped the id:f: rung. A CIGAR recompute is deliberately not
+// in the chain at all: a cg (M-style) CIGAR folds mismatches into M, so it would
+// report ~0 divergence (spurious 100% identity) for a divergent alignment.
+//
+// When the row's own de:f: is what the reader lands on, that string is passed
+// through byte-for-byte rather than recomputed: a round trip through toFixed(6)
+// would silently truncate a 7-decimal tag and drift the two tiers apart by the
+// exact mechanism this is guarding against.
+function coarseDivergence(tags, numMatches, blockLen) {
+    const rawDe = tags.find(f => f.startsWith('de:f:'))?.slice(5);
+    const identity = pafIdentity({
+        de: rawDe,
+        id: tags.find(f => f.startsWith('id:f:'))?.slice(5),
+        numMatches,
+        blockLen,
+    });
+    return rawDe !== undefined && 1 - +rawDe === identity
+        ? rawDe
+        : (1 - identity).toFixed(6);
+}
+function pifRow(fields) {
+    return `${fields.join('\t')}\n`;
+}
+function processLine(line, coarseSplitGap, stats) {
+    if (line.startsWith('#')) {
+        return '';
     }
-    finally {
-        rl1.close();
+    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);
+    const { tags, cigarIdx } = foldCsIntoCg(rest);
+    const cigar = cigarIdx === -1 ? undefined : tags[cigarIdx].slice(5);
+    // 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 (coarseSplitGap === undefined) {
+        return fineRows;
+    }
+    const numMatches = +tags[0];
+    const blockLen = +tags[1];
+    const mapq = tags[2];
+    // Every optional tag except the alignment string itself rides along, so a
+    // click on a coarse ribbon shows the same attributes as the same alignment
+    // does zoomed in (rustybam's tags, minimap2's tp/cm/s1, odgi's id). Only the
+    // CIGAR is dropped — dropping it is the entire point of the tier — and de:f:,
+    // which is rewritten below. No `cs:Z:` can reach here: it was folded into the
+    // cg above, since a PIF row carries one alignment string.
+    const passthrough = tags
+        .slice(3)
+        .filter(f => !f.startsWith('cg:Z:') && !f.startsWith('de:f:'));
+    const de = coarseDivergence(tags, numMatches, blockLen);
+    return (fineRows +
+        coarsePieces({
+            cigar,
+            strand: strand,
+            tstart: +s2,
+            tend: +e2,
+            qstart: +s1,
+            qend: +e1,
+            numMatches,
+            blockLen,
+            splitGap: coarseSplitGap,
+        })
+            .flatMap(piece => {
+            const tail = [
+                piece.numMatches,
+                piece.blockLen,
+                mapq,
+                ...passthrough,
+                `de:f:${de}`,
+            ];
+            const { tstart, tend, qstart, qend } = piece;
+            return [
+                pifRow([
+                    `T${c2}`,
+                    l2,
+                    tstart,
+                    tend,
+                    strand,
+                    c1,
+                    l1,
+                    qstart,
+                    qend,
+                    ...tail,
+                ]),
+                pifRow([
+                    `Q${c1}`,
+                    l1,
+                    qstart,
+                    qend,
+                    strand,
+                    c2,
+                    l2,
+                    tstart,
+                    tend,
+                    ...tail,
+                ]),
+            ];
+        })
+            .join(''));
+}
+function makePifTransform(coarseSplitGap, 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, coarseSplitGap, stats))
+                .join(''));
+        },
+        flush(callback) {
+            callback(null, tail ? processLine(tail, coarseSplitGap, stats) : '');
+        },
+    });
+}
+// 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, coarseSplitGap) {
+    const stats = {
+        samples: new Set(),
+        pairs: new Set(),
+        rows: 0,
+        skipped: 0,
+    };
+    const transform = makePifTransform(coarseSplitGap, 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;
 }
 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',
-    };
-    return spawn('sh', ['-c', fullCommand], {
-        env: minimalEnv,
+    const bgzipCommand = `bgzip > "$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.
+    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}`);
     }
 }