@aragon-agent/cli 0.5.6 → 0.5.9

package/dist/tools/patch.js

@@ -0,0 +1,453 @@
+/**
+ * Structured file patches (agent-activity-presentation §3.3).
+ *
+ * PURE, NO I/O, NO REACT, ASCII-ONLY MARKERS. `glyphs.test.ts`'s static scan
+ * walks ALL of `src/` (skipping only `__tests__/` and two exempt files), so this
+ * module sits inside that guard rail directly rather than by analogy. The
+ * substantive reason is the one `reducer.ts` gives for `PREVIEW_TRUNCATION_MARK`:
+ * a string produced outside `src/ui/**` has no `TermCapabilities` in scope and
+ * must be safe on a legacy `cmd.exe`.
+ *
+ * The ladder is ANCHORED SPLIT -> BOUNDED LCS -> BLOCK REPLACE, and every
+ * recursion path terminates in one of three leaf returns. `blockReplace` is
+ * exactly what `renderUnifiedDiff` produced before this round — every old row as
+ * `del`, then every new row as `add` — kept as the explicit, bounded fallback so
+ * a pathological input degrades to today's behaviour rather than hanging.
+ *
+ * `buildPatch` is TOTAL: it never throws, for any pair of strings.
+ */
+export const PATCH_LIMITS = {
+    /**
+     * Context rows kept either side of a change, FOR THE UI.
+     *
+     * The text renderer does NOT use this (D-20): `renderUnifiedDiff` keeps its
+     * own `CONTEXT_LINES = 2` default so the model-facing diff does not silently
+     * widen by two rows on every single-region edit. One algorithm, two widths,
+     * chosen by the caller.
+     */
+    context: 3,
+    /**
+     * Hunks separated by this many context rows or fewer are merged into one.
+     *
+     * MUST STAY `>= 2 * context` FOR EVERY CALLER'S CONTEXT WIDTH, or two adjacent
+     * hunks expanded by `context` would overlap and the same row would be rendered
+     * twice with two different line numbers. 6 covers both widths in use (3 and 2).
+     */
+    mergeGap: 6,
+    /** Rendered rows a patch may carry, across all hunks. */
+    maxLines: 200,
+    /** Total characters across all `PatchLine.text`. Mirrors STORED_PREVIEW_CHARS. */
+    maxChars: 8_000,
+    /** A single row is truncated past this, with `TRUNCATION_MARK`. */
+    maxLineChars: 500,
+    /** Above this cell count the LCS leaf is refused; the segment becomes a block replace. */
+    lcsCellBudget: 160_000, // 400 x 400
+    /** Recursion depth ceiling for the anchor split. */
+    maxDepth: 32,
+    /** Old-side bytes above which `write_file` does not read for a diff. */
+    readMaxBytes: 2 * 1024 * 1024,
+    /** Model-facing diff text ceiling — a bound `edit_file` does not have today. */
+    modelDiffMaxChars: 4_000,
+};
+/**
+ * Appended to a row clipped at `maxLineChars`.
+ *
+ * SPELLED HERE RATHER THAN IMPORTED from `agent/reducer.ts`, so that `tools/`
+ * does not take a runtime dependency on the view model for one three-character
+ * string. `patch.test.ts` asserts the two spellings are equal, so the pair
+ * cannot drift silently — which is the property the import would have bought.
+ */
+export const TRUNCATION_MARK = '...';
+/** The note emitted when exactly one side ends with a newline. */
+export const NO_NEWLINE_NOTE = '(no newline at end of file)';
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+export function buildPatch(oldText, newText, options) {
+    const context = clampContext(options.context);
+    const oldLines = oldText === null ? [] : splitLines(oldText);
+    const newLines = splitLines(newText);
+    const rows = oldText === null
+        ? newLines.map((_, i) => ({ kind: 'add', b: i }))
+        : collectRows(oldLines, newLines, context);
+    if (oldText !== null && endsWithNewline(oldText) !== endsWithNewline(newText)) {
+        rows.push({ kind: 'ctx', note: true });
+    }
+    // Counted BEFORE truncation, so the `+6 -5` summary always describes the real
+    // change even when the body is clipped.
+    let added = 0;
+    let removed = 0;
+    for (const row of rows) {
+        if (row.kind === 'add')
+            added += 1;
+        else if (row.kind === 'del')
+            removed += 1;
+    }
+    const budgeted = applyBudgets(assembleHunks(rows, oldLines, newLines, context));
+    return {
+        path: options.path,
+        kind: oldText === null && !options.degraded ? 'create' : 'update',
+        added,
+        removed,
+        hunks: budgeted.hunks,
+        truncated: budgeted.truncated,
+        lineCount: budgeted.lineCount,
+        ...(options.degraded ? { degraded: options.degraded } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// Step 0 — split and normalize
+// ---------------------------------------------------------------------------
+/**
+ * Split on `\n`, dropping the phantom trailing element a file-final newline
+ * produces. An empty string is ZERO lines, not one empty line.
+ *
+ * The RAW string is what later comparisons see, `\r` included: a CRLF-to-LF
+ * conversion is a change and must be reported as one. Only `PatchLine.text` has
+ * the CR stripped, and only for rendering.
+ */
+function splitLines(text) {
+    if (text.length === 0)
+        return [];
+    const lines = text.split('\n');
+    if (lines[lines.length - 1] === '')
+        lines.pop();
+    return lines;
+}
+function endsWithNewline(text) {
+    return text.endsWith('\n');
+}
+function renderText(raw) {
+    return raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+}
+/**
+ * The context width, clamped to HALF the merge gap.
+ *
+ * The ceiling is structural, not taste: two groups survive as separate hunks
+ * only when more than `mergeGap` context rows separate them, and each is then
+ * expanded by `context` rows from its own side. At `context > mergeGap / 2` the
+ * two expansions overlap and the same source row is rendered twice, under two
+ * different line numbers, with nothing reporting it. Both callers pass 3 or 2.
+ */
+function clampContext(requested) {
+    const ceiling = Math.floor(PATCH_LIMITS.mergeGap / 2);
+    if (requested === undefined || !Number.isFinite(requested)) {
+        return Math.min(PATCH_LIMITS.context, ceiling);
+    }
+    return Math.max(0, Math.min(ceiling, Math.floor(requested)));
+}
+// ---------------------------------------------------------------------------
+// Steps 2-3 — trim, then the anchored split
+// ---------------------------------------------------------------------------
+/**
+ * Trim the common prefix and suffix, diff the middle, and emit at most `context`
+ * unchanged rows on either side.
+ *
+ * Emitting only the fringe rather than the whole file is what keeps this O(change)
+ * in allocations: a one-line edit in a 50 000-line file builds a handful of rows,
+ * not fifty thousand.
+ */
+function collectRows(oldLines, newLines, context) {
+    let start = 0;
+    const maxStart = Math.min(oldLines.length, newLines.length);
+    while (start < maxStart && oldLines[start] === newLines[start])
+        start += 1;
+    let endOld = oldLines.length - 1;
+    let endNew = newLines.length - 1;
+    while (endOld >= start && endNew >= start && oldLines[endOld] === newLines[endNew]) {
+        endOld -= 1;
+        endNew -= 1;
+    }
+    // Identical files: no hunks at all, rather than today's stray context rows.
+    if (start > endOld && start > endNew)
+        return [];
+    const rows = [];
+    const lead = Math.min(context, start);
+    for (let i = start - lead; i < start; i += 1)
+        rows.push({ kind: 'ctx', a: i, b: i });
+    const middle = { aLo: start, aHi: endOld, bLo: start, bHi: endNew };
+    for (const row of diffRange(oldLines, newLines, middle, 0))
+        rows.push(row);
+    const tail = Math.min(context, oldLines.length - 1 - endOld);
+    for (let k = 1; k <= tail; k += 1)
+        rows.push({ kind: 'ctx', a: endOld + k, b: endNew + k });
+    return rows;
+}
+/**
+ * Patience-style recursive split.
+ *
+ * TERMINATION: the three degenerate cases and the depth cap return leaves
+ * outright; the recursive branch only runs when at least one anchor was kept,
+ * and every sub-range it builds excludes that anchor's rows on both sides — so
+ * each call is on a strictly smaller range.
+ */
+function diffRange(a, b, r, depth) {
+    if (r.aLo > r.aHi && r.bLo > r.bHi)
+        return [];
+    if (r.aLo > r.aHi)
+        return addRows(r.bLo, r.bHi);
+    if (r.bLo > r.bHi)
+        return delRows(r.aLo, r.aHi);
+    if (depth >= PATCH_LIMITS.maxDepth)
+        return blockReplace(r);
+    const anchors = pickAnchors(a, b, r);
+    if (anchors.length === 0) {
+        const cells = (r.aHi - r.aLo + 1) * (r.bHi - r.bLo + 1);
+        return cells <= PATCH_LIMITS.lcsCellBudget ? lcsDiff(a, b, r) : blockReplace(r);
+    }
+    const out = [];
+    let ai = r.aLo;
+    let bi = r.bLo;
+    for (const anchor of anchors) {
+        const gap = { aLo: ai, aHi: anchor.a - 1, bLo: bi, bHi: anchor.b - 1 };
+        for (const row of diffRange(a, b, gap, depth + 1))
+            out.push(row);
+        out.push({ kind: 'ctx', a: anchor.a, b: anchor.b });
+        ai = anchor.a + 1;
+        bi = anchor.b + 1;
+    }
+    const rest = { aLo: ai, aHi: r.aHi, bLo: bi, bHi: r.bHi };
+    for (const row of diffRange(a, b, rest, depth + 1))
+        out.push(row);
+    return out;
+}
+function addRows(lo, hi) {
+    const out = [];
+    for (let i = lo; i <= hi; i += 1)
+        out.push({ kind: 'add', b: i });
+    return out;
+}
+function delRows(lo, hi) {
+    const out = [];
+    for (let i = lo; i <= hi; i += 1)
+        out.push({ kind: 'del', a: i });
+    return out;
+}
+/** Today's behaviour, kept as the bounded fallback: every del, then every add. */
+function blockReplace(r) {
+    return [...delRows(r.aLo, r.aHi), ...addRows(r.bLo, r.bHi)];
+}
+/** Lines occurring EXACTLY ONCE on both sides, kept in a common increasing order. */
+function pickAnchors(a, b, r) {
+    const aSeen = new Map();
+    const aAt = new Map();
+    for (let i = r.aLo; i <= r.aHi; i += 1) {
+        const line = a[i];
+        aSeen.set(line, (aSeen.get(line) ?? 0) + 1);
+        aAt.set(line, i);
+    }
+    const bSeen = new Map();
+    const bAt = new Map();
+    for (let i = r.bLo; i <= r.bHi; i += 1) {
+        const line = b[i];
+        bSeen.set(line, (bSeen.get(line) ?? 0) + 1);
+        bAt.set(line, i);
+    }
+    const pairs = [];
+    for (const [line, count] of aSeen) {
+        if (count !== 1 || bSeen.get(line) !== 1)
+            continue;
+        pairs.push({ a: aAt.get(line), b: bAt.get(line) });
+    }
+    pairs.sort((x, y) => x.a - y.a);
+    return longestIncreasingByB(pairs);
+}
+/** Longest strictly-increasing subsequence by `b`, via binary-searched piles. */
+function longestIncreasingByB(pairs) {
+    const tails = [];
+    const prev = new Array(pairs.length).fill(-1);
+    for (let i = 0; i < pairs.length; i += 1) {
+        let lo = 0;
+        let hi = tails.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (pairs[tails[mid]].b < pairs[i].b)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        if (lo > 0)
+            prev[i] = tails[lo - 1];
+        tails[lo] = i;
+    }
+    const out = [];
+    let k = tails.length > 0 ? tails[tails.length - 1] : -1;
+    while (k >= 0) {
+        out.push(pairs[k]);
+        k = prev[k];
+    }
+    return out.reverse();
+}
+/** Textbook LCS over a leaf small enough to afford it (`lcsCellBudget`). */
+function lcsDiff(a, b, r) {
+    const n = r.aHi - r.aLo + 1;
+    const m = r.bHi - r.bLo + 1;
+    const width = m + 1;
+    const dp = new Int32Array((n + 1) * width);
+    for (let i = n - 1; i >= 0; i -= 1) {
+        for (let j = m - 1; j >= 0; j -= 1) {
+            dp[i * width + j] =
+                a[r.aLo + i] === b[r.bLo + j]
+                    ? dp[(i + 1) * width + j + 1] + 1
+                    : Math.max(dp[(i + 1) * width + j], dp[i * width + j + 1]);
+        }
+    }
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[r.aLo + i] === b[r.bLo + j]) {
+            out.push({ kind: 'ctx', a: r.aLo + i, b: r.bLo + j });
+            i += 1;
+            j += 1;
+        }
+        else if (dp[(i + 1) * width + j] >= dp[i * width + j + 1]) {
+            out.push({ kind: 'del', a: r.aLo + i });
+            i += 1;
+        }
+        else {
+            out.push({ kind: 'add', b: r.bLo + j });
+            j += 1;
+        }
+    }
+    for (; i < n; i += 1)
+        out.push({ kind: 'del', a: r.aLo + i });
+    for (; j < m; j += 1)
+        out.push({ kind: 'add', b: r.bLo + j });
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Step 4 — hunks
+// ---------------------------------------------------------------------------
+/**
+ * Group changed rows into hunks, expanding each group by `context` rows.
+ *
+ * THE NOTE ROW COUNTS AS A CHANGE for grouping purposes even though it renders
+ * as context: a file whose ONLY difference is its final newline has no `add` and
+ * no `del` row at all, and grouping on kind alone would produce zero hunks and
+ * report the change as nothing.
+ */
+function assembleHunks(rows, oldLines, newLines, context) {
+    const changed = [];
+    for (let i = 0; i < rows.length; i += 1) {
+        const row = rows[i];
+        if (row.kind !== 'ctx' || row.note)
+            changed.push(i);
+    }
+    if (changed.length === 0)
+        return [];
+    const groups = [];
+    let from = changed[0];
+    let to = changed[0];
+    for (let k = 1; k < changed.length; k += 1) {
+        const idx = changed[k];
+        if (idx - to - 1 <= PATCH_LIMITS.mergeGap) {
+            to = idx;
+            continue;
+        }
+        groups.push([from, to]);
+        from = idx;
+        to = idx;
+    }
+    groups.push([from, to]);
+    return groups.map(([lo, hi]) => {
+        const slice = rows.slice(Math.max(0, lo - context), Math.min(rows.length, hi + context + 1));
+        return makeHunk(slice.map((row) => toPatchLine(row, oldLines, newLines)));
+    });
+}
+function toPatchLine(row, oldLines, newLines) {
+    if (row.note)
+        return { kind: 'ctx', text: NO_NEWLINE_NOTE };
+    const line = { kind: row.kind, text: '' };
+    if (row.a !== undefined) {
+        line.oldLine = row.a + 1;
+        line.text = renderText(oldLines[row.a]);
+    }
+    if (row.b !== undefined) {
+        line.newLine = row.b + 1;
+        line.text = renderText(newLines[row.b]);
+    }
+    return line;
+}
+/** Derive the `@@` header numbers from the rows the hunk actually carries. */
+function makeHunk(lines) {
+    let oldStart = 0;
+    let oldCount = 0;
+    let newStart = 0;
+    let newCount = 0;
+    for (const line of lines) {
+        if (line.oldLine !== undefined) {
+            if (oldCount === 0)
+                oldStart = line.oldLine;
+            oldCount += 1;
+        }
+        if (line.newLine !== undefined) {
+            if (newCount === 0)
+                newStart = line.newLine;
+            newCount += 1;
+        }
+    }
+    return { oldStart, oldCount, newStart, newCount, lines };
+}
+/**
+ * Clip long rows, then drop whole hunks from the TAIL until the row and
+ * character budgets hold. Tail-first, because the top of a change is where a
+ * reader starts.
+ *
+ * THE FIRST HUNK IS KEPT EVEN WHEN IT ALONE EXCEEDS THE BUDGET, and its rows are
+ * clipped from the tail instead. A 300-line `write_file` is one hunk of 300 add
+ * rows against a 200-row ceiling: dropping whole hunks only would leave ZERO,
+ * and the card would render a `+300 -0` summary over nothing — precisely the
+ * "reported as a byte count" failure this feature exists to fix (see the Issues
+ * Found section of the design).
+ */
+function applyBudgets(input) {
+    const hunks = input.map(clipHunkText);
+    let rows = 0;
+    let chars = 0;
+    let keep = 0;
+    for (const hunk of hunks) {
+        const hunkRows = hunk.lines.length;
+        const hunkChars = hunk.lines.reduce((n, line) => n + line.text.length, 0);
+        const fits = rows + hunkRows <= PATCH_LIMITS.maxLines && chars + hunkChars <= PATCH_LIMITS.maxChars;
+        // The FIRST hunk is accepted whether or not it fits; see the note above.
+        if (keep > 0 && !fits)
+            break;
+        rows += hunkRows;
+        chars += hunkChars;
+        keep += 1;
+    }
+    const kept = hunks.slice(0, Math.max(1, Math.min(keep, hunks.length)));
+    let truncated = kept.length < hunks.length;
+    if (rows > PATCH_LIMITS.maxLines || chars > PATCH_LIMITS.maxChars) {
+        kept[0] = clipHunkRows(kept[0]);
+        truncated = true;
+    }
+    return {
+        hunks: kept,
+        truncated,
+        lineCount: kept.reduce((n, hunk) => n + hunk.lines.length, 0),
+    };
+}
+function clipHunkText(hunk) {
+    return {
+        ...hunk,
+        lines: hunk.lines.map((line) => line.text.length <= PATCH_LIMITS.maxLineChars
+            ? line
+            : { ...line, text: `${line.text.slice(0, PATCH_LIMITS.maxLineChars)}${TRUNCATION_MARK}` }),
+    };
+}
+/** Keep the head of one hunk's rows, and re-derive its header numbers from it. */
+function clipHunkRows(hunk) {
+    const lines = [];
+    let chars = 0;
+    for (const line of hunk.lines) {
+        if (lines.length >= PATCH_LIMITS.maxLines)
+            break;
+        if (lines.length > 0 && chars + line.text.length > PATCH_LIMITS.maxChars)
+            break;
+        lines.push(line);
+        chars += line.text.length;
+    }
+    return makeHunk(lines);
+}

package/dist/tools/terminal-output.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Raw child-process output to terminal-safe rows (agent-activity-presentation-live
+ * L2 / §3.2).
+ *
+ * NOTHING ELSE IN THIS TREE STRIPS ANSI (E-13). `renderBash` hands each line to
+ * `<Text>` unmodified (`ui/entries/ToolPreview.tsx:180`), and that survives only
+ * because the settled preview is printed ONCE, after the command has stopped
+ * writing. Redraw the same text every frame while the child is still emitting
+ * `\r`-rewritten progress bars and `\x1b[A` cursor moves and it stops being
+ * survivable: the terminal honours cursor motion Ink does not know it emitted,
+ * and `wrappedRows` measures escape bytes as if they were columns.
+ *
+ * So this module is the boundary. It runs ONCE, inside the store's `append`
+ * (§3.1.1), and every reader downstream is already safe.
+ *
+ * Pure, ASCII-only, React-free, Ink-free, and TOTAL: `sanitizeChunk` never
+ * throws, for any input including lone surrogates, NUL bytes, a chunk consisting
+ * solely of `\x1b`, and a 4 MB chunk containing no `\n` at all.
+ *
+ * D-27 — IT STRIPS, IT DOES NOT INTERPRET. Keeping colour would mean validating
+ * it (an unterminated SGR leaks its attribute into the rest of the frame), and
+ * interpreting cursor motion would mean owning a screen buffer. Neither is a
+ * presentation round's job.
+ */
+/** Columns a live row may occupy before it is clipped. */
+export declare const LIVE_ROW_MAX_CHARS = 200;
+/** Tab stop width, matching every terminal's default. */
+export declare const TAB_WIDTH = 8;
+/**
+ * The in-progress line's ceiling before it is flushed as a row (§3.2 step 7).
+ *
+ * AFTER STEP 4 THIS IS A RARE PATH RATHER THAN THE PROGRESS-BAR PATH (D-33). A
+ * `\r`-rewritten bar collapses to one row however many times it is redrawn, so
+ * reaching 400 characters with no `\n` requires a line that is genuinely that
+ * long -- `cat` on a minified bundle. Without the bound the carry is an
+ * unbounded accumulator.
+ */
+export declare const CARRY_MAX_CHARS: number;
+/**
+ * Appended to a row clipped at `LIVE_ROW_MAX_CHARS`.
+ *
+ * SPELLED HERE RATHER THAN IMPORTED from `agent/reducer.ts`, the rule
+ * `patch.ts:95-103` already states for the identical string: `tools/` keeps no
+ * runtime dependency on the view model for three characters, and
+ * `terminal-output.test.ts` asserts the spellings are equal so the pair cannot
+ * drift silently.
+ */
+export declare const TRUNCATION_MARK = "...";
+export interface SanitizeResult {
+    /** Complete rows, terminal-safe, in order. Each at most `LIVE_ROW_MAX_CHARS` (+ mark). */
+    rows: string[];
+    /**
+     * The in-progress line: stripped, `\r`-collapsed and tab-expanded, bounded by
+     * `CARRY_MAX_CHARS`.
+     *
+     * THIS IS STATE, NOT A ROW, and the difference is load-bearing. It is threaded
+     * back into the next `sanitizeChunk` call verbatim, so it is deliberately NOT
+     * clipped (a `'...'` spliced into the middle of a line the command is still
+     * writing would then be overwritten INTO the stream) and it may carry a
+     * trailing incomplete escape awaiting its final byte. Render it with
+     * `toDisplayRow`, never directly.
+     */
+    carry: string;
+}
+/**
+ * Remove every escape sequence and control byte except `\t` `\n` `\r`.
+ *
+ * Exported for the tests, and used by `toDisplayRow` as the second line of
+ * defence over a carry that ends mid-escape.
+ */
+export declare function stripAnsi(text: string): string;
+/**
+ * Apply `\r` as the LINE REWRITE it is (§3.2 step 4 / D-33).
+ *
+ * A piece containing `\r` is a sequence of overwrites, so the later segment
+ * replaces the earlier one's PREFIX and anything the earlier one had beyond it
+ * survives -- which is what a real terminal shows, and what keeps R-6's classic
+ * `\r`-only tooling from losing content. A thousand progress-bar rewrites
+ * collapse to one row holding the final state.
+ */
+export declare function applyCarriageReturns(piece: string): string;
+/** Expand tabs to the next multiple of `TAB_WIDTH`. */
+export declare function expandTabs(row: string): string;
+/** Clip a row at `LIVE_ROW_MAX_CHARS`, marking the cut. */
+export declare function clipRow(row: string): string;
+/**
+ * The carry as a RENDERED row: the held-back incomplete escape removed, then
+ * stripped and clipped.
+ *
+ * THE PARTIAL MUST BE CUT OFF, NOT STRIPPED (AC-24). `stripAnsi` alone is not
+ * enough and fails in the visible direction: its two-byte rule consumes the
+ * `\x1b[` of an unfinished CSI and leaves the PARAMETERS behind, so a chunk that
+ * split inside `\x1b[31m` renders as `red 3`. The bytes are held for the next
+ * chunk to complete; until then they are not text.
+ */
+export declare function toDisplayRow(carry: string): string;
+/**
+ * Turn a raw chunk into complete rows plus the in-progress line.
+ *
+ * The order of the steps IS the specification (§3.2), and step 4's "every piece,
+ * THE INCOMPLETE TAIL INCLUDED" is the whole of P0-1: a progress bar emits no
+ * `\n` for its entire run, so a rule that collapsed only completed lines would
+ * never run for npm, pip, curl, docker or any other `\r` writer -- the tail
+ * would stay empty, `showLive` false, and the card the single `running` row this
+ * round exists to replace.
+ */
+export declare function sanitizeChunk(carry: string, chunk: string): SanitizeResult;