first commit

docs/media/fonts/font-compress/src/bin/auto-boot.md

@@ -0,0 +1,69 @@
+# auto-boot
+
+## Purpose
+
+Pure side-effect entry imported by `suaveplan-font-compress.ts` for the
+shebang-launch case. The only behaviour is: if the running file is the
+`dist/bin/suaveplan-font-compress.js` binary (detected by the `argv[1]`
+basename), dynamically import the bin entry and run `main(process.argv.slice(2))`,
+then `process.exit` with the resulting code. The split exists so the
+`process.exit` branch — which cannot be honestly exercised from in-process
+without spawning a subprocess — can be excluded from coverage as a pure
+boot stub while the surrounding `main()` (which does the actual work) is
+fully covered by the in-process suites in this directory.
+
+## Features
+
+- Detects direct invocation via `process.argv[1]` rather than
+  `fileURLToPath(import.meta.url)` so the check works regardless of the
+  module's own location (auto-boot is a sibling of the entry, not the
+  entry itself).
+- Dynamic import of `./suaveplan-font-compress.js` so this module's static
+  init does not depend on the bin entry's static init, avoiding any
+  cyclic-import surprises with bundlers.
+- Maps a successful `main()` resolve to `process.exit(code)`; maps a
+  rejected promise to a stderr-printed message and `process.exit(1)`.
+
+## Usage: Basic
+
+The module has no exports — importing it as a side-effect is the entire
+API:
+
+```ts
+// In suaveplan-font-compress.ts
+import "./auto-boot.js";
+```
+
+## Usage: Advanced
+
+```sh
+# Direct shebang launch — boot runs through this module.
+node dist/bin/suaveplan-font-compress.js ./fonts -o ./out
+
+# In-process import — boot detects argv[1] does not end with the binary
+# name and stays silent; tests can then call `main()` directly without
+# accidentally launching a second instance.
+import { main } from "@suaveplan/font-compress/bin/suaveplan-font-compress";
+await main(["./fonts", "-o", "./out"]);
+```
+
+## API Reference
+
+No public API. The module's side effect runs once at import time:
+
+1. Check `process.argv[1]` for the binary basename suffix.
+2. If matched, dynamically import the bin entry and call its `main`.
+3. Map the resolved exit code to `process.exit(code)`; map a rejection
+   to stderr write + `process.exit(1)`.
+
+## Implementation Notes
+
+`process.argv[1].endsWith("suaveplan-font-compress.js")` is intentionally
+basename-based — the absolute path comparison used by single-file bin
+patterns does not work here because auto-boot is a sibling, not the entry.
+The `try/catch` around the check guards against environments where
+`process` is undefined (some non-Node runtimes) and against any pathologic
+`argv` shapes; both fall back to "not direct invocation" which is the safe
+default for an import-only module. Coverage excludes this file because
+every branch is either a `process.argv` predicate or a `process.exit`
+side-effect — neither can be honestly faked from in-process.