@nowline/cli 0.8.6 → 0.9.0

package/src/commands/serve.ts

@@ -1,19 +1,17 @@
 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 NormalizedZone,
-    normalizeZone,
-    resolveToday,
-    type ThemeName,
-    TimezoneError,
-} from '@nowline/layout';
-import { renderSvg } from '@nowline/renderer';
+import { isRoutedResolveDiagnostic } from '@nowline/core';
+import type { ThemeName } from '@nowline/layout';
+import { renderSvg, stageRoadmap } from '@nowline/renderer';
 import type { ParsedArgs } from '../cli/args.js';
+import { resolveCliOptions } from '../cli/options.js';
 import { getServices, parseSource } from '../core/parse.js';
-import { type DiagnosticSource, formatDiagnostics } from '../diagnostics/index.js';
+import {
+    adaptResolveDiagnostic,
+    type DiagnosticSource,
+    formatDiagnostics,
+} from '../diagnostics/index.js';
 import {
     describeContentLocaleSource,
     operatorLocale,
@@ -21,7 +19,8 @@ import {
     resolveLocaleOverride,
 } from '../i18n/locale.js';
 import { CliError, ExitCode } from '../io/exit-codes.js';
-import { createAssetResolver } from './render.js';
+import { createLog, type Log } from '../io/log.js';
+import { createAssetResolver, errorsOnlyWhenQuiet, loadConfigFor } from './render.js';
 
 export interface ServeHandlerOptions {
     args: ParsedArgs;
@@ -60,11 +59,20 @@ export async function serveHandler(options: ServeHandlerOptions): Promise<void>
         );
     }
 
+    const log = createLog(args.logLevel);
     const port = parsePort(args.port);
     const host = args.host ?? '127.0.0.1';
-    const theme = parseTheme(args.theme);
-    const today = resolveNowArg(args);
-    const resolvedLocale = resolveLocaleOverride({ flag: args.locale, env: process.env });
+    const { config, path: rcPath } = await loadConfigFor(args.positional, cwd);
+    // The same resolution as render: flag > .nowlinerc > default, so --width,
+    // the rc width, --no-links and --strict apply here too.
+    const cliOptions = resolveCliOptions(args, config, { rcPath, cwd });
+    cliOptions.assertValid();
+    const { theme, today, width, nonWorking } = cliOptions.surface;
+    const resolvedLocale = resolveLocaleOverride({
+        flag: args.locale,
+        env: process.env,
+        rc: cliOptions.rcLocale,
+    });
     const locale = resolvedLocale.tag;
     const opLocale = operatorLocale(resolvedLocale);
 
@@ -75,7 +83,9 @@ export async function serveHandler(options: ServeHandlerOptions): Promise<void>
         throw new CliError(ExitCode.InputError, `nowline: file not found: ${args.positional}`);
     }
 
-    const assetRoot = args.assetRoot ? path.resolve(cwd, args.assetRoot) : path.dirname(inputPath);
+    // `--asset-root`, else the rc `assetRoot` (relative to the `.nowlinerc`), else
+    // the input's directory.
+    const assetRoot = cliOptions.assetRoot ?? path.dirname(inputPath);
 
     const fileSink = args.output ? path.resolve(cwd, args.output) : undefined;
 
@@ -91,44 +101,94 @@ export async function serveHandler(options: ServeHandlerOptions): Promise<void>
             const parse = await parseSource(text, inputPath, { validate: true });
             if (parse.hasErrors) {
                 const sources = new Map<string, DiagnosticSource>([[inputPath, parse.source]]);
-                const rendered = formatDiagnostics(parse.diagnostics, 'text', sources, {
-                    color: false,
-                    operatorLocale: opLocale,
-                });
+                const format = (diagnostics: typeof parse.diagnostics): string =>
+                    formatDiagnostics(diagnostics, 'text', sources, {
+                        color: false,
+                        operatorLocale: opLocale,
+                    });
+                // The browser always gets the full report; stderr honors -q.
+                const rendered = format(parse.diagnostics);
                 lastPayload = { kind: 'error', body: rendered };
-                process.stderr.write(`${rendered}\n`);
+                process.stderr.write(`${format(errorsOnlyWhenQuiet(parse.diagnostics, log))}\n`);
                 broadcast(clients, 'error', rendered);
                 return;
             }
-            if (args.logLevel === 'verbose') {
-                const directive = readDirectiveLocale(parse.ast);
-                const { tag, source } = describeContentLocaleSource(directive, resolvedLocale);
-                process.stderr.write(`nowline: locale=${tag} (${source})\n`);
-            }
-            const resolved = await resolveIncludes(parse.ast, inputPath, {
-                services: getServices().Nowline,
+            const directive = readDirectiveLocale(parse.ast);
+            const { tag, source } = describeContentLocaleSource(directive, resolvedLocale);
+            log.verbose(`nowline: locale=${tag} (${source})`);
+            // Included files' text, kept for the code frames of routed diagnostics.
+            const sources = new Map<string, DiagnosticSource>([[inputPath, parse.source]]);
+            const assetResolver = createAssetResolver(assetRoot);
+            const stage = await stageRoadmap({
+                source: text,
+                sourcePath: inputPath,
+                services: getServices(),
+                readSource: async (absPath) => {
+                    const contents = await fs.readFile(absPath, 'utf-8');
+                    sources.set(absPath, { file: absPath, contents });
+                    return contents;
+                },
+                assetResolver,
+                document: parse.document,
+                layout: { theme, today, locale, width, nonWorking },
             });
-            if (resolved.diagnostics.some((d) => d.severity === 'error')) {
-                const msg = resolved.diagnostics
-                    .filter((d) => d.severity === 'error')
+            if (stage.kind === 'invalid') {
+                // The parse above found no errors, so the stage cannot disagree.
+                throw new Error(`${inputPath} failed validation.`);
+            }
+            if (stage.kind === 'include-error') {
+                // Uncoded include errors keep their one-line form, broadcast
+                // only, and take precedence: when any is present, routed
+                // (wave-rule) diagnostics are dropped. Otherwise routed
+                // diagnostics are reported like validator diagnostics
+                // (specs/waves.md §6.1).
+                const legacy = stage.resolved.diagnostics
+                    .filter((d) => d.severity === 'error' && !isRoutedResolveDiagnostic(d))
                     .map((d) => `${d.sourcePath}: ${d.message}`)
                     .join('\n');
+                let msg = legacy;
+                if (!legacy && stage.routed.some((d) => d.severity === 'error')) {
+                    const diagnostics = [
+                        ...parse.diagnostics,
+                        ...stage.routed.map((d) =>
+                            adaptResolveDiagnostic(
+                                d,
+                                d.sourcePath,
+                                sources.get(d.sourcePath)?.contents,
+                            ),
+                        ),
+                    ];
+                    const format = (shown: typeof diagnostics): string =>
+                        formatDiagnostics(shown, 'text', sources, {
+                            color: false,
+                            operatorLocale: opLocale,
+                        });
+                    process.stderr.write(`${format(errorsOnlyWhenQuiet(diagnostics, log))}\n`);
+                    msg = format(diagnostics);
+                }
                 lastPayload = { kind: 'error', body: msg };
                 broadcast(clients, 'error', msg);
                 return;
             }
-            const model = layoutRoadmap(parse.ast, resolved, { theme, today, locale });
-            const svg = await renderSvg(model, {
-                assetResolver: createAssetResolver(assetRoot),
-                warn: (m) => process.stderr.write(`warning: ${m}\n`),
+            // The logo's load warnings, then the renderer's; `--strict` makes
+            // any of them an error, as in render.
+            const warnings = [...stage.warnings];
+            const svg = await renderSvg(stage.model, {
+                assetResolver,
+                logo: stage.logo,
+                noLinks: args.noLinks,
+                strict: args.strict,
+                warn: (m) => warnings.push(m),
             });
+            if (args.strict && warnings.length > 0) {
+                throw new Error(`render warnings (--strict): ${warnings.join('; ')}`);
+            }
+            for (const m of warnings) log.notice(`warning: ${m}`);
             lastPayload = { kind: 'svg', body: svg };
             if (fileSink) {
                 try {
                     await fs.writeFile(fileSink, svg);
-                    if (args.logLevel === 'verbose') {
-                        process.stderr.write(`nowline: wrote ${fileSink}\n`);
-                    }
+                    log.verbose(`nowline: wrote ${fileSink}`);
                 } catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);
                     process.stderr.write(`nowline: failed to write ${fileSink}: ${msg}\n`);
@@ -183,7 +243,7 @@ export async function serveHandler(options: ServeHandlerOptions): Promise<void>
     process.stdout.write(`nowline serve: http://${host}:${port}\n`);
 
     if (args.open) {
-        await openBrowser(`http://${host}:${port}`);
+        await openBrowser(`http://${host}:${port}`, log);
     }
 
     const shutdown = async (): Promise<void> => {
@@ -217,39 +277,6 @@ function parsePort(raw: string | undefined): number {
     return port;
 }
 
-function parseTheme(raw: string | undefined): ThemeName {
-    const lower = (raw ?? 'light').toLowerCase();
-    if (lower !== 'light' && lower !== 'dark') {
-        throw new CliError(ExitCode.InputError, `nowline: invalid --theme "${raw}".`);
-    }
-    return lower;
-}
-
-// 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 "-".`,
-        );
-    }
-    return result;
-}
-
 function sendEvent(res: http.ServerResponse, event: string, data: string): void {
     const lines = data
         .split('\n')
@@ -279,7 +306,7 @@ function watchFile(target: string, onChange: () => Promise<void>): FSWatcher {
     return w;
 }
 
-async function openBrowser(url: string): Promise<void> {
+async function openBrowser(url: string, log: Log): Promise<void> {
     const { spawn } = await import('node:child_process');
     const platform = process.platform;
     const command = platform === 'darwin' ? 'open' : platform === 'win32' ? 'cmd' : 'xdg-open';
@@ -288,7 +315,7 @@ async function openBrowser(url: string): Promise<void> {
         const child = spawn(command, argList, { stdio: 'ignore', detached: true });
         child.unref();
     } catch {
-        process.stderr.write(`nowline: warning — failed to open browser; visit ${url} manually.\n`);
+        log.notice(`nowline: warning — failed to open browser; visit ${url} manually.`);
     }
 }
 
@@ -296,6 +323,7 @@ const emptySvg =
     '<svg xmlns="http://www.w3.org/2000/svg" width="400" height="60"><text x="10" y="30" font-family="system-ui" font-size="14" fill="#999">no output yet</text></svg>';
 
 function shellHtml(theme: ThemeName): string {
+    // Only dark needs dark chrome; grayscale sits on the light page.
     const bg = theme === 'dark' ? '#121212' : '#ffffff';
     const fg = theme === 'dark' ? '#e0e0e0' : '#212121';
     return `<!doctype html>

package/src/diagnostics/adapt.ts

@@ -1,8 +1,10 @@
 import {
     extractSuggestion,
+    inferCodeFromMessage,
     type LangiumLikeDiagnostic,
     type LexerErrorLike,
     type ParserErrorLike,
+    type ResolveDiagnostic,
     resolveDiagnosticCode,
 } from '@nowline/core';
 import type { CliDiagnostic, DiagnosticSeverity, LocalizedMessageData } from './model.js';
@@ -87,3 +89,63 @@ export function adaptLexerError(err: LexerErrorLike, file: string): CliDiagnosti
 function mapSeverity(severity: number | undefined): DiagnosticSeverity {
     return severity === 2 ? 'warning' : 'error';
 }
+
+/**
+ * Adapt a routed include-resolver diagnostic (a wave rule or an included
+ * file's NL.E0302). With a `range`, the column and span are the validator's
+ * for the same finding. Without one, the diagnostic carries only a 0-based
+ * line: `contents` is the text of the file it points into, when known, and
+ * the span covers the line's text, so the code frame still underlines the
+ * declaration. A coded diagnostic keeps `{ code, args }` in `data` for
+ * re-localization. An included file's syntax error is adapted like that
+ * file's own (`lex-error` / `parse-error`).
+ */
+export function adaptResolveDiagnostic(
+    diag: ResolveDiagnostic,
+    file: string,
+    contents?: string,
+): CliDiagnostic {
+    // An included file's syntax error reads as it does when that file is
+    // checked on its own.
+    if (diag.syntax?.origin === 'lexer') return adaptLexerError(diag.syntax.error, file);
+    if (diag.syntax?.origin === 'parser') return adaptParserError(diag.syntax.error, file);
+    return {
+        file,
+        ...resolveLocation(diag, contents),
+        severity: diag.severity,
+        // WV8 is uncoded; label it the way the validator's copy is labelled.
+        code: diag.code ?? inferCodeFromMessage(diag.message),
+        message: diag.message,
+        suggestion: extractSuggestion(diag.message),
+        data: diag.code === undefined ? undefined : { code: diag.code, args: diag.args ?? [] },
+    };
+}
+
+function resolveLocation(
+    diag: ResolveDiagnostic,
+    contents: string | undefined,
+): Pick<CliDiagnostic, 'line' | 'column' | 'span'> {
+    if (diag.range) {
+        const line = diag.range.start.line + 1;
+        const column = diag.range.start.character + 1;
+        return {
+            line,
+            column,
+            span: {
+                start: { line, column },
+                end: { line: diag.range.end.line + 1, column: diag.range.end.character + 1 },
+            },
+        };
+    }
+    const line = (diag.line ?? 0) + 1;
+    const text = contents?.split(/\r?\n/)[line - 1]?.trimEnd() ?? '';
+    const column = text.length - text.trimStart().length + 1;
+    return {
+        line,
+        column,
+        span:
+            text.trim() === ''
+                ? undefined
+                : { start: { line, column }, end: { line, column: text.length + 1 } },
+    };
+}

package/src/diagnostics/model.ts

@@ -35,7 +35,7 @@ export interface CliDiagnostic {
      * Stable code + args as captured by the validator. Present on
      * messages that flow through the `tr()` registry; absent for
      * literal-English validator strings, parser/lexer errors, and
-     * include-resolution diagnostics. The CLI re-formats `message`
+     * uncoded include-resolution diagnostics. The CLI re-formats `message`
      * from this when an operator locale is supplied to
      * `formatDiagnostics`.
      */

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.8.6";
+export const CLI_VERSION = "0.9.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": "29a8950",
+    "sha": "06f9e6f",
     "isRelease": true,
     "isDirty": false
 };

package/src/i18n/locale.ts

@@ -1,4 +1,5 @@
 import type { NowlineFile } from '@nowline/core';
+import { findProp } from '@nowline/core/internal';
 
 // Resolve the operator-locale override from CLI flag, environment, and
 // `.nowlinerc`. See `specs/localization.md` for the two-chain model.
@@ -100,12 +101,7 @@ export function describeContentLocaleSource(
  * absent, malformed, or omits the property.
  */
 export function readDirectiveLocale(file: NowlineFile | undefined): string | undefined {
-    const prop = file?.directive?.properties.find((p) => stripColon(p.key) === 'locale');
-    return prop?.value || undefined;
-}
-
-function stripColon(key: string): string {
-    return key.endsWith(':') ? key.slice(0, -1) : key;
+    return findProp(file?.directive?.properties ?? [], 'locale')?.value || undefined;
 }
 
 /**

package/src/index.ts

@@ -3,6 +3,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 { mcpInstallHandler } from './commands/mcp-install.js';
 import { renderHandler } from './commands/render.js';
 import { serveHandler } from './commands/serve.js';
 import { CliError, ExitCode } from './io/exit-codes.js';
@@ -33,6 +34,8 @@ async function run(): Promise<number> {
             await serveHandler({ args: parsed });
         } else if (parsed.mode === 'mcp') {
             await mcpHandler({ args: parsed });
+        } else if (parsed.mode === 'mcp-install' || parsed.mode === 'mcp-uninstall') {
+            await mcpInstallHandler({ args: parsed });
         } else {
             await renderHandler({ args: parsed });
         }

package/src/io/config.ts

@@ -5,7 +5,6 @@ export {
     type LoadConfigOptions,
     type LoadConfigResult,
     loadConfig,
-    mergeConfig,
     type NowlineRc,
     parseConfig,
 } from '@nowline/config';

package/src/io/log.ts

@@ -0,0 +1,33 @@
+export type LogLevel = 'verbose' | 'quiet' | 'normal';
+
+/**
+ * The one place `-v` / `-q` decide what reaches stderr. Errors (usage errors,
+ * failed writes, validation errors) and machine output (JSON diagnostics)
+ * bypass this and always print; everything else goes through here so every
+ * command honors the flags the same way.
+ */
+export interface Log {
+    /** `-v` only: progress lines such as `nowline: wrote <path>`. */
+    verbose(line: string): void;
+    /** Non-error notices (warnings, lossy summaries, banners). Dropped under `-q`. */
+    notice(line: string): void;
+    /** True under `-q`; callers that filter mixed output (diagnostics) check it. */
+    readonly quiet: boolean;
+}
+
+export function createLog(
+    level: LogLevel,
+    write: (chunk: string) => void = (chunk) => {
+        process.stderr.write(chunk);
+    },
+): Log {
+    return {
+        verbose: (line) => {
+            if (level === 'verbose') write(`${line}\n`);
+        },
+        notice: (line) => {
+            if (level !== 'quiet') write(`${line}\n`);
+        },
+        quiet: level === 'quiet',
+    };
+}