@nowline/cli 0.2.0

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@nowline/cli",
+  "version": "0.2.0",
+  "description": "Nowline command-line interface — validate, convert, init",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "nowline": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "man": [
+    "./man/nowline.1",
+    "./man/nowline.5"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "man/",
+    "src/",
+    "scripts/"
+  ],
+  "dependencies": {
+    "@babel/code-frame": "^7.29.0",
+    "@clack/prompts": "^0.11.0",
+    "chalk": "^5.6.0",
+    "citty": "^0.2.2",
+    "consola": "^3.4.0",
+    "js-yaml": "^4.1.0",
+    "langium": "~4.2.2",
+    "@nowline/config": "0.2.0",
+    "@nowline/core": "0.2.0",
+    "@nowline/export-core": "0.2.0",
+    "@nowline/export-html": "0.2.0",
+    "@nowline/export-mermaid": "0.2.0",
+    "@nowline/export-msproj": "0.2.0",
+    "@nowline/export-png": "0.2.0",
+    "@nowline/layout": "0.2.0",
+    "@nowline/export-pdf": "0.2.0",
+    "@nowline/renderer": "0.2.0",
+    "@nowline/export-xlsx": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/babel__code-frame": "^7.0.6",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "typescript": "~5.7.0",
+    "vitest": "^3.1.0"
+  },
+  "scripts": {
+    "bundle-templates": "node scripts/bundle-templates.mjs",
+    "prebuild": "node scripts/bundle-templates.mjs",
+    "build": "tsc -b tsconfig.json",
+    "watch": "tsc -b tsconfig.json --watch",
+    "pretest": "node scripts/bundle-templates.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "compile": "node scripts/compile.mjs",
+    "compile:local": "node scripts/compile.mjs --target=local"
+  }
+}

package/scripts/bundle-templates.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, '..');
+const repoRoot = path.resolve(packageRoot, '..', '..');
+const examplesDir = path.join(repoRoot, 'examples');
+const outDir = path.join(packageRoot, 'src', 'generated');
+
+const TEMPLATES = [
+    { name: 'minimal', file: 'minimal.nowline' },
+    { name: 'teams', file: 'teams.nowline' },
+    { name: 'product', file: 'product.nowline' },
+];
+
+mkdirSync(outDir, { recursive: true });
+
+// 1. Templates
+const templatesOutFile = path.join(outDir, 'templates.ts');
+const entries = TEMPLATES.map(({ name, file }) => {
+    const abs = path.join(examplesDir, file);
+    const contents = readFileSync(abs, 'utf-8');
+    return `    ${JSON.stringify(name)}: ${JSON.stringify(contents)}`;
+});
+
+const templatesBanner = [
+    '// Auto-generated by scripts/bundle-templates.mjs. Do not edit by hand.',
+    '// Run `pnpm run bundle-templates` to regenerate.',
+    '',
+    "export type TemplateName = 'minimal' | 'teams' | 'product';",
+    '',
+    "export const TEMPLATE_NAMES: readonly TemplateName[] = ['minimal', 'teams', 'product'];",
+    '',
+    'export const TEMPLATES: Record<TemplateName, string> = {',
+].join('\n');
+
+const templatesFooter = '\n};\n';
+
+writeFileSync(templatesOutFile, `${templatesBanner}\n${entries.join(',\n')}${templatesFooter}`);
+console.log(`wrote ${path.relative(packageRoot, templatesOutFile)}`);
+
+// 2. Version + build metadata.
+//
+// CLI_VERSION is the static SemVer from package.json (the same string
+// `npm publish` uses). CLI_BUILD captures the git state at compile time
+// so `nowline --version` can distinguish a tagged release from a dev
+// build. The two are emitted side-by-side; the renderer composes the
+// final string at runtime per SemVer's build-metadata rules:
+//
+//   release        -> "0.1.0"
+//   dev (clean)    -> "0.1.0+abc1234"
+//   dev (dirty)    -> "0.1.0+abc1234.dirty"
+//
+// `+...` is SemVer build metadata (RFC 2.0 §10) — informational only;
+// publishers (npm, Marketplace) reject it on their own version fields,
+// so it never reaches package.json.
+
+const versionOutFile = path.join(outDir, 'version.ts');
+const pkg = JSON.parse(readFileSync(path.join(packageRoot, 'package.json'), 'utf-8'));
+
+function tryGit(args) {
+    try {
+        return execFileSync('git', args, {
+            cwd: repoRoot,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf-8',
+        }).trim();
+    } catch {
+        return '';
+    }
+}
+
+const sha = tryGit(['rev-parse', '--short=7', 'HEAD']);
+// `--exact-match` exits non-zero (and tryGit returns '') when HEAD is
+// not a tagged commit, which we treat as "this is a dev build".
+const exactTag = tryGit(['describe', '--exact-match', '--tags', 'HEAD']);
+const expectedTag = `v${pkg.version}`;
+const isRelease = exactTag === expectedTag;
+const isDirty = tryGit(['status', '--porcelain']) !== '';
+
+writeFileSync(
+    versionOutFile,
+    [
+        '// Auto-generated by scripts/bundle-templates.mjs. Do not edit by hand.',
+        '',
+        `export const CLI_VERSION = ${JSON.stringify(pkg.version)};`,
+        '',
+        'export interface CliBuild {',
+        '    /** Short git SHA at build time, or empty when not in a git checkout. */',
+        '    readonly sha: string;',
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: emits a TypeScript JSDoc comment that intentionally contains a template-literal placeholder string for readers, not for evaluation.
+        '    /** True when HEAD is the tag matching `v${CLI_VERSION}`. */',
+        '    readonly isRelease: boolean;',
+        '    /** True when the working tree had uncommitted changes at build time. */',
+        '    readonly isDirty: boolean;',
+        '}',
+        '',
+        `export const CLI_BUILD: CliBuild = ${JSON.stringify({ sha, isRelease, isDirty }, null, 4)};`,
+        '',
+    ].join('\n'),
+);
+console.log(`wrote ${path.relative(packageRoot, versionOutFile)}`);

package/scripts/compile.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// Compile the CLI into standalone binaries for the six supported targets.
+// Uses `bun build --compile`. Requires bun to be installed; delegates errors
+// from bun rather than attempting a polyfill.
+//
+// One binary per platform: `nowline-<suffix>`. Bundles every `@nowline/export-*`
+// package — see `specs/cli-distribution.md` for the rationale (the bun runtime
+// dominates compiled binary size; a tiny/full split paid only ~5% size dividend
+// for the cost of doubled CI/release/distribution channels).
+
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, '..');
+
+// Per-target size ceilings (MB). Bun's standalone runtime varies by ~50 MB
+// across targets — darwin-arm64 ships ~60 MB, linux-x64 with glibc compat
+// shims is ~95 MB, and windows-x64 is ~110 MB. A single global ceiling would
+// either let darwin regressions slide or fail every Linux/Windows build, so
+// each target carries its own budget = (currently measured size) + ~6–10 MB
+// headroom for future bun-runtime growth and modest exporter additions.
+// Tight by design: a breach should trigger the conversation called out in
+// `specs/cli-distribution.md` "Size budget", not be silently absorbed.
+//
+// Last measured (bun 1.3.13) using --target on macOS-arm64:
+//   darwin-arm64=70  darwin-x64=75  linux-arm64=107  linux-x64=107
+//   windows-arm64=119  windows-x64=122
+const ALL_TARGETS = [
+    { id: 'bun-darwin-arm64', suffix: 'macos-arm64', maxMb: 80 },
+    { id: 'bun-darwin-x64', suffix: 'macos-x64', maxMb: 85 },
+    { id: 'bun-linux-x64', suffix: 'linux-x64', maxMb: 115 },
+    { id: 'bun-linux-arm64', suffix: 'linux-arm64', maxMb: 115 },
+    { id: 'bun-windows-x64', suffix: 'windows-x64.exe', maxMb: 130 },
+    { id: 'bun-windows-arm64', suffix: 'windows-arm64.exe', maxMb: 125 },
+];
+
+function parseArgs(argv) {
+    const out = { target: 'all' };
+    for (const arg of argv.slice(2)) {
+        if (arg.startsWith('--target=')) out.target = arg.slice('--target='.length);
+    }
+    return out;
+}
+
+function pickTargets(selector) {
+    if (selector === 'all') return ALL_TARGETS;
+    if (selector === 'local') {
+        const platformMap = {
+            'darwin/arm64': 'bun-darwin-arm64',
+            'darwin/x64': 'bun-darwin-x64',
+            'linux/x64': 'bun-linux-x64',
+            'linux/arm64': 'bun-linux-arm64',
+            'win32/x64': 'bun-windows-x64',
+            'win32/arm64': 'bun-windows-arm64',
+        };
+        const key = `${process.platform}/${process.arch}`;
+        const id = platformMap[key];
+        if (!id) throw new Error(`Unsupported local platform: ${key}`);
+        return ALL_TARGETS.filter((t) => t.id === id);
+    }
+    const match = ALL_TARGETS.filter((t) => t.id === selector || t.suffix === selector);
+    if (match.length === 0) throw new Error(`Unknown --target: ${selector}`);
+    return match;
+}
+
+function main() {
+    const { target } = parseArgs(process.argv);
+    const targets = pickTargets(target);
+    const outDir = path.join(packageRoot, 'dist-bin');
+    if (!safeStat(outDir)) {
+        mkdirSync(outDir, { recursive: true });
+    } else {
+        for (const name of readdirSync(outDir)) {
+            if (name.startsWith('nowline-')) {
+                rmSync(path.join(outDir, name), { force: true });
+            }
+        }
+    }
+
+    const entry = path.join(packageRoot, 'dist', 'index.js');
+    if (!safeStat(entry)) {
+        console.error(
+            `error: expected ${path.relative(packageRoot, entry)} to exist; run \`pnpm build\` first.`,
+        );
+        process.exit(1);
+    }
+
+    let failed = 0;
+    for (const tgt of targets) {
+        const outName = `nowline-${tgt.suffix}`;
+        const outPath = path.join(outDir, outName);
+        console.log(`compiling ${tgt.id} -> ${path.relative(packageRoot, outPath)}`);
+        const args = ['build', entry, '--compile', '--target', tgt.id, '--outfile', outPath];
+        const result = spawnSync('bun', args, { stdio: 'inherit', cwd: packageRoot });
+        if (result.status !== 0) {
+            console.error(`  FAILED ${tgt.id}`);
+            failed += 1;
+        }
+    }
+
+    const targetBySuffix = new Map(ALL_TARGETS.map((t) => [`nowline-${t.suffix}`, t]));
+    for (const entryName of readdirSync(outDir)) {
+        if (!entryName.startsWith('nowline-')) continue;
+        const tgt = targetBySuffix.get(entryName);
+        if (!tgt) continue; // unknown artifact; size budget is per known target
+        const p = path.join(outDir, entryName);
+        const size = statSync(p).size;
+        const mb = (size / 1024 / 1024).toFixed(1);
+        const maxBytes = tgt.maxMb * 1024 * 1024;
+        console.log(`  ${entryName}: ${mb} MB (max ${tgt.maxMb} MB)`);
+        if (size > maxBytes) {
+            console.error(`    ERROR: ${entryName} is larger than ${tgt.maxMb} MB (${mb} MB).`);
+            failed += 1;
+        }
+    }
+
+    process.exit(failed === 0 ? 0 : 1);
+}
+
+function safeStat(p) {
+    try {
+        return statSync(p);
+    } catch {
+        return undefined;
+    }
+}
+
+main();

package/src/cli/args.ts

@@ -0,0 +1,252 @@
+import { type ParseArgsConfig, parseArgs } from 'node:util';
+import { CliError, ExitCode } from '../io/exit-codes.js';
+
+export type ModeKind = 'render' | 'serve' | 'init' | 'help' | 'version';
+
+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?: string;
+    /** True if `--dry-run` / `-n` was passed (only valid for render mode). */
+    dryRun: boolean;
+    /** Logging level. Verbose and quiet are mutually exclusive. */
+    logLevel: 'verbose' | 'quiet' | 'normal';
+
+    // I/O
+    output?: string;
+    format?: string;
+    inputFormat?: string;
+
+    // Render options
+    theme?: string;
+    /** Now-line date string from `--now`. Undefined means "use the actual
+     *  current date" (the default). The literal value `"-"` means
+     *  "suppress the now-line entirely" (mirrors the Unix-`-` convention
+     *  used elsewhere in the CLI). Otherwise expected as YYYY-MM-DD;
+     *  parsed downstream by resolveNowArg. */
+    now?: string;
+    noLinks: boolean;
+    scale?: string;
+    strict: boolean;
+    width?: string;
+    assetRoot?: string;
+
+    // Format-specific options (m2c)
+    pageSize?: string;
+    orientation?: string;
+    margin?: string;
+    fontSans?: string;
+    fontMono?: string;
+    headless: boolean;
+    start?: string;
+
+    /**
+     * BCP-47 locale override (`fr-CA`, `fr`, …). When omitted the CLI
+     * falls back to `LC_ALL` / `LC_MESSAGES` / `LANG`, then to the
+     * file's `nowline v1 locale:` directive, then to `en-US`. See
+     * `specs/localization.md`.
+     */
+    locale?: string;
+
+    // Serve options
+    port?: string;
+    host?: string;
+    open: boolean;
+
+    // Validate / dry-run formatting
+    diagnosticFormat?: string;
+
+    // Init
+    template?: string;
+}
+
+/**
+ * Pure argument parser. Walks `argv` once, identifies mode flags, applies
+ * mutual-exclusivity rules, and returns a fully-resolved `ParsedArgs`. Throws
+ * `CliError(ExitCode.InputError)` for usage errors.
+ *
+ * Help / version short-circuit any other flag combinations.
+ */
+export function parseArgv(argv: readonly string[]): ParsedArgs {
+    if (argv.length === 0) {
+        return {
+            mode: 'help',
+            dryRun: false,
+            logLevel: 'normal',
+            noLinks: false,
+            strict: false,
+            open: false,
+            headless: false,
+        };
+    }
+
+    const config: ParseArgsConfig = {
+        args: argv as string[],
+        allowPositionals: true,
+        strict: true,
+        options: {
+            help: { type: 'boolean', short: 'h' },
+            version: { type: 'boolean', short: 'V' },
+            verbose: { type: 'boolean', short: 'v' },
+            quiet: { type: 'boolean', short: 'q' },
+
+            output: { type: 'string', short: 'o' },
+            format: { type: 'string', short: 'f' },
+            'input-format': { type: 'string' },
+
+            serve: { type: 'boolean' },
+            init: { type: 'boolean' },
+            'dry-run': { type: 'boolean', short: 'n' },
+
+            theme: { type: 'string', short: 't' },
+            // `--now <date>` overrides the now-line position; without it, the
+            // CLI defaults to today's calendar date. Use `--now -` to
+            // suppress the now-line entirely (Unix-`-` sentinel; same idea
+            // as `-o -` for stdout).
+            now: { type: 'string' },
+            'no-links': { type: 'boolean' },
+            scale: { type: 'string', short: 's' },
+            strict: { type: 'boolean' },
+            width: { type: 'string', short: 'w' },
+            'asset-root': { type: 'string' },
+
+            port: { type: 'string', short: 'p' },
+            host: { type: 'string' },
+            open: { type: 'boolean' },
+
+            'diagnostic-format': { type: 'string' },
+
+            template: { type: 'string' },
+
+            // Format-specific (m2c)
+            'page-size': { type: 'string' },
+            orientation: { type: 'string' },
+            margin: { type: 'string' },
+            'font-sans': { type: 'string' },
+            'font-mono': { type: 'string' },
+            headless: { type: 'boolean' },
+            start: { type: 'string' },
+
+            // Localization (m-loc-b)
+            locale: { type: 'string' },
+        },
+    };
+
+    let parsed: ReturnType<typeof parseArgs>;
+    try {
+        parsed = parseArgs(config);
+    } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new CliError(ExitCode.InputError, formatUsageError(message));
+    }
+
+    const values = parsed.values as Record<string, unknown>;
+    const positionals = parsed.positionals;
+
+    if (values.help === true) {
+        return {
+            mode: 'help',
+            dryRun: false,
+            logLevel: 'normal',
+            noLinks: false,
+            strict: false,
+            open: false,
+            headless: false,
+        };
+    }
+    if (values.version === true) {
+        return {
+            mode: 'version',
+            dryRun: false,
+            logLevel: 'normal',
+            noLinks: false,
+            strict: false,
+            open: false,
+            headless: false,
+        };
+    }
+
+    if (values.verbose === true && values.quiet === true) {
+        throw new CliError(
+            ExitCode.InputError,
+            'nowline: --verbose and --quiet are mutually exclusive.',
+        );
+    }
+
+    const modes: ModeKind[] = [];
+    if (values.serve === true) modes.push('serve');
+    if (values.init === true) modes.push('init');
+    if (modes.length > 1) {
+        throw new CliError(
+            ExitCode.InputError,
+            `nowline: --${modes[0]} and --${modes[1]} are mutually exclusive.`,
+        );
+    }
+
+    const dryRun = values['dry-run'] === true;
+    const mode: ModeKind = modes[0] ?? 'render';
+
+    if (dryRun && (mode === 'serve' || mode === 'init')) {
+        throw new CliError(
+            ExitCode.InputError,
+            `nowline: --dry-run cannot be combined with --${mode}.`,
+        );
+    }
+
+    if (positionals.length > 1) {
+        const extras = positionals
+            .slice(1)
+            .map((p) => JSON.stringify(p))
+            .join(' ');
+        throw new CliError(ExitCode.InputError, `nowline: unexpected extra arguments: ${extras}.`);
+    }
+
+    const logLevel: ParsedArgs['logLevel'] =
+        values.verbose === true ? 'verbose' : values.quiet === true ? 'quiet' : 'normal';
+
+    return {
+        mode,
+        positional: positionals[0],
+        dryRun,
+        logLevel,
+        output: stringOrUndefined(values.output),
+        format: stringOrUndefined(values.format),
+        inputFormat: stringOrUndefined(values['input-format']),
+        theme: stringOrUndefined(values.theme),
+        now: stringOrUndefined(values.now),
+        noLinks: values['no-links'] === true,
+        scale: stringOrUndefined(values.scale),
+        strict: values.strict === true,
+        width: stringOrUndefined(values.width),
+        assetRoot: stringOrUndefined(values['asset-root']),
+        port: stringOrUndefined(values.port),
+        host: stringOrUndefined(values.host),
+        open: values.open === true,
+        diagnosticFormat: stringOrUndefined(values['diagnostic-format']),
+        template: stringOrUndefined(values.template),
+        pageSize: stringOrUndefined(values['page-size']),
+        orientation: stringOrUndefined(values.orientation),
+        margin: stringOrUndefined(values.margin),
+        fontSans: stringOrUndefined(values['font-sans']),
+        fontMono: stringOrUndefined(values['font-mono']),
+        headless: values.headless === true,
+        start: stringOrUndefined(values.start),
+        locale: stringOrUndefined(values.locale),
+    };
+}
+
+function stringOrUndefined(value: unknown): string | undefined {
+    if (typeof value === 'string') return value;
+    return undefined;
+}
+
+function formatUsageError(message: string): string {
+    if (message.startsWith('Unknown option')) {
+        return `nowline: ${message}. Try --help for usage.`;
+    }
+    if (message.includes('expected')) {
+        return `nowline: ${message}. Try --help for usage.`;
+    }
+    return `nowline: ${message}`;
+}