@nowline/cli 0.0.0-dev.20260601071750.g04bdff9

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,13 @@
+// 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' | 'showcase';
+
+export const TEMPLATE_NAMES: readonly TemplateName[] = ['minimal', 'teams', 'product', 'showcase'];
+
+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",
+    "showcase": "nowline v1\n\nroadmap showcase \"Nowline Showcase\" start:2026-01-05 scale:1m author:\"Nowline\"\n\nanchor kickoff date:2026-01-05\n\nswimlane engineering \"Engineering\"\n  item design \"Design spec\" duration:2w after:kickoff status:done\n  parallel after:design\n    group build \"Build\"\n      item api \"API surface\" duration:3w status:in-progress remaining:1w\n      item ui \"Web client\" duration:3w status:in-progress remaining:2w\n    item integrate \"Integration tests\" duration:2w\n  item ship \"Ship\" duration:1w after:integrate\n\nswimlane marketing \"Marketing\"\n  item brief \"Launch brief\" duration:1w after:kickoff status:done\n  item assets \"Launch assets\" duration:3w after:brief\n  item announce \"Announcement\" duration:1w after:ship\n\nmilestone launch \"Launch\" after:[ship, announce]\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.0.0-dev.20260601071750.g04bdff9";
+
+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": "04bdff9",
+    "isRelease": false,
+    "isDirty": true
+};

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';
+    }
+}

package/src/io/read.ts

@@ -0,0 +1,70 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { CliError, ExitCode } from './exit-codes.js';
+
+export interface ReadInputResult {
+    contents: string;
+    path: string;
+    displayPath: string;
+    isStdin: boolean;
+}
+
+export interface ReadInputOptions {
+    readFile?: (absPath: string) => Promise<string>;
+    readStdin?: () => Promise<string>;
+    cwd?: string;
+}
+
+export async function readInput(
+    inputArg: string,
+    options: ReadInputOptions = {},
+): Promise<ReadInputResult> {
+    const readFile = options.readFile ?? ((p) => fs.readFile(p, 'utf-8'));
+    const readStdin = options.readStdin ?? defaultReadStdin;
+    const cwd = options.cwd ?? process.cwd();
+
+    if (inputArg === '-') {
+        return {
+            contents: await readStdin(),
+            path: '<stdin>',
+            displayPath: '<stdin>',
+            isStdin: true,
+        };
+    }
+
+    const absPath = path.resolve(cwd, inputArg);
+    try {
+        const contents = await readFile(absPath);
+        return {
+            contents,
+            path: absPath,
+            displayPath: inputArg,
+            isStdin: false,
+        };
+    } catch (err) {
+        throw new CliError(ExitCode.InputError, formatReadError(inputArg, err));
+    }
+}
+
+function formatReadError(inputArg: string, err: unknown): string {
+    if (isNodeError(err)) {
+        if (err.code === 'ENOENT') return `File not found: ${inputArg}`;
+        if (err.code === 'EACCES') return `Permission denied: ${inputArg}`;
+        if (err.code === 'EISDIR') return `Not a file: ${inputArg}`;
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return `Could not read ${inputArg}: ${message}`;
+}
+
+function isNodeError(err: unknown): err is NodeJS.ErrnoException {
+    return err instanceof Error && typeof (err as { code?: unknown }).code === 'string';
+}
+
+async function defaultReadStdin(): Promise<string> {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    for await (const chunk of process.stdin) {
+        data += chunk;
+    }
+    return data;
+}

package/src/io/write.ts

@@ -0,0 +1,94 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { CliError, ExitCode } from './exit-codes.js';
+
+export interface WriteOutputOptions {
+    /**
+     * Current working directory used to resolve relative output paths. Defaults
+     * to `process.cwd()`.
+     */
+    cwd?: string;
+    /**
+     * Test seam: writes the output bytes to `absPath`. Defaults to
+     * `fs.writeFile`.
+     */
+    writeFile?: (absPath: string, data: string | Uint8Array) => Promise<void>;
+    /**
+     * Test seam: stdout writer. Defaults to `process.stdout.write`.
+     */
+    stdoutWrite?: (data: string | Uint8Array) => boolean;
+    /**
+     * Test seam: stdout-is-a-TTY override. Defaults to `process.stdout.isTTY`.
+     */
+    stdoutIsTTY?: boolean;
+}
+
+export type OutputFormat = 'text' | 'binary';
+
+/**
+ * Writes `data` to either a file (`outputArg` is a path) or stdout (`outputArg`
+ * is `-` or `undefined` — though `undefined` is no longer the default; mode
+ * dispatch always resolves a concrete path now).
+ *
+ * Existing files are silently overwritten. m2b.5 removed the `--force` gate;
+ * matches POSIX redirection (`> file`) and every peer drawing CLI (mmdc, d2,
+ * prettier, tsc, pandoc).
+ */
+export async function writeOutput(
+    outputArg: string | undefined,
+    data: string | Uint8Array,
+    format: OutputFormat,
+    options: WriteOutputOptions = {},
+): Promise<void> {
+    if (outputArg === undefined || outputArg === '-') {
+        guardBinaryStdout(format, options);
+        const write = options.stdoutWrite ?? ((chunk) => process.stdout.write(chunk));
+        const payload = ensureTrailingNewline(data, format);
+        write(payload);
+        return;
+    }
+
+    const cwd = options.cwd ?? process.cwd();
+    const absPath = path.resolve(cwd, outputArg);
+
+    const writeFile = options.writeFile ?? ((p, d) => fs.writeFile(p, d));
+    try {
+        await writeFile(absPath, data);
+    } catch (err) {
+        throw new CliError(ExitCode.OutputError, formatWriteError(outputArg, err));
+    }
+}
+
+function guardBinaryStdout(format: OutputFormat, options: WriteOutputOptions): void {
+    if (format !== 'binary') return;
+    const isTTY = options.stdoutIsTTY ?? process.stdout.isTTY === true;
+    if (isTTY) {
+        throw new CliError(
+            ExitCode.InputError,
+            'nowline: binary output to terminal refused; use -o <path> or pipe to a file.',
+        );
+    }
+}
+
+function ensureTrailingNewline(
+    data: string | Uint8Array,
+    format: OutputFormat,
+): string | Uint8Array {
+    if (format !== 'text') return data;
+    if (typeof data !== 'string') return data;
+    return data.endsWith('\n') ? data : `${data}\n`;
+}
+
+function formatWriteError(outputArg: string, err: unknown): string {
+    if (isNodeError(err)) {
+        if (err.code === 'EACCES') return `Permission denied: ${outputArg}`;
+        if (err.code === 'ENOENT') return `Output directory does not exist: ${outputArg}`;
+        if (err.code === 'EISDIR') return `Output path is a directory: ${outputArg}`;
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return `Could not write ${outputArg}: ${message}`;
+}
+
+function isNodeError(err: unknown): err is NodeJS.ErrnoException {
+    return err instanceof Error && typeof (err as { code?: unknown }).code === 'string';
+}

package/src/version.ts

@@ -0,0 +1,21 @@
+export { CLI_BUILD, CLI_VERSION, type CliBuild } from './generated/version.js';
+
+import { CLI_BUILD, CLI_VERSION } from './generated/version.js';
+
+/**
+ * Compose the user-visible version string per SemVer build-metadata
+ * rules. Released builds print just the SemVer (`0.1.0`); dev builds
+ * append the short SHA (and `.dirty` if the working tree had local
+ * edits when the binary was built):
+ *
+ *   release        -> 0.1.0
+ *   dev (clean)    -> 0.1.0+abc1234
+ *   dev (dirty)    -> 0.1.0+abc1234.dirty
+ */
+export function fullVersionString(): string {
+    if (CLI_BUILD.isRelease || CLI_BUILD.sha === '') {
+        return CLI_VERSION;
+    }
+    const dirty = CLI_BUILD.isDirty ? '.dirty' : '';
+    return `${CLI_VERSION}+${CLI_BUILD.sha}${dirty}`;
+}