@msout/microsoft-onenote-exporter 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -6,6 +6,103 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-10-02
+
+A **patch**. It changes what is published, not what the package does.
+
+### Fixed
+
+- **`entrypoint.sh` and `start-container.sh` are published again.** The `files`
+  whitelist listed `src/` and the four documents, so the tarball had eleven files
+  and neither container script — 0.1.0 and 0.1.1 both shipped that way. It
+  mattered because six of the fixes in 0.1.1 live inside those two files, and
+  because the README's Docker section is built on them: a consumer who installed
+  the package and then tried to run a container from it had no entrypoint to
+  build an image from and no wrapper to call.
+
+  The publish gate missed it because it only ever checked what must *not* ship —
+  no test suites, no auth state, no workflow files — and never what must. Two
+  tests now cover that direction, and one of them checks the executable bit too,
+  since a tarball carrying the scripts as `0644` would fail at the `ENTRYPOINT`
+  line with `Cannot exec: permission denied`.
+
+  Thirteen files, up from eleven.
+
+### Changed
+
+- **`docker-output/` is gitignored.** A container run pointed at that directory
+  leaves `auth.json` beside the exported notes, and `git add -A` would have staged
+  a live full-account session.
+
+Tests: 128 → 130.
+
+## [0.1.1] - 2026-10-01
+
+A **patch**, and an unusual one: it fixes six bugs and changes no documented
+behaviour. 0.1.0 built, installed and passed 102 tests, and could not export a
+single note inside the container. Every bug here was found by running
+`start-container.sh` against a real notebook and looking for Markdown on the
+host — not by reading the code, and not by the test suite.
+
+### Fixed
+
+- **The container was never given the subcommand.** The wrapper forwarded the
+  caller's flags verbatim, and the CLI takes the step as a subcommand, so the
+  container received only `--notebook <name>` and answered
+  `error: unknown option '--notebook'`. The wrapper now supplies `export` by
+  default and accepts an explicit step.
+- **The wrapper reported success while the export was still running.** The wait
+  loop read `State.ExitCode` and stopped as soon as it was non-empty — and that
+  field is `0` *while the container is running*. So it printed
+  `Exported files are in: ...` for a run that had written nothing. It now uses
+  `docker wait`, which blocks until the container stops, with a one-hour
+  watchdog that reports rather than hangs.
+- **Notes were written inside the image and lost on exit.** The container's
+  working directory is `/app`, so the CLI's own default for `--output-dir` —
+  `./output` against the cwd — resolved to `/app/output`. That directory exists
+  and is writable, so the export ran to completion and logged
+  `Files saved in: /app/output/<notebook>`, and every file died with the
+  container: `/app/output` is inside the image, not the mounted volume. The
+  entrypoint now points `--output-dir` at `/data/output` whenever a volume is
+  mounted, and warns when none is.
+- **The documented way to run could not run.** With the session in `./output`
+  there is no second mount to make, so the optional-mount array was empty, and
+  expanding an empty array under `set -u` failed with
+  `AUTH_MOUNT[@]: unbound variable` before starting any container. The
+  `~/.microsoft-webauth` fallback worked and hid it — the bug was invisible from
+  the side of the code that happened to work.
+- **The container name collided on every run after the first**, because the
+  wrapper never removed what it created and the name is derived from the working
+  directory.
+- **The logger swallowed the error it was asked to report.** It formatted only
+  its first argument, but the export step reports `logger.error('Export failed:',
+  e)`, so a genuine failure printed the word `failed:` and nothing else — no
+  message, no stack, and an empty log file. That is what concealed the bug above.
+  Errors are now read from any argument position, which is how all three step
+  packages call it.
+
+### Changed
+
+- **The session now defaults to the one `login` writes**, so "sign in on the
+  host, then run this" works with no preparation. It used to default to
+  `./output/auth.json` and fail with `no auth file` unless you knew to make a
+  copy that no document mentioned.
+- **The Docker section of the README** is written around a single mounted volume
+  at `/data/output`, showing the copy step, the resulting directory tree, and the
+  separate read-only mount as the alternative for keeping the session out of the
+  notes directory.
+
+Tests: 102 → 128. Verified by a real export: 18 notes written to
+`./output/NotebookLongSimple`, `logs/app.log` beside them, one image downloaded.
+
+### Release process
+
+0.1.0 was published from a laptop, so it carries no provenance and this
+repository had no tags or releases at all — which is why neither the tag-triggered
+OIDC workflow nor a GitHub Release existed for it. From 0.1.1 the release is
+`v0.1.1` pushed to `main`, so the workflow publishes with a provenance statement
+attached.
+
 ## [0.1.0] - 2026-10-01
 
 The first release. It adds a CLI over three existing packages and changes none of

package/README.md

@@ -129,31 +129,106 @@ authenticated DOM of a real account: cookies, tenant hostnames, note titles.
 
 ## Docker
 
+One image, one Chromium, serving all five commands. It replaces the three separate
+images these packages used to ship, each carrying its own browser.
+
 ```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`.
+### Mounting
+
+The container reads and writes through a single volume mounted at
+`/data/output`. The host directory of your choice — `./output` below — receives
+the exported notes *and* provides the saved session:
+
+```
+host ./output  ->  /data/output
+```
+
+A login cannot happen inside the container: without credentials the browser has
+to be shown, and there is nobody there to show it to. So you sign in on the host
+first, put the session in the mount, and the container reads it from there:
+
+```sh
+# 1. sign in on the host, once
+microsoft-onenote-exporter login
+
+# 2. put the session where the container can see it
+mkdir -p output
+cp ~/.microsoft-webauth/auth-file.json output/auth.json
+
+# 3. export, writing notes back into ./output
+docker run --rm --init --shm-size=1g \
+  -v "$PWD/output:/data/output" \
+  microsoft-onenote-exporter export \
+    --notebook "NotebookLongSimple" \
+    --non-interactive
+```
+
+That produces:
+
+```
+output/
+├── auth.json                    the session (a live credential - see below)
+├── logs/app.log                 every step of the run, in order
+└── NotebookLongSimple/
+    ├── Section1/
+    │   ├── Section1-Note1.md
+    │   └── Section1-Note2w2Pic.md
+    └── Section2/assets/         images and attachments, beside the notes
+```
+
+Two flags are required and are easy to leave out:
+
+- **`--shm-size=1g`** — Chromium crashes on memory-heavy pages with Docker's
+  default 64 MB of shared memory.
+- **`--init`** — reaps Chromium's child processes instead of leaving zombies.
+
+If you omit the `-v` mount, the entrypoint warns you: the notes would be written
+inside the container and lost when it exits. That is not a hypothetical — it is
+what happens by default, because the CLI's own default for `--output-dir` is
+`./output` relative to a working directory of `/app`, which exists and is
+writable, so the export succeeds and the files vanish. Whenever a volume is
+mounted, the entrypoint points `--output-dir` at it.
+
+`output/auth.json` is a full account credential. Keep the directory out of git —
+`.gitignore` covers `output/` — and be careful with anything that syncs it whole,
+such as a cloud backup or an Obsidian vault. If you would rather keep the session
+out of the notes directory, mount it separately instead:
 
 ```sh
 docker run --rm --init --shm-size=1g \
-  -v "$PWD/out:/data/output" \
-  microsoft-onenote-exporter export --notebook "Work" --non-interactive
+  -v "$PWD/output:/data/output" \
+  -v "$HOME/.microsoft-webauth/auth-file.json:/data/auth/session.json:ro" \
+  microsoft-onenote-exporter export \
+    --notebook "NotebookLongSimple" --non-interactive \
+    --auth-file /data/auth/session.json
 ```
 
-Or use the wrapper, which waits for the run and translates the exit code:
+### The wrapper
+
+`start-container.sh` does the mounting, waits for the run, and translates the
+exit code into an explanation:
 
 ```sh
-./start-container.sh --notebook "Work" --output-dir ./out
+cp ~/.microsoft-webauth/auth-file.json ./output/auth.json   # once
+./start-container.sh --notebook "NotebookLongSimple"
 ```
 
-`--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.
+It defaults `OUTPUT_DIR` to `./output`, so that is where the notes and
+`logs/app.log` land. If `./output/auth.json` is absent it falls back to the
+session in `~/.microsoft-webauth`, mounting that read-only instead — so it works
+either way.
+
+```sh
+CONTAINER=other-name ./start-container.sh --notebook "Work"   # rename the container
+IMAGE=my-registry/microsoft-onenote-exporter ./start-container.sh --notebook "Work"
+```
 
-`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.
+The wrapper runs detached and reports the container's exit status. It removes the
+container it created, so it can be run repeatedly; if one is still running it
+says so rather than colliding with it.
 
 ## Development
 

package/entrypoint.sh

@@ -0,0 +1,106 @@
+#!/bin/sh
+# Container entrypoint for microsoft-onenote-exporter.
+#
+# One image, five commands. The old images took a session GUID and a notebook
+# name as positional arguments, which was tied to one pipeline's idea of what a
+# session is; this dispatches on the subcommand instead, so the same image can
+# also be used to log in or to list.
+
+set -e
+
+if [ $# -eq 0 ]; then
+    echo "Usage: microsoft-onenote-exporter <command> [options]"
+    echo ""
+    echo "Commands:"
+    echo "  login     Sign in to Microsoft and save the session"
+    echo "  check     Report whether the saved session is still valid"
+    echo "  logout    Delete the saved session"
+    echo "  list      List the notebooks on the account"
+    echo "  export    Export one notebook to Markdown"
+    echo ""
+    echo "Example:"
+    echo "  docker run -v ./out:/data/output microsoft-onenote-exporter \\"
+    echo "    export --auth-file /data/output/auth.json --notebook 'Work' --non-interactive"
+    exit 0
+fi
+
+# A login cannot run headless: without an email and a password the browser has to
+# be shown, and there is nobody at a terminal inside a container to type into it.
+case "$1" in
+    login)
+        echo "ERROR: 'login' needs a visible browser, which a container has no way to show." >&2
+        echo "       Log in on the host first, then mount the resulting auth file:" >&2
+        echo "         microsoft-onenote-exporter login" >&2
+        echo "         docker run -v \$HOME/.microsoft-webauth:/data/auth ..." >&2
+        exit 2
+        ;;
+esac
+
+# Allow a shell in the container for debugging, and node for poking at the CLI.
+if [ "$1" = "/bin/sh" ] || [ "$1" = "sh" ]; then
+    exec "$@"
+fi
+# `shift` first, then exec node with what is left. Without the shift this runs
+# `node node <script>`, which node reads as a module path named "node" and fails
+# with MODULE_NOT_FOUND - so the documented debugging route
+#
+#   docker run --rm -it microsoft-onenote-exporter node /app/src/index.js list
+#
+# never worked. Found by running the built image rather than by reading it.
+if [ "$1" = "node" ]; then
+    shift
+    exec node "$@"
+fi
+
+# Where the notes go, unless the caller said otherwise.
+#
+# The container's working directory is /app, so the CLI's own default - ./output
+# against the cwd - resolves to /app/output. That directory exists and is
+# writable, so nothing fails: the export runs to completion and reports
+# "Files saved in: /app/output/<notebook>". The notes are then destroyed with the
+# container, because /app/output is inside the image rather than the mounted
+# volume. A run that looked entirely successful and produced nothing on the host.
+#
+# /data/output is the volume mount, so that is the only default that survives.
+# /app/output stays in the image as a fallback for anyone running the CLI with a
+# working directory of their own choosing.
+if [ ! -d /data/output ]; then
+    # No volume mounted: warn rather than silently writing into the image, since
+    # that is the failure this line exists to prevent.
+    echo "WARNING: no volume is mounted at /data/output." >&2
+    echo "         Exported notes will be written inside the container and lost" >&2
+    echo "         when it exits. Mount one, for example:" >&2
+    echo "           -v \"\$PWD/output:/data/output\"" >&2
+else
+    # Appending --output-dir rather than exporting a variable, because the CLI has
+    # no environment variable for it and its default resolves against a cwd of
+    # /app. Only when the caller did not pass one, for the same reason as
+    # --auth-file below: an explicit choice must never be overridden.
+    has_output_dir=false
+    for arg in "$@"; do
+        if [ "$arg" = "--output-dir" ]; then
+            has_output_dir=true
+            break
+        fi
+    done
+    if [ "$has_output_dir" = false ]; then
+        set -- "$@" --output-dir /data/output
+    fi
+fi
+
+# Only injected when the caller did not pass --auth-file themselves: appending it
+# unconditionally would silently override an explicit choice, and the container
+# would read a different session than the one asked for.
+AUTH_FILE="${AUTH_FILE:-/data/output/auth.json}"
+for arg in "$@"; do
+    if [ "$arg" = "--auth-file" ]; then
+        AUTH_FILE=""
+        break
+    fi
+done
+
+if [ -n "$AUTH_FILE" ]; then
+    exec node /app/src/index.js "$@" --auth-file "$AUTH_FILE"
+fi
+
+exec node /app/src/index.js "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msout/microsoft-onenote-exporter",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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": {
@@ -14,6 +14,8 @@
   },
   "files": [
     "src/",
+    "entrypoint.sh",
+    "start-container.sh",
     "README.md",
     "LICENSE",
     "NOTICE.md",

package/src/config.js

@@ -5,6 +5,35 @@
 const os = require('os');
 const path = require('path');
 
+/** Cached so one run cannot write to two different places. */
+let outputDir;
+
+/**
+ * Where exported notes go when --output-dir is not given.
+ *
+ * Absolute, and resolved against the working directory rather than against this
+ * package's own location. It has to be: the export step's own default is
+ * `<its package dir>/output`, which as a dependency lands inside node_modules -
+ * and in the container node_modules is root-owned, so a default export died with
+ * EACCES after it had already signed in, found the notebook and loaded the
+ * editor. Same class of bug as the log directory, and the same fix: resolve the
+ * path here rather than letting a dependency resolve it against its own install
+ * location.
+ *
+ * @param {string} [dir] - Explicit override, resolved to an absolute path
+ * @returns {string} Absolute path of the output directory
+ */
+function defaultOutputDir(dir) {
+    if (dir) return path.resolve(dir);
+    if (!outputDir) outputDir = path.resolve(process.cwd(), 'output');
+    return outputDir;
+}
+
+/** Test seam: forgets the cached default so the next call re-resolves it. */
+function resetOutputDir() {
+    outputDir = undefined;
+}
+
 /**
  * Where the three step packages should write their logs.
  *
@@ -77,4 +106,12 @@ const EXIT = {
     partial: 3,
 };
 
-module.exports = { resolveLogDir, shareLogDir, defaultAuthFile, TARGETS, EXIT };
+module.exports = {
+    resolveLogDir,
+    shareLogDir,
+    defaultAuthFile,
+    defaultOutputDir,
+    resetOutputDir,
+    TARGETS,
+    EXIT,
+};

package/src/index.js

@@ -144,7 +144,7 @@ sharedOptions(
 )
     .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('--output-dir <path>', 'Where to write the Markdown (default: ./output, resolved against the working directory)')
     .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) => {

package/src/logger.js

@@ -16,6 +16,43 @@ 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 };
 
+/**
+ * JSON.stringify that cannot throw, and that still says something useful.
+ *
+ * A logger that throws while reporting a failure replaces the failure with its
+ * own, and the original is lost - the opposite of what a logger is for.
+ * Circular structures are the usual cause, and this logger is handed whatever a
+ * deep call site thought was worth mentioning.
+ *
+ * The fallback walks the object and renders what it can rather than returning
+ * String(value), which for a circular object yields "[object Object]" and throws
+ * away every field - including the ones outside the cycle, which were the reason
+ * for logging it in the first place.
+ */
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value, null, 2);
+    } catch {
+        try {
+            return JSON.stringify(value, circularReplacer(), 2);
+        } catch {
+            return String(value);
+        }
+    }
+}
+
+/** Marks already-visited objects as "[circular]" instead of recursing forever. */
+function circularReplacer() {
+    const seen = new WeakSet();
+    return (key, val) => {
+        if (val !== null && typeof val === 'object') {
+            if (seen.has(val)) return '[circular]';
+            seen.add(val);
+        }
+        return val;
+    };
+}
+
 class Logger {
     constructor() {
         this.months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
@@ -66,13 +103,37 @@ class Logger {
         return str.replace(/\u001b\[[0-9;]*m/g, '');
     }
 
-    _write(level, message, color) {
+    /**
+     * Formats one call's worth of arguments into a printable string.
+     *
+     * Errors are read out of the argument list rather than being passed whole.
+     * This exists because of a real failure: the export step's catch reports
+     * `logger.error('Export failed:', e)`, so an Error arrives as the *second*
+     * argument, not the first. Formatting only the first argument stringified it
+     * and dropped the stack, so a failure that had navigated OneNote, found the
+     * notebook and loaded the editor reported nothing but the words
+     * "failed:" - no message, no stack, nothing in the log file either.
+     *
+     * The extra arguments are joined after the first rather than dropped, which
+     * is what makes `error('context:', err)` read the way it was written.
+     */
+    _format(args) {
+        return args
+            .map((part) => {
+                if (part instanceof Error) return part.stack || part.message;
+                if (typeof part === 'string') return part;
+                return safeStringify(part);
+            })
+            .join(' ')
+            .trim();
+    }
+
+    _write(level, args, 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 body = this._format(args);
+        if (!body) return;
 
         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');
@@ -85,12 +146,12 @@ class Logger {
         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); }
+    debug(...args) { this._write('debug', args, chalk.gray); }
+    info(...args) { this._write('info', args, chalk.blue); }
+    step(...args) { this._write('step', args, chalk.magenta); }
+    success(...args) { this._write('success', args, chalk.green); }
+    warn(...args) { this._write('warn', args, chalk.yellow); }
+    error(...args) { this._write('error', args, chalk.red); }
 }
 
 module.exports = new Logger();

package/src/steps/export.js

@@ -3,7 +3,7 @@
  * @copyright 2026 msout
  */
 const logger = require('../logger');
-const { EXIT } = require('../config');
+const { EXIT, defaultOutputDir } = require('../config');
 
 /**
  * Loads the package.
@@ -16,6 +16,20 @@ function load() {
     return require('@msout/microsoft-onenote-export-notebook');
 }
 
+/**
+ * Where notes are written.
+ *
+ * Absolute in every case, and never inside a dependency: see the comment where
+ * exportDir is passed to runExport for why that package's own default cannot be
+ * used here.
+ *
+ * @param {string} [dir] - What --output-dir was given, if anything
+ * @returns {string} Absolute path
+ */
+function resolveOutputDir(dir) {
+    return defaultOutputDir(dir);
+}
+
 /**
  * Exports one notebook to Obsidian-flavoured Markdown.
  *
@@ -44,7 +58,27 @@ async function exportNotebook(options) {
         authFile: options.authFile,
         notebook: options.notebook,
         notebookLink: options.notebookLink,
-        exportDir: options.outputDir,
+        // Always absolute, and never the package's own default. That default is
+        // `path.resolve(__dirname, '../output')`, which is correct for a checkout
+        // and wrong as a dependency: it resolves to
+        //
+        //   node_modules/@msout/microsoft-onenote-export-notebook/output
+        //
+        // Inside the container that is root-owned and read-only to the runtime
+        // user, so a real export died with
+        //
+        //   EACCES: permission denied, mkdir '.../microsoft-onenote-export-notebook/output'
+        //
+        // after it had already signed in, found the notebook and loaded the
+        // editor. Same class of bug as the log directory, and the same fix: the
+        // umbrella resolves the path against the working directory rather than
+        // letting a dependency resolve it against its own install location.
+        //
+        // A relative --output-dir is resolved too, rather than handed through:
+        // handed through it would be re-resolved by the export step against
+        // whatever its own idea of the base directory is, which is the bug above
+        // all over again with an extra step.
+        exportDir: resolveOutputDir(options.outputDir),
         notheadless: options.notheadless,
         dodump: options.dodump,
         nopassasked: options.nopassasked,

package/start-container.sh

@@ -0,0 +1,301 @@
+#!/bin/bash
+# Runs one export in a container.
+#
+# Usage: ./start-container.sh --notebook "Work" [--output-dir ./out] [more flags...]
+#
+# Everything is overridable through the environment, because the previous script
+# pointed at a sibling checkout that only existed on one machine and used a fixed
+# image name, so it could not be used anywhere else.
+#
+#   IMAGE        image to run            (default: microsoft-onenote-exporter)
+#   CONTAINER    container name          (default: ms_onenote_export)
+#   OUTPUT_DIR   host dir for the export (default: ./output)
+#   AUTH_FILE    session to use          (default: the one `login` wrote)
+
+set -euo pipefail
+
+SESSION="$(basename "${PWD}")"
+IMAGE="${IMAGE:-microsoft-onenote-exporter}"
+CONTAINER="${CONTAINER:-ms_onenote_export_${SESSION}}"
+OUTPUT_DIR="${OUTPUT_DIR:-./output}"
+
+# The session defaults to where `microsoft-onenote-exporter login` writes it.
+# Spelled out rather than read from @msout/microsoft-webauth/config at runtime,
+# because this script runs before any node_modules is guaranteed to be present -
+# it has to work in a fresh checkout. test/docker.test.js asserts this path
+# matches what the CLI reports, so the two cannot drift apart silently.
+#
+# This used to default to $OUTPUT_DIR/auth.json, which meant the documented
+# sequence - log in on the host, then run this script - always failed with "no
+# auth file", because the copy step it demanded was never written down
+# anywhere. Logging in on the host is the supported way to get a session into a
+# container, since a container cannot run an interactive login, so the default
+# simply follows it and no copy is needed.
+# Which session to use, in order of preference:
+#
+#   1. $AUTH_FILE, if the caller set it
+#   2. ./output/auth.json, the convention the README documents - the session sits
+#      beside the notes in the one mounted volume, so there is nothing else to
+#      mount and no copy step on every run
+#   3. ~/.microsoft-webauth/auth-file.json, where `login` writes it, so the
+#      "log in on the host, then run this" sequence works with no preparation
+#
+# The default is NOT just (3): a check for (2) has to come first, because with the
+# default set to (3) the script looks for a file named `auth-file.json` in the
+# output directory and silently ignores the `auth.json` a user following the
+# README actually placed there.
+if [ -z "${AUTH_FILE:-}" ]; then
+    if [ -f "${OUTPUT_DIR}/auth.json" ]; then
+        AUTH_FILE="${OUTPUT_DIR}/auth.json"
+    else
+        AUTH_FILE="$HOME/.microsoft-webauth/auth-file.json"
+    fi
+fi
+
+# The subcommand, when the caller did not give one.
+#
+# This script forwards "$@" to the CLI verbatim, so it has to supply `export`
+# itself - the CLI takes it as a subcommand, not as a flag. Without this the
+# container received only `--notebook <name> --non-interactive` and answered
+#
+#   error: unknown option '--notebook'
+#
+# which is commander refusing the first flag it saw because the subcommand that
+# should have preceded it was missing. Fixed here rather than by rewriting the
+# caller's arguments, so `./start-container.sh export --notebook X` also works.
+SUBCOMMAND="${1:-}"
+case "$SUBCOMMAND" in
+    login | check | logout | list | export)
+        shift
+        ;;
+    *)
+        SUBCOMMAND="export"
+        ;;
+esac
+
+if [ $# -eq 0 ] && [ "$SUBCOMMAND" = "export" ]; then
+    echo "Usage: $0 [--export] --notebook <name> | --notebook-link <url> [options...]" >&2
+    echo "" >&2
+    echo "Example:" >&2
+    echo "  $0 --notebook 'Work' --output-dir ./out" >&2
+    echo "" >&2
+    echo "Or name the step explicitly:" >&2
+    echo "  $0 list          $0 check" >&2
+    exit 1
+fi
+
+if [ $# -eq 0 ]; then
+    echo "Usage: $0 <$SUBCOMMAND> [options...]" >&2
+    exit 1
+fi
+
+# One of these two must be present for a non-interactive export, and finding out
+# here rather than inside the container is the difference between an explanation
+# and `error: unknown option '--notebook-link'`.
+if [ "$SUBCOMMAND" = "export" ]; then
+    has_notebook=false
+    for arg in "$@"; do
+        case "$arg" in
+            --notebook | --notebook-link)
+                has_notebook=true
+                ;;
+        esac
+    done
+    if [ "$has_notebook" = false ]; then
+        echo "ERROR: an export needs --notebook <name> or --notebook-link <url>." >&2
+        echo "  This script always runs unattended, so there is no interactive picker" >&2
+        echo "  to fall back on." >&2
+        exit 2
+    fi
+fi
+
+# The container name is derived from the working directory, so it is stable across
+# runs on the same machine - which means the second run collides with the first.
+# Docker refuses to reuse a name, and the error it gives ("Conflict ... already in
+# use by container 302415178a51") names a hash rather than telling you what to do
+# about it, so a script that is meant to be run repeatedly only worked once.
+#
+# A leftover container here is always from a previous run of this script: it exits
+# with `docker run --detach`, so it is never expected to still be running. Removing
+# it is safe for the current run and is what makes the next one possible. Named
+# volumes are untouched; only the container is removed.
+if docker container inspect "$CONTAINER" >/dev/null 2>&1; then
+    state="$(docker inspect -f '{{.State.Status}}' "$CONTAINER" 2>/dev/null || echo unknown)"
+    if [ "$state" = "running" ]; then
+        echo "ERROR: container '$CONTAINER' is already running." >&2
+        echo "  Stop it first if that is expected, or set CONTAINER=<other name>." >&2
+        exit 1
+    fi
+    docker rm "$CONTAINER" >/dev/null
+fi
+
+if ! docker image inspect "$IMAGE" >/dev/null 2>&1; then
+    echo "ERROR: image '$IMAGE' is not built." >&2
+    echo "  Build it:  docker build -t $IMAGE ." >&2
+    # The message this replaces only said "build it", which is unhelpful when the
+    # image exists under another tag - and "docker build -t foo ." produces
+    # foo:latest, while a build tagged foo:test leaves foo:latest missing. So a
+    # script looking for an untagged name would report "not built" next to a
+    # perfectly good image, with nothing to suggest the retag.
+    # Match on the part of the name that survives a tag difference. The tag is
+    # stripped because that is the whole point - `foo` and `foo:test` are the
+    # same image, and the tag is what the user got wrong. Non-alphanumerics are
+    # left in place: stripping them turns `ms-onenote-exporter` into
+    # `msonenoteexporter`, which matches no image at all and made this branch
+    # silently dead.
+    similar="$(docker images --format '{{.Repository}}:{{.Tag}}' 2>/dev/null \
+        | grep -i -- "$(printf '%s' "$IMAGE" | tr '[:upper:]' '[:lower:]' | cut -d: -f1)" || true)"
+    if [ -n "$similar" ]; then
+        echo "" >&2
+        echo "  But these exist:" >&2
+        printf '    %s\n' $similar >&2
+        echo "" >&2
+        echo "  Use one of them, or retag:" >&2
+        echo "    docker tag ${similar%%:*}:${similar##*:} $IMAGE" >&2
+    fi
+    exit 1
+fi
+
+# The auth file has to exist before the container starts, because the mount is
+# created from this path and Docker creates a directory when the source is
+# missing - which produces a confusing "not a storage state" error from inside
+# the container rather than an obvious one here.
+if [ ! -f "$AUTH_FILE" ]; then
+    echo "ERROR: no auth file at $AUTH_FILE" >&2
+    echo "  A container cannot run an interactive login, so sign in on the host first:" >&2
+    echo "    microsoft-onenote-exporter login" >&2
+    echo "  Then either copy the session into the output directory:" >&2
+    echo "    cp ~/.microsoft-webauth/auth-file.json ./output/auth.json" >&2
+    echo "  or point this at it directly:" >&2
+    echo "    AUTH_FILE=~/.microsoft-webauth/auth-file.json \$0 --notebook 'Work'" >&2
+    exit 1
+fi
+
+mkdir -p "$OUTPUT_DIR"
+
+# Resolve so the -v argument is valid even when the path has not been created yet.
+OUTPUT_DIR_ABS="$(cd "$OUTPUT_DIR" && pwd)"
+AUTH_FILE_ABS="$(cd "$(dirname "$AUTH_FILE")" && pwd)/$(basename "$AUTH_FILE")"
+
+# The session is mounted separately, read-only, rather than being required to sit
+# inside the output directory. It lives in ~/.microsoft-webauth and is a live
+# credential: it does not belong in the directory the exported notes are
+# collected into, and mounting it read-only means a bug in the container cannot
+# rewrite or delete it. Mounting the file rather than its directory also means
+# the container cannot see the other sessions sitting beside it.
+AUTH_MOUNT=()
+if [ ! -f "${OUTPUT_DIR_ABS}/$(basename "$AUTH_FILE_ABS")" ]; then
+    AUTH_MOUNT=(-v "${AUTH_FILE_ABS}:/data/auth/session.json:ro")
+    CONTAINER_AUTH_FILE="/data/auth/session.json"
+else
+    # Already inside the output directory: mounting it twice would be redundant,
+    # and the export should write its logs and notes beside it as documented.
+    #
+    # This leaves AUTH_MOUNT empty, which is the documented primary path, and an
+    # empty array expanded as "${AUTH_MOUNT[@]}" under `set -u` is an error on some
+    # bash builds: the wrapper died with
+    #
+    #   line 222: AUTH_MOUNT[@]: unbound variable
+    #
+    # before starting any container at all - so the documented way to run an
+    # export could not run, while the fallback path worked and hid the bug. The
+    # expansion below is guarded so an empty array contributes no arguments.
+    CONTAINER_AUTH_FILE="/data/output/$(basename "$AUTH_FILE_ABS")"
+fi
+
+# Logs go beside the notes, not inside the image. Without this the run's
+# app.log - the only record of what an export actually did - died with the
+# container, and the script's own "see logs/app.log" advice pointed at a path
+# that never existed on the host.
+ONENOTE_EXPORT_LOG_DIR=/data/output/logs
+
+echo "Container : $CONTAINER"
+echo "Image     : $IMAGE"
+echo "Auth file : $AUTH_FILE_ABS"
+echo "Output    : $OUTPUT_DIR_ABS"
+echo ""
+# Echoed to match what is really executed below. This line used to print
+# "microsoft-onenote-exporter $* --non-interactive", which was missing the
+# subcommand that the invocation adds - so the most reassuring line in the script
+# was describing a command that was never run.
+echo "Running: microsoft-onenote-exporter $SUBCOMMAND $* --auth-file $CONTAINER_AUTH_FILE"
+echo ""
+
+# Chromium needs more than Docker's default 64 MB of shared memory or it crashes
+# on memory-heavy pages, hence --shm-size. --init runs a tiny PID-1 reaper so
+# Chromium's child processes are cleaned up instead of accumulating as zombies
+# when the export ends.
+#
+# The container runs detached and the exit status is polled below, so the script
+# can report the result and the image can be reused for another run without
+# rebuilding it.
+docker run --detach \
+    --name "$CONTAINER" \
+    --init \
+    --shm-size=1g \
+    -e ONENOTE_EXPORT_LOG_DIR="$ONENOTE_EXPORT_LOG_DIR" \
+    -v "${OUTPUT_DIR_ABS}:/data/output" \
+    ${AUTH_MOUNT[@]+"${AUTH_MOUNT[@]}"} \
+    "$IMAGE" \
+    "$SUBCOMMAND" "$@" --auth-file "$CONTAINER_AUTH_FILE" >/dev/null
+
+# Wait for the export to finish.
+#
+# `docker wait` is used rather than a poll loop over `docker inspect`. A loop
+# written the obvious way reads State.ExitCode first and stops as soon as it is
+# non-empty - and that field is 0 *while the container is still running*, so the
+# loop exited on its first iteration and reported success for an export that had
+# not written a single file. `docker wait` blocks until the container actually
+# stops and then returns its status, which is the one question being asked here.
+#
+# It has no timeout, so a separate watchdog decides when to stop waiting and say
+# so. The cap is generous - a large notebook over a slow connection can
+# legitimately take tens of minutes - but past it the script reports rather than
+# appearing to still be working. The container is left running so it can be
+# inspected with `docker logs`.
+WAIT_LIMIT=$((60 * 60)) # one hour
+( sleep "$WAIT_LIMIT"
+  if docker inspect -f '{{.State.Running}}' "$CONTAINER" 2>/dev/null | grep -q true; then
+      echo "WARNING: the export is still running after $((WAIT_LIMIT / 60)) minutes." >&2
+      echo "         It has been left running; watch it with:" >&2
+      echo "           docker logs -f $CONTAINER" >&2
+      # 124 is the conventional timeout status, and is reported as a failure
+      # rather than a success so a pipeline cannot mistake it for a clean run.
+      docker stop -t 30 "$CONTAINER" >/dev/null 2>&1 || true
+  fi
+) &
+WATCHDOG_PID=$!
+
+# Wait for it, then propagate the status. The container runs the export as PID 1
+# under the reaper, so this is the container's exit status - which is the export's,
+# because the CLI exits with the code the export step reported.
+EXIT_CODE="$(docker wait "$CONTAINER")"
+
+kill "$WATCHDOG_PID" 2>/dev/null || true
+wait "$WATCHDOG_PID" 2>/dev/null || true
+
+echo ""
+if [ "$EXIT_CODE" -eq 0 ]; then
+    echo "Exported files are in: $OUTPUT_DIR_ABS"
+else
+    case "$EXIT_CODE" in
+        1)
+            echo "WARNING: the export failed and produced nothing usable." >&2
+            ;;
+        2)
+            echo "WARNING: the arguments were wrong - check --notebook or --notebook-link." >&2
+            ;;
+        3)
+            echo "NOTE: the export finished but some pages, sections or groups are missing." >&2
+            echo "      The notes that were written are complete and name any asset they" >&2
+            echo "      could not download. Re-run to try again." >&2
+            ;;
+        *)
+            echo "WARNING: the container exited with status $EXIT_CODE." >&2
+            ;;
+    esac
+    echo "Anything already written to $OUTPUT_DIR_ABS has been kept." >&2
+    echo "See logs/app.log inside the output directory for the full run." >&2
+fi
+
+exit "$EXIT_CODE"