disqus-wxr-middleware 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Semiologic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# disqus-wxr-middleware
+
+[![CI](https://github.com/graphcomment/disqus-wxr-middleware/actions/workflows/ci.yml/badge.svg)](https://github.com/graphcomment/disqus-wxr-middleware/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+> Exports a **Disqus** forum to a **WordPress WXR** file through the Disqus API.
+> A standalone command-line tool, run by the client with their own Disqus
+> credentials — **no dependency on any third-party infrastructure**.
+
+The generated WXR file is a standard WordPress export (WXR 1.2): it can be imported
+as-is into GraphComment through the WordPress import flow.
+
+## Table of contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Options](#options)
+- [Resuming after an interruption](#resuming-after-an-interruption)
+- [Limits & duration](#limits--duration)
+- [What to do with the WXR file](#what-to-do-with-the-wxr-file)
+- [Programmatic API](#programmatic-api)
+- [Security & data](#security--data)
+- [GDPR — read before exporting](#gdpr--read-before-exporting)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Requirements
+
+- **Node.js ≥ 18** (the tool uses native `fetch`, no external network dependency).
+- A **Disqus application** ([disqus.com/api/applications/](https://disqus.com/api/applications/))
+  owned by the **forum owner**, with the **email** permission granted
+  (read-only "Read" access is enough for the export). From it you need:
+  - the **secret key** (`api_secret`) — **required**;
+  - the **access token** — **required**;
+  - the *public key* (`api_key`) — **optional** (no call made by the tool uses it).
+
+> The **email** permission is what allows the API to return the commenters' real
+> addresses. Without it, the export still works but emails will be missing.
+> See [GDPR](#gdpr--read-before-exporting) before enabling this scope.
+
+## Installation
+
+No permanent installation is needed — the tool runs through `npx`:
+
+```bash
+npx disqus-wxr-middleware --help
+```
+
+For a project-local installation:
+
+```bash
+npm install disqus-wxr-middleware
+```
+
+## Usage
+
+```bash
+# Export a forum to a WXR file
+npx disqus-wxr-middleware --forum <shortname> --out ./export.wxr.xml \
+  --api-secret <SECRET> --access-token <TOKEN>
+
+# Credentials can also be passed through the environment
+DISQUS_API_SECRET=<SECRET> DISQUS_ACCESS_TOKEN=<TOKEN> \
+  npx disqus-wxr-middleware --forum <shortname> --out ./export.wxr.xml
+
+# Validate the configuration without running the export (no API call)
+npx disqus-wxr-middleware --forum <shortname> --api-secret <SECRET> --access-token <TOKEN> --dry-run
+```
+
+The `<shortname>` is your Disqus forum's short identifier (the one in the URL
+`https://<shortname>.disqus.com/`).
+
+## Options
+
+| Option | Description | Default |
+|---|---|---|
+| `--forum <shortname>` | Shortname of the Disqus forum to export (**required**). | — |
+| `--out <file.xml>` | Output WXR file. | `./disqus-export.wxr.xml` |
+| `--api-secret <secret>` | Disqus secret key (or env `DISQUS_API_SECRET`) — **required**. | — |
+| `--access-token <token>` | Disqus access token (or env `DISQUS_ACCESS_TOKEN`) — **required**. | — |
+| `--api-key <key>` | Disqus public key (or env `DISQUS_API_KEY`) — optional, unused. | — |
+| `--resume` | Resumes the export from the last checkpoint (see below). | off |
+| `--rate-budget <n>` | API request budget per hour (Disqus rate limit). | `1000` |
+| `--max-buffer <n>` | Maximum number of comments held in memory before flushing to disk. | `50000` |
+| `--dry-run` | Validates the configuration without running the export (no API call). | off |
+| `-v, --version` | Prints the version and exits. | — |
+| `--help` | Prints the full help. | — |
+
+`npx disqus-wxr-middleware --help` lists all up-to-date options.
+
+## Resuming after an interruption
+
+A large forum can take **hours, or even days** to retrieve (the Disqus API rate
+limit spreads the export over time — see [Limits & duration](#limits--duration)).
+An interruption (network, machine shutdown, temporarily exhausted Disqus quota)
+must not force you to start over.
+
+Re-run **the same command** with `--resume`: the export **picks up where it
+stopped**, without re-downloading or duplicating already-exported comments.
+
+```bash
+npx disqus-wxr-middleware --forum <shortname> --out ./export.wxr.xml \
+  --api-secret <SECRET> --access-token <TOKEN> --resume
+```
+
+## Limits & duration
+
+The channel that returns emails (the Disqus API) is also the one that **scales the
+worst**. The API is capped at **1000 requests per hour**, and each request returns
+at most **100 comments** — a maximum throughput of **~100,000 comments per hour**.
+
+| Forum size | Minimum export duration |
+|---|---|
+| 100,000 comments | ~1 h |
+| 1,000,000 comments | ~10 h |
+| 5,000,000 comments | ~2 days |
+| 10,000,000 comments | ~4 days |
+
+The tool handles the rate limit automatically (throttling, recovery after a `429`)
+and spreads requests across hourly windows. For a very large forum, combine with
+`--resume` to withstand interruptions.
+
+> **History goes back ~5 years.** The Disqus API caps how far back history can be
+> retrieved to roughly 5 years: older comments may not be exportable.
+
+## What to do with the WXR file
+
+The generated `.wxr.xml` file is a **standard WordPress export (WXR 1.2)**. Import
+it into GraphComment through the **WordPress import flow** (the same one used for a
+regular WordPress export): the Disqus threads and comments are recreated there,
+preserving the reply hierarchy.
+
+## Programmatic API
+
+Besides the CLI, the package exposes a programmatic entry point so it can be driven
+from another Node project (for example a hosted export service):
+
+```js
+// ESM-only package — a CommonJS project MUST use dynamic import (never `require()`).
+const { runExport, createWxrWriter, createLogger } = await import('disqus-wxr-middleware');
+
+const logger = createLogger();
+const stats = await runExport({
+  config: {
+    forum: 'my-forum',
+    out: 'export.wxr.xml',
+    apiSecret: process.env.DISQUS_API_SECRET,
+    accessToken: process.env.DISQUS_ACCESS_TOKEN,
+  },
+  logger,
+});
+// stats → { items, comments, orphanThreads, orphanComments, flushes, out }
+```
+
+Exported functions: `runExport`, `createDisqusClient`, `createWxrWriter`,
+`createLogger` (+ `mask`), and the checkpoint helpers (`checkpointPath`,
+`readCheckpoint`, `writeCheckpoint`, `deleteCheckpoint`, `CheckpointError`).
+
+- **`logger`** must expose six methods — `error`, `warn`, `info`, `debug`,
+  `progress`, `budget`. `createLogger()` returns a compliant instance; pass your own
+  only if it implements all six.
+- **`createWriter`** can be injected into `runExport` to stream the WXR somewhere
+  other than a local file (`createWxrWriter` accepts a `Writable` in place of a
+  path).
+
+## Security & data
+
+- Disqus credentials are **never** written to logs or error messages (systematic
+  masking).
+- The generated WXR file may contain **plain-text emails** (see
+  [GDPR](#gdpr--read-before-exporting)). The project's `.gitignore` already ignores
+  sensitive outputs (`*.wxr.xml`, `disqus-export*.xml`, `*.checkpoint.json`) —
+  **never commit an export or a checkpoint to a public repository**, and store them
+  on a medium you control.
+
+## GDPR — read before exporting
+
+> ⚠️ **The Disqus API returns commenters' emails in plain text to the forum
+> owner**, whereas Disqus's public export omits them and the moderation interface
+> only shows them obfuscated. Exporting these emails with this tool may therefore
+> **bypass an anonymization measure** that Disqus otherwise applies.
+
+This tool **observes** this API behavior; it takes **no position** on its
+lawfulness. As the **data controller** of your forum, it is your responsibility to
+verify:
+
+- the **legal basis** for retrieving and storing these emails;
+- the **information given to the commenters** whose data you retrieve;
+- the appropriate **retention period**.
+
+These obligations fall on the **client** running the tool, not on GraphComment. If
+you are migrating to GraphComment, refer to the legal guidance provided by your
+GraphComment contacts regarding email retention on the platform side.
+
+## Contributing
+
+Contributions are welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+[MIT](./LICENSE) © 2026 Semiologic

package/bin/disqus-wxr.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// CLI entry point of the Disqus → WXR middleware.
+// All the logic lives in src/cli.js (testable without spawning a process). Here: shebang +
+// delegation + catching unexpected errors (expected errors — missing credentials —
+// set process.exitCode themselves and never bubble up this far).
+import { run } from '../src/cli.js';
+
+run().catch((err) => {
+  // Safety net: never let a raw stack trace leak a secret.
+  process.stderr.write(`[error] Unexpected error: ${err?.message ?? err}\n`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "disqus-wxr-middleware",
+  "version": "0.3.0",
+  "description": "Exports a Disqus forum to a WordPress WXR file through the Disqus API (client-run tool, no WordPress required).",
+  "type": "module",
+  "bin": {
+    "disqus-wxr": "bin/disqus-wxr.js"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "disqus",
+    "wxr",
+    "wordpress",
+    "export",
+    "migration",
+    "comments"
+  ],
+  "license": "MIT",
+  "author": "Semiologic",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/graphcomment/disqus-wxr-middleware.git"
+  },
+  "bugs": {
+    "url": "https://github.com/graphcomment/disqus-wxr-middleware/issues"
+  },
+  "homepage": "https://github.com/graphcomment/disqus-wxr-middleware#readme",
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "sax": "^1.6.0"
+  }
+}

package/src/checkpoint.js

@@ -0,0 +1,182 @@
+// Persistence of the resume checkpoint (B2_01) + the injectable checkpoint STORE (B4_03, C11).
+//
+// TWO layers live here:
+//  1. The historical low-level FS helpers (`checkpointPath`/`readCheckpoint`/`writeCheckpoint`/
+//     `deleteCheckpoint`/`CheckpointError`) — a local JSON file next to `--out`. UNCHANGED,
+//     still exported (C10, tested by test/api.test.js). They back the default store below.
+//  2. `createFsCheckpointStore(outPath)` (B4_03) — the DEFAULT implementation of the injectable
+//     `checkpointStore` the resumable pipeline consumes. It owns BOTH the checkpoint I/O AND the
+//     physical WXR stream lifecycle (fresh open / resume rewind / durable-offset measurement), so
+//     `runResumableExport` no longer contains any `fs.*` of its own. A server (api/, B5_02) injects
+//     its OWN store (checkpoint on the Mongo job, stream to GridFS) implementing the same shape.
+//
+// The local JSON checkpoint materializes the durable state of the export so `--resume` picks up
+// without starting over:
+//   { forum, cursor, exhausted, comments_written, bytes_written, threads_resolved,
+//     started_at, last_page_at }
+// - `cursor`       : Disqus boundary cursor of the LAST fully flushed page
+//                    (pagination resume point); null = beginning / no more pages.
+// - `exhausted`    : true = Disqus stream exhausted (no more pages) → distinguishes
+//                    "cursor null = end" from "cursor null = beginning" on resume.
+// - `bytes_written`: DURABLE byte offset of the WXR file = truncation target on resume.
+//                    Invariant: bytes [0, bytes_written) contain exactly the comments
+//                    of the pages strictly before `cursor`. (FS store only — an injected store
+//                    may treat this field as an opaque durable position of its own.)
+//
+// ⚠ NO Disqus credential (`api_secret`/`access_token`/`api_key`) EVER appears in the
+// checkpoint — the file stays on the client's machine. The shape is closed (the pipeline
+// only writes the 8 keys above) and a test verifies it explicitly. An injected store MUST
+// keep the same opacity: the checkpoint object it persists is the pipeline's, never enriched
+// with a token.
+//
+// ATOMIC write (tmp + fsync + rename): a crash during the write can never leave a
+// half-written checkpoint — the rename only publishes the complete file.
+
+import * as fs from 'node:fs';
+import { createWriteStream } from 'node:fs';
+
+// Canonical checkpoint path derived from the WXR output file.
+export function checkpointPath(out) {
+  return `${out}.checkpoint.json`;
+}
+
+// Error: checkpoint present but unreadable (corrupted JSON / I/O). Distinct from "absent"
+// (readCheckpoint returns null when the file simply does not exist). Carries an exitCode
+// for the entry point. Never contains a credential.
+export class CheckpointError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CheckpointError';
+    this.exitCode = 1;
+  }
+}
+
+// Reads the checkpoint. Returns the parsed object, or `null` if the file does not exist
+// (normal case of a first run). Throws `CheckpointError` if the file exists but is
+// unreadable or is not valid JSON (the pipeline turns that into a clear message).
+export function readCheckpoint(path) {
+  let raw;
+  try {
+    raw = fs.readFileSync(path, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw new CheckpointError(`unreadable checkpoint (${path}): ${err.message}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new CheckpointError(`corrupted checkpoint (${path}): ${err.message}`);
+  }
+}
+
+// Writes the checkpoint ATOMICALLY: serializes into `<path>.tmp`, fsync, then rename
+// onto `path` (atomic within the same filesystem). The current checkpoint is therefore
+// always either the old complete one or the new complete one — never a mix.
+export function writeCheckpoint(path, checkpoint) {
+  const tmp = `${path}.tmp`;
+  const fd = fs.openSync(tmp, 'w');
+  try {
+    fs.writeFileSync(fd, JSON.stringify(checkpoint, null, 2));
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, path);
+}
+
+// Deletes the checkpoint if it exists: successful end of run (nothing left to resume) OR
+// purge of a stale checkpoint at the start of a fresh run (no `--resume`). ENOENT ignored.
+export function deleteCheckpoint(path) {
+  try {
+    fs.unlinkSync(path);
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+}
+
+// ─── Injectable checkpoint STORE (B4_03, contract C11) ──────────────────────────────────────
+//
+// createFsCheckpointStore(outPath) → the DEFAULT store the resumable pipeline uses. It is the
+// existing FS behavior, moved BEHIND an interface — byte-for-byte identical (test/resume.test.js
+// stays green). A consumer injects a store of the SAME SHAPE to resume against a non-seekable
+// target (GridFS) and a checkpoint persisted off the filesystem.
+//
+// Store contract (all async — the injected implementations do real I/O):
+//   read()               → Promise<checkpoint|null>   persisted checkpoint, or null if none.
+//                          Throws (CheckpointError-like) if present but unreadable.
+//   write(checkpoint)    → Promise<void>              persists atomically.
+//   delete()             → Promise<void>              removes the checkpoint (idempotent).
+//   open()               → Promise<Writable>          FRESH run: a Writable to write the WXR
+//                          from the start (FS: truncate/create in 'w' mode).
+//   rewindTo(checkpoint) → Promise<Writable>          RESUME: rewinds the target to the durable
+//                          boundary of `checkpoint` and returns a Writable positioned to append
+//                          from there (FS: truncate the file to `bytes_written`, reopen in 'a').
+//                          Throws if the target is inconsistent with the checkpoint (missing /
+//                          shorter than the durable offset) — never resumes onto a bad target.
+//   durableOffset(stream)→ Promise<number>            the durable position of everything written
+//                          to `stream` so far (FS: write-barrier + fsync + fstat on the fd). The
+//                          pipeline stores this as the checkpoint's `bytes_written`. An injected
+//                          store returns whatever opaque durable position it can guarantee.
+//
+// The pipeline treats `bytes_written`/the offset as OPAQUE: it reads it from durableOffset() and
+// hands it back via the same store's rewindTo() — it never interprets it as bytes itself.
+export function createFsCheckpointStore(outPath) {
+  const path = checkpointPath(outPath);
+
+  return {
+    async read() {
+      return readCheckpoint(path); // throws CheckpointError if corrupted; null if absent
+    },
+
+    async write(checkpoint) {
+      writeCheckpoint(path, checkpoint);
+    },
+
+    async delete() {
+      deleteCheckpoint(path);
+    },
+
+    // Fresh run: (re)create the WXR file empty and return an append/truncate write stream.
+    // 'w' truncates any pre-existing file — matching the previous fresh-run behavior.
+    async open() {
+      return createWriteStream(outPath, { flags: 'w', encoding: 'utf8' });
+    },
+
+    // Resume: validate the file against the checkpoint, truncate it to the durable offset
+    // (strips the footer + any partial post-checkpoint write), then reopen in append mode.
+    // This is exactly the sequence the pipeline used to run inline (fs.statSync + fs.truncateSync
+    // + createWriteStream {flags:'a'}), moved here unchanged so resume.test.js keeps passing.
+    async rewindTo(checkpoint) {
+      let size;
+      try {
+        size = fs.statSync(outPath).size;
+      } catch {
+        throw new Error(
+          `Checkpoint present but output file ${outPath} not found — cannot resume. ` +
+            `Delete the checkpoint to start over.`,
+        );
+      }
+      if (size < checkpoint.bytes_written) {
+        throw new Error(
+          `Output file ${outPath} (${size} B) shorter than the checkpoint ` +
+            `(${checkpoint.bytes_written} B) — inconsistent state. Delete the checkpoint to start over.`,
+        );
+      }
+      fs.truncateSync(outPath, checkpoint.bytes_written); // strips footer + partial post-checkpoint data
+      return createWriteStream(outPath, { flags: 'a', encoding: 'utf8' });
+    },
+
+    // DURABLE byte offset of the file, read AFTER everything the writer wrote has actually
+    // reached the fd: write barrier (callback of an empty write → all prior writes, FIFO
+    // ordered, are processed), then fsync (OS → disk), then fstat. Without this barrier,
+    // the offset could undercount (chunks still in Node's buffer) → on resume, a too-short
+    // truncation would lose the tail of an already-written page.
+    async durableOffset(stream) {
+      await new Promise((resolve, reject) => {
+        stream.write(Buffer.alloc(0), (err) => (err ? reject(err) : resolve()));
+      });
+      fs.fsyncSync(stream.fd);
+      return fs.fstatSync(stream.fd).size;
+    },
+  };
+}

package/src/cli.js

@@ -0,0 +1,110 @@
+// CLI of the Disqus → WXR middleware.
+// Responsibility (B0_01): declare the options, handle --help/--version, resolve and
+// validate the configuration (credentials included), then stop. No API call and no
+// WXR generation here — B1_01→B1_03 plug onto the validated config + the logger.
+import { createRequire } from 'node:module';
+import { Command } from 'commander';
+import { resolveConfig, MissingCredentialsError } from './config.js';
+import { createLogger, mask } from './logger.js';
+import { runExport, DEFAULT_MAX_BUFFER } from './pipeline.js';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+
+// Builds the commander program. Exported for tests / introspection.
+export function buildProgram() {
+  const program = new Command();
+  program
+    .name('disqus-wxr')
+    .description(
+      'Exports a Disqus forum to a WordPress WXR file through the Disqus API.\n' +
+        'Standalone tool, run by the client with their own Disqus credentials (outside WordPress).',
+    )
+    // --version and --help are handled natively by commander and short-circuit
+    // any validation (including the required --forum), exiting with code 0.
+    .version(pkg.version, '-v, --version', 'print the version and exit')
+    .requiredOption('--forum <shortname>', 'shortname of the Disqus forum to export (required)')
+    .option('--out <file.xml>', 'output WXR file', './disqus-export.wxr.xml')
+    .option(
+      '--api-key <key>',
+      'Disqus public key (or env DISQUS_API_KEY) — optional: no call uses it',
+    )
+    .option('--api-secret <secret>', 'Disqus secret key (or env DISQUS_API_SECRET) — required')
+    .option('--access-token <token>', 'Disqus access token (or env DISQUS_ACCESS_TOKEN) — required')
+    .option('--resume', 'resume from the last checkpoint', false)
+    .option(
+      '--rate-budget <n>',
+      'API request budget per hour (Disqus rate limit)',
+      '1000',
+    )
+    .option(
+      '--max-buffer <n>',
+      'maximum number of buffered comments before flushing (per-thread grouping over the global stream)',
+      String(DEFAULT_MAX_BUFFER),
+    )
+    .option('--dry-run', 'validate the configuration without running the export (no API call)', false);
+  return program;
+}
+
+// Logical entry point. Returns the validated config (reused by B1+) or null
+// if validation failed (process.exitCode is then set to 1).
+export async function run(argv = process.argv) {
+  const program = buildProgram();
+  program.parse(argv); // commander handles --help / --version here (exit 0)
+
+  const logger = createLogger({ level: process.env.DISQUS_WXR_LOG_LEVEL || 'info' });
+  const opts = program.opts();
+
+  let config;
+  try {
+    config = resolveConfig(opts, process.env);
+  } catch (err) {
+    if (err instanceof MissingCredentialsError) {
+      logger.error(err.message);
+      process.exitCode = err.exitCode; // 1
+      return null;
+    }
+    throw err;
+  }
+
+  // Config ready.
+  logger.info(`Configuration validated for forum "${config.forum}".`);
+  // Credential details are only emitted at debug level, and ALWAYS masked.
+  logger.debug(
+    `Credentials — secret ${mask(config.apiSecret)}, token ${mask(config.accessToken)}, ` +
+      `api-key ${mask(config.apiKey)}.`,
+  );
+  logger.info(
+    `WXR output: ${config.out} · API budget: ${config.rateBudget} req/h · ` +
+      `resume: ${config.resume ? 'yes' : 'no'}.`,
+  );
+
+  // --max-buffer: maximum number of buffered comments before flushing (per-thread grouping
+  // over the global ascending stream — local decision "bounded configurable" 2026-06-30).
+  // Strictly positive integer, otherwise default (same validation as --rate-budget). Read
+  // HERE, not in resolveConfig (whose output contract for B1_01 is frozen/tested), and
+  // passed directly to runExport.
+  const rawMaxBuffer = String(opts.maxBuffer ?? '').trim();
+  const maxBuffer =
+    /^\d+$/.test(rawMaxBuffer) && Number.parseInt(rawMaxBuffer, 10) > 0
+      ? Number.parseInt(rawMaxBuffer, 10)
+      : DEFAULT_MAX_BUFFER;
+
+  // --dry-run: validate the config without running the export (check the credentials
+  // without spending API budget). Short-circuits BEFORE any network call.
+  if (opts.dryRun) {
+    logger.info(`--dry-run mode: configuration OK (max buffer ${maxBuffer}), export not started.`);
+    return config;
+  }
+
+  // Actual wiring (B1_03): Disqus export → streaming WXR. A business error (Disqus
+  // auth/quota, file I/O) is turned into a clear message + exit 1 (never a raw stack
+  // trace that could leak a secret; the safety net in bin/ then sees nothing bubble up).
+  try {
+    return await runExport({ config, logger, maxBuffer });
+  } catch (err) {
+    logger.error(`Export failed: ${err?.message ?? err}`);
+    process.exitCode = err?.exitCode ?? 1;
+    return null;
+  }
+}

package/src/config.js

@@ -0,0 +1,69 @@
+// Resolution + validation of the middleware configuration.
+// Credential sources: CLI flags ∪ environment variables, flags taking precedence.
+// REQUIRED set = api_secret + access_token (D2, decided 2026-06-30): the middleware's
+// single API call (`posts/list.json?forum=…&api_secret=…&access_token=…`, audit §5.A)
+// does NOT use the public key — it is accepted but never required.
+
+// Business error: one or more required credentials are missing. Carries its own
+// exit code so the entry point does not have to guess it. The message NEVER contains
+// a credential value (only the name of what is missing).
+export class MissingCredentialsError extends Error {
+  constructor(missing) {
+    super(
+      `Missing Disqus credentials: ${missing.join(', ')}.\n` +
+        'Create an app at https://disqus.com/api/applications/ and grant it the "email" ' +
+        'permission (read-only "Read" access is enough for the export), then provide the ' +
+        'secret key and the access token through --api-secret / --access-token or the ' +
+        'DISQUS_API_SECRET / DISQUS_ACCESS_TOKEN environment variables.',
+    );
+    this.name = 'MissingCredentialsError';
+    this.exitCode = 1;
+    this.missing = missing;
+  }
+}
+
+// Returns the first non-empty candidate (flag then env), TRIMMED, otherwise undefined.
+// - treats `DISQUS_API_SECRET=""` or `"   "` as absent (emptied-env trap in tests/CI);
+// - trims the retained value (a credential pasted with stray whitespace would
+//   otherwise break the Disqus URL in B1 → 401).
+function firstNonEmpty(value, fallback) {
+  for (const candidate of [value, fallback]) {
+    if (candidate !== undefined && candidate !== null && String(candidate).trim() !== '') {
+      return String(candidate).trim();
+    }
+  }
+  return undefined;
+}
+
+// Resolves the config from the commander options and the environment.
+// Throws MissingCredentialsError if the required set is not complete.
+export function resolveConfig(opts, env = process.env) {
+  const apiKey = firstNonEmpty(opts.apiKey, env.DISQUS_API_KEY);
+  const apiSecret = firstNonEmpty(opts.apiSecret, env.DISQUS_API_SECRET);
+  const accessToken = firstNonEmpty(opts.accessToken, env.DISQUS_ACCESS_TOKEN);
+
+  const missing = [];
+  if (!apiSecret) missing.push('--api-secret (or DISQUS_API_SECRET)');
+  if (!accessToken) missing.push('--access-token (or DISQUS_ACCESS_TOKEN)');
+  if (missing.length > 0) throw new MissingCredentialsError(missing);
+
+  // --rate-budget: STRICTLY positive integer (digits only), otherwise fall back to the
+  // default 1000 (measured Disqus rate limit, audit §1.B). Strict validation rather than
+  // `parseInt`, which would silently truncate `2.7`→2 (a typo would throttle the export
+  // in B1). The actual wiring — and the user warning — arrive in B1_01.
+  const rawBudget = String(opts.rateBudget ?? '').trim();
+  const rateBudget =
+    /^\d+$/.test(rawBudget) && Number.parseInt(rawBudget, 10) > 0
+      ? Number.parseInt(rawBudget, 10)
+      : 1000;
+
+  return {
+    forum: opts.forum,
+    out: opts.out,
+    apiKey: apiKey ?? null,
+    apiSecret,
+    accessToken,
+    resume: Boolean(opts.resume),
+    rateBudget,
+  };
+}