@msout/microsoft-onenote-exporter 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -6,6 +6,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msout/microsoft-onenote-exporter",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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": {

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,