@nowline/cli 0.5.1 → 0.6.0

package/src/commands/render.ts

@@ -1,9 +1,21 @@
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
-import { resolveIncludes } from '@nowline/core';
+import {
+    type ExportFormat,
+    exportDocument,
+    type HostEnv,
+    type RenderInputs,
+} from '@nowline/export';
 import { lengthToPoints, parseLength } from '@nowline/export-core';
-import { layoutRoadmap, normalizeThemeName, type ThemeName } from '@nowline/layout';
-import { type AssetResolver, renderSvg } from '@nowline/renderer';
+import {
+    type NormalizedZone,
+    normalizeThemeName,
+    normalizeZone,
+    resolveToday,
+    type ThemeName,
+    TimezoneError,
+} from '@nowline/layout';
+import type { AssetResolver } from '@nowline/renderer';
 import type { ParsedArgs } from '../cli/args.js';
 import {
     FormatResolutionError,
@@ -15,7 +27,7 @@ import { resolveRenderOutputPath } from '../cli/output-path.js';
 import { parseNowlineJson } from '../convert/parse-json.js';
 import { printNowlineFile } from '../convert/printer.js';
 import { serializeToJson } from '../convert/schema.js';
-import { getServices, parseSource } from '../core/parse.js';
+import { parseSource } from '../core/parse.js';
 import { type DiagnosticSource, formatDiagnostics } from '../diagnostics/index.js';
 import {
     describeContentLocaleSource,
@@ -93,7 +105,7 @@ export async function renderHandler(options: RenderHandlerOptions): Promise<void
         absInputPath: input.isStdin ? path.resolve(cwd, 'stdin.nowline') : input.path,
         isStdin: input.isStdin,
         theme: parseTheme(args.theme),
-        today: resolveNowArg(args),
+        today: resolveNowCli(args),
         width: parseWidthArg(args.width),
         noLinks: args.noLinks,
         strict: args.strict,
@@ -106,6 +118,7 @@ export async function renderHandler(options: RenderHandlerOptions): Promise<void
         fontSans: args.fontSans ?? stringFromConfig(config, 'fontSans'),
         fontMono: args.fontMono ?? stringFromConfig(config, 'fontMono'),
         headless: args.headless || boolFromConfig(config, 'headlessFonts'),
+        useSystemFonts: args.useSystemFonts || boolFromConfig(config, 'useSystemFonts'),
         scale: args.scale,
         start: args.start,
         locale,
@@ -191,6 +204,8 @@ interface ProduceArgs {
     fontSans?: string;
     fontMono?: string;
     headless: boolean;
+    /** Opt in to system-font probing for raster/PDF export (bundled-first by default). */
+    useSystemFonts: boolean;
     scale?: string;
     start?: string;
     /** Resolved locale override (CLI flag or env-var fallback); undefined falls through to the directive. */
@@ -208,69 +223,67 @@ interface ProduceResult {
     isBinary: boolean;
 }
 
+const BINARY_FORMATS = new Set<OutputFormat>(['png', 'pdf', 'xlsx']);
+const FONT_FORMATS = new Set<OutputFormat>(['png', 'pdf']);
+
 async function produce(args: ProduceArgs): Promise<ProduceResult> {
-    if (args.format === 'json') {
-        return { rendered: await produceJson(args), isBinary: false };
-    }
+    // `nowline` canonical-text format is not part of ExportFormat; handle here.
     if (args.format === 'nowline') {
         return { rendered: await produceCanonicalNowline(args), isBinary: false };
     }
 
-    // The remaining formats all start from a positioned model + (sometimes) an
-    // SVG. Build them once and dispatch to the format-specific exporter via
-    // dynamic import — keeps each exporter's heavy deps off cold paths and
-    // leaves room to re-extract a package later if a future build profile
-    // wants to slim down.
-    const stage = await stageRoadmap(args);
+    // Convert JSON-AST input to DSL text before handing to the kernel.
+    const sourceText =
+        args.inputFormat === 'json'
+            ? jsonToNowlineText(args.contents, args.displayPath)
+            : args.contents;
+
+    // Pre-validate with locale-aware diagnostic formatting so validation
+    // errors reach the operator in their locale. The kernel will re-parse
+    // the same source below — double work accepted in exchange for faithful
+    // stderr output.
+    await parseAndValidate(sourceText, args);
 
-    if (args.format === 'svg') {
-        return { rendered: stage.svg, isBinary: false };
+    const assetRoot = args.assetRoot
+        ? path.resolve(args.assetRoot)
+        : path.dirname(args.absInputPath);
+
+    const host = createNodeHostEnv(assetRoot);
+
+    // Resolve fonts lazily — only for formats that rasterize or embed them.
+    let fonts: RenderInputs['fonts'];
+    if (FONT_FORMATS.has(args.format)) {
+        fonts = await resolveNodeFonts(args);
     }
+
+    const kernelInputs: RenderInputs = {
+        sourcePath: args.absInputPath,
+        today: args.today,
+        locale: args.locale ?? 'und',
+        theme: args.theme,
+        fonts,
+        width: args.width,
+        noLinks: args.noLinks,
+        strict: args.strict,
+        pageSize: args.pageSize,
+        orientation: parseOrientation(args.orientation),
+        marginPt: parseMargin(args.margin),
+        pngScale: parseScale(args.scale),
+        msprojStart: args.start,
+    };
+
     try {
-        if (args.format === 'html') {
-            const mod = await import('@nowline/export-html');
-            const html = await mod.exportHtml(stage.exportInputs, stage.svg);
-            return { rendered: html, isBinary: false };
-        }
-        if (args.format === 'mermaid') {
-            const mod = await import('@nowline/export-mermaid');
-            const md = mod.exportMermaid(stage.exportInputs);
-            return { rendered: md, isBinary: false };
-        }
-        if (args.format === 'msproj') {
-            const mod = await import('@nowline/export-msproj');
-            const xml = mod.exportMsProjXml(stage.exportInputs, {
-                startDate: args.start,
-            });
-            return { rendered: xml, isBinary: false };
-        }
-        if (args.format === 'png') {
-            const fonts = await stage.fontPair();
-            const mod = await import('@nowline/export-png');
-            const png = await mod.exportPng(stage.exportInputs, stage.svg, {
-                scale: parseScale(args.scale),
-                fonts,
-            });
-            return { rendered: png, isBinary: true };
-        }
-        if (args.format === 'pdf') {
-            const fonts = await stage.fontPair();
-            const mod = await import('@nowline/export-pdf');
-            const pdf = await mod.exportPdf(stage.exportInputs, stage.svg, {
-                pageSize: args.pageSize,
-                orientation: parseOrientation(args.orientation),
-                marginPt: parseMargin(args.margin),
-                fonts,
-            });
-            return { rendered: pdf, isBinary: true };
-        }
-        if (args.format === 'xlsx') {
-            const mod = await import('@nowline/export-xlsx');
-            const xlsx = await mod.exportXlsx(stage.exportInputs, {
-                generated: args.today,
-            });
-            return { rendered: xlsx, isBinary: true };
-        }
+        const bytes = await exportDocument(
+            sourceText,
+            args.format as ExportFormat,
+            kernelInputs,
+            host,
+        );
+        const isBinary = BINARY_FORMATS.has(args.format);
+        const rendered: string | Uint8Array = isBinary
+            ? bytes
+            : new TextDecoder('utf-8').decode(bytes);
+        return { rendered, isBinary };
     } catch (err) {
         if (err instanceof CliError) throw err;
         const message = err instanceof Error ? err.message : String(err);
@@ -279,22 +292,100 @@ async function produce(args: ProduceArgs): Promise<ProduceResult> {
             `nowline: ${args.format} export failed: ${message}`,
         );
     }
+}
 
-    throw new CliError(ExitCode.InputError, `nowline: unsupported format "${args.format}".`);
+// ---- Node HostEnv -----------------------------------------------------------
+
+function createNodeHostEnv(assetRoot: string): HostEnv {
+    const root = path.resolve(assetRoot);
+    return {
+        readSource: async (absPath: string): Promise<string> => {
+            return await fs.readFile(absPath, 'utf-8');
+        },
+        readAsset: async (ref: string): Promise<Uint8Array> => {
+            const absPath = path.resolve(root, ref);
+            if (!absPath.startsWith(root + path.sep) && absPath !== root) {
+                throw new Error(`Asset ${ref} escapes asset-root ${assetRoot}`);
+            }
+            const bytes = await fs.readFile(absPath);
+            return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        },
+        loadWasm: async (): Promise<ArrayBuffer> => {
+            // Two code paths:
+            //
+            // 1. Bun compiled binary: scripts/bun-entry.mjs imports
+            //    dist/resvg.wasm via `with { type: 'file' }` (the only Bun
+            //    pattern the bundler embeds) and stashes the VFS path in
+            //    globalThis.__RESVG_WASM_PATH__. Read it with Bun.file().
+            //
+            // 2. Plain Node.js (dev, tests, uncompiled dist/index.js run):
+            //    dist/resvg.wasm is copied by scripts/copy-wasm.mjs (postbuild).
+            //    Use fs.readFile via a new URL relative to this module.
+            // biome-ignore lint/suspicious/noExplicitAny: Bun-specific global not in TS types
+            const bunWasmPath = (globalThis as any).__RESVG_WASM_PATH__ as string | undefined;
+            if (bunWasmPath) {
+                // biome-ignore lint/suspicious/noExplicitAny: Bun-specific global not in TS types
+                return (globalThis as any).Bun.file(
+                    bunWasmPath,
+                ).arrayBuffer() as Promise<ArrayBuffer>;
+            }
+            const wasmUrl = new URL('../resvg.wasm', import.meta.url);
+            const bytes = await fs.readFile(wasmUrl);
+            return bytes.buffer as ArrayBuffer;
+        },
+    };
 }
 
-async function produceJson(args: ProduceArgs): Promise<string> {
-    if (args.inputFormat === 'json') {
-        // Re-parse JSON → DSL → JSON to canonicalize through @nowline/core.
-        const { ast } = parseNowlineJson(args.contents, args.displayPath);
-        const text = printNowlineFile(ast);
-        const parsed = await parseAndValidate(text, args);
-        return JSON.stringify(serializeToJson(parsed.document, text), null, 2);
+// ---- Font resolution --------------------------------------------------------
+
+async function resolveNodeFonts(
+    args: ProduceArgs,
+): Promise<import('@nowline/export-core').ResolvedFontPair> {
+    const { resolveFonts } = await import('@nowline/export-core');
+    const result = await resolveFonts({
+        fontSans: args.fontSans,
+        fontMono: args.fontMono,
+        headless: args.headless,
+        useSystemFonts: args.useSystemFonts,
+    });
+
+    // A variable font was explicitly requested but cannot be rasterized; we
+    // substituted bundled DejaVu. Always warn — and fail under --strict, since
+    // the requested font silently did not apply.
+    const vfSubstituted = result.sansVariableFontSubstituted || result.monoVariableFontSubstituted;
+    if (vfSubstituted) {
+        const roles = [
+            result.sansVariableFontSubstituted ? 'sans' : null,
+            result.monoVariableFontSubstituted ? 'mono' : null,
+        ].filter(Boolean) as string[];
+        const message = `requested variable font(s) for ${roles.join(
+            ', ',
+        )} cannot be rasterized; substituted bundled DejaVu`;
+        if (args.strict) {
+            throw new CliError(ExitCode.InputError, `nowline: ${message}`);
+        }
+        process.stderr.write(`warning: ${message}\n`);
     }
-    const parsed = await parseAndValidate(args.contents, args);
-    return JSON.stringify(serializeToJson(parsed.document, args.contents), null, 2);
+
+    // Bundled fallback after an opted-in probe found no usable system font.
+    // Only meaningful when --use-system-fonts is set; warn under --strict.
+    if (args.strict) {
+        if (result.sansFellBackToBundled) {
+            process.stderr.write(
+                'warning: sans font fell back to bundled DejaVu (no platform font found)\n',
+            );
+        }
+        if (result.monoFellBackToBundled) {
+            process.stderr.write(
+                'warning: mono font fell back to bundled DejaVu (no platform font found)\n',
+            );
+        }
+    }
+    return { sans: result.sans, mono: result.mono };
 }
 
+// ---- nowline canonical-text format (not part of ExportFormat) ---------------
+
 async function produceCanonicalNowline(args: ProduceArgs): Promise<string> {
     if (args.inputFormat === 'json') {
         const { ast } = parseNowlineJson(args.contents, args.displayPath);
@@ -305,93 +396,7 @@ async function produceCanonicalNowline(args: ProduceArgs): Promise<string> {
     return printNowlineFile(doc.ast);
 }
 
-interface StagedRoadmap {
-    svg: string;
-    exportInputs: import('@nowline/export-core').ExportInputs;
-    /** Lazy: only loads the resolved font pair when a format actually needs it. */
-    fontPair: () => Promise<import('@nowline/export-core').ResolvedFontPair>;
-}
-
-async function stageRoadmap(args: ProduceArgs): Promise<StagedRoadmap> {
-    const parsed = await parseAndValidate(
-        args.inputFormat === 'json'
-            ? jsonToNowlineText(args.contents, args.displayPath)
-            : args.contents,
-        args,
-    );
-    const resolved = await resolveIncludes(parsed.ast, args.absInputPath, {
-        services: getServices().Nowline,
-    });
-    for (const diag of resolved.diagnostics) {
-        if (diag.severity === 'error') {
-            process.stderr.write(`${diag.sourcePath}: ${diag.message}\n`);
-        }
-    }
-    if (resolved.diagnostics.some((d) => d.severity === 'error')) {
-        throw new CliError(ExitCode.ValidationError, '');
-    }
-
-    const model = layoutRoadmap(parsed.ast, resolved, {
-        theme: args.theme,
-        today: args.today,
-        width: args.width,
-        locale: args.locale,
-    });
-
-    const assetRoot = args.assetRoot
-        ? path.resolve(args.assetRoot)
-        : path.dirname(args.absInputPath);
-    const resolver: AssetResolver = createAssetResolver(assetRoot);
-
-    const warnings: string[] = [];
-    const svg = await renderSvg(model, {
-        assetResolver: resolver,
-        noLinks: args.noLinks,
-        strict: args.strict,
-        warn: (msg) => warnings.push(msg),
-    });
-
-    for (const w of warnings) {
-        process.stderr.write(`warning: ${w}\n`);
-    }
-
-    let cachedFonts: import('@nowline/export-core').ResolvedFontPair | undefined;
-    const fontPair = async () => {
-        if (cachedFonts) return cachedFonts;
-        const mod = await import('@nowline/export-core');
-        const result = await mod.resolveFonts({
-            fontSans: args.fontSans,
-            fontMono: args.fontMono,
-            headless: args.headless,
-        });
-        if (args.strict) {
-            if (result.sansFellBackToBundled) {
-                process.stderr.write(
-                    'warning: sans font fell back to bundled DejaVu (no platform font found)\n',
-                );
-            }
-            if (result.monoFellBackToBundled) {
-                process.stderr.write(
-                    'warning: mono font fell back to bundled DejaVu (no platform font found)\n',
-                );
-            }
-        }
-        cachedFonts = { sans: result.sans, mono: result.mono };
-        return cachedFonts;
-    };
-
-    return {
-        svg,
-        exportInputs: {
-            ast: parsed.ast,
-            resolved,
-            model,
-            sourcePath: args.displayPath,
-            today: args.today,
-        },
-        fontPair,
-    };
-}
+// ---- Shared helpers ---------------------------------------------------------
 
 function jsonToNowlineText(contents: string, displayPath: string): string {
     const { ast } = parseNowlineJson(contents, displayPath);
@@ -443,31 +448,41 @@ function parseTheme(raw: string | undefined): ThemeName {
     return theme;
 }
 
-// Resolve the now-line date from the CLI flag.
+// Resolve the now-line date from the CLI flags.
 //
 // Precedence:
-//   1. `--now -`            → undefined  (suppresses the now-line)
-//   2. `--now <YYYY-MM-DD>` → that date
-//   3. flag omitted          → today (UTC calendar date)
+//   1. `--now -`                           → undefined (suppress now-line)
+//   2. `--now YYYY-MM-DD`                  → floating date; zone ignored
+//   3. `--now YYYY-MM-DDTHH:MM:SS[±HH:MM]` → civil date at embedded offset; --timezone ignored
+//   4. `--now YYYY-MM-DDTHH:MM:SSZ`        → civil date in UTC; --timezone ignored
+//   5. `--now YYYY-MM-DDTHH:MM:SS`         → floating; written date part; zone ignored
+//   6. flag omitted                        → civil date of today in --timezone (default: local)
 //
-// The "default to today" behavior matches what the tool's name promises —
-// you should see a "now" line by default. Use `--now -` to opt out (Unix
-// `-` sentinel, mirroring `-o -` for stdout), or `--now <date>` for
-// deterministic snapshots / planning a hypothetical date.
-function resolveNowArg(args: { now?: string }): Date | undefined {
-    if (args.now === '-') return undefined;
-    if (args.now) {
-        const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(args.now);
-        if (!m) {
-            throw new CliError(
-                ExitCode.InputError,
-                `nowline: invalid --now "${args.now}". Expected YYYY-MM-DD or "-".`,
-            );
+// `--timezone` is only consulted for case 6. Authored dates in the roadmap
+// (bars, milestones, axis) are floating and are never affected.
+function resolveNowCli(args: { now?: string; timezone?: string }): Date | undefined {
+    let zone: NormalizedZone | undefined;
+    if (args.timezone) {
+        try {
+            zone = normalizeZone(args.timezone);
+        } catch (err) {
+            if (err instanceof TimezoneError) {
+                throw new CliError(ExitCode.InputError, err.message);
+            }
+            throw err;
         }
-        return new Date(Date.UTC(parseInt(m[1], 10), parseInt(m[2], 10) - 1, parseInt(m[3], 10)));
     }
-    const today = new Date();
-    return new Date(Date.UTC(today.getUTCFullYear(), today.getUTCMonth(), today.getUTCDate()));
+    const result = resolveToday({ now: args.now, zone });
+    // resolveToday returns undefined for unrecognised strings; surface that as
+    // an input error so the user gets a clear message instead of a silent no-line.
+    if (result === undefined && args.now !== undefined && args.now !== '-') {
+        throw new CliError(
+            ExitCode.InputError,
+            `nowline: invalid --now "${args.now}". ` +
+                `Expected YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS[Z|±HH:MM], or "-".`,
+        );
+    }
+    return result;
 }
 
 function parseScale(raw: string | undefined): number | undefined {
@@ -544,6 +559,8 @@ function emitDiagnostics(
     if (rendered) process.stderr.write(`${rendered}\n`);
 }
 
+// ---- Asset resolver (still used by serve.ts) --------------------------------
+
 export function createAssetResolver(assetRoot: string): AssetResolver {
     const root = path.resolve(assetRoot);
     return async (ref: string) => {

package/src/commands/serve.ts

@@ -2,7 +2,14 @@ import { type FSWatcher, promises as fs, watch as fsWatch } from 'node:fs';
 import * as http from 'node:http';
 import * as path from 'node:path';
 import { resolveIncludes } from '@nowline/core';
-import { layoutRoadmap, type ThemeName } from '@nowline/layout';
+import {
+    layoutRoadmap,
+    type NormalizedZone,
+    normalizeZone,
+    resolveToday,
+    type ThemeName,
+    TimezoneError,
+} from '@nowline/layout';
 import { renderSvg } from '@nowline/renderer';
 import type { ParsedArgs } from '../cli/args.js';
 import { getServices, parseSource } from '../core/parse.js';
@@ -218,17 +225,29 @@ function parseTheme(raw: string | undefined): ThemeName {
     return lower;
 }
 
-// Mirrors render.ts: `--now -` disables the line, `--now <date>` overrides
-// it, and the default is today's UTC calendar date.
-function resolveNowArg(args: { now?: string }): Date | undefined {
-    if (args.now === '-') return undefined;
-    if (args.now) {
-        const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(args.now);
-        if (!m) throw new CliError(ExitCode.InputError, `nowline: invalid --now "${args.now}".`);
-        return new Date(Date.UTC(parseInt(m[1], 10), parseInt(m[2], 10) - 1, parseInt(m[3], 10)));
+// Resolve the now-line date from the CLI flags. Mirrors render.ts.
+// Delegates to the shared resolveToday; see render.ts for the full precedence table.
+function resolveNowArg(args: { now?: string; timezone?: string }): Date | undefined {
+    let zone: NormalizedZone | undefined;
+    if (args.timezone) {
+        try {
+            zone = normalizeZone(args.timezone);
+        } catch (err) {
+            if (err instanceof TimezoneError) {
+                throw new CliError(ExitCode.InputError, err.message);
+            }
+            throw err;
+        }
+    }
+    const result = resolveToday({ now: args.now, zone });
+    if (result === undefined && args.now !== undefined && args.now !== '-') {
+        throw new CliError(
+            ExitCode.InputError,
+            `nowline: invalid --now "${args.now}". ` +
+                `Expected YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS[Z|±HH:MM], or "-".`,
+        );
     }
-    const t = new Date();
-    return new Date(Date.UTC(t.getUTCFullYear(), t.getUTCMonth(), t.getUTCDate()));
+    return result;
 }
 
 function sendEvent(res: http.ServerResponse, event: string, data: string): void {

package/src/generated/version.ts

@@ -1,6 +1,6 @@
 // Auto-generated by scripts/bundle-templates.mjs. Do not edit by hand.
 
-export const CLI_VERSION = "0.5.1";
+export const CLI_VERSION = "0.6.0";
 
 export interface CliBuild {
     /** Short git SHA at build time, or empty when not in a git checkout. */
@@ -12,7 +12,7 @@ export interface CliBuild {
 }
 
 export const CLI_BUILD: CliBuild = {
-    "sha": "fc40638",
+    "sha": "e2e4d9d",
     "isRelease": true,
     "isDirty": false
 };

package/src/index.ts

@@ -2,6 +2,7 @@
 import { parseArgv } from './cli/args.js';
 import { renderHelp, renderVersion } from './cli/help.js';
 import { initHandler } from './commands/init.js';
+import { mcpHandler } from './commands/mcp.js';
 import { renderHandler } from './commands/render.js';
 import { serveHandler } from './commands/serve.js';
 import { CliError, ExitCode } from './io/exit-codes.js';
@@ -30,6 +31,8 @@ async function run(): Promise<number> {
             await initHandler({ args: parsed });
         } else if (parsed.mode === 'serve') {
             await serveHandler({ args: parsed });
+        } else if (parsed.mode === 'mcp') {
+            await mcpHandler({ args: parsed });
         } else {
             await renderHandler({ args: parsed });
         }