edfcore 0.1.16 → 0.1.18

package/CHANGELOG.md

@@ -0,0 +1,119 @@
+# Changelog
+
+Notable changes per release. Fixes say what was wrong and what it cost, because a version number
+alone does not tell you whether you were affected.
+
+edfcore is pre-1.0. Patch releases have carried behaviour changes where the old behaviour was a
+defect; those are called out below.
+
+## 0.1.18
+
+- **Added** this changelog, and documentation for the CLI.
+
+## 0.1.17
+
+- **Added** a CLI: `npx edfcore header|validate|events|json <file>`. Exit codes are the contract —
+  0 success, 1 unreadable or failed validation, 2 bad usage — so `edfcore validate` gates a CI job
+  without parsing output. Patient identification is opt-in.
+
+## 0.1.16
+
+- **Added** an exhaustiveness check to the public API test. It was an allowlist, which only proved
+  that listed exports exist; fifteen helpers reached npm undocumented because nothing failed.
+
+## 0.1.15
+
+- **Fixed** `readEnvelope` reporting `precededByGap: undefined` on every chunk, so an EDF+D
+  envelope claimed no gaps. Introduced in 0.1.7. At one bucket per pixel a gap is invisible in the
+  data itself, so a viewer had nothing to go on.
+
+## 0.1.14
+
+- **Added** [API — helpers](https://edfcore.vercel.app/docs/api-helpers), documenting everything
+  shipped in 0.1.7 through 0.1.13.
+
+## 0.1.13
+
+- **Added** `formatValidationReport` to `edfcore/validate`.
+
+## 0.1.12
+
+- **Added** `formatHeader`. Omits patient identification unless asked.
+
+## 0.1.11
+
+- **Added** `sampleIndexAt`, `sampleStartTicks`, `sampleStartSeconds`. `Math.round(seconds *
+  sampleRateHz)` drifts by one over a long recording when the rate has no exact float
+  representation, and yields `NaN` for a zero record duration.
+
+## 0.1.10
+
+- **Added** `filterAnnotationsByTime`, `filterAnnotationsByText`, `countAnnotationsByText`. All
+  comparisons are on `onsetTicks`, not on float seconds.
+
+## 0.1.9
+
+- **Added** `streamRecords`, an async iterator over a window with bounded memory.
+
+## 0.1.8
+
+- **Added** BioSemi Status-channel helpers: `getStatusSignal`, `decodeStatusWord`, `readTriggers`.
+  One event per change of the trigger word, not one per sample.
+
+## 0.1.7
+
+- **Added** min/max envelope decimation: `readEnvelope`, `toPhysicalEnvelope`,
+  `envelopeOfSamples`. `toPhysicalEnvelope` swaps the bounds when the gain is negative, which
+  `toPhysical` applied twice would not.
+
+## 0.1.6
+
+- **Fixed** `validateRecording` throwing `RangeError: Maximum call stack size exceeded` once a
+  sweep collected about 125,000 diagnostics. `push(...array)` passes each element as a call
+  argument. A 32 MiB file with 130,000 records and a damaged annotation section reached it
+  honestly, and the thrown value was neither an `EdfError` nor a caller mistake.
+- **Fixed** record onsets wrapping silently in their `BigInt64Array` for an overflowing record
+  duration, producing an index that reported `coverage: 'complete'` with one segment per record,
+  negative gaps, and no diagnostic. A declared span past the tick range is now refused with a new
+  fatal `RECORDING_SPAN_UNREPRESENTABLE`.
+
+## 0.1.5
+
+- **Changed** `readWindow` to validate `signalIndices` before resolving the window. An
+  out-of-range index previously threw for a window over data and returned `[]` for a window past
+  the end — and `[]` is documented to mean "no records here", never "the read failed".
+
+## 0.1.4
+
+- **Fixed** a record whose timekeeping TAL is missing deriving its onset from zero rather than
+  from the recording's start. Three failures came from this one gap: a missing TAL in the last
+  record faked a discontinuity and made `readWindow` refuse an entire conforming file; the scan
+  chunk size changed the onsets, the segments and even a fatal `TIMELINE_NOT_MONOTONIC`; and the
+  same record reported two different start times depending on how many neighbours were read with
+  it.
+
+## 0.1.3
+
+- **Fixed** `cachedSource` returning fabricated zero bytes when `blockBytes` or `maxBytes` was
+  `NaN`. The `< 1` guard cannot fire for `NaN`.
+- **Fixed** `httpSource` hanging forever on a `NaN` `maxConcurrency` — no error, no timeout.
+- **Fixed** `httpSource` re-downloading a Range-ignoring resource once per concurrent read. 32
+  concurrent reads cost 32 full transfers; now one.
+- **Fixed** a source-level `AbortSignalLike` shim being ignored, so the same object behaved
+  differently depending on where it was passed.
+- **Fixed** `validateRecording` allocating its scan scratch buffer without checking
+  `maxMaterializeBytes`, reachable as 400 MB from one corrupted field in a 512-byte file.
+
+## 0.1.2
+
+- Release tooling only.
+
+## 0.1.1
+
+- **Fixed** a false claim in the README: `strictNullChecks` does not catch an unguarded
+  `toPhysical` call. The type stops you reading the gain; it does not gate the call.
+- **Fixed** three README links that 404ed on npmjs.com.
+
+## 0.1.0
+
+First release. Reads EDF, EDF+, BDF and BDF+ with real random access.

package/README.md

@@ -7,6 +7,17 @@ Node. Real random access, no dependencies.
 npm install edfcore
 ```
 
+## Look at a file without writing code
+
+```bash
+npx edfcore header overnight.edf     # signals, rates, ranges, diagnostics
+npx edfcore events hypnogram.edf     # annotations, counted by text
+npx edfcore validate overnight.edf   # full conformance sweep; exits 1 on failure
+npx edfcore json overnight.edf       # the header as JSON, for jq
+```
+
+Patient identification is omitted unless you pass `--patient`.
+
 ## How do I read an EDF file in JavaScript?
 
 Open a source, pick a signal, read a time window, convert it to physical units. In the browser,

package/dist/cli-run.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What `npx edfcore` actually does, with the process factored out.
+ *
+ * `cli.ts` is a shell that supplies real `node:fs` and `node:process`; everything decidable lives
+ * here, behind an injected `CliIo`. That is not ceremony — a CLI tested by spawning a subprocess
+ * can only be tested once the package is built, so the tests either skip in CI or test a stale
+ * binary. This way the exit codes and the output are ordinary unit tests.
+ */
+/** Everything the CLI touches outside itself. */
+export interface CliIo {
+    readFile(path: string): Promise<Uint8Array>;
+    out(text: string): void;
+    err(text: string): void;
+}
+export interface Args {
+    readonly command: string | undefined;
+    readonly file: string | undefined;
+    readonly patient: boolean;
+    readonly limit: number | undefined;
+}
+export declare function parseArgs(argv: readonly string[]): Args;
+export declare function runCli(args: Args, io: CliIo): Promise<number>;
+//# sourceMappingURL=cli-run.d.ts.map

package/dist/cli-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-run.d.ts","sourceRoot":"","sources":["../src/cli-run.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH,iDAAiD;AACjD,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC5C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAgBD,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAoBvD;AAQD,wBAAsB,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAoFnE"}

package/dist/cli-run.js

@@ -0,0 +1,126 @@
+/**
+ * What `npx edfcore` actually does, with the process factored out.
+ *
+ * `cli.ts` is a shell that supplies real `node:fs` and `node:process`; everything decidable lives
+ * here, behind an injected `CliIo`. That is not ceremony — a CLI tested by spawning a subprocess
+ * can only be tested once the package is built, so the tests either skip in CI or test a stale
+ * binary. This way the exit codes and the output are ordinary unit tests.
+ */
+import { countAnnotationsByText } from './annotations-query.js';
+import { formatDiagnostics } from './diagnostics/format.js';
+import { formatHeader } from './format-header.js';
+import { formatValidationReport } from './format-report.js';
+import { byteSource } from './io/bytes.js';
+import { openEdf, readAnnotations } from './recording.js';
+import { validateRecording } from './validate.js';
+const USAGE = `edfcore — read EDF, EDF+, BDF and BDF+ files
+
+  npx edfcore header <file>       the header, the signals, and any diagnostics
+  npx edfcore validate <file>     a full conformance sweep, scanning every sample
+  npx edfcore events <file>       the annotations, counted by text
+  npx edfcore json <file>         the header as JSON, for piping into jq
+
+Options
+  --patient                       include patient identification (header, json)
+  --limit <n>                     individual diagnostics to print (default 20)
+
+Exit codes: 0 success, 1 the file is unreadable or failed validation, 2 bad usage.
+`;
+export function parseArgs(argv) {
+    const positional = [];
+    let patient = false;
+    let limit;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--patient')
+            patient = true;
+        else if (arg === '--limit') {
+            const value = Number(argv[i + 1]);
+            // A NaN limit would disable the cap silently, which is the opposite of what was asked for.
+            if (!Number.isSafeInteger(value) || value < 0) {
+                throw new RangeError(`--limit needs a whole number, received ${String(argv[i + 1])}`);
+            }
+            limit = value;
+            i += 1;
+        }
+        else if (arg !== undefined && !arg.startsWith('-'))
+            positional.push(arg);
+    }
+    return { command: positional[0], file: positional[1], patient, limit };
+}
+async function open(io, file) {
+    // Read whole rather than fileSource: a CLI invocation is one pass over one file, and holding
+    // it in memory removes any question of a descriptor outliving the process.
+    return openEdf(byteSource(await io.readFile(file)));
+}
+export async function runCli(args, io) {
+    const { command, file } = args;
+    if (command === undefined || command === 'help' || command === '--help') {
+        io.out(USAGE);
+        return command === undefined ? 2 : 0;
+    }
+    if (file === undefined) {
+        io.err(`edfcore ${command}: no file given\n\n${USAGE}`);
+        return 2;
+    }
+    switch (command) {
+        case 'header': {
+            const recording = await open(io, file);
+            io.out(`${formatHeader(recording.header, { includePatientId: args.patient })}\n`);
+            if (recording.header.diagnostics.length > 0) {
+                io.out(`\n${formatDiagnostics(recording.header.diagnostics, { maxItems: args.limit ?? 20 })}\n`);
+            }
+            return 0;
+        }
+        case 'validate': {
+            const recording = await open(io, file);
+            const report = await validateRecording(recording, { scanSamples: true });
+            io.out(`${formatValidationReport(report, { header: recording.header, maxItems: args.limit ?? 20 })}\n`);
+            // Exit 1 on failure so a CI job can gate on it without parsing the output.
+            return report.ok ? 0 : 1;
+        }
+        case 'events': {
+            const recording = await open(io, file);
+            const { annotations } = await readAnnotations(recording, {
+                start: 0,
+                count: recording.header.recordCount,
+            });
+            if (annotations.length === 0) {
+                io.out('no annotations\n');
+                return 0;
+            }
+            io.out(`${annotations.length} annotation(s)\n\n`);
+            for (const { text, count } of countAnnotationsByText(annotations)) {
+                io.out(`${String(count).padStart(8)}  ${text}\n`);
+            }
+            return 0;
+        }
+        case 'json': {
+            const recording = await open(io, file);
+            const { header } = recording;
+            io.out(`${JSON.stringify({
+                variant: header.variant,
+                recordCount: header.recordCount,
+                recordDurationSeconds: header.recordDurationSeconds,
+                spanSeconds: recording.timeline.spanSeconds,
+                // Patient identification is opt-in here for the same reason it is in formatHeader:
+                // the obvious thing to do with this output is pipe it somewhere.
+                ...(args.patient ? { patient: header.patient.raw.trim() } : {}),
+                signals: header.signals.map((signal) => ({
+                    index: signal.index,
+                    label: signal.label,
+                    kind: signal.kind,
+                    samplesPerRecord: signal.samplesPerRecord,
+                    sampleRateHz: signal.sampleRateHz,
+                    physicalDimension: signal.physicalDimension,
+                })),
+                diagnostics: header.diagnostics.map((d) => ({ code: d.code, severity: d.severity })),
+            }, null, 2)}\n`);
+            return 0;
+        }
+        default:
+            io.err(`edfcore: unknown command ${JSON.stringify(command)}\n\n${USAGE}`);
+            return 2;
+    }
+}
+//# sourceMappingURL=cli-run.js.map

package/dist/cli-run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-run.js","sourceRoot":"","sources":["../src/cli-run.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * `npx edfcore` — looking at a file without writing code.
+ *
+ * A separate entry point, never re-exported from the barrel, because it imports `node:fs` and
+ * `node:process`. The universal entry must stay free of Node built-ins, and a test asserts it.
+ *
+ * This file is only the wiring. The decisions live in `cli-run.ts`, so they can be tested without
+ * spawning a process against a build that may not exist yet.
+ *
+ * `main()` runs unconditionally rather than behind an `import.meta.url === process.argv[1]` guard.
+ * That guard is a known trap for a bin: `npx` runs the command through a symlink, so the two paths
+ * differ, the condition is false, and the CLI exits 0 having done nothing.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;GAYG"}

package/dist/cli.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * `npx edfcore` — looking at a file without writing code.
+ *
+ * A separate entry point, never re-exported from the barrel, because it imports `node:fs` and
+ * `node:process`. The universal entry must stay free of Node built-ins, and a test asserts it.
+ *
+ * This file is only the wiring. The decisions live in `cli-run.ts`, so they can be tested without
+ * spawning a process against a build that may not exist yet.
+ *
+ * `main()` runs unconditionally rather than behind an `import.meta.url === process.argv[1]` guard.
+ * That guard is a known trap for a bin: `npx` runs the command through a symlink, so the two paths
+ * differ, the condition is false, and the CLI exits 0 having done nothing.
+ */
+// biome-ignore lint/suspicious/noTsIgnore: @ts-expect-error errors when unused — see node.ts.
+// @ts-ignore 'node:fs/promises' has no declarations under `types: []`; its shape is below.
+import * as nodeFsPromises from 'node:fs/promises';
+// biome-ignore lint/suspicious/noTsIgnore: as above.
+// @ts-ignore 'node:process' has no declarations under `types: []`; its shape is below.
+import * as nodeProcess from 'node:process';
+import { parseArgs, runCli } from './cli-run.js';
+import { isEdfError } from './errors.js';
+const fs = nodeFsPromises;
+const proc = nodeProcess.default ??
+    nodeProcess;
+const io = {
+    readFile: (path) => fs.readFile(path),
+    out: (text) => {
+        proc.stdout.write(text);
+    },
+    err: (text) => {
+        proc.stderr.write(text);
+    },
+};
+async function main() {
+    try {
+        proc.exitCode = await runCli(parseArgs(proc.argv.slice(2)), io);
+    }
+    catch (error) {
+        // An EdfError already says what is wrong, where, and what to do next; a stack trace over the
+        // top of it would bury the one useful line.
+        const message = isEdfError(error) || error instanceof Error ? error.message : String(error);
+        proc.stderr.write(`edfcore: ${message}\n`);
+        proc.exitCode = 1;
+    }
+}
+// Not `await main()`: the package documents that no module in its graph uses top-level await,
+// which is what keeps require() safe on Node >= 22.12. main() catches everything, so it cannot
+// reject, and Node keeps the process alive until it settles.
+void main();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;GAYG;AAEH,8FAA8F;AAC9F,2FAA2F;AAC3F,OAAO,KAAK,cAAc,MAAM,kBAAkB,CAAC;AACnD,qDAAqD;AACrD,uFAAuF;AACvF,OAAO,KAAK,WAAW,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAc,SAAS,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAYzC,MAAM,EAAE,GAAW,cAAmC,CAAC;AACvD,MAAM,IAAI,GACP,WAAoD,CAAC,OAAO;IAC5D,WAAsC,CAAC;AAE1C,MAAM,EAAE,GAAU;IAChB,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC;IACrC,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE;QACZ,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IACD,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE;QACZ,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;CACF,CAAC;AAEF,KAAK,UAAU,IAAI;IACjB,IAAI,CAAC;QACH,IAAI,CAAC,QAAQ,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAClE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,6FAA6F;QAC7F,4CAA4C;QAC5C,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5F,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,OAAO,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;IACpB,CAAC;AACH,CAAC;AAED,8FAA8F;AAC9F,+FAA+F;AAC/F,6DAA6D;AAC7D,KAAK,IAAI,EAAE,CAAC"}

package/dist/constants.d.ts

@@ -109,5 +109,5 @@ export declare const SIGNAL_FIELD_BLOCK_OFFSETS: {
     readonly reserved: 224;
 };
 /** Published package version. Kept in sync with package.json by a test. */
-export declare const VERSION = "0.1.16";
+export declare const VERSION = "0.1.18";
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.js

@@ -79,5 +79,5 @@ export const SIGNAL_FIELD_BLOCK_OFFSETS = {
     reserved: 224,
 };
 /** Published package version. Kept in sync with package.json by a test. */
-export const VERSION = '0.1.16';
+export const VERSION = '0.1.18';
 //# sourceMappingURL=constants.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edfcore",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Modern, typed, zero-dependency reader for EDF, EDF+, BDF and BDF+ biosignal files. Works in browsers and Node with true random access.",
   "keywords": [
     "edf",
@@ -32,6 +32,7 @@
   "type": "module",
   "sideEffects": false,
   "files": [
+    "CHANGELOG.md",
     "dist",
     "src"
   ],
@@ -74,5 +75,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "bin": {
+    "edfcore": "./dist/cli.js"
   }
 }

package/src/cli-run.ts

@@ -0,0 +1,158 @@
+/**
+ * What `npx edfcore` actually does, with the process factored out.
+ *
+ * `cli.ts` is a shell that supplies real `node:fs` and `node:process`; everything decidable lives
+ * here, behind an injected `CliIo`. That is not ceremony — a CLI tested by spawning a subprocess
+ * can only be tested once the package is built, so the tests either skip in CI or test a stale
+ * binary. This way the exit codes and the output are ordinary unit tests.
+ */
+
+import { countAnnotationsByText } from './annotations-query.js';
+import { formatDiagnostics } from './diagnostics/format.js';
+import { formatHeader } from './format-header.js';
+import { formatValidationReport } from './format-report.js';
+import { byteSource } from './io/bytes.js';
+import { openEdf, readAnnotations } from './recording.js';
+import { validateRecording } from './validate.js';
+
+/** Everything the CLI touches outside itself. */
+export interface CliIo {
+  readFile(path: string): Promise<Uint8Array>;
+  out(text: string): void;
+  err(text: string): void;
+}
+
+const USAGE = `edfcore — read EDF, EDF+, BDF and BDF+ files
+
+  npx edfcore header <file>       the header, the signals, and any diagnostics
+  npx edfcore validate <file>     a full conformance sweep, scanning every sample
+  npx edfcore events <file>       the annotations, counted by text
+  npx edfcore json <file>         the header as JSON, for piping into jq
+
+Options
+  --patient                       include patient identification (header, json)
+  --limit <n>                     individual diagnostics to print (default 20)
+
+Exit codes: 0 success, 1 the file is unreadable or failed validation, 2 bad usage.
+`;
+
+export interface Args {
+  readonly command: string | undefined;
+  readonly file: string | undefined;
+  readonly patient: boolean;
+  readonly limit: number | undefined;
+}
+
+export function parseArgs(argv: readonly string[]): Args {
+  const positional: string[] = [];
+  let patient = false;
+  let limit: number | undefined;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--patient') patient = true;
+    else if (arg === '--limit') {
+      const value = Number(argv[i + 1]);
+      // A NaN limit would disable the cap silently, which is the opposite of what was asked for.
+      if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError(`--limit needs a whole number, received ${String(argv[i + 1])}`);
+      }
+      limit = value;
+      i += 1;
+    } else if (arg !== undefined && !arg.startsWith('-')) positional.push(arg);
+  }
+
+  return { command: positional[0], file: positional[1], patient, limit };
+}
+
+async function open(io: CliIo, file: string) {
+  // Read whole rather than fileSource: a CLI invocation is one pass over one file, and holding
+  // it in memory removes any question of a descriptor outliving the process.
+  return openEdf(byteSource(await io.readFile(file)));
+}
+
+export async function runCli(args: Args, io: CliIo): Promise<number> {
+  const { command, file } = args;
+  if (command === undefined || command === 'help' || command === '--help') {
+    io.out(USAGE);
+    return command === undefined ? 2 : 0;
+  }
+  if (file === undefined) {
+    io.err(`edfcore ${command}: no file given\n\n${USAGE}`);
+    return 2;
+  }
+
+  switch (command) {
+    case 'header': {
+      const recording = await open(io, file);
+      io.out(`${formatHeader(recording.header, { includePatientId: args.patient })}\n`);
+      if (recording.header.diagnostics.length > 0) {
+        io.out(
+          `\n${formatDiagnostics(recording.header.diagnostics, { maxItems: args.limit ?? 20 })}\n`,
+        );
+      }
+      return 0;
+    }
+
+    case 'validate': {
+      const recording = await open(io, file);
+      const report = await validateRecording(recording, { scanSamples: true });
+      io.out(
+        `${formatValidationReport(report, { header: recording.header, maxItems: args.limit ?? 20 })}\n`,
+      );
+      // Exit 1 on failure so a CI job can gate on it without parsing the output.
+      return report.ok ? 0 : 1;
+    }
+
+    case 'events': {
+      const recording = await open(io, file);
+      const { annotations } = await readAnnotations(recording, {
+        start: 0,
+        count: recording.header.recordCount,
+      });
+      if (annotations.length === 0) {
+        io.out('no annotations\n');
+        return 0;
+      }
+      io.out(`${annotations.length} annotation(s)\n\n`);
+      for (const { text, count } of countAnnotationsByText(annotations)) {
+        io.out(`${String(count).padStart(8)}  ${text}\n`);
+      }
+      return 0;
+    }
+
+    case 'json': {
+      const recording = await open(io, file);
+      const { header } = recording;
+      io.out(
+        `${JSON.stringify(
+          {
+            variant: header.variant,
+            recordCount: header.recordCount,
+            recordDurationSeconds: header.recordDurationSeconds,
+            spanSeconds: recording.timeline.spanSeconds,
+            // Patient identification is opt-in here for the same reason it is in formatHeader:
+            // the obvious thing to do with this output is pipe it somewhere.
+            ...(args.patient ? { patient: header.patient.raw.trim() } : {}),
+            signals: header.signals.map((signal) => ({
+              index: signal.index,
+              label: signal.label,
+              kind: signal.kind,
+              samplesPerRecord: signal.samplesPerRecord,
+              sampleRateHz: signal.sampleRateHz,
+              physicalDimension: signal.physicalDimension,
+            })),
+            diagnostics: header.diagnostics.map((d) => ({ code: d.code, severity: d.severity })),
+          },
+          null,
+          2,
+        )}\n`,
+      );
+      return 0;
+    }
+
+    default:
+      io.err(`edfcore: unknown command ${JSON.stringify(command)}\n\n${USAGE}`);
+      return 2;
+  }
+}

package/src/cli.ts

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * `npx edfcore` — looking at a file without writing code.
+ *
+ * A separate entry point, never re-exported from the barrel, because it imports `node:fs` and
+ * `node:process`. The universal entry must stay free of Node built-ins, and a test asserts it.
+ *
+ * This file is only the wiring. The decisions live in `cli-run.ts`, so they can be tested without
+ * spawning a process against a build that may not exist yet.
+ *
+ * `main()` runs unconditionally rather than behind an `import.meta.url === process.argv[1]` guard.
+ * That guard is a known trap for a bin: `npx` runs the command through a symlink, so the two paths
+ * differ, the condition is false, and the CLI exits 0 having done nothing.
+ */
+
+// biome-ignore lint/suspicious/noTsIgnore: @ts-expect-error errors when unused — see node.ts.
+// @ts-ignore 'node:fs/promises' has no declarations under `types: []`; its shape is below.
+import * as nodeFsPromises from 'node:fs/promises';
+// biome-ignore lint/suspicious/noTsIgnore: as above.
+// @ts-ignore 'node:process' has no declarations under `types: []`; its shape is below.
+import * as nodeProcess from 'node:process';
+import { type CliIo, parseArgs, runCli } from './cli-run.js';
+import { isEdfError } from './errors.js';
+
+interface NodeFs {
+  readFile(path: string): Promise<Uint8Array>;
+}
+interface NodeProcess {
+  readonly argv: readonly string[];
+  exitCode: number | undefined;
+  readonly stdout: { write(text: string): unknown };
+  readonly stderr: { write(text: string): unknown };
+}
+
+const fs: NodeFs = nodeFsPromises as unknown as NodeFs;
+const proc: NodeProcess =
+  (nodeProcess as unknown as { default?: NodeProcess }).default ??
+  (nodeProcess as unknown as NodeProcess);
+
+const io: CliIo = {
+  readFile: (path) => fs.readFile(path),
+  out: (text) => {
+    proc.stdout.write(text);
+  },
+  err: (text) => {
+    proc.stderr.write(text);
+  },
+};
+
+async function main(): Promise<void> {
+  try {
+    proc.exitCode = await runCli(parseArgs(proc.argv.slice(2)), io);
+  } catch (error) {
+    // An EdfError already says what is wrong, where, and what to do next; a stack trace over the
+    // top of it would bury the one useful line.
+    const message = isEdfError(error) || error instanceof Error ? error.message : String(error);
+    proc.stderr.write(`edfcore: ${message}\n`);
+    proc.exitCode = 1;
+  }
+}
+
+// Not `await main()`: the package documents that no module in its graph uses top-level await,
+// which is what keeps require() safe on Node >= 22.12. main() catches everything, so it cannot
+// reject, and Node keeps the process alive until it settles.
+void main();

package/src/constants.ts

@@ -93,4 +93,4 @@ export const SIGNAL_FIELD_BLOCK_OFFSETS = {
 } as const;
 
 /** Published package version. Kept in sync with package.json by a test. */
-export const VERSION = '0.1.16';
+export const VERSION = '0.1.18';