@nowline/cli 0.2.0

package/src/diagnostics/adapt.ts

@@ -0,0 +1,148 @@
+import type { CliDiagnostic, DiagnosticSeverity, LocalizedMessageData } from './model.js';
+
+// Minimal LSP-style diagnostic shape. Langium re-exports vscode-languageserver-types'
+// Diagnostic internally; we keep a narrow local type to avoid a direct coupling and
+// to survive cross-version type relocations.
+export interface LangiumLikeDiagnostic {
+    message: string;
+    severity?: number;
+    code?: string | number;
+    range?: {
+        start: { line: number; character: number };
+        end: { line: number; character: number };
+    };
+    /**
+     * Validator's stash for re-formattable messages. The shape is
+     * `{ code: MessageCode, args: MessageArgs<K> }`; we keep it
+     * `unknown` here to avoid coupling the CLI's diagnostic adapter
+     * to `@nowline/core`'s internal i18n types.
+     */
+    data?: unknown;
+}
+
+// Minimal shapes for chevrotain parser/lexer errors to avoid pulling chevrotain types.
+interface ChevrotainParserError {
+    message: string;
+    token?: {
+        startLine?: number;
+        startColumn?: number;
+        startOffset?: number;
+        endLine?: number;
+        endColumn?: number;
+        endOffset?: number;
+    };
+}
+
+interface ChevrotainLexerError {
+    message: string;
+    line?: number;
+    column?: number;
+    offset?: number;
+    length?: number;
+}
+
+export function adaptLangiumDiagnostic(diag: LangiumLikeDiagnostic, file: string): CliDiagnostic {
+    const severity = mapSeverity(diag.severity);
+    const line = (diag.range?.start.line ?? 0) + 1;
+    const column = (diag.range?.start.character ?? 0) + 1;
+    const data = extractMessageData(diag.data);
+    return {
+        file,
+        line,
+        column,
+        severity,
+        // Localized validator data carries the stable message code; prefer it
+        // over the heuristic message-substring inference below.
+        code: data?.code ?? diagnosticCode(diag),
+        message: diag.message,
+        span: diag.range
+            ? {
+                  start: { line, column },
+                  end: {
+                      line: (diag.range.end.line ?? 0) + 1,
+                      column: (diag.range.end.character ?? 0) + 1,
+                  },
+              }
+            : undefined,
+        suggestion: extractSuggestion(diag.message),
+        data,
+    };
+}
+
+/**
+ * Validate the shape of `diag.data`. Validator-emitted diagnostics
+ * stash `{ code: MessageCode, args: MessageArgs<K> }` (where `args` is
+ * the spread tuple `[]` or `[{...}]`). Anything else (vscode code
+ * actions, third-party data, etc.) is ignored.
+ */
+function extractMessageData(data: unknown): LocalizedMessageData | undefined {
+    if (!data || typeof data !== 'object') return undefined;
+    const obj = data as { code?: unknown; args?: unknown };
+    if (typeof obj.code !== 'string') return undefined;
+    if (!Array.isArray(obj.args)) return undefined;
+    return { code: obj.code, args: obj.args };
+}
+
+export function adaptParserError(err: ChevrotainParserError, file: string): CliDiagnostic {
+    const line = err.token?.startLine ?? 1;
+    const column = err.token?.startColumn ?? 1;
+    const endLine = err.token?.endLine ?? line;
+    const endColumn = (err.token?.endColumn ?? column) + 1;
+    return {
+        file,
+        line,
+        column,
+        severity: 'error',
+        code: 'parse-error',
+        message: err.message,
+        span: { start: { line, column }, end: { line: endLine, column: endColumn } },
+    };
+}
+
+export function adaptLexerError(err: ChevrotainLexerError, file: string): CliDiagnostic {
+    const line = err.line ?? 1;
+    const column = err.column ?? 1;
+    const length = err.length ?? 1;
+    return {
+        file,
+        line,
+        column,
+        severity: 'error',
+        code: 'lex-error',
+        message: err.message,
+        span: {
+            start: { line, column },
+            end: { line, column: column + Math.max(length, 1) },
+        },
+    };
+}
+
+function mapSeverity(severity: number | undefined): DiagnosticSeverity {
+    return severity === 2 ? 'warning' : 'error';
+}
+
+function diagnosticCode(diag: LangiumLikeDiagnostic): string {
+    if (typeof diag.code === 'string' && diag.code !== '') return diag.code;
+    if (typeof diag.code === 'number') return String(diag.code);
+    return inferCodeFromMessage(diag.message);
+}
+
+function inferCodeFromMessage(message: string): string {
+    const lower = message.toLowerCase();
+    if (lower.includes('duplicate identifier')) return 'duplicate-identifier';
+    if (lower.includes('unknown reference') || lower.includes('did you mean'))
+        return 'unknown-reference';
+    if (lower.includes('circular')) return 'circular-dependency';
+    if (lower.includes('requires') && lower.includes('date:')) return 'missing-date';
+    if (lower.includes('duration')) return 'duration';
+    if (lower.includes('include')) return 'include';
+    if (lower.includes('indent')) return 'indentation';
+    return 'validation';
+}
+
+const DID_YOU_MEAN_RE = /did you mean ['"]?([^'"?]+)['"]?\??/i;
+
+function extractSuggestion(message: string): string | undefined {
+    const match = message.match(DID_YOU_MEAN_RE);
+    return match ? match[1].trim() : undefined;
+}

package/src/diagnostics/format.ts

@@ -0,0 +1,70 @@
+import { type MessageCode, tr } from '@nowline/core';
+import { renderJson } from './json.js';
+import type { CliDiagnostic, DiagnosticSource } from './model.js';
+import { renderText } from './text.js';
+
+export type DiagnosticFormat = 'text' | 'json';
+
+export interface FormatDiagnosticsOptions {
+    color?: boolean;
+    /**
+     * Operator locale (BCP-47) used to re-format validator messages
+     * that carry `data: { code, args }`. Validator messages without
+     * `data` and parser/lexer errors pass through unchanged.
+     *
+     * Defaults to en-US: an unset operator locale produces the same
+     * canonical English text the validator stashed at parse time.
+     * See `specs/localization.md` for the two-chain model.
+     */
+    operatorLocale?: string;
+}
+
+export function isDiagnosticFormat(value: unknown): value is DiagnosticFormat {
+    return value === 'text' || value === 'json';
+}
+
+export function formatDiagnostics(
+    diagnostics: CliDiagnostic[],
+    format: DiagnosticFormat,
+    sources: Map<string, DiagnosticSource>,
+    options: FormatDiagnosticsOptions = {},
+): string {
+    const localized = relocalizeDiagnostics(diagnostics, options.operatorLocale);
+    if (format === 'json') return renderJson(localized);
+    return renderText(localized, sources, { color: options.color });
+}
+
+/**
+ * Re-format any diagnostic carrying `data.{code,args}` in the operator
+ * locale. Diagnostics without `data` (literal-English validator
+ * strings, parser/lexer errors, include-resolution errors) pass
+ * through verbatim.
+ *
+ * No-op when `operatorLocale` is undefined or `'en-US'`: the messages
+ * stashed by the validator are already en-US, so we avoid the work
+ * and the allocation in the common case.
+ */
+function relocalizeDiagnostics(
+    diagnostics: CliDiagnostic[],
+    operatorLocale: string | undefined,
+): CliDiagnostic[] {
+    if (!operatorLocale || operatorLocale === 'en-US') return diagnostics;
+    return diagnostics.map((d) => {
+        if (!d.data) return d;
+        // The validator stashes args as the verbatim spread tuple it received,
+        // typed strongly per-code in `@nowline/core/i18n`. By the time it
+        // reaches us through `unknown` it has lost that tagged shape; we cast
+        // back here because the only producer is the validator and the
+        // `code` half of the pair pins the expected arity.
+        const args = d.data.args as Parameters<typeof tr<MessageCode>> extends [
+            string,
+            MessageCode,
+            ...infer R,
+        ]
+            ? R
+            : never;
+        const message = tr(operatorLocale, d.data.code as MessageCode, ...args);
+        if (message === d.message) return d;
+        return { ...d, message };
+    });
+}

package/src/diagnostics/index.ts

@@ -0,0 +1,4 @@
+export * from './adapt.js';
+export * from './format.js';
+export { DIAGNOSTICS_SCHEMA_VERSION, type DiagnosticsDocument } from './json.js';
+export * from './model.js';

package/src/diagnostics/json.ts

@@ -0,0 +1,30 @@
+import type { CliDiagnostic } from './model.js';
+
+export const DIAGNOSTICS_SCHEMA_VERSION = '1';
+
+export interface DiagnosticsDocument {
+    $nowlineDiagnostics: string;
+    diagnostics: CliDiagnostic[];
+}
+
+export function renderJson(diagnostics: CliDiagnostic[]): string {
+    const doc: DiagnosticsDocument = {
+        $nowlineDiagnostics: DIAGNOSTICS_SCHEMA_VERSION,
+        diagnostics: diagnostics.map(normalize),
+    };
+    return JSON.stringify(doc, null, 2);
+}
+
+function normalize(d: CliDiagnostic): CliDiagnostic {
+    const out: CliDiagnostic = {
+        file: d.file,
+        line: d.line,
+        column: d.column,
+        severity: d.severity,
+        code: d.code,
+        message: d.message,
+    };
+    if (d.suggestion) out.suggestion = d.suggestion;
+    if (d.span) out.span = d.span;
+    return out;
+}

package/src/diagnostics/model.ts

@@ -0,0 +1,48 @@
+export type DiagnosticSeverity = 'error' | 'warning';
+
+export interface SourcePosition {
+    line: number;
+    column: number;
+    offset?: number;
+}
+
+export interface SourceSpan {
+    start: SourcePosition;
+    end: SourcePosition;
+}
+
+/**
+ * Carries the validator's stable message code plus the named-argument
+ * record it was formatted from, so the CLI can re-format the human
+ * message in the operator's locale at print time. See
+ * `specs/localization.md` for the two-chain precedence model.
+ */
+export interface LocalizedMessageData {
+    code: string;
+    args: ReadonlyArray<unknown>;
+}
+
+export interface CliDiagnostic {
+    file: string;
+    line: number;
+    column: number;
+    severity: DiagnosticSeverity;
+    code: string;
+    message: string;
+    suggestion?: string;
+    span?: SourceSpan;
+    /**
+     * 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`
+     * from this when an operator locale is supplied to
+     * `formatDiagnostics`.
+     */
+    data?: LocalizedMessageData;
+}
+
+export interface DiagnosticSource {
+    file: string;
+    contents: string;
+}

package/src/diagnostics/text.ts

@@ -0,0 +1,62 @@
+import { codeFrameColumns } from '@babel/code-frame';
+import chalk from 'chalk';
+import type { CliDiagnostic, DiagnosticSource } from './model.js';
+
+export interface RenderTextOptions {
+    color?: boolean;
+}
+
+export function renderText(
+    diagnostics: CliDiagnostic[],
+    sources: Map<string, DiagnosticSource>,
+    options: RenderTextOptions = {},
+): string {
+    const useColor = options.color ?? chalk.level > 0;
+    const parts = diagnostics.map((d) => renderOne(d, sources.get(d.file), useColor));
+    return parts.join('\n\n');
+}
+
+function renderOne(
+    diag: CliDiagnostic,
+    source: DiagnosticSource | undefined,
+    useColor: boolean,
+): string {
+    const header = renderHeader(diag, useColor);
+    if (!source) return header;
+    const frame = codeFrameColumns(
+        source.contents,
+        {
+            start: { line: diag.line, column: diag.column },
+            end: diag.span ? { line: diag.span.end.line, column: diag.span.end.column } : undefined,
+        },
+        {
+            highlightCode: useColor,
+            linesAbove: 2,
+            linesBelow: 1,
+            forceColor: useColor,
+        },
+    );
+    return `${header}\n${frame}`;
+}
+
+function renderHeader(diag: CliDiagnostic, useColor: boolean): string {
+    const loc = `${diag.file}:${diag.line}:${diag.column}`;
+    const severityWord = diag.severity === 'error' ? 'error' : 'warning';
+    if (!useColor) {
+        const suffix = diag.suggestion ? ` — did you mean '${diag.suggestion}'?` : '';
+        return `${loc} ${severityWord}: ${stripSuggestion(diag.message, diag.suggestion)}${suffix}`;
+    }
+    const coloredLoc = chalk.cyan(loc);
+    const coloredSeverity =
+        diag.severity === 'error' ? chalk.red.bold(severityWord) : chalk.yellow.bold(severityWord);
+    const message = stripSuggestion(diag.message, diag.suggestion);
+    const suggestion = diag.suggestion
+        ? ` ${chalk.dim('—')} did you mean ${chalk.green(`'${diag.suggestion}'`)}?`
+        : '';
+    return `${coloredLoc} ${coloredSeverity}: ${message}${suggestion}`;
+}
+
+function stripSuggestion(message: string, suggestion: string | undefined): string {
+    if (!suggestion) return message;
+    return message.replace(/ —\s*did you mean ['"]?[^'"?]+['"]?\??/i, '').trimEnd();
+}

package/src/generated/templates.ts

@@ -0,0 +1,12 @@
+// 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> = {
+    "minimal": "nowline v1\n\nroadmap minimal \"Starter\" start:2026-01-05 scale:2w author:\"Jane Doe\"\n\nswimlane engineering \"Engineering\"\n  parallel concurrent-block style:concurrent\n    group research-group \"Research\"\n      item research \"Research\"  duration:3w status:done\n      item design   \"Design\"    duration:2w status:in-progress remaining:5d\n      item build    \"Build\"     duration:3w status:planned\n    group release-group \"Release\"\n      item release  \"Release\"   duration:1w status:planned\n      item deploy   \"Deploy\"    duration:1w status:planned\n",
+    "teams": "nowline v1\n\nroadmap teams-2026 \"Teams Roadmap 2026\" start:2026-01-05\n\nperson sam \"Sam Chen\" link:https://github.com/samchen\nperson jen \"Jennifer Wu\"\nperson alex \"Alex Rivera\"\n\nteam engineering \"Engineering\"\n  team platform-team \"Platform Team\"\n    person sam\n    person jen\n  team mobile-team \"Mobile Team\"\n    person alex\n\nanchor kickoff date:2026-01-06\nanchor mid-year date:2026-07-01\nanchor eoy \"End of Year\" date:2026-12-15\n\nswimlane platform owner:platform-team\n  item auth \"Auth refactor\" duration:1m after:kickoff owner:sam status:done\n  item api-v2 \"API v2\" duration:2w owner:jen status:in-progress remaining:40%\n\nswimlane mobile owner:mobile-team\n  item offline \"Offline mode\" duration:1m after:kickoff owner:alex status:at-risk remaining:60%\n  item push \"Push notifications\" duration:2w owner:alex\n\nmilestone beta \"Beta\" after:[auth, api-v2]\nmilestone ga \"GA\" date:2026-12-01 after:[offline, push]\n\nfootnote eng-capacity \"Mobile team capacity risk\" on:mobile-team\n  description \"Mobile team is understaffed through Q2.\"\n\nfootnote vendor-dep \"Vendor dependency\" on:[auth, api-v2]\n  description \"Blocked until vendor contract is signed.\"\n",
+    "product": "nowline v1\n\nconfig\n\nscale\n  name: weeks\n  label-every: 2\n  label: \"W{n}\"\n\ncalendar\n  days-per-week: 5\n  days-per-month: 22\n  days-per-quarter: 65\n  days-per-year: 260\n\nstyle enterprise-style \"Enterprise readiness\"\n  bg: blue\n  fg: navy\n  text: white\n  border: solid\n\nstyle risky\n  border: dashed\n  fg: orange\n\nstyle subtle\n  bg: gray\n\ndefault item shadow:subtle\ndefault swimlane padding:sm spacing:none\ndefault roadmap padding:md header-height:md font:sans\ndefault parallel bracket:none\n\nroadmap platform-2026 \"Platform 2026\" author:\"Acme Engineering\" start:2026-01-05 calendar:custom\n\nperson sam \"Sam Chen\"\nperson jen \"Jennifer Wu\"\n\nsize xs effort:1d\nsize sm effort:3d\nsize md effort:1w\nsize lg effort:2w\nsize xl effort:1m\n\nstatus awaiting-review\nstatus in-review\n\nlabel enterprise \"Enterprise readiness\" style:enterprise-style\nlabel security \"Security hardening\" style:enterprise-style\nlabel low-confidence style:risky\n\nanchor kickoff date:2026-01-06\nanchor code-freeze \"Code Freeze\" date:2026-05-01\nanchor ga-date \"GA Date\" date:2026-06-01\n\nswimlane platform\n  item auth-refactor \"Auth refactor\" size:lg after:kickoff status:done owner:sam labels:enterprise link:https://github.com/acme/platform/issues/123\n  parallel after:auth-refactor\n    group audit-track \"Audit Track\" labels:security\n      item audit-log \"Audit log v2\" size:xl before:code-freeze remaining:30% labels:[enterprise, security]\n        description \"Comprehensive audit trail for all admin actions\"\n      item audit-ui \"Audit UI\" size:md\n    item sso \"SSO plugins\" size:md labels:[enterprise, low-confidence]\n  item platform-qa \"Platform QA\" size:sm\n\nswimlane mobile\n  item offline \"Offline mode\" size:lg after:kickoff owner:jen status:at-risk remaining:60% link:https://github.com/acme/mobile/pull/87\n  item push-v2 \"Push notifications v2\" size:md\n\nmilestone beta \"Beta\" after:auth-refactor\nmilestone ga-launch \"GA launch\" date:2026-06-01 after:[auth-refactor, audit-log]\n\nfootnote vendor-footnote \"Vendor dependency\" on:audit-log\n  description \"Blocked until vendor contract is signed. Expected March resolution.\"\n"
+};

package/src/generated/version.ts

@@ -0,0 +1,18 @@
+// Auto-generated by scripts/bundle-templates.mjs. Do not edit by hand.
+
+export const CLI_VERSION = "0.2.0";
+
+export interface CliBuild {
+    /** Short git SHA at build time, or empty when not in a git checkout. */
+    readonly sha: string;
+    /** 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 = {
+    "sha": "c51e2a4",
+    "isRelease": true,
+    "isDirty": false
+};

package/src/i18n/locale.ts

@@ -0,0 +1,133 @@
+import type { NowlineFile } from '@nowline/core';
+
+// Resolve the operator-locale override from CLI flag, environment, and
+// `.nowlinerc`. See `specs/localization.md` for the two-chain model.
+//
+// Operator locale governs CLI message output: validator diagnostics on
+// stderr, `--help`, format errors, verbose logs. It is independent from
+// the file's `locale:` directive, which governs the rendered artifact.
+//
+// Returns the resolved tag plus the source it came from, so verbose
+// logging can describe the chain without re-walking it.
+
+const ENV_VARS = ['LC_ALL', 'LC_MESSAGES', 'LANG'] as const;
+type EnvVar = (typeof ENV_VARS)[number];
+
+export type LocaleSource = 'flag' | 'env' | 'rc';
+
+export interface ResolvedLocale {
+    /** BCP-47 tag, or undefined when no source produced one. */
+    tag: string | undefined;
+    /** Which input chain produced `tag`. Undefined iff `tag` is undefined. */
+    source: LocaleSource | undefined;
+    /** When `source === 'env'`, the specific variable that contributed. */
+    envVar?: EnvVar;
+}
+
+export interface ResolveLocaleInputs {
+    /** Value of the `--locale` flag, or undefined. */
+    flag: string | undefined;
+    /** Process environment, parameterized for testability. */
+    env: NodeJS.ProcessEnv;
+    /** Optional `.nowlinerc` `locale` key. Slots below env vars. */
+    rc?: string | undefined;
+}
+
+/**
+ * Resolve the operator's locale override.
+ *
+ * Precedence (highest wins): `--locale` flag > env vars > `.nowlinerc`.
+ * POSIX `C` / `POSIX` env values mean "no localization" and are skipped.
+ *
+ * Returns `{ tag: undefined, source: undefined }` when nothing is set —
+ * `operatorLocale` then defaults to `en-US`, while the layout's content
+ * chain falls back to whatever the file's `locale:` directive declares.
+ */
+export function resolveLocaleOverride({ flag, env, rc }: ResolveLocaleInputs): ResolvedLocale {
+    if (flag) return { tag: flag, source: 'flag' };
+    for (const name of ENV_VARS) {
+        const raw = env[name];
+        if (!raw) continue;
+        const stripped = stripPosixSuffix(raw);
+        if (!stripped || stripped === 'C' || stripped === 'POSIX') {
+            // POSIX `C` / `POSIX` locale means "no localization." Skip and
+            // let the next env var or the rc file take over.
+            continue;
+        }
+        return { tag: normalizePosixToBcp47(stripped), source: 'env', envVar: name };
+    }
+    if (rc) return { tag: rc, source: 'rc' };
+    return { tag: undefined, source: undefined };
+}
+
+/**
+ * Resolve the operator-facing locale used to format CLI message output.
+ * `en-US` when the operator has no signal in the environment.
+ */
+export function operatorLocale(resolved: ResolvedLocale): string {
+    return resolved.tag ?? 'en-US';
+}
+
+/**
+ * Describe which locale governs the rendered artifact and where the
+ * value came from. Used by the `--verbose` log line so an operator can
+ * see at a glance whether the file or the operator chain is winning.
+ *
+ * Precedence mirrors the layout's `resolveLocale`:
+ *   file directive > CLI flag > env > `.nowlinerc` > en-US (default).
+ */
+export function describeContentLocaleSource(
+    directive: string | undefined,
+    resolved: ResolvedLocale,
+): { tag: string; source: string } {
+    if (directive) return { tag: directive, source: 'from file directive' };
+    if (resolved.tag === undefined) return { tag: 'en-US', source: 'default' };
+    switch (resolved.source) {
+        case 'flag':
+            return { tag: resolved.tag, source: 'from --locale' };
+        case 'env':
+            return { tag: resolved.tag, source: `from ${resolved.envVar} env var` };
+        case 'rc':
+            return { tag: resolved.tag, source: 'from .nowlinerc' };
+        default:
+            return { tag: resolved.tag, source: 'from operator chain' };
+    }
+}
+
+/**
+ * Read the optional `locale:` property from a parsed file's
+ * `nowline v1` directive. Returns undefined when the directive is
+ * 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;
+}
+
+/**
+ * POSIX `LANG` values look like `en_US.UTF-8` or `fr_CA@euro`. Strip
+ * everything from `.` or `@` onward — Nowline only cares about the
+ * language and region.
+ */
+function stripPosixSuffix(value: string): string {
+    const dot = value.indexOf('.');
+    const at = value.indexOf('@');
+    let end = value.length;
+    if (dot !== -1 && dot < end) end = dot;
+    if (at !== -1 && at < end) end = at;
+    return value.slice(0, end).trim();
+}
+
+/**
+ * Normalize `fr_CA` to `fr-CA`. POSIX uses `_`; BCP-47 uses `-`.
+ * Casing follows BCP-47 conventions: language lowercase, region
+ * uppercase 2-letter, but the layout's BCP-47 walker normalizes again
+ * defensively, so this is best-effort.
+ */
+function normalizePosixToBcp47(value: string): string {
+    return value.replace('_', '-');
+}

package/src/index.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { parseArgv } from './cli/args.js';
+import { renderHelp, renderVersion } from './cli/help.js';
+import { initHandler } from './commands/init.js';
+import { renderHandler } from './commands/render.js';
+import { serveHandler } from './commands/serve.js';
+import { CliError, ExitCode } from './io/exit-codes.js';
+
+async function run(): Promise<number> {
+    const argv = process.argv.slice(2);
+
+    let parsed: ReturnType<typeof parseArgv>;
+    try {
+        parsed = parseArgv(argv);
+    } catch (err) {
+        return handleError(err);
+    }
+
+    if (parsed.mode === 'help') {
+        process.stdout.write(renderHelp());
+        return ExitCode.Success;
+    }
+    if (parsed.mode === 'version') {
+        process.stdout.write(renderVersion());
+        return ExitCode.Success;
+    }
+
+    try {
+        if (parsed.mode === 'init') {
+            await initHandler({ args: parsed });
+        } else if (parsed.mode === 'serve') {
+            await serveHandler({ args: parsed });
+        } else {
+            await renderHandler({ args: parsed });
+        }
+        return ExitCode.Success;
+    } catch (err) {
+        return handleError(err);
+    }
+}
+
+function handleError(err: unknown): number {
+    if (err instanceof CliError) {
+        if (err.message) process.stderr.write(`${err.message}\n`);
+        return err.exitCode;
+    }
+    const message = err instanceof Error ? (err.stack ?? err.message) : String(err);
+    process.stderr.write(`${message}\n`);
+    return ExitCode.ValidationError;
+}
+
+run()
+    .then((code) => {
+        process.exit(code);
+    })
+    .catch((err: unknown) => {
+        const message = err instanceof Error ? (err.stack ?? err.message) : String(err);
+        process.stderr.write(`${message}\n`);
+        process.exit(ExitCode.ValidationError);
+    });

package/src/io/config.ts

@@ -0,0 +1,11 @@
+// Thin re-export of the shared `.nowlinerc` loader. The implementation
+// lives in `@nowline/config` so the VS Code/Cursor extension can read the
+// same files without depending on the CLI's heavier export-format graph.
+export {
+    type LoadConfigOptions,
+    type LoadConfigResult,
+    loadConfig,
+    mergeConfig,
+    type NowlineRc,
+    parseConfig,
+} from '@nowline/config';

package/src/io/exit-codes.ts

@@ -0,0 +1,18 @@
+export const ExitCode = {
+    Success: 0,
+    ValidationError: 1,
+    InputError: 2,
+    OutputError: 3,
+} as const;
+
+export type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];
+
+export class CliError extends Error {
+    constructor(
+        public readonly exitCode: ExitCode,
+        message: string,
+    ) {
+        super(message);
+        this.name = 'CliError';
+    }
+}