@compdict/cli

The compdict command-line tool and programmatic API. It checks live RFC 9842 origins, creates dcb and dcz artifacts, inspects streams, evaluates match patterns, and runs a local test origin.

Requires Node.js 22 or later.

Most command-line users should install the unscoped compdict package:

npx compdict validate https://example.com/static/app.v2.js

Install @compdict/cli directly when you want to call commands from Node.js:

npm install @compdict/cli

import { renderJson, runValidate } from '@compdict/cli';

const { report, exitCode } = await runValidate({
  url: 'https://example.com/app.v2.js',
  dictionaryUrl: 'https://example.com/app.v1.js',
  encodings: ['dcb', 'dcz'],
  protocols: ['http/1.1', 'h2'],
  repeat: 1,
  json: true,
  allowWarnings: false,
  quiet: false,
  color: 'never',
  verbose: false,
});

process.stdout.write(renderJson(report));
process.exitCode = exitCode;

Programmatic commands return { report, exitCode }; they do not write the report to standard output. The exported command functions are:

When ValidateOptions.dest is omitted, runValidate() first uses a supplied dictionary's first recognised matching match-dest. It otherwise infers script or style from the resource pathname's .js or .css extension and defaults to document. Query parameters and fragments are ignored.

Identical findings from the HTTP/1.1 and HTTP/2 test matrices are collapsed into one report entry. finding.data.testCases lists the protocols where the finding occurred.

The CLI's default protocol mode tries h2, then falls back to HTTP/1.1 if h2 cannot complete. Programmatic callers can request the same behaviour with protocols: ['h2', 'http/1.1'] and protocolFallback: true. Savings are measured on the first successful protocol using clean identity and gzip, br, zstd requests plus isolated dcb and dcz requests.

runValidate() reports dictionary freshness and cacheability problems but still forces otherwise usable dictionary bytes through the diagnostic request matrix. Malformed, mismatched, unsafe, mutated or unsupported dictionaries remain blocked.

The synthetic SEC_FETCH_CROSS_ORIGIN probe is informational. Set pageUrl to an origin different from the resource to test a declared cross-origin deployment and retain warning severity. The probe sends that page origin in Origin and honours wildcard or exact Access-Control-Allow-Origin.

• runValidate(options)
• runEncode(options)
• runInspect(options)
• runMatch(options)
• runServe(options)

runEncode() accepts hashSuffix: 'base64url' or hashSuffix: 'hex' to append the dictionary SHA-256 to the complete output path.

runServe() resolves after its listeners bind and returns their origins plus a close() method:

import { runServe } from '@compdict/cli';

const server = await runServe({
  port: 0,
  misconfigure: ['none'],
  tls: false,
  json: false,
  allowWarnings: false,
  quiet: false,
  color: 'never',
  verbose: false,
});

try {
  console.log(server.origins.http1, server.origins.h2c);
} finally {
  await server.close();
}

The package also exports raw transports, browser-like request header builders, human and JSON renderers, verdict helpers, and all command option types. The report schemas are exported as @compdict/cli/schema/report-1.0.0.json and @compdict/cli/schema/report-1.1.0.json.

The transport uses node:http, node:https, and node:http2 rather than fetch. It preserves raw, content-coded response bodies and gives the caller exact control over negotiation fields. HTTPS requests pin ALPN to the selected protocol. Cleartext requests select HTTP/1.1 or h2c directly.

• CLI reference
• JSON report format
• Troubleshooting
• Full project README

Apache-2.0.