Nowline

コードとしてのロードマップを、すべての人に。
人が読みやすく、AI 向けに構築されたロードマップ。
プレーンな .nowline テキストファイル。バージョン管理に対応。SVG、PNG、PDF、HTML、Mermaid、XLSX、MS Project XML に出力できます。

---

Nowline とは？

Nowline は、製品やエンジニアリングのロードマップを記述するための、テキストファーストな DSL です。人にも機械にも読みやすく、インデントとキーワードを使った差分の確認しやすいプレーンな .nowline テキストファイルを作成すると、ツールでタイムラインとして描画したり、検証したり、組み合わせたりできます。

examples/minimal.nowline:

nowline v1

roadmap minimal "Starter" start:2026-01-05 scale:2w author:"Jane Doe"

swimlane engineering "Engineering"
  item research "Research"  duration:3w status:done
  item design   "Design"    duration:2w status:in-progress remaining:5d
  item build    "Build"     duration:3w status:planned

次のように描画されます。

Nowline を選ぶ理由

• ガントチャートではなく、テキスト。 バージョン管理でき、差分を確認でき、PR でレビューできます。
• XML ではなく、インデント。 人の思考に合ったアウトライン形式でロードマップを読めます。
• ミスを検出できる厳密さ。 30 以上の検証ルールを備え、行番号と列番号を含む明確なエラーメッセージを表示します。
• 組み合わせ可能。 include でほかのファイルを取り込み、merge／ignore／isolate のセマンティクスを明示的に指定できます。

クイックスタート

パッケージマネージャーから CLI をインストールします。

brew trust lolay/tap                                 # macOS / Linux / WSL (one-time)
brew install lolay/tap/nowline

Debian／Ubuntu および Windows のユーザーは、GitHub Releases から最新の .deb または .exe をダウンロードできます。インストール方法の一覧（man nowline のセットアップを含む）は、packages/cli/README.md をご覧ください。

ツールチェーン

Node のポリシーは 2 段階です。@nowline/* パッケージを利用するには Node ≥ 22（公開する各パッケージの engines.node）、開発するには Node 26（.nvmrc）が必要です。CI ではすべての PR で両方のバージョンをテストします。ポリシーとバージョン更新手順の詳細は、ツールチェーンとサポート対象バージョンをご覧ください。

最初のロードマップを描画します。

nowline examples/minimal.nowline                     # writes ./minimal.svg
nowline --version

または、テンプレートから新しいファイルを作成します。

nowline --init my-project                            # ./my-project.nowline
nowline --init my-project -t teams                   # ./my-project.nowline (teams template)

AI エージェントに Nowline ツールを使わせるには、このリポジトリのマーケットプレイスからプラグインをインストールします。Claude Code の場合：

/plugin install nowline --marketplace lolay/nowline

GitHub Copilot CLI と Codex は同じマーケットプレイスを参照します。これらの方法や、MCP サーバーを追加するほかの方法については、plugins/nowline/README.md をご覧ください。

VS Code／Cursor／VSCodium 拡張機能は、VS Code Marketplace または Open VSX で Nowline を検索してください。

0.x のバージョン管理。 埋め込み機能の仕様と IDE 対応の拡張を確定する間、nowline は 0.x.y です。マイナーバージョン間で公開 API が変更される場合があります。完全な SemVer の保証は 1.0 のリリース後に適用されます。バージョンの契約については、specs/releasing.md をご覧ください。

ローカル開発用にチェックアウトから実行する場合（pnpm install && pnpm build）は、CONTRIBUTING.md をご覧ください。

CLI を使う

nowline は動詞不要です。描画がデフォルトの動作で、ほかの操作は同じコマンドにフラグを指定して実行します。

描画（デフォルト）

nowline roadmap.nowline                          # writes ./roadmap.svg
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 to stdout
nowline roadmap.nowline --theme dark --now 2026-03-15
nowline roadmap.nowline --now - --asset-root ./brand --no-links --strict
nowline roadmap.nowline -f pdf --page-size a4 --orientation landscape --margin 0.5in
cat roadmap.nowline | nowline -                  # stdin → ./roadmap.svg

描画パイプラインは、@nowline/core による解析 → @nowline/layout によるレイアウト → @nowline/renderer による SVG 生成 → 形式別のエクスポートです。同じ入力、テーマ、--now に対して、出力はバイト単位で決定論的です。単一の nowline バイナリで、すべての形式を利用できます。インストール方法は、packages/cli/README.md をご覧ください。

検証（--dry-run）

書き込みを行わず、パイプライン全体（解析 + 検証 + レイアウト + 書式設定）を実行します。成功時は 0、エラーが出力された場合は 1 で終了します。

nowline roadmap.nowline --dry-run
nowline roadmap.nowline -n                          # short alias
cat roadmap.nowline | nowline - --dry-run           # read stdin
nowline roadmap.nowline -n --diagnostic-format json # machine-readable output
nowline - -n --format=json < roadmap.nowline        # same, json is the default here

--diagnostic-format text|json で stderr の形式を選択します。--dry-run --format=json の場合はデフォルトで json、それ以外は text です。JSON モードでは、診断がある場合（警告を含む）、{ "$nowlineDiagnostics": "1", "diagnostics": [...] } ドキュメントを 1 つ stderr に出力するため、警告のみのソースはドキュメントを出力して 0 で終了します。問題のないソースでは何も出力されません。

テキスト ↔ JSON の変換

変換には -f json（逆方向の場合は -f nowline）を指定します。入力形式は拡張子から推測されます。通常と異なるファイル名の場合は、--input-format で上書きできます。

nowline roadmap.nowline -f json -o roadmap.json    # text → JSON
nowline roadmap.json -f nowline -o roadmap.nowline # JSON → text (canonical)
nowline roadmap.nowline -f json -o - | jq '.ast.roadmapDecl.name'

出力される JSON には最上位の "$nowlineSchema": "1" が含まれるため、後続のツールでスキーマの変更を検出できます。ラウンドトリップではコメントは保持されません。標準プリンターの規則については、packages/cli/README.md を参照してください。

起動（--serve）

ブラウザーでライブリロード対応のプレビューを起動します。作成中の確認に便利です。

nowline roadmap.nowline --serve                    # http://127.0.0.1:4318
nowline roadmap.nowline --serve -p 4400 -t dark --open
nowline roadmap.nowline --serve -o latest.svg      # rewrite latest.svg on each rebuild

サーバーはファイルが変更されるたびに再解析、再検証、再レイアウト、再描画を行います。接続中のクライアントは、Server-Sent Events によって自動的に更新されます。検証エラーは、直近の正常な描画の上にオーバーレイとして表示されます。

初期化（--init）

現在の作業ディレクトリに新しい .nowline ファイルのひな形を作成します。位置引数はファイルパスではなく、プロジェクト名です。.nowline は自動的に追加されます。

nowline --init                              # ./roadmap.nowline (default name)
nowline --init my-project                   # ./my-project.nowline
nowline --init my-plan.nowline              # ./my-plan.nowline (literal)
nowline --init my-project --template=teams  # use the teams template

minimal、teams、product は examples/ 内のファイルに対応しています。既存のファイルは警告なしで上書きされます。

終了コード

コード	意味
0	成功
1	検証エラー（解析失敗、無効な参照、インクルードの欠落やインクルードされたファイル間の wave ルールなど、あらゆるインクルードエラー）
2	使用方法のエラー（入力の欠落、不正なフラグ、未対応の形式、ファイルが見つからない、空の stdin、無効な --diagnostic-format、バイナリから TTY への出力拒否）
3	出力エラー（出力先に書き込めない）

マニュアル

パッケージマネージャー（brew install lolay/tap/nowline、npm install -g @nowline/cli、または GitHub Releases の .deb）でインストールすると、man nowline で CLI マニュアルを、man 5 nowline で DSL の完全なリファレンスを確認できます。両方の man ページは、すべての GitHub Release で単体のアセットとしても配布されています。mdoc ソースについては、packages/cli/man/ を参照してください。

言語の概要

ファイル構造

nowline v1                        // 1. version directive (optional, must be first)

include "shared/teams.nowline"    // 2. includes
include "brand.nowline" config:isolate

config                            // 3. config section (optional)
scale
  name: weeks
style enterprise
  bg: blue
  fg: navy

roadmap r "My Roadmap"            // 4. roadmap section

swimlane platform
  item x "Work item" duration:1w status:done

エンティティ

キーワード	用途
roadmap	最上位のロードマップ宣言です。1 ファイルにつき最大 1 つです。
swimlane	作業の横方向のレーンです。
item	スイムレーン内の作業単位です。
parallel	子要素が並行して実行されるブロックです。
group	項目をまとめて表示する論理的なグループです。
anchor	タイムライン上の日付に名前を付けます。
milestone	作業に依存する、特定時点のマーカーです。
wave	すべてのスイムレーンにまたがるバリアです。次の wave の作業は、この wave が終了するまで開始されません。
footnote	1 つ以上のエンティティにひも付く注記です。
person、team	所有者への参照です。
non-working、working	作業時間を消費しない日（週末、祝日、休業日）と、それらを取り消す例外です。date:、start: / end:、または every: を持つ設定エントリです。weekend という名前の宣言は、標準の週末を置き換えます。タイトル付きの日付指定の休業日はチャート上にラベル付けされ（Thanksgiving · 2d）、MS Project と Mermaid のエクスポートにも反映されます。タイトル付きの稼働日は、追加する日数とともにラベル付けされます（Crunch Saturday · +1d）。
style、symbol、label、size、status、scale、calendar、default	設定および宣言のエントリです。

プロパティ

item auth "Auth refactor"
  duration: 2w              // duration literal: d, w, m, q, y
  status: in-progress       // builtin or custom from config
  owner: sam                // id reference (person or team)
  wave: build               // barrier the item belongs to (a declared wave)
  after: kickoff            // dependency (single)
  after: [kickoff, approvals] // dependency (list)
  remaining: 30%             // percentage
  labels: [security, p0]     // list of label ids
  link: https://…            // URL (bare, no quotes)

ロードマップの開始日

roadmap には、タイムラインの基準点となる任意の start:YYYY-MM-DD を指定できます。

roadmap platform-2026 "Platform 2026" start:2026-01-06

• ロードマップに anchor が含まれる場合、または date: プロパティを持つ milestone が含まれる場合、start: は必須です。
• これらの日付はすべて start: 以降でなければなりません。
• duration: と after: のみで構成される完全な相対指定のロードマップには、start: は不要です。
• roadmap:ignore を使わない include 全体で、親と各インクルード先のロードマップは start: の値が一致していなければなりません。どちらも未指定であるか、どちらも同じ値を指定する必要があります。不一致はエラーになり、暗黙に上書きされることはありません。

インクルード

include "teams.nowline"                     // merge everything (default)
include "snippet.nowline"  config:ignore    // skip child config
include "partner.nowline"  roadmap:isolate  // render child as a separate region

• merge — デフォルトです。子の内容をマージし、定義が競合する場合は親の定義を優先します。
• ignore — 該当する種類の子の内容を破棄します。
• isolate — 子のロードマップを独立した領域として保持します（子に roadmap が必要です）。

ウェーブはマージされません。roadmap:merge または roadmap:isolate の場合、ロードマップ、スイムレーン、またはウェーブを宣言するインクルード先のファイルは、親と同じウェーブを同じ順序で、同じ開始下限とともに宣言する必要があります（NL.E0202）。

文法の詳細については、specs/dsl.md を参照してください。

例

段階的に内容が充実する例を収録しています。main のすべてのビルドでこれらと、tests/ のレンダラーフィクスチャが review.nowline.dev に表示されます。

• examples/minimal.nowline — 最小限の完全なファイルです。
• examples/capacity.nowline — レーンと項目の capacity:。オンコールサポートがチームの稼働時間の 4 分の 1 を占める例と、レーンの稼働率の下線表示です。
• examples/sizing.nowline — T シャツサイズによる size: の指定と、capacity:（並行作業）によるカレンダー期間の短縮です。
• examples/teams.nowline — 担当者、チーム、アンカー、マイルストーン、脚注です。
• examples/product.nowline — 完全な設定、スタイル、ラベル、並行作業、グループ、説明です。
• examples/long.nowline — ストレステスト用です。8 個のスイムレーン、約 160 個の項目、並行作業、グループ、アンカー、マイルストーン、脚注、複数領域にまたがるラベルを含みます。レイアウトとレンダリングのパフォーマンス測定に使用します。
• examples/nested.nowline + examples/nested/ — 親の Security スイムレーンと、チームごとに分離された 5 つのロードマップのインクルード（iOS、Android、Web、Platform、Data）です。roadmap:isolate の例です。
• examples/waves.nowline — wave による障壁です。3 つのレーンにまたがる 3 つのウェーブ（Foundations、Build、Launch）、子要素を割り当てる group wave:、ウェーブに属さないバックグラウンド作業、ウェーブの after: に設定されたマイルストーンを含みます。
• examples/waves-program.nowline + examples/waves-program/ — 複数チームのウェーブです。Web チームと API チームのファイルが開始下限付きで同じウェーブを再宣言するため、それぞれを単独でレンダリングでき、プログラムファイルでは 1 つの障壁のもとにマージされます。

エディターのサポート

TextMate 文法は grammars/nowline.tmLanguage.json にあります。TextMate 文法に対応するエディター（VS Code、Sublime Text、Zed、サードパーティープラグイン経由の IntelliJ など）で使用できます。専用の LSP サーバーと VS Code 拡張機能は、packages/lsp/ と packages/vscode-extension/ で開発中です。

ライブラリとしての使用

@nowline/core は、Langium を基盤とする、純粋な TypeScript 製のパーサー、型付き AST、バリデーターです。CLI が解析後に行う処理はすべて、このライブラリを使って構築されています。API と使用例については、packages/core/README.md を参照してください。

ステータス

Nowline は v0.x 段階です。Homebrew、npm、VS Code Marketplace、Open VSX、GitHub Releases で公開されています。パーサー、バリデーター、レイアウト、レンダラー、すべてのエクスポート形式（SVG、PNG、PDF、HTML、Markdown+Mermaid、XLSX、MS Project XML）、および動詞なしの CLI（--dry-run、--init、--serve）は、現在ご利用いただけます。埋め込み機能と IDE 拡張が整うまで、0.x のマイナーバージョン間で破壊的変更が行われる可能性があります。完全な SemVer の保証は 1.0 から適用されます。リリースごとのロードマップは specs/milestones.md をご覧ください。

コントリビューション

バグ報告、機能リクエスト、プルリクエストを歓迎します。環境設定、ビルド／テストコマンド、想定されるワークフローについては、まず CONTRIBUTING.md をご確認ください。イシューを作成する前に、.github/ISSUE_TEMPLATE/ にあるテンプレートをご確認ください。セキュリティに関する問題は SECURITY.md に従って報告してください。すべての参加者は CODE_OF_CONDUCT.md に定める行動規範に従うものとします。

DSL、レンダラー、CLI、IDE 連携、OSS のマイルストーンに関する設計仕様は specs/ にあります。コードに手を加える前に、まずこちらで Nowline の設計をご確認ください。

ライセンス

Apache 2.0 — 詳細は LICENSE をご覧ください。