@north-light/api 0.3.579 → 0.3.587

package/dist/core/termrender/code-doc.d.ts

@@ -0,0 +1,12 @@
+import { type RenderedDoc } from './termrender.js';
+export declare function isMarkdownFile(file: string): boolean;
+/** Fence info string for a source file — `text` when the extension is unknown,
+ *  which every highlighter degrades to plain text on. */
+export declare function fenceLanguageFor(file: string): string;
+/** Wrap source text as a fenced block. The fence is grown past the longest
+ *  backtick run in the content, so a file that itself contains ``` can't close
+ *  its own block. */
+export declare function codeFenceDocument(content: string, language: string): string;
+/** Render a source file as a syntax-highlighted code panel whose spans are
+ *  source lines — the code-file counterpart of `renderReviewDoc`. */
+export declare function codeRenderedDoc(content: string, language: string, width: number): RenderedDoc;

package/dist/core/termrender/code-doc.js

@@ -0,0 +1,92 @@
+import { extname } from 'node:path';
+import { documentLines } from '../document-lines.js';
+import { renderMarkdownWithMap } from './termrender.js';
+// ── Source files as review documents ─────────────────────────────────────────
+//
+// A review ticket may point at a .ts/.py/.sql source file, not just a .md
+// artifact. Every surface still wants ONE rendering story, so a source file is
+// presented as a single fenced code block: termrender (Pygments) and the
+// browser (highlight.js) then syntax-highlight it for free, and the fence's
+// language comes from the file extension.
+//
+// The one cost is a line shift: the fence's opening line makes source line N
+// land on line N+1 of the wrapped document. `codeRenderedDoc` folds that back
+// out so every span/anchor the surfaces expose is a real SOURCE line number.
+/** Extension → fence info string. Names are the ones Pygments (termrender) and
+ *  highlight.js (browser) both accept, so one map serves every surface. */
+const FENCE_BY_EXT = {
+    '.ts': 'typescript', '.mts': 'typescript', '.cts': 'typescript', '.tsx': 'tsx',
+    '.js': 'javascript', '.mjs': 'javascript', '.cjs': 'javascript', '.jsx': 'jsx',
+    '.py': 'python', '.rb': 'ruby', '.go': 'go', '.rs': 'rust', '.java': 'java',
+    '.c': 'c', '.h': 'c', '.cc': 'cpp', '.cpp': 'cpp', '.hpp': 'cpp', '.cs': 'csharp',
+    '.swift': 'swift', '.kt': 'kotlin', '.php': 'php', '.lua': 'lua', '.pl': 'perl',
+    '.sh': 'bash', '.bash': 'bash', '.zsh': 'bash', '.fish': 'fish',
+    '.sql': 'sql', '.json': 'json', '.jsonc': 'json', '.yaml': 'yaml', '.yml': 'yaml',
+    '.toml': 'toml', '.ini': 'ini', '.xml': 'xml', '.html': 'html', '.htm': 'html',
+    '.css': 'css', '.scss': 'scss', '.less': 'less', '.vim': 'vim', '.el': 'lisp',
+    '.ex': 'elixir', '.exs': 'elixir', '.erl': 'erlang', '.hs': 'haskell',
+    '.scala': 'scala', '.dart': 'dart', '.r': 'r', '.jl': 'julia', '.zig': 'zig',
+    '.tf': 'terraform', '.proto': 'protobuf', '.graphql': 'graphql', '.gql': 'graphql',
+    '.dockerfile': 'dockerfile', '.diff': 'diff', '.patch': 'diff', '.csv': 'text',
+    '.txt': 'text', '.log': 'text', '.env': 'bash', '.mk': 'makefile',
+};
+/** Markdown extensions render as a DOCUMENT (headings, tables, Mermaid); every
+ *  other text file renders as code. */
+const MARKDOWN_EXTENSIONS = new Set(['.md', '.markdown', '.mdown', '.mkd']);
+export function isMarkdownFile(file) {
+    return MARKDOWN_EXTENSIONS.has(extname(file).toLowerCase());
+}
+/** Fence info string for a source file — `text` when the extension is unknown,
+ *  which every highlighter degrades to plain text on. */
+export function fenceLanguageFor(file) {
+    const ext = extname(file).toLowerCase();
+    if (ext === '') {
+        // Extensionless but conventionally-named files still have obvious types.
+        const base = file.slice(file.lastIndexOf('/') + 1).toLowerCase();
+        if (base === 'dockerfile')
+            return 'dockerfile';
+        if (base === 'makefile')
+            return 'makefile';
+        return 'text';
+    }
+    return FENCE_BY_EXT[ext] ?? 'text';
+}
+/** Wrap source text as a fenced block. The fence is grown past the longest
+ *  backtick run in the content, so a file that itself contains ``` can't close
+ *  its own block. */
+export function codeFenceDocument(content, language) {
+    let longest = 0;
+    for (const run of content.matchAll(/`+/g))
+        longest = Math.max(longest, run[0].length);
+    const fence = '`'.repeat(Math.max(3, longest + 1));
+    const body = content.endsWith('\n') ? content.slice(0, -1) : content;
+    return `${fence}${language}\n${body}\n${fence}\n`;
+}
+/** Shift a rendered wrapped-document map back onto SOURCE line numbers: the
+ *  opening fence occupies line 1, so document line N is source line N-1.
+ *
+ *  Rows that touch a fence line are the panel's border/title chrome, not
+ *  source: they lose BOTH their span and their block row so nothing anchors to
+ *  them — otherwise the top border would be a step in j/k that selects the
+ *  whole file. */
+function foldFenceOffset(doc, sourceLineCount) {
+    const closingFenceLine = sourceLineCount + 2;
+    const clamp = (line) => Math.max(1, Math.min(line - 1, sourceLineCount));
+    const chrome = doc.spans.map((span) => span !== null && (span[0] <= 1 || span[1] >= closingFenceLine));
+    return {
+        lines: doc.lines,
+        rows: doc.rows.map((row, index) => (chrome[index] === true ? null : row)),
+        spans: doc.spans.map((span, index) => {
+            if (span === null || chrome[index] === true)
+                return null;
+            return [clamp(span[0]), clamp(span[1])];
+        }),
+        blocks: doc.blocks.map((block) => ({ type: block.type, start: clamp(block.start), end: clamp(block.end) })),
+    };
+}
+/** Render a source file as a syntax-highlighted code panel whose spans are
+ *  source lines — the code-file counterpart of `renderReviewDoc`. */
+export function codeRenderedDoc(content, language, width) {
+    const sourceLineCount = documentLines(content).length;
+    return foldFenceOffset(renderMarkdownWithMap(codeFenceDocument(content, language), width), sourceLineCount);
+}

package/dist/core/termrender/display.d.ts

@@ -0,0 +1,16 @@
+/** Options for `display()` — the live-watch tmux pane surface. The pane always
+ *  watches the file and live-updates on edits; there is no non-watched mode. */
+export interface DisplayOpts {
+    /** `'auto'` (default) splits until the pane budget, then opens a new window. */
+    window?: 'auto' | 'split' | 'new';
+    /** Pane budget per window before `'auto'` opens a new window. Default 3. */
+    maxPanes?: number;
+}
+export type DisplayResult = {
+    paneId: string;
+    reason?: never;
+} | {
+    paneId?: never;
+    reason: string;
+};
+export declare function display(path: string, opts?: DisplayOpts): DisplayResult;

package/dist/core/termrender/display.js

@@ -0,0 +1,56 @@
+import { envNodeId } from '../../shared/env.js';
+import { spawnSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { breakPane, closePane, currentTmux, paneOfNode, splitWindow, } from '../runtime/placement-tmux.js';
+import { documentWatchCommand } from './termrender.js';
+function targetPane() {
+    const callerPane = process.env['TMUX_PANE'];
+    if (callerPane !== undefined && callerPane !== '')
+        return callerPane;
+    const nodeId = envNodeId();
+    if (nodeId !== undefined && nodeId !== '') {
+        const viewerPane = paneOfNode(nodeId);
+        if (viewerPane !== null)
+            return viewerPane;
+    }
+    return currentTmux()?.pane ?? null;
+}
+function countPanes(target) {
+    const result = spawnSync('tmux', ['list-panes', '-t', target, '-F', '#{pane_id}'], {
+        encoding: 'utf8',
+    });
+    if (result.status !== 0)
+        return null;
+    return result.stdout.split('\n').filter((line) => line.trim() !== '').length;
+}
+export function display(path, opts) {
+    const window = (opts?.window === 'split' || opts?.window === 'new') ? opts.window : 'auto';
+    const maxPanes = (opts?.maxPanes !== undefined && opts.maxPanes > 0) ? opts.maxPanes : 3;
+    const command = documentWatchCommand(resolve(path));
+    if (command === null)
+        return { reason: 'renderer unavailable' };
+    const target = targetPane();
+    if (target === null)
+        return { reason: 'no pane on screen' };
+    let newWindow = window === 'new';
+    if (window === 'auto') {
+        const paneCount = countPanes(target);
+        if (paneCount === null)
+            return { reason: `tmux could not inspect target pane ${target}` };
+        newWindow = paneCount >= maxPanes;
+    }
+    const pane = splitWindow(target, {
+        cwd: process.cwd(),
+        env: {},
+        command,
+    });
+    if (pane === null)
+        return { reason: `tmux could not split target pane ${target}` };
+    if (!newWindow)
+        return { paneId: pane };
+    const opened = breakPane(pane);
+    if (opened !== null)
+        return { paneId: opened.pane };
+    closePane(pane);
+    return { reason: 'tmux could not move the document pane into a new window' };
+}

package/dist/core/termrender/termrender.d.ts

@@ -0,0 +1,71 @@
+type RendererDiagnostic = (message: string) => void;
+/**
+ * Memoized, self-healing. Guarantees at most one authoritative renderer
+ * lifecycle per process: trust a valid stamp outright (zero subprocess spawns),
+ * else run ONE provision/verify/publish transition under the exclusive lock.
+ * There is no permanent legacy-verifier fallback — the spawn-based verify
+ * (`binaryOk` + `installedVersion`) is a step INSIDE that single transition,
+ * always followed by publishing the stamp, never a lasting alternate path.
+ *
+ * Single degradation path: `uv` absent → one stderr remediation line + plaintext.
+ * win32 → plaintext (no renderer).
+ *
+ * Invoked at postinstall AND lazily on the first render/check/display call,
+ * so `npm ci --ignore-scripts` consumers still self-heal on first use.
+ */
+export declare function ensureRenderer(report?: RendererDiagnostic): void;
+/** Cheap predicate — true when the pinned managed binary is verified ready. Does not install or spawn. */
+export declare function isRendererReady(): boolean;
+/** Render markdown to terminal lines via the pinned binary; plaintext fallback.
+ *  Callers own the returned array — every return is a fresh copy, so a caller
+ *  that appends to it cannot grow the cached render on the next hit. */
+export declare function renderMarkdown(md: string, width: number): string[];
+export interface RenderedDoc {
+    /** Rendered ANSI rows — byte-identical to the plain `doc render` output. */
+    lines: string[];
+    /** Per-row index into `blocks`; null for the blank separator rows between blocks. */
+    rows: (number | null)[];
+    /** Per-row finest 1-indexed inclusive source-line range the renderer knows
+     *  (a bullet, a table row, a code line…); null for separator rows and rows
+     *  of unmapped blocks. Same length as `lines`. */
+    spans: ([number, number] | null)[];
+    /** Per top-level block: its termrender block type plus 1-indexed inclusive
+     *  source-line bounds. Never empty. */
+    blocks: {
+        type: string;
+        start: number;
+        end: number;
+    }[];
+}
+/** Render markdown with a row→source-line map via the pinned binary
+ *  (`doc render --line-map`); plaintext paragraph-block fallback. */
+export declare function renderMarkdownWithMap(md: string, width: number): RenderedDoc;
+/**
+ * The shared block-aware mapped render: prose blocks keep the readability cap
+ * (`proseWidth`), while diagram blocks are re-rendered at the pane's full
+ * `paneWidth` and spliced back in by block index. Both surfaces (terminal
+ * review and the ask page) go through this, so "which blocks may be wide" is
+ * decided once, from the renderer's own block types, never by heuristics on
+ * the emitted rows.
+ *
+ * Row order, block list and source spans are the narrow render's; only the
+ * rows OF a wide block are replaced, so anchoring stays source-based and
+ * unchanged.
+ */
+export declare function renderMarkdownBlockAware(md: string, proseWidth: number, paneWidth: number): RenderedDoc;
+/** Block-aware render as plain rows, for surfaces that do not anchor. The rows
+ *  are the caller's own array: the block-aware render can pass the mapped
+ *  cache's line array straight through, and a caller appending to it would
+ *  otherwise poison every later render of the same document. */
+export declare function renderMarkdownBlockAwareLines(md: string, proseWidth: number, paneWidth: number): string[];
+/** Validate markdown via `termrender doc check`. */
+export declare function checkMarkdown(md: string): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** Shell command for a pane that live-renders `path` with crouter's pinned
+ *  termrender. Null means the managed renderer could not be provisioned. */
+export declare function documentWatchCommand(path: string): string | null;
+export {};