@nowline/cli 0.2.0

package/src/cli/formats.ts

@@ -0,0 +1,207 @@
+import * as path from 'node:path';
+
+export type OutputFormat =
+    | 'svg'
+    | 'png'
+    | 'pdf'
+    | 'html'
+    | 'mermaid'
+    | 'xlsx'
+    | 'msproj'
+    | 'json'
+    | 'nowline';
+
+export type InputFormat = 'nowline' | 'json';
+
+const TEXT_FORMATS: ReadonlySet<OutputFormat> = new Set([
+    'svg',
+    'html',
+    'mermaid',
+    'msproj',
+    'json',
+    'nowline',
+]);
+
+const BINARY_FORMATS: ReadonlySet<OutputFormat> = new Set(['png', 'pdf', 'xlsx']);
+
+export const ALL_OUTPUT_FORMATS: readonly OutputFormat[] = [
+    'svg',
+    'png',
+    'pdf',
+    'html',
+    'mermaid',
+    'xlsx',
+    'msproj',
+    'json',
+    'nowline',
+];
+
+export function isOutputFormat(value: string): value is OutputFormat {
+    return (ALL_OUTPUT_FORMATS as readonly string[]).includes(value);
+}
+
+/**
+ * User-facing format aliases. The canonical token is `msproj` (matches the
+ * package name `@nowline/export-msproj`); `ms-project` and `mspx` are
+ * accepted shorthands documented in `specs/handoffs/m2c.md` § 8.
+ */
+const FORMAT_ALIASES: Readonly<Record<string, OutputFormat>> = {
+    'ms-project': 'msproj',
+    msproject: 'msproj',
+    mspx: 'msproj',
+    md: 'mermaid',
+    markdown: 'mermaid',
+    excel: 'xlsx',
+    'ms-excel': 'xlsx',
+};
+
+export function normalizeFormatAlias(raw: string): string {
+    const lower = raw.toLowerCase();
+    return FORMAT_ALIASES[lower] ?? lower;
+}
+
+export function isInputFormat(value: string): value is InputFormat {
+    return value === 'nowline' || value === 'json';
+}
+
+export function isBinaryFormat(format: OutputFormat): boolean {
+    return BINARY_FORMATS.has(format);
+}
+
+export function isTextFormat(format: OutputFormat): boolean {
+    return TEXT_FORMATS.has(format);
+}
+
+const EXTENSION_MAP: ReadonlyMap<string, OutputFormat> = new Map<string, OutputFormat>([
+    ['.svg', 'svg'],
+    ['.png', 'png'],
+    ['.pdf', 'pdf'],
+    ['.html', 'html'],
+    ['.htm', 'html'],
+    ['.md', 'mermaid'],
+    ['.markdown', 'mermaid'],
+    ['.xlsx', 'xlsx'],
+    ['.json', 'json'],
+    ['.nowline', 'nowline'],
+]);
+
+const CANONICAL_EXTENSION: Readonly<Record<OutputFormat, string>> = {
+    svg: '.svg',
+    png: '.png',
+    pdf: '.pdf',
+    html: '.html',
+    mermaid: '.md',
+    xlsx: '.xlsx',
+    msproj: '.xml',
+    json: '.json',
+    nowline: '.nowline',
+};
+
+/**
+ * Maps a recognized output extension to its canonical format.
+ *
+ * `.xml` is intentionally absent — it is ambiguous (MS Project XML vs generic
+ * XML) and requires `-f msproj` to disambiguate.
+ */
+export function formatFromExtension(extension: string): OutputFormat | undefined {
+    return EXTENSION_MAP.get(extension.toLowerCase());
+}
+
+export function canonicalExtension(format: OutputFormat): string {
+    return CANONICAL_EXTENSION[format];
+}
+
+export interface FormatResolutionInputs {
+    /** `-f / --format` flag value (already lower-cased). */
+    flagFormat?: string;
+    /** `-o / --output` path; the literal string the user wrote. */
+    outputPath?: string;
+    /** `defaultFormat` from `.nowlinerc`. */
+    configFormat?: string;
+    /** True when output is `-` (stdout); skips extension inference. */
+    isStdout?: boolean;
+}
+
+export interface FormatResolution {
+    format: OutputFormat;
+    /** Where the format came from. Useful for `-v` diagnostics. */
+    source: 'flag' | 'output-extension' | 'config' | 'fallback';
+}
+
+/**
+ * Resolves the output format using the documented precedence chain:
+ *
+ *   1. `-f / --format` flag
+ *   2. `-o <path>` recognized extension (skipped for `-` / stdout)
+ *   3. `.nowlinerc` `defaultFormat`
+ *   4. Built-in fallback `svg`
+ *
+ * Returns the resolved format and the precedence step that produced it. May
+ * throw a `FormatResolutionError` for unsupported / ambiguous inputs (caller
+ * is expected to surface this as an exit-2 usage error).
+ */
+export function resolveFormat(inputs: FormatResolutionInputs): FormatResolution {
+    if (inputs.flagFormat) {
+        const flag = normalizeFormatAlias(inputs.flagFormat);
+        if (!isOutputFormat(flag)) {
+            throw new FormatResolutionError(
+                `Unknown --format "${inputs.flagFormat}". Expected one of: ${ALL_OUTPUT_FORMATS.join(', ')}.`,
+            );
+        }
+        return { format: flag, source: 'flag' };
+    }
+
+    if (!inputs.isStdout && inputs.outputPath) {
+        const ext = path.extname(inputs.outputPath);
+        if (ext) {
+            if (ext.toLowerCase() === '.xml') {
+                throw new FormatResolutionError(
+                    'Cannot infer format from .xml extension; use -f msproj for MS Project XML output.',
+                );
+            }
+            const inferred = formatFromExtension(ext);
+            if (inferred) {
+                return { format: inferred, source: 'output-extension' };
+            }
+        }
+    }
+
+    if (inputs.configFormat) {
+        const cfg = normalizeFormatAlias(inputs.configFormat);
+        if (!isOutputFormat(cfg)) {
+            throw new FormatResolutionError(
+                `Invalid .nowlinerc defaultFormat "${inputs.configFormat}". Expected one of: ${ALL_OUTPUT_FORMATS.join(', ')}.`,
+            );
+        }
+        return { format: cfg, source: 'config' };
+    }
+
+    return { format: 'svg', source: 'fallback' };
+}
+
+/**
+ * Applies the documented output-extension auto-add rule:
+ *
+ * - If `<path>` ends in no extension, append the canonical extension for the
+ *   resolved format (`-o report -f pdf` → `report.pdf`).
+ * - If `<path>` ends in the canonical extension for the resolved format, leave
+ *   it alone.
+ * - If `<path>` ends in any *other* extension, leave it alone (no auto-rename).
+ *   The user wrote literal bytes; we trust them.
+ *
+ * Stdout (`-`) is never rewritten; callers should bypass this helper for stdout.
+ */
+export function autoAddExtension(outputPath: string, format: OutputFormat): string {
+    const ext = path.extname(outputPath);
+    if (!ext) {
+        return outputPath + canonicalExtension(format);
+    }
+    return outputPath;
+}
+
+export class FormatResolutionError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'FormatResolutionError';
+    }
+}

package/src/cli/help.ts

@@ -0,0 +1,92 @@
+import { fullVersionString } from '../version.js';
+
+// Use the dev-aware string here too: a contributor running `pnpm dev`
+// against a feature branch should see e.g. `0.1.0+abc1234.dirty` in
+// `--help` so it's obvious which build they're looking at.
+const HELP_TEXT = `nowline ${fullVersionString()} — render, validate, and serve .nowline roadmaps.
+
+USAGE
+  nowline <input> [options]
+  nowline --serve <input> [options]
+  nowline --init [<name>]
+  nowline --version
+  nowline --help
+
+INPUT
+  <input>                 Path to .nowline or .json, or '-' for stdin.
+                          Required for render, --serve, and --dry-run.
+
+I/O OPTIONS
+  -f, --format <fmt>      Output format: svg, png, pdf, html, mermaid, xlsx,
+                          msproj, json, nowline. Default: inferred from -o
+                          extension, else .nowlinerc 'defaultFormat', else svg.
+  -o, --output <path>     Output file path. Use '-' for stdout (Unix dash).
+                          Default: <cwd>/<input-base>.<format>.
+                          Existing files are silently overwritten.
+      --input-format <f>  Force input format: nowline | json. Default: by
+                          extension; stdin defaults to nowline.
+
+MODE FLAGS (mutually exclusive)
+      --serve             Live HTTP preview server. -o opt-in writes the
+                          rendered output to disk on each rebuild.
+      --init [<name>]     Scaffold a starter .nowline file in cwd. Positional
+                          becomes project name; .nowline appended if missing.
+  -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.
+
+RENDER OPTIONS
+  -t, --theme <name>      light | dark
+      --now <YYYY-MM-DD>  Date for the now-line. Default: today.
+                          Use --now - to suppress the now-line.
+      --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).
+      --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
+                          when the file does not declare its own
+                          'nowline v1 locale:' directive — the file always
+                          wins for content. Falls back to LC_ALL /
+                          LC_MESSAGES / LANG, then en-US.
+
+SERVE OPTIONS
+  -p, --port <n>          Port (default: 4318).
+      --host <host>       Bind address (default: 127.0.0.1).
+      --open              Open the browser on start.
+
+LOGGING (mutually exclusive)
+  -v, --verbose           Print extra diagnostics to stderr.
+  -q, --quiet             Suppress non-error stderr.
+
+STANDARD
+  -h, --help              Print this help and exit 0.
+  -V, --version           Print version and exit 0.
+
+EXAMPLES
+  nowline roadmap.nowline                   # writes ./roadmap.svg
+  nowline roadmap.nowline -f pdf            # writes ./roadmap.pdf
+  nowline roadmap.nowline -o roadmap.pdf    # format inferred from extension
+  nowline roadmap.nowline -o -              # SVG to stdout
+  cat foo.nowline | nowline -               # stdin → ./roadmap.svg
+  nowline roadmap.nowline -f json -o -      # JSON AST to stdout
+  nowline roadmap.nowline --dry-run         # validate-only
+  nowline roadmap.nowline --serve -p 8080   # live preview
+  nowline --init my-project                 # scaffold ./my-project.nowline
+
+EXIT CODES
+  0  Success
+  1  Validation error
+  2  Usage error (missing input, bad flags, format unavailable)
+  3  Output error (cannot write to destination)
+`;
+
+export function renderHelp(): string {
+    return HELP_TEXT;
+}
+
+export function renderVersion(): string {
+    return `${fullVersionString()}\n`;
+}

package/src/cli/output-path.ts

@@ -0,0 +1,98 @@
+import * as path from 'node:path';
+import { autoAddExtension, canonicalExtension, type OutputFormat } from './formats.js';
+
+export interface DefaultOutputInputs {
+    /** Original input argument: file path or `-` for stdin. */
+    inputArg: string;
+    /** True when input is `-` (stdin). */
+    isStdin: boolean;
+    /** Resolved output format. */
+    format: OutputFormat;
+    /** Current working directory; defaults to `process.cwd()`. */
+    cwd?: string;
+}
+
+/**
+ * Resolves the default output path for render operations when `-o` is absent.
+ *
+ * Rules:
+ * - Default-named outputs land in **cwd**, never next to the input.
+ * - File input: `<cwd>/<input-base>.<format>` (input directory is ignored).
+ * - Stdin input: `<cwd>/roadmap.<format>`.
+ */
+export function defaultRenderOutputPath(inputs: DefaultOutputInputs): string {
+    const cwd = inputs.cwd ?? process.cwd();
+    const ext = canonicalExtension(inputs.format);
+    if (inputs.isStdin) {
+        return path.join(cwd, `roadmap${ext}`);
+    }
+    const base = path.basename(inputs.inputArg, path.extname(inputs.inputArg)) || 'roadmap';
+    return path.join(cwd, `${base}${ext}`);
+}
+
+export interface InitOutputInputs {
+    /** Positional argument from `--init` (project name); undefined → default `roadmap`. */
+    name?: string;
+    /** Current working directory; defaults to `process.cwd()`. */
+    cwd?: string;
+}
+
+/**
+ * Resolves the output path for `--init`. The positional is treated as a project
+ * *name*, not a file path:
+ *
+ *  - No extension (`my-project`) → append `.nowline`.
+ *  - Already `.nowline` → use literal.
+ *  - Other extension → caller should reject as a usage error (exit 2).
+ *  - Missing → default name `roadmap`.
+ */
+export function defaultInitOutputPath(inputs: InitOutputInputs): string {
+    const cwd = inputs.cwd ?? process.cwd();
+    const name = inputs.name ?? 'roadmap';
+    const ext = path.extname(name);
+    if (!ext) {
+        return path.join(cwd, `${name}.nowline`);
+    }
+    return path.join(cwd, name);
+}
+
+/**
+ * Returns true when an `--init` positional has an extension other than
+ * `.nowline`. Caller should reject this with an exit-2 usage error.
+ */
+export function initNameHasIncompatibleExtension(name: string): boolean {
+    const ext = path.extname(name).toLowerCase();
+    return ext !== '' && ext !== '.nowline';
+}
+
+/**
+ * Resolves the final output path for render operations, applying the
+ * extension-auto-add rule when `-o` is provided and has no extension.
+ */
+export function resolveRenderOutputPath(args: {
+    outputArg: string | undefined;
+    isStdout: boolean;
+    inputArg: string;
+    isStdin: boolean;
+    format: OutputFormat;
+    cwd?: string;
+}): { path: string; isStdout: boolean } {
+    if (args.isStdout) {
+        return { path: '-', isStdout: true };
+    }
+    if (args.outputArg !== undefined) {
+        return {
+            path: autoAddExtension(args.outputArg, args.format),
+            isStdout: false,
+        };
+    }
+    return {
+        path: defaultRenderOutputPath({
+            inputArg: args.inputArg,
+            isStdin: args.isStdin,
+            format: args.format,
+            cwd: args.cwd,
+        }),
+        isStdout: false,
+    };
+}

package/src/commands/init.ts

@@ -0,0 +1,99 @@
+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 { writeOutput } from '../io/write.js';
+
+export interface InitHandlerOptions {
+    args: ParsedArgs;
+    /** Test seam: cwd override. Defaults to `process.cwd()`. */
+    cwd?: string;
+}
+
+/**
+ * `--init` mode handler. Scaffolds a starter `.nowline` file in cwd.
+ *
+ * Positional argument is the project *name*, not a file path:
+ *   - No extension      → append `.nowline`.
+ *   - `.nowline`        → use literal.
+ *   - Other extension   → exit 2.
+ *   - Missing positional → default name "roadmap".
+ *
+ * `-o` overrides the resolved path. Existing files are silently overwritten.
+ */
+export async function initHandler(options: InitHandlerOptions): Promise<void> {
+    const { args } = options;
+    const cwd = options.cwd ?? process.cwd();
+    const template = parseTemplateName(args.template);
+    const positional = args.positional;
+
+    if (
+        positional !== undefined &&
+        positional !== '' &&
+        initNameHasIncompatibleExtension(positional)
+    ) {
+        throw new CliError(
+            ExitCode.InputError,
+            `nowline: --init only scaffolds .nowline files; got "${positional}".`,
+        );
+    }
+
+    const projectName = projectNameFor(positional);
+    const titleName = titleFor(positional);
+    const templateText = TEMPLATES[template];
+    const rendered = applyName(templateText, titleName);
+
+    const outputPath = args.output ?? defaultInitOutputPath({ name: projectName, cwd });
+
+    await writeOutput(outputPath, rendered, 'text', { cwd });
+
+    if (args.logLevel === 'verbose') {
+        process.stderr.write(`nowline: wrote ${outputPath}\n`);
+    }
+}
+
+function parseTemplateName(raw: string | undefined): TemplateName {
+    const value = (raw ?? '').toLowerCase();
+    if (value === '') return 'minimal';
+    if ((TEMPLATE_NAMES as readonly string[]).includes(value)) {
+        return value as TemplateName;
+    }
+    throw new CliError(
+        ExitCode.InputError,
+        `nowline: unknown --template "${raw}". Choose one of: ${TEMPLATE_NAMES.join(', ')}.`,
+    );
+}
+
+function projectNameFor(positional: string | undefined): string | undefined {
+    if (!positional) return undefined;
+    return positional;
+}
+
+/**
+ * Returns the title to substitute into the roadmap declaration. When the user
+ * passes a positional we use it as-is; trailing `.nowline` is stripped so the
+ * title isn't `My Plan.nowline`.
+ */
+function titleFor(positional: string | undefined): string | undefined {
+    if (!positional) return undefined;
+    return positional.endsWith('.nowline') ? positional.slice(0, -'.nowline'.length) : positional;
+}
+
+export function applyName(template: string, name: string | undefined): string {
+    if (!name) return template;
+    const lines = template.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!/^\s*roadmap\b/.test(line)) continue;
+        lines[i] = rewriteRoadmapTitle(line, name);
+        break;
+    }
+    return lines.join('\n');
+}
+
+function rewriteRoadmapTitle(line: string, name: string): string {
+    const match = line.match(/^(\s*roadmap\s+[A-Za-z_][A-Za-z0-9_-]*)(\s+"[^"]*")?(.*)$/);
+    if (!match) return line;
+    const [, head, , tail] = match;
+    return `${head} ${JSON.stringify(name)}${tail}`;
+}