@bobfrankston/msgcommon

Common CLI argument parsing and shared types for msger and msgview. Also exports the renderMarkdown helper used by mdview.

Installation

npm install @bobfrankston/msgcommon

Usage

import { parseCommonArgs, runCli } from '@bobfrankston/msgcommon';
import type { MessageBoxOptions, MessageBoxResult } from '@bobfrankston/msgcommon';
import { renderMarkdown } from '@bobfrankston/msgcommon/markdown';

Shared types

MessageBoxResult

Returned by both msger's and msgview's showMessageBox and printed as JSON to stdout by their CLIs.

interface MessageBoxResult {
    button?: string;          // Label of the clicked button (or 'closed', 'dismissed', 'timeout', 'error')
    input?: string;           // Text entered in the input field, if allowInput was true
    dismissed?: boolean;      // True if dismissed via ESC key
    closed?: boolean;         // True if the user closed the window (X button, Alt-F4, etc.)
    bounds?: {                // Screen-relative window geometry at close time (pixels)
        x: number;            //   outer X position
        y: number;            //   outer Y position
        width: number;        //   inner width
        height: number;       //   inner height
    };
    // ...host-specific fields: timeout, error, debug, form, value
}

bounds is populated by both hosts at every exit path (button click, close, dismiss, timeout). Downstream tools like mdview's reload loop use it to respawn the window at the same position the user left it.

Coordinate system — virtual desktop, not monitor-relative. bounds.x / bounds.y are coordinates on the OS's single virtual-desktop plane that spans all monitors. On Windows: primary monitor origin is (0,0); a monitor physically to the right starts at (1920, 0) (or whatever the primary's width is); a monitor to the left gets negative X; etc. We do not return a screen index alongside. This matches what -pos x,y (without a screen index) accepts on both hosts — you can feed bounds straight back into -pos bounds.x,bounds.y to respawn at the same physical spot.

If you want to persist geometry across sessions (where monitor layout might change between runs), you'll need to convert: find which monitor contains (bounds.x, bounds.y) and subtract that monitor's origin to get a (x, y, screen) triple that survives monitor reordering. The immediate reload use case (mdview) doesn't need this because the monitor layout can't change between close and respawn.

See each host's README for the full MessageBoxResult shape with host-specific additions.

MessageBoxOptions

See msger's README or msgview's README for the full option interface — both hosts accept the same shape.

Sub-path exports

• @bobfrankston/msgcommon — runCli, parseCommonArgs, MessageBoxOptions, MessageBoxResult
• @bobfrankston/msgcommon/cliparser — low-level arg parser
• @bobfrankston/msgcommon/markdown — renderMarkdown(md, title, baseHref?), looksLikeMarkdown(url)
• @bobfrankston/msgcommon/pinning — Windows Start Menu shortcut helper

Development

This package is part of the msgx workspace.

npm run build  # Compile TypeScript
npm run watch  # Watch mode