@msout/microsoft-onenote-exporter 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-01
+
+The first release. It adds a CLI over three existing packages and changes none of
+their behaviour.
+
+### Added
+
+- **`microsoft-onenote-exporter <login|check|logout|list|export>`.** One binary over
+  `@msout/microsoft-webauth`, `@msout/microsoft-onenote-list-notebooks` and
+  `@msout/microsoft-onenote-export-notebook`, all three of which remain
+  separately installable and separately tested. A typical first run is `login`,
+  then `list`, then `export --notebook "Work"`.
+- **A single Playwright, and therefore a single Chromium.** The three step
+  packages each declared `playwright: ^1.58.1` behind their own lockfile, so npm
+  resolved them independently — 1.61.0 in one, 1.61.1 in another — and each
+  wanted a different Chromium revision. A machine with all three checkouts out
+  held four revisions and 3.2 GB of browser. They are now pinned to exact versions
+  with an `overrides` block forcing one `playwright` and `playwright-core` across
+  the tree, and `test/wiring.test.js` fails if that ever stops being true.
+- **One log per run.** Each package resolved its own log directory at load time,
+  so a pipeline produced three `app.log` files in three directories. The
+  environment variable those packages read is set before any of them is loaded,
+  so all four loggers — this CLI's and the three steps' — write one file.
+- **One Docker image** for all five commands, with one Chromium. It replaces
+  three images that each carried their own browser; the list image also installed
+  a distribution `chromium` from apt that nothing used. `start-container.sh`
+  replaces the positional `<session-guid> <notebook-name>` interface with
+  subcommands, waits for the run, and explains exit code 3 as a partial export
+  rather than a failure.
+- **Exit codes that mean something.** 0 success, 1 failure, 2 bad arguments, and
+  3 for an export that finished while missing pages, sections or groups. The
+  third is passed through from the export package's own `exitCodeForStats`, which
+  is asked rather than reimplemented, so the two CLIs cannot disagree.
+
+### Notes
+
+- `login` cannot run headless without `--email` and `--password`, and the
+  container refuses `login` outright rather than opening a browser nobody can see.
+  Interactive sign-in happens on the host.
+- `all`, which chains login → list → export in one invocation, is deliberately
+  not in this release. None of the three packages accepts an injected browser, so
+  it would still be three Chromium launches behind one command — and the change
+  needed to make it one launch reaches into the most delicate file in the set.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ms-OneNote-Exporter
+
+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/NOTICE.md

@@ -0,0 +1,38 @@
+# Notices
+
+This project is distributed under the MIT licence. It is an umbrella: it contains
+no copy of the work below, and depends on it at runtime.
+
+## Bundled work
+
+None. The three packages in the table below are installed from npm as ordinary
+dependencies. None of their source is vendored into this repository or into the
+Docker image built from it.
+
+## Dependencies
+
+| Package | Version | Licence | Role |
+|---|---|---|---|
+| `@msout/microsoft-webauth` | 0.1.8 | MIT | `login`, `check`, `logout` |
+| `@msout/microsoft-onenote-list-notebooks` | 0.0.6 | MIT | `list` |
+| `@msout/microsoft-onenote-export-notebook` | 0.3.7 | MIT | `export` |
+
+All three are by the same authors and under the same MIT licence as this project.
+They are developed in sibling repositories:
+
+- <https://github.com/Ms-OneNote-Exporter/microsoft-webauth>
+- <https://github.com/Ms-OneNote-Exporter/microsoft-onenote-list-notebooks>
+- <https://github.com/Ms-OneNote-Exporter/microsoft-onenote-export-notebook>
+
+One file *is* duplicated on purpose: `logPaths.js` exists in all three packages
+with only the package name changed. They are separately published and cannot share
+source, and keeping the copies byte-identical is what stops the three from
+disagreeing about where an installed copy writes its logs. It says so at the top
+of each file, and it should collapse to one module if the packages are ever
+merged.
+
+## Trademarks
+
+Microsoft, OneNote, Outlook and Microsoft 365 are trademarks of Microsoft
+Corporation. This project is not affiliated with or endorsed by Microsoft. It
+automates a browser session against services the user already has an account for.

package/README.md

@@ -0,0 +1,199 @@
+# microsoft-onenote-exporter
+
+One command for the whole Microsoft OneNote pipeline: sign in, list the notebooks
+on the account, export one to Obsidian-flavoured Markdown.
+
+This is an umbrella over three packages that remain separately installable and
+separately tested:
+
+| Step | Package |
+|---|---|
+| `login`, `check`, `logout` | [`@msout/microsoft-webauth`](https://github.com/Ms-OneNote-Exporter/microsoft-webauth) |
+| `list` | [`@msout/microsoft-onenote-list-notebooks`](https://github.com/Ms-OneNote-Exporter/microsoft-onenote-list-notebooks) |
+| `export` | [`@msout/microsoft-onenote-export-notebook`](https://github.com/Ms-OneNote-Exporter/microsoft-onenote-export-notebook) |
+
+Each one works on its own, and you can still install just the one you need. What
+this adds is a single binary that can do all three, one Playwright install, one
+Docker image, and one log per run.
+
+## Why it exists
+
+The three packages each declared `playwright: ^1.58.1` behind their own
+lockfile, so npm resolved them independently — 1.61.0 in one, 1.61.1 in another.
+Each resolved version wants a different Chromium revision, so a machine with all
+three checkouts out downloads several browser builds into the shared
+`~/Library/Caches/ms-playwright` cache. On the machine this was built on, that
+cache held four Chromium revisions and weighed 3.2 GB.
+
+It also let a single run produce three `app.log` files in three directories,
+because each package resolved its own log path at load time.
+
+Both problems are fixed at the root rather than papered over:
+
+- the three dependencies are pinned to **exact** versions, and `overrides` forces
+  a single `playwright` / `playwright-core` across the whole tree. A caret range
+  always takes the newest match, so it is the wrong tool here;
+- `ONENOTE_EXPORT_LOG_DIR` is set before any step package is loaded, so all four
+  loggers write one `app.log`.
+
+There is a test for each: `test/wiring.test.js` fails if more than one Playwright
+is installed, or if the pins drift back to a range.
+
+## Install
+
+```sh
+npm install -g @msout/microsoft-onenote-exporter
+npx playwright install chromium
+```
+
+The Chromium download is separate from `npm install` and is required — without it
+every command that opens a browser fails.
+
+Two command names are installed, pointing at the same binary:
+
+```sh
+microsoft-onenote-exporter login    # matches the package and repository name
+ms-onenote-exporter login           # shorter, for typing
+```
+
+Everything below uses the long one.
+
+## Use
+
+```sh
+microsoft-onenote-exporter login                              # opens a browser; sign in there
+microsoft-onenote-exporter list                               # what is on the account
+microsoft-onenote-exporter export --notebook "Work"           # export one
+```
+
+That is the whole pipeline. The session written by `login` is picked up by
+`list` and `export` automatically.
+
+### Commands
+
+| Command | What it does |
+|---|---|
+| `login` | Signs in and saves the session. Without `--email`/`--password` the browser opens and you sign in yourself — an interactive login cannot run headless. |
+| `check` | Reports whether the saved session is still valid. A dead session is deleted, so the next command needs a fresh `login`. |
+| `logout` | Deletes the saved session and its metadata. |
+| `list` | Lists the notebooks on the account. An empty result is a success, not an error. |
+| `export` | Exports one notebook to Markdown. |
+
+### Options
+
+Every command accepts `--auth-file`, `--notheadless`, `--dodump`, `--verbose` and
+`--quiet`.
+
+| Command | Additional options |
+|---|---|
+| `login` | `--email`, `--password`, `--against onenote\|outlook`, `--screenshot` |
+| `check` | `--against onenote\|outlook` |
+| `export` | `--notebook <name>`, `--notebook-link <url>`, `--output-dir <path>`, `--nopassasked`, `--non-interactive` |
+
+`--screenshot` only means something together with `--dodump`, so asking for one
+turns the other on and says so.
+
+### Unattended use
+
+`--non-interactive` is for containers and CI. It requires `--notebook` or
+`--notebook-link`, and implies `--nopassasked`, so the run cannot stop at a prompt
+nobody is there to answer:
+
+```sh
+microsoft-onenote-exporter export --notebook "Work" --non-interactive --output-dir ./out
+```
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success. |
+| 1 | The command failed — unusable auth file, dead run. |
+| 2 | The arguments were wrong. |
+| 3 | The export finished, but pages, sections or groups are missing. |
+
+Three is deliberately not an error: the notes that were written are complete and
+name any asset they could not download, so the output is worth keeping and
+re-running is worth doing. It comes from
+`@msout/microsoft-onenote-export-notebook`'s own rule, which this CLI asks for
+rather than reimplementing.
+
+## Logs
+
+Every step of a run — this CLI's messages and all three packages' — goes to one
+`logs/app.log` under the working directory. Override it with
+`ONENOTE_EXPORT_LOG_DIR`, or use `--dodump` to also write the HTML of each page.
+
+The directory and the log file are created owner-only. Dumps hold the
+authenticated DOM of a real account: cookies, tenant hostnames, note titles.
+
+## Docker
+
+```sh
+docker build -t microsoft-onenote-exporter .
+```
+
+One image, one Chromium, serving all five commands. The auth file is read from
+`/data/output/auth.json` unless you pass `--auth-file`.
+
+```sh
+docker run --rm --init --shm-size=1g \
+  -v "$PWD/out:/data/output" \
+  microsoft-onenote-exporter export --notebook "Work" --non-interactive
+```
+
+Or use the wrapper, which waits for the run and translates the exit code:
+
+```sh
+./start-container.sh --notebook "Work" --output-dir ./out
+```
+
+`--shm-size=1g` is required: Chromium crashes on memory-heavy pages with Docker's
+default 64 MB of shared memory. `--init` reaps Chromium's child processes.
+
+`login` is refused inside the container — without credentials the browser has to
+be shown, and there is nobody there to show it to. Log in on the host first and
+mount the resulting file.
+
+## Development
+
+The three step packages are pinned to versions that must exist on npm. To work
+against local checkouts before they are published:
+
+```sh
+npm run use:local      # pack the sibling repos and install those
+npm test
+npm run use:published  # go back to the registry copies
+```
+
+`use:local` expects the three repositories one directory up, and leaves
+`package.json` pinning published versions — only `node_modules` differs, so a
+`file:` spec can never be committed.
+
+```sh
+npm test        # no browser and no account needed
+npm run lint
+```
+
+### Release order
+
+There is an ordering constraint, and it is the one thing that cannot be worked
+around: **this package cannot have a committed `package-lock.json` until the
+three step packages are on npm.** Their pinned versions do not resolve before
+then, and `use:local` produces a lockfile full of `file:.local-tarballs/…`
+entries that works only on the machine that made it — `.local-tarballs/` is
+gitignored, so CI and the Docker image would both fail to install from it.
+
+So the first release goes:
+
+1. Publish the three step packages from their own repositories.
+2. Here: `rm -rf node_modules .local-tarballs && npm install`.
+3. Commit the generated `package-lock.json`. After this, `npm ci` works and CI
+   and the Dockerfile function.
+
+`test/lockfile.test.js` fails with these instructions until step 3 happens, so the
+gap is visible rather than discovered during a build.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE) and [NOTICE.md](NOTICE.md).

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@msout/microsoft-onenote-exporter",
+  "version": "0.1.0",
+  "description": "Log in, list and export Microsoft OneNote notebooks as Obsidian Markdown - one CLI over @msout/microsoft-webauth, @msout/microsoft-onenote-list-notebooks and @msout/microsoft-onenote-export-notebook.",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./cli": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "ms-onenote-exporter": "src/index.js",
+    "microsoft-onenote-exporter": "src/index.js"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE",
+    "NOTICE.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "lint": "eslint .",
+    "use:local": "sh scripts/use-local-packages.sh",
+    "use:published": "sh scripts/use-published-packages.sh"
+  },
+  "keywords": [
+    "microsoft",
+    "onenote",
+    "playwright",
+    "export",
+    "obsidian",
+    "markdown",
+    "cli"
+  ],
+  "author": "msout@tuta.io",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ms-OneNote-Exporter/microsoft-onenote-exporter.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Ms-OneNote-Exporter/microsoft-onenote-exporter/issues"
+  },
+  "homepage": "https://github.com/Ms-OneNote-Exporter/microsoft-onenote-exporter#readme",
+  "dependencies": {
+    "@msout/microsoft-onenote-export-notebook": "0.3.7",
+    "@msout/microsoft-onenote-list-notebooks": "0.0.6",
+    "@msout/microsoft-webauth": "0.1.8",
+    "chalk": "^4.1.2",
+    "commander": "^14.0.3",
+    "fs-extra": "^11.3.3",
+    "playwright": "1.63.0"
+  },
+  "overrides": {
+    "playwright": "1.63.0",
+    "playwright-core": "1.63.0"
+  },
+  "devDependencies": {
+    "eslint": "^9.39.5",
+    "jest": "^29.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/config.js

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview Configuration for the umbrella CLI.
+ * @copyright 2026 msout
+ */
+const os = require('os');
+const path = require('path');
+
+/**
+ * Where the three step packages should write their logs.
+ *
+ * Each of them is a separately installable package with its own logger, and each
+ * one is a singleton constructed the moment it is required. This function has to
+ * run before any of them is loaded, which is why src/index.js calls it at the
+ * very top rather than passing a path around: by the time a step is invoked the
+ * log directories have already been decided.
+ *
+ * The default is <cwd>/logs rather than a per-package directory because all three
+ * steps write `app.log` into the same directory, so a pipeline run produces one
+ * log with the steps in order rather than three logs in three places.
+ */
+function resolveLogDir() {
+    const override = process.env.ONENOTE_EXPORT_LOG_DIR;
+    if (override && override.trim()) {
+        return path.resolve(override.trim());
+    }
+    return path.resolve(process.cwd(), 'logs');
+}
+
+/**
+ * Points the three step packages at this process's log directory.
+ *
+ * Setting the environment variable rather than passing an option is not a
+ * shortcut, it is the only channel those packages have: each resolves its log
+ * directory at require time from ONENOTE_EXPORT_LOG_DIR, and none of them accept
+ * a path as an argument. Idempotent, and it never overrides a value the caller
+ * already set - a container or a CI step that mounts its own log volume keeps it.
+ *
+ * @param {string} [logDir] - Directory to use; resolved from the environment when omitted
+ * @returns {string} The absolute directory all four loggers will write to
+ */
+function shareLogDir(logDir = resolveLogDir()) {
+    process.env.ONENOTE_EXPORT_LOG_DIR = logDir;
+    return logDir;
+}
+
+/** The saved session, shared by every step. */
+function defaultAuthFile() {
+    const home = os.homedir();
+    return path.join(home, '.microsoft-webauth', 'auth-file.json');
+}
+
+/**
+ * Where to authenticate against.
+ *
+ * Both URLs are the ones the step packages pin. ONENOTE_URL is the pre-rebrand
+ * /notebooks path on purpose: Microsoft 365 Copilot moved the app to
+ * /copilotnotebooks but /notebooks still redirects there, so a login entered at
+ * the old path is detected as authenticated a few seconds later. Re-pinning it
+ * here would trade a working alias for a path that can move again - see
+ * ONENOTE_URL in @msout/microsoft-webauth.
+ */
+const TARGETS = {
+    onenote: 'https://onenote.cloud.microsoft/notebooks',
+    outlook: 'https://outlook.cloud.microsoft/mail/',
+};
+
+/** Exit codes, so a caller can tell the outcomes apart without parsing output. */
+const EXIT = {
+    ok: 0,
+    /** The command itself failed: bad arguments, unusable auth file, a dead run. */
+    failed: 1,
+    /** Unattended use asked for without a way to choose a notebook. */
+    usage: 2,
+    /** Finished, but pages, sections or groups are missing. Passed through from
+     *  @msout/microsoft-onenote-export-notebook, which distinguishes this from a
+     *  total failure because partial output is still worth keeping. */
+    partial: 3,
+};
+
+module.exports = { resolveLogDir, shareLogDir, defaultAuthFile, TARGETS, EXIT };

package/src/index.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview CLI over the three OneNote exporter steps.
+ * @copyright 2026 msout
+ *
+ * One binary, three steps. The packages it drives remain separately installable
+ * and separately tested; what this adds is a single command that can do all
+ * three, one Playwright install, one Docker image, and one log per run.
+ */
+const { shareLogDir } = require('./config');
+
+// Before anything else, and before any step package is loaded: each of those
+// decides its log directory at require time, from the environment. Doing this
+// lower in the file would leave three loggers pointing somewhere this run never
+// writes. See shareLogDir for why an environment variable is the only channel
+// available.
+const LOG_DIR = shareLogDir();
+
+const { program } = require('commander');
+const logger = require('./logger');
+const { EXIT, TARGETS } = require('./config');
+const { version: PKG_VERSION } = require('../package.json');
+
+// Read from ./config rather than from the step package, so `--help` does not
+// pull in Playwright and three loggers just to print a default path. steps/auth
+// re-exports the same value for anyone who wants the package's own answer.
+const { defaultAuthFile } = require('./steps/auth');
+
+/**
+ * Options every step understands.
+ *
+ * Declared once and reused, because a flag that works on `login` but not on
+ * `export` is indistinguishable from a bug in the tool.
+ */
+function sharedOptions(command) {
+    return command
+        // No "(default: ...)" in the description: commander appends the real
+        // value itself, and spelling it out here printed it twice.
+        .option('--auth-file <path>', 'Path to the saved session', defaultAuthFile())
+        .option('--notheadless', 'Show the browser. Required for an interactive login, which cannot run headless')
+        .option('--dodump', 'Write the HTML of each page to the log directory, for debugging')
+        .option('-v, --verbose', 'Include debug output')
+        .option('-q, --quiet', 'Warnings and errors only');
+}
+
+/**
+ * Applies the verbosity flags.
+ *
+ * Sets this process's logger and the environment variable the export step reads,
+ * so one flag configures all four loggers instead of two of them.
+ */
+function applyVerbosity(options) {
+    if (options.verbose) {
+        logger.setLevel('debug');
+        process.env.ONENOTE_EXPORT_LOG_LEVEL = 'debug';
+    } else if (options.quiet) {
+        logger.setLevel('warn');
+        process.env.ONENOTE_EXPORT_LOG_LEVEL = 'warn';
+    }
+}
+
+/**
+ * Runs one step and turns its result into this process's exit code.
+ *
+ * Every failure path ends here, which is why there is exactly one place that
+ * decides the status: a command that reported an error and exited 0 is how a
+ * pipeline ends up treating a failed listing as a pass.
+ */
+async function run(step) {
+    try {
+        const { exitCode } = await step();
+        process.exitCode = exitCode;
+    } catch (e) {
+        logger.error(`${program.name()} failed:`, e);
+        process.exitCode = EXIT.failed;
+    }
+}
+
+program
+    .name('microsoft-onenote-exporter')
+    .description('Sign in to Microsoft OneNote, list the notebooks on the account, and export one to Markdown.')
+    .version(PKG_VERSION)
+    .addHelpText('after', `
+Also installed as: ms-onenote-exporter
+
+Logs for every step of a run are written to one app.log in:
+  ${LOG_DIR}
+
+A typical first run:
+  microsoft-onenote-exporter login
+  microsoft-onenote-exporter list
+  microsoft-onenote-exporter export --notebook "Work"
+`);
+
+sharedOptions(
+    program
+        .command('login')
+        .description('Sign in to Microsoft and save the session for the other steps')
+)
+    .option('--email <email>', 'Account email. Without it, the browser opens and you sign in yourself')
+    .option('--password <password>', 'Account password. Supplying it makes the login headless')
+    .option('--against <target>', `Service to authenticate against: ${Object.keys(TARGETS).join(' | ')}`, 'onenote')
+    .option('--screenshot', 'With --dodump, also save a PNG of each dumped page')
+    .action(async (options) => {
+        applyVerbosity(options);
+        await run(() => require('./steps/auth').login(options));
+    });
+
+sharedOptions(
+    program
+        .command('check')
+        .description('Report whether the saved session is still valid')
+)
+    .option('--against <target>', `Service to check: ${Object.keys(TARGETS).join(' | ')}`, 'onenote')
+    .action(async (options) => {
+        applyVerbosity(options);
+        await run(() => require('./steps/auth').check(options));
+    });
+
+sharedOptions(
+    program
+        .command('logout')
+        .description('Delete the saved session and its metadata')
+)
+    .action(async (options) => {
+        applyVerbosity(options);
+        await run(() => require('./steps/auth').logout(options));
+    });
+
+sharedOptions(
+    program
+        .command('list')
+        .description('List the notebooks on the signed-in account')
+)
+    .action(async (options) => {
+        applyVerbosity(options);
+        await run(() => require('./steps/list').list(options));
+    });
+
+sharedOptions(
+    program
+        .command('export')
+        .description('Export one notebook to Obsidian-flavoured Markdown')
+)
+    .option('--notebook <name>', 'Notebook to export, by name (skips the interactive picker)')
+    .option('--notebook-link <url>', 'Notebook to export, by URL (skips listing and picking)')
+    .option('--output-dir <path>', 'Where to write the Markdown (default: ./output)')
+    .option('--nopassasked', 'Skip password-protected sections instead of asking for the password')
+    .option('--non-interactive', 'Run unattended: requires --notebook or --notebook-link, and implies --nopassasked')
+    .action(async (options) => {
+        applyVerbosity(options);
+
+        // Fail before a browser is launched. Left to the export step, an
+        // unattended run with no way to choose a notebook reaches the
+        // interactive picker and waits forever - which in a container looks
+        // exactly like a hung export.
+        if (options.nonInteractive && !(options.notebook || options.notebookLink)) {
+            logger.error('--non-interactive requires --notebook <name> or --notebook-link <url>.');
+            logger.error('Without one of them the export would stop at the interactive notebook picker.');
+            process.exitCode = EXIT.usage;
+            return;
+        }
+
+        await run(() => require('./steps/export').exportNotebook(options));
+    });
+
+// A Playwright target that dies mid-run - the tab closed, the renderer crashed,
+// the browser was killed - also rejects one of Playwright's own internal
+// promises, which nothing awaits. Node treats that as fatal and kills the
+// process with a bare stack trace, so a dead OneNote tab would end a run with no
+// message, no summary and no status. Report it like any other failure and let
+// the run finish unwinding.
+process.on('unhandledRejection', (reason) => {
+    logger.error('Unexpected internal failure (this is a bug):', reason);
+    process.exitCode = EXIT.failed;
+});
+
+program.parseAsync().catch((e) => {
+    // The handlers above report their own failures; this is the net for anything
+    // else, including a throw while arguments were parsed.
+    logger.error('Failed:', e);
+    process.exitCode = EXIT.failed;
+});

package/src/logger.js

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview Logger for the umbrella CLI.
+ * @copyright 2026 msout
+ *
+ * A fourth logger, which is not the point of this exercise but is unavoidable
+ * while the three steps are separate packages: none of them exports its logger,
+ * and each constructs its own singleton at require time. This one handles the
+ * umbrella's own messages, and points the other three at the same directory (see
+ * src/config.js shareLogDir) so a run produces one app.log.
+ */
+const chalk = require('chalk');
+const fs = require('fs-extra');
+const path = require('path');
+const { resolveLogDir } = require('./config');
+
+/** Severity order, lowest first. A message is emitted if its level >= the threshold. */
+const LEVELS = { debug: 10, info: 20, step: 20, success: 20, warn: 30, error: 40 };
+
+class Logger {
+    constructor() {
+        this.months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+        this.logDir = resolveLogDir();
+        this.logFilePath = path.join(this.logDir, 'app.log');
+        this.level = Logger._initialLevel();
+        fs.ensureDirSync(this.logDir);
+    }
+
+    /**
+     * Reads the initial threshold from the environment.
+     *
+     * ONENOTE_EXPORT_LOG_LEVEL is the name the export step already uses, so
+     * `--verbose` and a container's environment variable set the same thing for
+     * all four loggers rather than two of them.
+     */
+    static _initialLevel() {
+        const raw = (process.env.ONENOTE_EXPORT_LOG_LEVEL || '').toLowerCase().trim();
+        if (raw === 'debug' || raw === 'verbose') return LEVELS.debug;
+        if (raw === 'warn' || raw === 'quiet') return LEVELS.warn;
+        if (raw === 'error') return LEVELS.error;
+        return LEVELS.info;
+    }
+
+    /**
+     * Raises or lowers the threshold at runtime.
+     * @param {string} name - One of debug|info|warn|error
+     */
+    setLevel(name) {
+        const level = LEVELS[(name || '').toLowerCase()];
+        if (level !== undefined) {
+            this.level = level;
+        }
+    }
+
+    /** True when a message at `level` should be emitted. */
+    _enabled(level) {
+        return (LEVELS[level] ?? LEVELS.info) >= this.level;
+    }
+
+    _timestamp() {
+        const now = new Date();
+        return `[${this.months[now.getMonth()]} ${String(now.getDate()).padStart(2, '0')} ${now.toTimeString().split(' ')[0]}]`;
+    }
+
+    _stripColors(str) {
+        // eslint-disable-next-line no-control-regex
+        return str.replace(/\u001b\[[0-9;]*m/g, '');
+    }
+
+    _write(level, message, color) {
+        if (!this._enabled(level)) return;
+
+        const stamp = this._timestamp();
+        const body = message instanceof Error
+            ? (message.stack || message.message)
+            : (typeof message === 'string' ? message : JSON.stringify(message, null, 2));
+
+        const plain = body.split('\n').map((line) => `[${level}] ${line}`).join('\n');
+        const colored = body.split('\n').map((line) => `${chalk.gray(stamp)} ${color(`[${level}]`)} ${line}`).join('\n');
+
+        // mode only applies at creation; an app.log from another logger in this
+        // same directory may predate it and be 0644.
+        fs.appendFileSync(this.logFilePath, `${plain}\n`, { mode: 0o600 });
+
+        const stream = level === 'error' ? process.stderr : process.stdout;
+        stream.write(`${colored}\n`);
+    }
+
+    debug(message) { this._write('debug', message, chalk.gray); }
+    info(message) { this._write('info', message, chalk.blue); }
+    step(message) { this._write('step', message, chalk.magenta); }
+    success(message) { this._write('success', message, chalk.green); }
+    warn(message) { this._write('warn', message, chalk.yellow); }
+    error(message) { this._write('error', message, chalk.red); }
+}
+
+module.exports = new Logger();

package/src/steps/auth.js

@@ -0,0 +1,124 @@
+/**
+ * @fileoverview Adapters over @msout/microsoft-webauth.
+ * @copyright 2026 msout
+ *
+ * This is a translation layer and nothing more: it renames the CLI's options into
+ * the names that package expects, calls one function, and returns. All the
+ * behaviour - the login flow, the blocking-screen handling, the credential
+ * redaction in dumps - stays in that package, which is separately installable and
+ * separately tested. If a rule ever needs to exist in two places, it belongs
+ * here as a comment and not as code.
+ */
+const logger = require('../logger');
+const { TARGETS, EXIT } = require('../config');
+
+/**
+ * Loads the package.
+ *
+ * Required lazily, inside the command, rather than at the top of the module: the
+ * package's logger is a singleton built at require time and decides its log
+ * directory from the environment, so it must not be loaded before src/index.js
+ * has set ONENOTE_EXPORT_LOG_DIR. Loading it at import time would put its app.log
+ * somewhere this run never looks.
+ */
+function load() {
+    return require('@msout/microsoft-webauth');
+}
+
+/** The auth file default, read from the package that owns the convention. */
+function defaultAuthFile() {
+    return require('@msout/microsoft-webauth/config').DEFAULT_AUTH_FILE;
+}
+
+/** Resolves the --against value to a URL the login flow will accept. */
+function targetUrl(against) {
+    return against === 'outlook' ? TARGETS.outlook : TARGETS.onenote;
+}
+
+/**
+ * Signs in and writes the session to the auth file.
+ *
+ * Note what decides headless: that package runs headless only when it is given
+ * both an email and a password. Without them it shows the browser, because an
+ * interactive login needs somewhere to type the password and click the MFA
+ * prompt. `--notheadless` is therefore only meaningful alongside credentials, and
+ * saying so is better than letting a flag appear to do nothing.
+ *
+ * @param {object} options - CLI options
+ * @returns {Promise<object>} The auth metadata the package recorded
+ */
+async function login(options) {
+    const { login: doLogin } = load();
+
+    if (!options.notheadless && !(options.email && options.password)) {
+        logger.debug('No --email/--password given, so the browser will be shown for an interactive login.');
+    }
+    if (options.screenshot && !options.dodump) {
+        logger.warn('--screenshot only applies to the pages written by --dodump; enabling --dodump as well.');
+        options.dodump = true;
+    }
+
+    await doLogin({
+        email: options.email,
+        password: options.password,
+        targetUrl: targetUrl(options.against),
+        authFile: options.authFile,
+        notheadless: options.notheadless,
+        dodump: options.dodump,
+        screenshot: options.screenshot,
+    });
+
+    return { exitCode: EXIT.ok };
+}
+
+/**
+ * Reports whether the saved session still works.
+ *
+ * Worth being precise about what this proves: the underlying check launches a
+ * browser, loads the auth file and follows the redirect. If it redirects to a
+ * Microsoft login page the session is dead, and the package deletes the stale
+ * file. So a `false` here does not just mean "not authenticated", it means the
+ * file has been cleaned up and the next command needs a fresh `login`.
+ *
+ * @param {object} options - CLI options
+ * @returns {Promise<object>} { authenticated, exitCode }
+ */
+async function check(options) {
+    const { checkAuth, getAuthMeta } = load();
+
+    const authenticated = await checkAuth(targetUrl(options.against), options.authFile);
+
+    if (!authenticated) {
+        logger.error('Not authenticated, or the saved session has expired.');
+        logger.error('Run "microsoft-onenote-exporter login" to create a new one.');
+        return { authenticated: false, exitCode: EXIT.failed };
+    }
+
+    logger.success(`Authenticated${options.against === 'outlook' ? ' against Outlook' : ''}.`);
+
+    const meta = await getAuthMeta(options.authFile);
+    if (meta && meta.email) {
+        logger.info(`Signed in as: ${meta.email}`);
+    }
+    if (meta && meta.loginTime) {
+        logger.info(`Session started: ${new Date(meta.loginTime).toLocaleString()}`);
+    }
+
+    return { authenticated: true, exitCode: EXIT.ok };
+}
+
+/**
+ * Deletes the saved session and its metadata.
+ *
+ * @param {object} options - CLI options
+ * @returns {Promise<object>} { exitCode }
+ */
+async function logout(options) {
+    const { logout: doLogout } = load();
+
+    await doLogout(options.authFile);
+    logger.success('Signed out. The saved session has been deleted.');
+    return { exitCode: EXIT.ok };
+}
+
+module.exports = { login, check, logout, defaultAuthFile, targetUrl };

package/src/steps/export.js

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Adapter over @msout/microsoft-onenote-export-notebook.
+ * @copyright 2026 msout
+ */
+const logger = require('../logger');
+const { EXIT } = require('../config');
+
+/**
+ * Loads the package.
+ *
+ * Lazily, for the same reason as in steps/auth.js: its logger is a singleton
+ * constructed at require time and reads the log directory from the environment,
+ * so it must not be loaded before src/index.js has set ONENOTE_EXPORT_LOG_DIR.
+ */
+function load() {
+    return require('@msout/microsoft-onenote-export-notebook');
+}
+
+/**
+ * Exports one notebook to Obsidian-flavoured Markdown.
+ *
+ * On exit codes. That package uses three - 1 for a run that produced nothing
+ * usable, 2 for bad arguments, 3 for a run that finished while missing pages,
+ * sections or groups - and it reports 3 by setting `process.exitCode` as a side
+ * effect from inside the export, then returns its stats object.
+ *
+ * The return value is the better channel and this uses it: exitCodeForStats is
+ * exported precisely so a caller can ask the same question the package asked,
+ * and reading a global that a library mutated is how a composed pipeline ends up
+ * with the wrong status. src/index.js sets the real exit code afterwards, which
+ * also means the side effect is overwritten rather than inherited.
+ *
+ * Three is deliberately not collapsed into one here. Partial output is worth
+ * keeping and re-running, and a caller that cannot tell "partial" from "nothing"
+ * has to discard both.
+ *
+ * @param {object} options - CLI options
+ * @returns {Promise<object>} { stats, exitCode }
+ */
+async function exportNotebook(options) {
+    const { runExport, exitCodeForStats } = load();
+
+    const stats = await runExport({
+        authFile: options.authFile,
+        notebook: options.notebook,
+        notebookLink: options.notebookLink,
+        exportDir: options.outputDir,
+        notheadless: options.notheadless,
+        dodump: options.dodump,
+        nopassasked: options.nopassasked,
+        nonInteractive: options.nonInteractive,
+    });
+
+    // The package's own rule, not a copy of it: if the two ever disagree, this
+    // one follows the package.
+    const exitCode = exitCodeForStats(stats);
+
+    if (exitCode === EXIT.partial) {
+        logger.warn('The export finished, but some pages, sections or groups are missing.');
+        logger.warn('The notes that were written are complete, and name any asset they could not download.');
+        logger.warn('Re-run the export to try again.');
+    }
+
+    return { stats, exitCode };
+}
+
+module.exports = { exportNotebook };

package/src/steps/list.js

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview Adapter over @msout/microsoft-onenote-list-notebooks.
+ * @copyright 2026 msout
+ */
+const logger = require('../logger');
+const { EXIT } = require('../config');
+
+/**
+ * Loads the package.
+ *
+ * Lazily, for the same reason as in steps/auth.js: its logger is a singleton
+ * constructed at require time and reads the log directory from the environment,
+ * so it must not be loaded before src/index.js has set ONENOTE_EXPORT_LOG_DIR.
+ */
+function load() {
+    return require('@msout/microsoft-onenote-list-notebooks');
+}
+
+/**
+ * Lists the notebooks on the signed-in account.
+ *
+ * An empty result is not an error: it means the account is authenticated and has
+ * no notebooks, which is a different situation from a failure and is reported as
+ * success. The distinction matters because the export step can still work from a
+ * `--notebook-link` when the listing comes back empty - Microsoft for the web
+ * does not always list a notebook the account can otherwise open directly.
+ *
+ * @param {object} options - CLI options
+ * @returns {Promise<object>} { notebooks, exitCode }
+ */
+async function list(options) {
+    const { listNotebooks } = load();
+
+    const notebooks = await listNotebooks({
+        authFile: options.authFile,
+        notheadless: options.notheadless,
+        dodump: options.dodump,
+    });
+
+    if (notebooks.length === 0) {
+        logger.warn('No notebooks were found on this account.');
+        logger.warn('If you know the notebook exists, export it by URL:');
+        logger.warn('  microsoft-onenote-exporter export --notebook-link <url>');
+    } else {
+        logger.step('\nAvailable notebooks:');
+        notebooks.forEach((nb, index) => {
+            logger.info(`${index + 1}. ${nb.name}`);
+            logger.debug(`   ${nb.url}`);
+        });
+    }
+
+    return { notebooks, exitCode: EXIT.ok };
+}
+
+module.exports = { list };