@nowline/cli 0.8.6 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nowline/cli",
-  "version": "0.8.6",
+  "version": "0.10.0",
   "description": "Command-line tool to check, convert, and create Nowline roadmaps.",
   "license": "Apache-2.0",
   "engines": {
@@ -32,33 +32,33 @@
   "dependencies": {
     "@babel/code-frame": "^8.0.6",
     "@clack/prompts": "^1.8.1",
-    "@modelcontextprotocol/node": "^2.1.0",
-    "@modelcontextprotocol/server": "^2.2.0",
-    "@nowline/config": "0.8.6",
-    "@nowline/core": "0.8.6",
-    "@nowline/export": "0.8.6",
-    "@nowline/export-core": "0.8.6",
-    "@nowline/export-html": "0.8.6",
-    "@nowline/export-mermaid": "0.8.6",
-    "@nowline/export-msproj": "0.8.6",
-    "@nowline/export-pdf": "0.8.6",
-    "@nowline/export-png": "0.8.6",
-    "@nowline/export-xlsx": "0.8.6",
-    "@nowline/layout": "0.8.6",
-    "@nowline/mcp": "0.8.6",
-    "@nowline/renderer": "0.8.6",
+    "@modelcontextprotocol/server": "^2.3.1",
+    "@nowline/config": "0.10.0",
+    "@nowline/core": "0.10.0",
+    "@nowline/export": "0.10.0",
+    "@nowline/export-core": "0.10.0",
+    "@nowline/export-html": "0.10.0",
+    "@nowline/export-mermaid": "0.10.0",
+    "@nowline/export-msproj": "0.10.0",
+    "@nowline/export-pdf": "0.10.0",
+    "@nowline/export-png": "0.10.0",
+    "@nowline/export-xlsx": "0.10.0",
+    "@nowline/layout": "0.10.0",
+    "@nowline/mcp": "0.10.0",
+    "@nowline/renderer": "0.10.0",
     "chalk": "^6.0.1",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
-    "js-yaml": "^5.4.2",
+    "js-yaml": "^5.5.0",
+    "jsonc-parser": "^3.3.1",
     "langium": "~4.4.0"
   },
   "devDependencies": {
     "@resvg/resvg-wasm": "^2.6.2",
     "@types/babel__code-frame": "^7.27.0",
-    "@types/node": "^26.6.3",
+    "@types/node": "^26.6.5",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.2"
+    "vitest": "^5.0.5"
   },
   "scripts": {
     "bundle-templates": "node scripts/bundle-templates.mjs",

package/src/cli/args.ts

@@ -1,18 +1,33 @@
 import { type ParseArgsConfig, parseArgs } from 'node:util';
 import { isDiagnosticFormat } from '../diagnostics/format.js';
 import { CliError, ExitCode } from '../io/exit-codes.js';
+import type { LogLevel } from '../io/log.js';
 
-export type ModeKind = 'render' | 'serve' | 'init' | 'mcp' | 'help' | 'version';
+export type ModeKind =
+    | 'render'
+    | 'serve'
+    | 'init'
+    | 'mcp'
+    | 'mcp-install'
+    | 'mcp-uninstall'
+    | 'help'
+    | 'version';
+
+export type McpScope = 'user' | 'project';
+export type McpServerKind = 'self' | 'npx';
 
 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 argument, or undefined. Render = input path. Init = project name. Serve = input path.
+     * MCP install / uninstall = client id.
+     */
     positional?: string;
-    /** True if `--dry-run` / `-n` was passed (only valid for render mode). */
+    /** True if `--dry-run` / `-n` was passed (render and MCP install / uninstall). */
     dryRun: boolean;
     /** Logging level. Verbose and quiet are mutually exclusive. */
-    logLevel: 'verbose' | 'quiet' | 'normal';
+    logLevel: LogLevel;
 
     // I/O
     output?: string;
@@ -38,6 +53,12 @@ export interface ParsedArgs {
     scale?: string;
     strict: boolean;
     width?: string;
+    /**
+     * Raw `--non-working` value (`hide` or `show`). Undefined means unset, so
+     * the file's `default roadmap non-working:` key still applies. Validated
+     * by the render and serve commands, like `--width`.
+     */
+    nonWorking?: string;
     assetRoot?: string;
 
     // Format-specific options (m2c)
@@ -78,6 +99,10 @@ export interface ParsedArgs {
 
     // MCP
     root?: string;
+    /** `--scope` for --mcp-install / --mcp-uninstall; validated in parseArgv. */
+    scope?: McpScope;
+    /** `--server` for --mcp-install; validated in parseArgv. */
+    server?: McpServerKind;
 }
 
 /**
@@ -118,6 +143,8 @@ export function parseArgv(argv: readonly string[]): ParsedArgs {
             serve: { type: 'boolean' },
             init: { type: 'boolean' },
             mcp: { type: 'boolean' },
+            'mcp-install': { type: 'boolean' },
+            'mcp-uninstall': { type: 'boolean' },
             'dry-run': { type: 'boolean', short: 'n' },
 
             theme: { type: 'string', short: 't' },
@@ -133,6 +160,7 @@ export function parseArgv(argv: readonly string[]): ParsedArgs {
             scale: { type: 'string', short: 's' },
             strict: { type: 'boolean' },
             width: { type: 'string', short: 'w' },
+            'non-working': { type: 'string' },
             'asset-root': { type: 'string' },
 
             port: { type: 'string', short: 'p' },
@@ -145,6 +173,8 @@ export function parseArgv(argv: readonly string[]): ParsedArgs {
 
             // MCP
             root: { type: 'string' },
+            scope: { type: 'string' },
+            server: { type: 'string' },
 
             // Format-specific (m2c)
             'page-size': { type: 'string' },
@@ -208,6 +238,8 @@ export function parseArgv(argv: readonly string[]): ParsedArgs {
     if (values.serve === true) modes.push('serve');
     if (values.init === true) modes.push('init');
     if (values.mcp === true) modes.push('mcp');
+    if (values['mcp-install'] === true) modes.push('mcp-install');
+    if (values['mcp-uninstall'] === true) modes.push('mcp-uninstall');
     if (modes.length > 1) {
         throw new CliError(
             ExitCode.InputError,
@@ -233,6 +265,21 @@ export function parseArgv(argv: readonly string[]): ParsedArgs {
         throw new CliError(ExitCode.InputError, `nowline: unexpected extra arguments: ${extras}.`);
     }
 
+    const scope = stringOrUndefined(values.scope);
+    if (scope !== undefined && scope !== 'user' && scope !== 'project') {
+        throw new CliError(
+            ExitCode.InputError,
+            `nowline: invalid --scope "${scope}". Expected user or project.`,
+        );
+    }
+    const server = stringOrUndefined(values.server);
+    if (server !== undefined && server !== 'self' && server !== 'npx') {
+        throw new CliError(
+            ExitCode.InputError,
+            `nowline: invalid --server "${server}". Expected self or npx.`,
+        );
+    }
+
     const rawDiagnosticFormat = stringOrUndefined(values['diagnostic-format']);
     if (rawDiagnosticFormat !== undefined && !isDiagnosticFormat(rawDiagnosticFormat)) {
         throw new CliError(
@@ -241,7 +288,7 @@ export function parseArgv(argv: readonly string[]): ParsedArgs {
         );
     }
 
-    const logLevel: ParsedArgs['logLevel'] =
+    const logLevel: LogLevel =
         values.verbose === true ? 'verbose' : values.quiet === true ? 'quiet' : 'normal';
 
     return {
@@ -259,6 +306,7 @@ export function parseArgv(argv: readonly string[]): ParsedArgs {
         scale: stringOrUndefined(values.scale),
         strict: values.strict === true,
         width: stringOrUndefined(values.width),
+        nonWorking: stringOrUndefined(values['non-working']),
         assetRoot: stringOrUndefined(values['asset-root']),
         port: stringOrUndefined(values.port),
         host: stringOrUndefined(values.host),
@@ -275,6 +323,8 @@ export function parseArgv(argv: readonly string[]): ParsedArgs {
         start: stringOrUndefined(values.start),
         locale: stringOrUndefined(values.locale),
         root: stringOrUndefined(values.root),
+        scope,
+        server,
     };
 }
 

package/src/cli/help.ts

@@ -9,6 +9,7 @@ USAGE
   nowline <input> [options]
   nowline --serve <input> [options]
   nowline --init [<name>]
+  nowline --mcp-install [<client>] [options]
   nowline --version
   nowline --help
 
@@ -35,6 +36,14 @@ MODE FLAGS (mutually exclusive)
                           exposing validate, render, export, and file tools.
                           Shares the same @nowline/mcp server code as
                           \`npx @nowline/mcp\`.
+      --mcp-install [<client>]
+                          Register the MCP server with an agent: claude-code,
+                          claude-desktop, cursor, vscode, codex, gemini,
+                          antigravity, muse, opencode, copilot, windsurf, zed,
+                          amp, goose, or all. Omitted: every agent found on this machine.
+                          Re-running is safe; -n previews the change.
+      --mcp-uninstall [<client>]
+                          Remove the server from the same configs.
   -n, --dry-run           Run the full pipeline (parse + validate + layout +
                           format) but skip the write step. Subsumes the old
                           'validate' verb. Exit 0 on success, 1 on errors.
@@ -66,8 +75,18 @@ RENDER OPTIONS
       --no-links          Omit link icons from rendered items.
   -s, --scale <n>         Raster scale factor (PNG only; default 1).
       --strict            Promote asset / sanitizer warnings to errors.
-  -w, --width <px>        Canvas width in pixels (default: 1280).
-      --asset-root <dir>  Root for logo / image assets (default: input dir).
+  -w, --width <px>        Maximum canvas width in pixels. Default: fit the
+                          content. A wider roadmap shrinks its timeline to
+                          fit; long captions can still overflow it.
+      --non-working <hide|show>
+                          How a business calendar's non-working days appear:
+                          hide collapses them (the default), show draws them
+                          as shaded bands. Overrides the file's
+                          'default roadmap non-working:' key; omit it to let
+                          the key apply. Mermaid, MS Project, and XLSX output
+                          is the same in both views.
+      --asset-root <dir>  Root for logo / image assets (default: the
+                          .nowlinerc assetRoot key, then the input dir).
       --locale <bcp47>    BCP-47 locale (e.g. fr, fr-CA) for CLI message
                           output (validator diagnostics, --help, errors).
                           Used as a fallback for the rendered drawing only
@@ -99,6 +118,13 @@ SERVE OPTIONS
 MCP OPTIONS
       --root <dir>        Allowed-root directory for file tools (default: cwd).
                           File paths are resolved and restricted to this root.
+                          With --mcp-install, written into the registered
+                          command.
+      --scope <s>         --mcp-install target: user (default, every
+                          project) or project (config files in cwd).
+      --server <s>        What --mcp-install registers: self (default, this
+                          nowline binary; needs no Node) or npx
+                          (npx -y @nowline/mcp, tracks npm).
 
 LOGGING (mutually exclusive)
   -v, --verbose           Print extra diagnostics to stderr.
@@ -118,8 +144,10 @@ EXAMPLES
   nowline roadmap.nowline --dry-run         # validate-only
   nowline roadmap.nowline --serve -p 8080   # live preview
   nowline --init my-project                 # scaffold ./my-project.nowline
-  nowline --mcp                             # start MCP stdio server in cwd
+  nowline --mcp                             # start MCP stdio server
   nowline --mcp --root ./roadmaps           # MCP server with custom root
+  nowline --mcp-install                     # register with every agent found
+  nowline --mcp-install cursor --scope project -n   # preview .cursor/mcp.json
 
 EXIT CODES
   0  Success

package/src/cli/options.ts

@@ -0,0 +1,286 @@
+// How the CLI turns flags and `.nowlinerc` keys into render options. The five
+// shared options (theme, width, now, page size, non-working display) come from
+// `@nowline/config`'s schema; the CLI-only keys are registered here as option
+// specs over the same two layers, so adding an rc key is one entry in
+// `CLI_OPTION_SPECS` rather than a hand-written merge in each command
+// (specs/surface-options.md §3.1).
+
+import * as path from 'node:path';
+import {
+    ASSET_ROOT_SPEC,
+    type NowlineRc,
+    type OptionError,
+    type OptionLayer,
+    type OptionParse,
+    type OptionSpec,
+    rcLayer,
+    resolveOptions,
+    resolveSurfaceOptions,
+    SURFACE_OPTION_SPECS,
+    type SurfaceOptions,
+} from '@nowline/config';
+import { lengthToPoints, parseLength } from '@nowline/export-core';
+import { type NormalizedZone, normalizeZone, TimezoneError } from '@nowline/layout';
+import { CliError, ExitCode } from '../io/exit-codes.js';
+import type { ParsedArgs } from './args.js';
+
+// ---- CLI-only option specs --------------------------------------------------
+
+export type PdfOrientation = 'portrait' | 'landscape' | 'auto';
+
+const ORIENTATIONS: readonly PdfOrientation[] = ['portrait', 'landscape', 'auto'];
+
+/** An rc key the CLI reads as a string; any other type is ignored, as it always was. */
+function lenientString(raw: unknown): OptionParse<string> {
+    return { ok: true, value: typeof raw === 'string' ? raw : undefined };
+}
+
+/** An rc or flag switch: only a literal `true` turns it on. */
+function lenientSwitch(raw: unknown): OptionParse<boolean> {
+    return { ok: true, value: raw === true ? true : undefined };
+}
+
+function parseOrientation(raw: unknown): OptionParse<PdfOrientation> {
+    if (raw === '') return { ok: true, value: undefined };
+    const lower = typeof raw === 'string' ? raw.toLowerCase() : undefined;
+    const found = ORIENTATIONS.find((orientation) => orientation === lower);
+    if (found) return { ok: true, value: found };
+    return { ok: false, detail: 'must be an orientation', expected: ORIENTATIONS };
+}
+
+function parseMargin(raw: unknown): OptionParse<number> {
+    if (raw === '') return { ok: true, value: undefined };
+    // A bare number is points; YAML and JSON hand the rc one over as a number.
+    if (typeof raw === 'number' && Number.isFinite(raw) && raw >= 0) {
+        return { ok: true, value: raw };
+    }
+    const text = String(raw);
+    if (/^\d+(?:\.\d+)?$/.test(text)) return { ok: true, value: Number(text) };
+    try {
+        return { ok: true, value: lengthToPoints(parseLength(text)) };
+    } catch (err) {
+        return { ok: false, detail: err instanceof Error ? err.message : String(err) };
+    }
+}
+
+/** Every option the CLI resolves over its flag and rc layers: the shared five, then its own. */
+export const CLI_OPTION_SPECS = Object.freeze({
+    ...SURFACE_OPTION_SPECS,
+    orientation: { rcKey: 'pdfOrientation', parse: parseOrientation } as OptionSpec<PdfOrientation>,
+    margin: { rcKey: 'pdfMargin', parse: parseMargin } as OptionSpec<number>,
+    defaultFormat: { rcKey: 'defaultFormat', parse: lenientString } as OptionSpec<string>,
+    fontSans: { rcKey: 'fontSans', parse: lenientString } as OptionSpec<string>,
+    fontMono: { rcKey: 'fontMono', parse: lenientString } as OptionSpec<string>,
+    headless: { rcKey: 'headlessFonts', parse: lenientSwitch } as OptionSpec<boolean>,
+    useSystemFonts: { rcKey: 'useSystemFonts', parse: lenientSwitch } as OptionSpec<boolean>,
+    locale: { rcKey: 'locale', parse: lenientString } as OptionSpec<string>,
+    assetRoot: ASSET_ROOT_SPEC as OptionSpec<string>,
+});
+
+type CliSpecs = typeof CLI_OPTION_SPECS;
+export type CliOptionKey = Extract<keyof CliSpecs, string>;
+
+/** The flag each option is passed as, for an error that names its source. */
+const FLAG_NAMES: Readonly<Partial<Record<CliOptionKey, string>>> = {
+    theme: '--theme',
+    width: '--width',
+    now: '--now',
+    pageSize: '--page-size',
+    nonWorking: '--non-working',
+    orientation: '--orientation',
+    margin: '--margin',
+    fontSans: '--font-sans',
+    fontMono: '--font-mono',
+    headless: '--headless',
+    useSystemFonts: '--use-system-fonts',
+    assetRoot: '--asset-root',
+};
+
+// ---- Resolution -------------------------------------------------------------
+
+export interface CliOptions {
+    /** Theme, width, now-line date and non-working display; page size when set. */
+    surface: SurfaceOptions;
+    orientation?: PdfOrientation;
+    /** Page margin in points. */
+    margin?: number;
+    /** The rc `defaultFormat`; the `--format` flag is resolved by `resolveFormat`. */
+    defaultFormat?: string;
+    fontSans?: string;
+    fontMono?: string;
+    headless: boolean;
+    useSystemFonts: boolean;
+    /**
+     * Where `logo:` assets are read from, as an absolute path: `--asset-root`,
+     * else the rc `assetRoot`. Unset means the input file's directory.
+     */
+    assetRoot?: string;
+    /** The rc `locale`; the flag and `NOWLINE_LOCALE` rank above it (`resolveLocaleOverride`). */
+    rcLocale?: string;
+    /**
+     * Throw the first invalid option as a usage error, in the order the CLI
+     * has always reported them: theme, timezone, now, width, non-working.
+     */
+    assertValid(): void;
+    /**
+     * Throw the first invalid PDF setting (page size, orientation, margin).
+     * Run after validation, so these errors follow any diagnostics.
+     */
+    assertPdfSettingsValid(): void;
+}
+
+/**
+ * Resolve the CLI's options over the flag layer, then the `.nowlinerc` layer.
+ * `render` and `--serve` both call this, so they read the same keys the same
+ * way. `cwd` is what a relative `--asset-root` resolves against (default: the
+ * process's). Nothing throws here: a caller reads `defaultFormat` early and reports bad
+ * values at the point it always did, through `assertValid`.
+ */
+export function resolveCliOptions(
+    args: ParsedArgs,
+    config: NowlineRc | null,
+    context: { rcPath?: string; cwd?: string; clock?: () => Date } = {},
+): CliOptions {
+    const { rcPath, cwd, clock } = context;
+    const layers = [flagLayer(args), rcLayer(config ?? {}, CLI_OPTION_SPECS)];
+
+    // `--timezone` is validated even when `--now` is explicit, as it always was.
+    const zone = readZone(args.timezone);
+    const { options, errors: surfaceErrors } = resolveSurfaceOptions(
+        layers,
+        { theme: 'light' },
+        { zone: zone.zone, clock },
+    );
+    const { values, errors: cliErrors } = resolveOptions(CLI_OPTION_SPECS, layers);
+    const failures = new Map<string, OptionError<CliOptionKey>>(
+        [...surfaceErrors, ...cliErrors].map((error) => [error.key, error]),
+    );
+    const failure = (key: CliOptionKey): CliError | undefined => {
+        const error = failures.get(key);
+        return error && new CliError(ExitCode.InputError, formatOptionError(error));
+    };
+
+    return {
+        surface: options,
+        orientation: values.orientation,
+        margin: values.margin,
+        defaultFormat: values.defaultFormat,
+        fontSans: values.fontSans,
+        fontMono: values.fontMono,
+        headless: values.headless ?? false,
+        useSystemFonts: values.useSystemFonts ?? false,
+        assetRoot: absoluteAssetRoot(values.assetRoot, args.assetRoot !== undefined, rcPath, cwd),
+        rcLocale: values.locale,
+        assertValid: () =>
+            throwFirst([
+                failure('theme'),
+                zone.error,
+                failure('now'),
+                failure('width'),
+                failure('nonWorking'),
+                failure('assetRoot'),
+            ]),
+        assertPdfSettingsValid: () =>
+            throwFirst([failure('pageSize'), failure('orientation'), failure('margin')]),
+    };
+}
+
+function throwFirst(candidates: readonly (CliError | undefined)[]): void {
+    for (const candidate of candidates) {
+        if (candidate) throw candidate;
+    }
+}
+
+function flagLayer(args: ParsedArgs): OptionLayer<CliOptionKey> {
+    return {
+        source: (key) => ({ kind: 'flag', name: FLAG_NAMES[key] ?? `--${key}` }),
+        values: {
+            // An empty `--theme ""` has always meant "not passed", so the rc theme applies.
+            theme: args.theme || undefined,
+            width: args.width,
+            now: args.now,
+            pageSize: args.pageSize,
+            nonWorking: args.nonWorking,
+            orientation: args.orientation,
+            margin: args.margin,
+            fontSans: args.fontSans,
+            fontMono: args.fontMono,
+            assetRoot: args.assetRoot,
+            // A switch flag is absent or on; absent leaves the rc to decide.
+            headless: args.headless || undefined,
+            useSystemFonts: args.useSystemFonts || undefined,
+        },
+    };
+}
+
+function readZone(raw: string | undefined): { zone?: NormalizedZone; error?: CliError } {
+    if (!raw) return {};
+    try {
+        return { zone: normalizeZone(raw) };
+    } catch (err) {
+        if (err instanceof TimezoneError) {
+            return { error: new CliError(ExitCode.InputError, err.message) };
+        }
+        throw err;
+    }
+}
+
+// ---- Asset root -------------------------------------------------------------
+
+/**
+ * The asset root as an absolute path. A flag resolves against `cwd` (the
+ * process's, unless a caller passes its own); an rc value against the
+ * directory of the `.nowlinerc` it came from, so a checked-in `assetRoot:
+ * assets` means the same directory wherever `nowline` is run from.
+ */
+function absoluteAssetRoot(
+    value: string | undefined,
+    fromFlag: boolean,
+    rcPath: string | undefined,
+    cwd?: string,
+): string | undefined {
+    if (value === undefined) return undefined;
+    if (fromFlag || rcPath === undefined) return path.resolve(cwd ?? '.', value);
+    return path.resolve(path.dirname(rcPath), value);
+}
+
+// ---- Error text -------------------------------------------------------------
+
+/**
+ * An {@link OptionError} in the CLI's wording, naming the flag or `.nowlinerc`
+ * key the value came from: `nowline: invalid --width "abc". Must be an integer
+ * ≥ 320.` The templates are the ones the CLI used before the schema, so
+ * scripts that match them keep working.
+ */
+export function formatOptionError(error: OptionError<string>): string {
+    const lead = `nowline: invalid ${describeSource(error.source)} "${String(error.raw)}"`;
+    if (error.expected) return `${lead}. Expected ${formatChoices(error.expected)}.`;
+    switch (error.key) {
+        // Detail reads "must be YYYY-MM-DD, ...": the CLI says "Expected".
+        case 'now':
+            return `${lead}. Expected ${error.detail.replace(/^must be /, '')}.`;
+        // These two carry the parser's own message after a colon.
+        case 'pageSize':
+        case 'margin':
+            return `${lead}: ${error.detail}`;
+        default:
+            return `${lead}. ${error.detail.charAt(0).toUpperCase()}${error.detail.slice(1)}.`;
+    }
+}
+
+function describeSource(source: OptionError['source']): string {
+    switch (source.kind) {
+        case 'flag':
+        case 'argument':
+        case 'setting':
+            return source.name;
+        case 'rc':
+            return `.nowlinerc ${source.key}`;
+    }
+}
+
+// `a`, `a or b`, `a, b, or c`.
+export function formatChoices(names: readonly string[]): string {
+    if (names.length <= 2) return names.join(' or ');
+    return `${names.slice(0, -1).join(', ')}, or ${names[names.length - 1]}`;
+}

package/src/commands/init.ts

@@ -2,6 +2,7 @@ import type { ParsedArgs } from '../cli/args.js';
 import { defaultInitOutputPath, initNameHasIncompatibleExtension } from '../cli/output-path.js';
 import { TEMPLATE_NAMES, TEMPLATES, type TemplateName } from '../generated/templates.js';
 import { CliError, ExitCode } from '../io/exit-codes.js';
+import { createLog } from '../io/log.js';
 import { writeOutput } from '../io/write.js';
 
 export interface InitHandlerOptions {
@@ -47,9 +48,7 @@ export async function initHandler(options: InitHandlerOptions): Promise<void> {
 
     await writeOutput(outputPath, rendered, 'text', { cwd });
 
-    if (args.logLevel === 'verbose') {
-        process.stderr.write(`nowline: wrote ${outputPath}\n`);
-    }
+    createLog(args.logLevel).verbose(`nowline: wrote ${outputPath}`);
 }
 
 function parseTemplateName(raw: string | undefined): TemplateName {