@holmes-lab/holmes-kit 0.1.18 → 0.2.0

package/dist/holmes/cli/screen-safe.d.ts

@@ -0,0 +1,94 @@
+/**
+ * One terminal row's worth of SUBJECT, with the template's own cells already subtracted: an 80
+ * column row, minus the widest template prefix on this screen (`\u2713 \uc2b9\uc778 \u2014 `, nine columns)
+ * and the kind cell (16) and its space, leaves 52. Every line the decision surface prints is bounded by it, so a queue of any size stays a
+ * screen the operator can read top to bottom — the property the batch confirmation depends on
+ * (round-5: the field was bounded and the LINE was not, so a bounded field still wrapped).
+ */
+/** The terminal this screen promises to fit. The floor no terminal goes below. */
+export declare const ROW_MAX = 80;
+export declare const ROW_COLS = 50;
+/**
+ * The `kind` cell. Round-7: at 16 the truncation NOTICE (`… (200자 잘림)`, fifteen columns) consumed
+ * the entire budget, so a non-ASCII kind rendered ZERO columns of the operator's text — the category
+ * of authority being granted, unreadable, in the list AND the item header AND the confirmation AND
+ * every decision echo. That is the round-5 lesson ("a bound met by showing nothing is the
+ * concealment this module exists to prevent") reached through a budget nobody re-checked. Twenty
+ * columns plus the short notice form below leaves real text on the line.
+ */
+export declare const KIND_COLS = 20;
+/**
+ * Did rendering this value into `max` columns hide any of it?
+ *
+ * Round-8: this used to be a REGEX OVER THE RENDERED TEXT, and the data can end with any string it
+ * likes — a target ending `… (5자 잘림)` was reported as clipped when nothing had been clipped, so
+ * `[A]` refused to batch it and told the operator, falsely, that it did not fit on a row. An agent
+ * could disable batch approval for a whole session by choosing its own suffix. The renderer knows
+ * the answer; nobody should have to parse it back out of the output.
+ */
+export declare function isClipped(value: string, max?: number): boolean;
+/**
+ * How many terminal COLUMNS a string occupies. Round-5 measured why a code-point budget is not a
+ * screen budget: a 200-code-point line of markers rendered 302 columns — four wrapped rows at 80 —
+ * because `⟪`, `⟫` and every Hangul character in `자 제거` are East Asian WIDE (two columns each).
+ * The budget exists to bound SCREEN SPACE, so it must be counted in the unit the screen uses.
+ */
+export declare function displayWidth(s: string): number;
+/**
+ * One line, no control bytes, bounded in terminal COLUMNS — for a field the template puts on a line
+ * of its own. `max` is a column budget, not a character count (round-5): the caller is buying screen
+ * space, and on this screen a character can cost one column or two.
+ *
+ * The budget is spent on the OPERATOR'S text: the source is clipped first so escape spam cannot
+ * evict the real command (round-3), and the sanitised result is clipped again so markers cannot
+ * inflate the output (round-4). The truncation notice is appended AFTER sanitising, so no sequence
+ * sitting at the clip boundary can swallow it (round-4).
+ */
+export declare function flattenField(s: string, max?: number): string;
+/**
+ * @implements A-SPEC-262.1 §13
+ * The form agent-controlled text takes on a DECISION ROW: only characters whose width is fixed by
+ * the standard, everything else as an ASCII escape.
+ *
+ * Eight adversarial rounds found the same shape of defect eight times — a character whose width the
+ * code guessed (Ambiguous, combining, zero-width), or whose cursor effect it did not model (TAB,
+ * ESC), or whose position let the data choose a line boundary (alignment, folding). None of them can
+ * occur here, because none of those characters survive to the row: a control byte is not stripped
+ * and counted, it is SHOWN as `\u001b`. Nothing is removed, so nothing is hidden — which also
+ * retires the removal marker, its forgery guard and its size accounting from this path entirely.
+ *
+ * What passes through: printable ASCII (one column each) and East_Asian_Width W or F (two columns
+ * each, fixed by the standard). Korean and CJK commands therefore stay readable on the screen the
+ * operator decides from — the requirement that made this a hybrid rather than a full escaping.
+ * A backslash is doubled first, so data can never spell an escape the renderer did not write.
+ */
+export declare function rowLiteral(s: string): string;
+/**
+ * @implements A-SPEC-262.1 §13
+ * A decision row's field: the row literal, cut to `max` columns, with what it could not show stated.
+ */
+export declare function rowField(value: string, max?: number): string;
+export declare function wrapColumns(s: string, cols?: number, indent?: string): string;
+export declare function stripControl(s: string): string;
+/**
+ * Clip on a CODE POINT boundary. Round-1: slicing UTF-16 units cut a surrogate pair in half and the
+ * last visible character of a clipped command rendered as a replacement glyph — on a screen whose
+ * whole job is showing the subject verbatim.
+ */
+export declare function clipCodePoints(s: string, max: number): string;
+/**
+ * Quote a value that is about to appear inside a COPY-PASTEABLE command line.
+ *
+ * Round-2: the non-TTY hint (A-SPEC-260) fills the real queue id into three `holmes-kit approve …`
+ * lines whose whole purpose is being pasted into a shell — and the id is agent-controlled. Flattening
+ * stops it forging lines, but a flattened `… | sh` still PIPES when pasted. POSIX single quotes make
+ * any byte inert; a literal quote is closed, escaped and reopened.
+ */
+export declare function shellQuote(s: string): string;
+/**
+ * A reference for a pasteable command line: left ALONE when it is already inert (the shape a real
+ * queue id has), quoted only when it is not. Round-2 wanted every pasted byte harmless; quoting
+ * unconditionally would also have rewritten the A-SPEC-260 hint that ships today, so the blast
+ * radius is kept to the case that needs it — a normal session's screen is byte-for-byte unchanged.
+ */
+export declare function safeRef(s: string): string;