@nowline/cli 0.2.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Lolay, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,372 @@
+# @nowline/cli
+
+The `nowline` command-line tool parses, validates, and renders `.nowline` roadmap files.
+
+**License:** Apache 2.0
+**Part of:** [`lolay/nowline`](https://github.com/lolay/nowline) monorepo
+
+## Install
+
+A single `nowline` binary ships every export format (SVG, PNG, PDF, HTML,
+Markdown+Mermaid, XLSX, MS Project XML) plus AST round-trip
+(`json` ↔ `nowline`). Approximate size: ~70 MB (the bun runtime is
+~60 MB of that — see
+[`specs/cli-distribution.md`](../../specs/cli-distribution.md) for why
+we don't ship a smaller "tiny" tier).
+
+```bash
+# macOS / Linux / WSL — Homebrew
+brew install lolay/tap/nowline
+
+# Debian / Ubuntu — download .deb from GitHub Releases
+curl -L -o nowline.deb \
+  https://github.com/lolay/nowline/releases/latest/download/nowline_amd64.deb
+sudo dpkg -i nowline.deb
+
+# Windows — direct .exe download from GitHub Releases
+#   nowline-windows-x64.exe
+#   (unsigned; see SmartScreen walkthrough below)
+
+# npm (any platform)
+npm install -g @nowline/cli
+# or one-shot: npx @nowline/cli roadmap.nowline -o -
+```
+
+After any of the package-manager installs above, `man nowline` shows the
+CLI manual (flags + a `LANGUAGE` cheatsheet) and `man 5 nowline` shows
+the full `.nowline` DSL reference. The Homebrew formula's
+`resource "manpage"` / `resource "manpage5"`, the `.deb`'s
+`/usr/share/man/man1/nowline.1.gz` / `/usr/share/man/man5/nowline.5.gz`,
+and npm's `"man"` field (which lists both files) all install the same
+hand-authored mdoc sources from [`man/nowline.1`](./man/nowline.1) and
+[`man/nowline.5`](./man/nowline.5). For direct binary downloads from
+GitHub Releases, both man pages ship as separate `nowline.1` and
+`nowline.5` assets alongside the platform binaries.
+
+## Usage
+
+`nowline` is **verbless**: rendering is the default. Other modes are flags on the same command:
+
+```bash
+nowline <input> [options]              # render (default)
+nowline <input> --serve [-p <port>]    # live HTTP preview
+nowline --init [<name>]                # scaffold a starter file
+nowline <input> --dry-run              # validate-only (no write)
+nowline --help                         # print help
+nowline --version                      # print version
+nowline                                # no args → print help
+```
+
+### Examples
+
+```bash
+nowline roadmap.nowline                          # writes ./roadmap.svg in cwd
+nowline roadmap.nowline -f png                   # writes ./roadmap.png
+nowline roadmap.nowline -f pdf                   # writes ./roadmap.pdf
+nowline roadmap.nowline -f html                  # writes ./roadmap.html
+nowline roadmap.nowline -f mermaid               # writes ./roadmap.md
+nowline roadmap.nowline -f xlsx                  # writes ./roadmap.xlsx
+nowline roadmap.nowline -f msproj                # writes ./roadmap.xml
+nowline roadmap.nowline -o roadmap.pdf           # format inferred from extension
+nowline roadmap.nowline -o -                     # SVG → stdout (Unix dash)
+nowline roadmap.json -f svg                      # JSON-AST input
+cat foo.nowline | nowline -                      # stdin → ./roadmap.svg
+nowline roadmap.nowline -f json -o roadmap.json  # convert text → JSON
+nowline roadmap.nowline --dry-run                # validate-only; nothing written
+nowline roadmap.nowline --serve -p 8080          # live preview on :8080
+nowline --init                                   # ./roadmap.nowline
+nowline --init my-project                        # ./my-project.nowline
+nowline roadmap.nowline -f pdf -o report         # auto-extension → report.pdf
+nowline roadmap.nowline -f pdf --page-size a4 --orientation landscape --margin 0.5in
+nowline roadmap.nowline -f png --scale 3         # 3x raster
+nowline roadmap.nowline --headless               # bundled DejaVu fonts (deterministic)
+```
+
+## Flags
+
+### I/O
+
+| Flag                       | Default                                | Notes                                          |
+|----------------------------|----------------------------------------|------------------------------------------------|
+| `-f, --format <fmt>`       | inferred                               | `svg`, `png`, `pdf`, `html`, `mermaid`, `xlsx`, `msproj`, `json`, `nowline`. |
+| `-o, --output <path>`      | `<cwd>/<input-base>.<format>`           | `-` for stdout. Existing files silently overwritten. |
+| `--input-format <fmt>`     | by extension; stdin → `nowline`        | `nowline` or `json`.                            |
+
+### Mode flags (mutually exclusive)
+
+| Flag                | Description                                                       |
+|---------------------|-------------------------------------------------------------------|
+| `--serve`           | Live HTTP preview. Opt-in `-o <path>` writes on each rebuild.     |
+| `--init [<name>]`   | Scaffold a starter `.nowline` in cwd. Auto-appends `.nowline`.    |
+| `-n, --dry-run`     | Run pipeline; skip the write. Replaces the old `validate` verb.   |
+
+### Render options
+
+| Flag                  | Default      | Notes                                       |
+|-----------------------|--------------|---------------------------------------------|
+| `-t, --theme <name>`  | `light`      | `light` \| `dark`.                          |
+| `--now YYYY-MM-DD`    | today (UTC)  | Override the now-line anchor date. Use `--now -` to suppress it. |
+| `--no-links`          | (off)        | Omit link icons from items.                 |
+| `-s, --scale <n>`     | `1`          | Raster scale (PNG only).                    |
+| `--strict`            | (off)        | Promote asset / sanitizer warnings to errors. |
+| `-w, --width <px>`    | `1280`       | Canvas width.                                |
+| `--asset-root <dir>`  | input dir    | Root for `logo:` / image refs.              |
+
+### Format-specific options
+
+| Flag                       | Default      | Applies to | Notes |
+|----------------------------|--------------|------------|-------|
+| `--page-size <size>`       | `letter`     | pdf        | Preset (`letter`, `legal`, `tabloid`, `ledger`, `a1`–`a5`, `b3`–`b5`), `content` for auto-fit, or `WxHunit` for custom (`8.5x11in`, `210x297mm`). |
+| `--orientation <name>`     | `auto`       | pdf        | `portrait` \| `landscape` \| `auto`. |
+| `--margin <length>`        | `36pt`       | pdf        | Page margin. Bare numbers are points; `0.5in`, `12mm`, `1cm` accepted. |
+| `--font-sans <path\|alias>` | platform-resolved | png, pdf | TTF/OTF path, or alias `sf`, `helvetica`, `dejavu`, etc. |
+| `--font-mono <path\|alias>` | platform-resolved | png, pdf | TTF/OTF path or alias for monospace. |
+| `--headless`               | (off)        | png, pdf   | Skip platform font probe; use bundled DejaVu pair. Byte-stable across machines. |
+| `--start YYYY-MM-DD`       | `today`       | msproj    | Anchor date for relative-only roadmaps. |
+
+### Serve options
+
+| Flag                 | Default     |
+|----------------------|-------------|
+| `-p, --port <n>`     | `4318`      |
+| `--host <host>`      | `127.0.0.1` |
+| `--open`             | (off)       |
+
+### Logging (mutually exclusive)
+
+| Flag             | Description                          |
+|------------------|--------------------------------------|
+| `-v, --verbose`  | Extra diagnostics on stderr.         |
+| `-q, --quiet`    | Suppress non-error stderr.           |
+
+### Standard
+
+| Flag             | Description                          |
+|------------------|--------------------------------------|
+| `-h, --help`     | Print help, exit 0.                  |
+| `-V, --version`  | Print version, exit 0.               |
+
+## Behavior contracts
+
+### Format resolution (precedence chain)
+
+1. **`-f / --format` flag** — explicit always wins.
+2. **`-o <path>` extension** — recognized: `.svg`, `.png`, `.pdf`, `.html`/`.htm`, `.md`/`.markdown` (mermaid), `.xlsx`, `.json`, `.nowline`. `.xml` is **ambiguous** and requires `-f msproj`.
+3. **`.nowlinerc` `defaultFormat`** — project default.
+4. **`svg`** — built-in fallback.
+
+If `-f` and `-o` extension disagree, `-f` wins and the output filename is preserved as written (no auto-rename).
+
+### Output extension auto-add
+
+- `-o report -f pdf` → `report.pdf` (no extension → append canonical).
+- `-o report.pdf -f pdf` → `report.pdf` (matching → leave alone).
+- `-o foo.txt -f pdf` → `foo.txt` (mismatched → leave alone, write PDF bytes there).
+- `-o -` (stdout) is never rewritten.
+
+### Default output paths
+
+All default-named outputs land in **cwd**:
+
+- File input: `<cwd>/<input-base>.<format>`.
+- Stdin input: `<cwd>/roadmap.<format>`.
+- `--init` (no `-o`): `<cwd>/<name>.nowline` (default name `roadmap`).
+
+Existing files are silently overwritten — no `--force` flag, matching POSIX redirection and peer tools (mmdc, d2, prettier, tsc).
+
+### Stdout
+
+- `-o -` is the only way to write to stdout (Unix dash convention).
+- Binary formats (png, pdf, xlsx) on a TTY are refused with exit 2 (`nowline: binary output (png) to terminal refused; use -o or pipe to a file`). Pipes / redirects are fine.
+
+### Mode dispatch
+
+Mutual exclusivity rules (all exit 2 with a message):
+
+- `--serve` + `--init`.
+- `--dry-run` + `--serve` (serve doesn't write by default).
+- `--dry-run` + `--init` (init *is* the write).
+- `-v / --verbose` + `-q / --quiet`.
+
+`nowline` (no args) prints help and exits 0 (matches git, kubectl, gh, cargo, docker).
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | Success |
+| 1    | Validation error |
+| 2    | Usage error (missing input, bad flags, unsupported format, file not found, binary→TTY refusal) |
+| 3    | Output error (cannot write to destination, exporter failure, page too small for margin) |
+
+## Configuration: `.nowlinerc`
+
+On any operation that takes an `<input>` file, `nowline` walks up from the input file's directory looking for a `.nowlinerc` (JSON or YAML). The nearest one wins. CLI flags override config values. Environment variables are not consulted.
+
+```yaml
+# .nowlinerc (YAML)
+theme: dark
+defaultFormat: svg
+width: 1200
+
+# m2c format defaults — override with CLI flags at any time
+pdfPageSize: a4            # --page-size
+pdfOrientation: landscape  # --orientation
+pdfMargin: 0.5in           # --margin
+fontSans: sf               # --font-sans  (alias or path)
+fontMono: sf-mono          # --font-mono
+headlessFonts: false       # --headless
+```
+
+```json
+{
+  "theme": "dark",
+  "defaultFormat": "svg",
+  "width": 1200,
+  "pdfPageSize": "a4",
+  "pdfOrientation": "landscape",
+  "pdfMargin": "0.5in",
+  "fontSans": "sf",
+  "fontMono": "sf-mono",
+  "headlessFonts": false
+}
+```
+
+Unknown keys are ignored.
+
+## Validation (`--dry-run`)
+
+```bash
+nowline roadmap.nowline --dry-run
+nowline roadmap.nowline -n                       # short alias
+nowline roadmap.nowline -n --diagnostic-format json
+```
+
+Each diagnostic is rendered in a biome/oxc-style frame via `@babel/code-frame`:
+
+```
+roadmap.nowline:7:34 error: Unknown reference 'auth-refactro' in after — did you mean 'auth-refactor'?
+  5 |   item auth-refactor "Auth refactor" size:l
+  6 |   parallel after:auth-refactor
+> 7 |     group audit-track "Audit Track" labels:security
+    |                                     ^^^^^^^^^^^^^^^
+  8 |       item audit-log "Audit log v2" size:xl before:code-freeze
+```
+
+`--diagnostic-format json` emits the stable diagnostic schema:
+
+```ts
+type Diagnostic = {
+  file: string;
+  line: number;        // 1-based
+  column: number;      // 1-based
+  severity: 'error' | 'warning';
+  code: string;
+  message: string;
+  suggestion?: string;
+};
+```
+
+Exit 0 if no errors; exit 1 if any errors. Warnings never change the exit code.
+
+## JSON AST round-trip
+
+`-f json` emits the JSON AST; `-f nowline` re-prints canonical `.nowline`:
+
+```bash
+nowline roadmap.nowline -f json -o roadmap.json   # text → JSON
+nowline roadmap.json -f nowline -o roadmap.nowline # JSON → text (canonical)
+```
+
+The JSON form is a **versioned, published contract** (`$nowlineSchema: "1"`) intended for MCP (m7) and editor (m5) round-trips:
+
+```ts
+type NowlineDocument = {
+  $nowlineSchema: "1";
+  file: { uri: string; source: string };
+  ast: NowlineFileNode;
+};
+```
+
+Every node carries `$type`, `$position`, and the properties defined by the corresponding `@nowline/core` AST interface. Container back-references (`$container`, `$containerProperty`, `$containerIndex`) are omitted — parent-child relationship is captured by document structure.
+
+### Canonical `.nowline` printer rules
+
+- **Indent:** 2 spaces.
+- **Positional order on declaration lines:** `id` → `title` → keyed properties.
+- **Keyed-property order:** `date, length, on, duration, status, owner, after, before, remaining, labels, style, link, (any remaining keys, alphabetical)`.
+- **List shape:** single-element lists render as bare (`labels:enterprise`); multi-element lists use bracket form (`labels:[enterprise, security]`).
+- **`description` sub-directive:** rendered on its own line indented one level under its host.
+- **Comments:** not preserved across round-trips. Documented limitation; a follow-up grammar ticket will add trivia support.
+
+Round-trip property: for every file in `examples/`, `text → json → text` and `json → text → json` are idempotent modulo comment loss. Enforced by the test suite.
+
+## `--serve`
+
+Live-reload preview. Opens a minimal HTML shell at `http://<host>:<port>/` that fetches `/svg` and subscribes to `/events` (SSE). On file changes, the server re-parses, re-validates, re-lays-out, and re-renders; clients refresh automatically. Validation errors appear as an overlay on top of the most recent successful render.
+
+```bash
+nowline roadmap.nowline --serve
+nowline roadmap.nowline --serve -p 4400 -t dark --open
+nowline roadmap.nowline --serve -o latest.svg     # rewrites latest.svg on each rebuild
+```
+
+`--serve` is intended for local authoring only. It is not a production preview service. `-o -` (stdout) is rejected.
+
+## `--init`
+
+Create a starter `.nowline` file in the current directory. Three templates (`minimal`, `teams`, `product`) correspond to the three files in `examples/` and are embedded into the CLI at build time — binaries are self-contained.
+
+- Positional argument is the **project name**, not a file path.
+- `.nowline` is auto-appended if missing.
+- Other extensions (`.txt`, `.json`) are rejected with exit 2.
+- Existing files are silently overwritten.
+
+```bash
+nowline --init                    # ./roadmap.nowline (default name)
+nowline --init my-project         # ./my-project.nowline (auto-append)
+nowline --init my-plan.nowline    # ./my-plan.nowline (literal)
+nowline --init --template product # use the product template
+```
+
+## Arg parser choice
+
+`@nowline/cli` parses arguments with Node's native [`util.parseArgs`](https://nodejs.org/api/util.html#utilparseargsconfig). Reasons:
+
+- Zero runtime dependency.
+- Native short/long flag support, kebab-case option names, mixed-position positionals, and the `--` end-of-options sentinel.
+- Verbless dispatch is straightforward — modes are just boolean flags resolved after parsing.
+
+Supporting libraries:
+
+- [`@babel/code-frame`](https://babeljs.io/docs/babel-code-frame) — biome/oxc-style source excerpts with caret/tilde underlines for `--dry-run` text output.
+- [`js-yaml`](https://github.com/nodeca/js-yaml) — `.nowlinerc` YAML parsing (JSON also supported).
+
+## Distribution
+
+A single `nowline` binary ships per platform, bundling every
+`@nowline/export-*` package. Compiled with `bun build --compile`; the
+CLI's format dispatch uses dynamic `import()` of each per-format package
+so the heavy exporter deps stay off cold paths and the binary stays
+straightforward to slim down later if a profile change ever justifies
+re-introducing a tier (see
+[`specs/cli-distribution.md`](../../specs/cli-distribution.md)).
+
+Six platform binaries ship per release (macOS arm64/x64, Linux
+x64/arm64, Windows x64/arm64), attached to every GitHub Release. Size
+budgets are per target (Bun's standalone runtime varies by ~50 MB across
+platforms): macOS-arm64 ~70 MB, macOS-x64 ~75 MB, Linux ~107 MB, Windows
+~119–122 MB. CI asserts on disk for every target via
+[`packages/cli/scripts/compile.mjs`](./scripts/compile.mjs). See
+[`specs/cli-distribution.md`](../../specs/cli-distribution.md#size-budget)
+for the full ceiling table.
+
+### Windows SmartScreen walkthrough
+
+The shipped `.exe` binaries are **unsigned**. Windows may show a SmartScreen warning ("Windows protected your PC"). To run the downloaded binary:
+
+1. Right-click the `.exe` → **Properties**.
+2. Check **Unblock** at the bottom of the **General** tab → **OK**.
+3. Run the binary from a terminal (`cmd` or PowerShell).
+
+Corporate endpoints may block unsigned binaries entirely. In that case, `npm install -g @nowline/cli` (which runs on Node/Bun) is an alternative.

package/dist/cli/args.d.ts

@@ -0,0 +1,54 @@
+export type ModeKind = 'render' | 'serve' | 'init' | 'help' | 'version';
+export interface ParsedArgs {
+    /** Resolved mode after dispatch (mutual-exclusivity already checked). */
+    mode: ModeKind;
+    /** Positional argument, or undefined. Render = input path. Init = project name. Serve = input path. */
+    positional?: string;
+    /** True if `--dry-run` / `-n` was passed (only valid for render mode). */
+    dryRun: boolean;
+    /** Logging level. Verbose and quiet are mutually exclusive. */
+    logLevel: 'verbose' | 'quiet' | 'normal';
+    output?: string;
+    format?: string;
+    inputFormat?: string;
+    theme?: string;
+    /** Now-line date string from `--now`. Undefined means "use the actual
+     *  current date" (the default). The literal value `"-"` means
+     *  "suppress the now-line entirely" (mirrors the Unix-`-` convention
+     *  used elsewhere in the CLI). Otherwise expected as YYYY-MM-DD;
+     *  parsed downstream by resolveNowArg. */
+    now?: string;
+    noLinks: boolean;
+    scale?: string;
+    strict: boolean;
+    width?: string;
+    assetRoot?: string;
+    pageSize?: string;
+    orientation?: string;
+    margin?: string;
+    fontSans?: string;
+    fontMono?: string;
+    headless: boolean;
+    start?: string;
+    /**
+     * BCP-47 locale override (`fr-CA`, `fr`, …). When omitted the CLI
+     * falls back to `LC_ALL` / `LC_MESSAGES` / `LANG`, then to the
+     * file's `nowline v1 locale:` directive, then to `en-US`. See
+     * `specs/localization.md`.
+     */
+    locale?: string;
+    port?: string;
+    host?: string;
+    open: boolean;
+    diagnosticFormat?: string;
+    template?: string;
+}
+/**
+ * Pure argument parser. Walks `argv` once, identifies mode flags, applies
+ * mutual-exclusivity rules, and returns a fully-resolved `ParsedArgs`. Throws
+ * `CliError(ExitCode.InputError)` for usage errors.
+ *
+ * Help / version short-circuit any other flag combinations.
+ */
+export declare function parseArgv(argv: readonly string[]): ParsedArgs;
+//# sourceMappingURL=args.d.ts.map

package/dist/cli/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAExE,MAAM,WAAW,UAAU;IACvB,yEAAyE;IACzE,IAAI,EAAE,QAAQ,CAAC;IACf,uGAAuG;IACvG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAC;IAChB,+DAA+D;IAC/D,QAAQ,EAAE,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;IAGzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IAGrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;8CAI0C;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IAGnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAGhB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IAGd,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAG1B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU,CAsK7D"}