@xiaoso/dsh-tool-plus 0.1.7 → 0.1.8-beta.3

package/lib/types/web/client/rows/image-card.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Image material for the `read` card, as a pure derivation.
+ *
+ * A `read` that resolves to an image settles with the reference in the
+ * result's own image block, never in `meta`: metadata rides the 256 KiB
+ * lossless-JSON budget and is the wrong carrier for a session-authorized
+ * resource, so the image branch of the read row is exactly the case where the
+ * text card declines (`narrowReadCardMeta` returns `null`).
+ *
+ * The derivation is deliberately strict — one block of an unknown type, one
+ * malformed reference, or a missing path declines the whole card — because the
+ * alternative is a card that draws a picture while silently dropping whatever
+ * else the result carried.
+ * @module @xiaoso/dsh-tool-plus/web/client/rows/image-card
+ */
+import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
+import { type CardBlockView } from '../row-utils.ts';
+/** What the read row needs to draw a result's images, and nothing more. */
+export interface CardImageMaterial {
+    /** Display label for the card header: the request path, workspace-shortened. */
+    label: string;
+    /** The requested path, verbatim — the absolute path the file viewer opens. */
+    path: string;
+    /** The result's durable references, in result order. */
+    images: ImageAttachmentRef[];
+}
+/**
+ * Display box for a lone image — DSH's own rule, copied from
+ * `ui-attachment/src/MessageImage.tsx::singleFit` so a tool-card image and a
+ * message image of the same file occupy the same box: long edge 240px, the
+ * rendered aspect ratio clamped to [0.25, 4] (the clamped overflow is cropped
+ * by `object-fit: cover`), never upscaled past the natural size, and the crop
+ * anchored to the top of very tall images / the left of very wide ones, where
+ * the informative content usually starts.
+ *
+ * The clamp is deliberately not strict: an exactly 4:1 image stays centred.
+ * @param size - the reference's intrinsic dimensions, in pixels.
+ * @returns the rendered box and the crop anchor.
+ */
+export declare function imageFitBox(size: {
+    width: number;
+    height: number;
+}): {
+    width: number;
+    height: number;
+    objectPosition: string;
+};
+/**
+ * Derive the read card's image material from a settled result.
+ *
+ * Declines — rather than guessing — whenever the result would not be fully
+ * representable: a running call, a failed call, a result whose content carries
+ * a block that is neither text nor image, an image whose reference is
+ * malformed, a text-only result (the text card owns those), or a call whose
+ * arguments name no path.
+ * @param block - the frozen call node.
+ * @param cwd - the session workspace root, for shortening the label.
+ * @returns the material, or `null` to leave the row on its existing path.
+ */
+export declare function imageCardMaterial(block: CardBlockView, cwd: string | undefined): CardImageMaterial | null;

package/lib/types/web/client/rows/read-card-facts.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Collapsed-summary facts for the `read` card.
+ *
+ * The Host projection strips the inline selector off the path
+ * (`stripReadSelector` in `web/host/read.ts`) because the card's *link* must
+ * point at a real file, and it keeps only the file's own window. The collapsed
+ * head is then the one place where the question the model actually asked is
+ * still readable — and the projected path cannot answer it: a windowed read of
+ * `package.json:22-25,31-34` and a whole-file read of `package.json` project to
+ * the very same string, so the card hides the difference.
+ *
+ * The summary is therefore built from the call's own argument, selector and
+ * all, with the projected path kept as the fallback for a result whose call
+ * head fell outside the session window (a truncated window carries no
+ * `tool/call` event, so no argument survives). That fallback states a fact the
+ * card already holds; nothing is invented.
+ * @module @xiaoso/dsh-tool-plus/web/client/rows/read-card-facts
+ */
+/**
+ * The `read` card's collapsed summary: the path the model asked for, keeping
+ * whatever inline selector it carried (`:22-25`, `:raw`, `:conflicts`, `:28-`,
+ * a sqlite row, an archive member) and shortened against the workspace root.
+ *
+ * The selector is deliberately not validated against the read grammar: the head
+ * reports the call verbatim, and a selector this plugin does not recognize is
+ * still what the model typed — substituting the projection's stripped path
+ * would erase the evidence that two calls differ.
+ * @param args - the call's parsed arguments, or `null` when its head is gone.
+ * @param metaPath - the Host-projected path (already selector-free).
+ * @param cwd - the session workspace root, when known.
+ * @returns the workspace-shortened argument path, or the projected path.
+ */
+export declare function readCardSummary(args: Record<string, unknown> | null, metaPath: string, cwd: string | undefined): string;

package/lib/types/web/client/rows/search-card-facts.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Collapsed-summary facts for the `grep` / `ast_grep` / `glob` cards.
+ *
+ * The row's summary is the search's *subject* — `pattern` for grep, `pat` for
+ * ast_grep, the path pattern for glob — so the one question the collapsed head
+ * could not answer is "which tree was searched?", and the counts sat in the
+ * folded body. That reads worst on an empty result: a bare `Grep · zzz` looks
+ * like a bad pattern rather than like a search of the wrong directory.
+ *
+ * Two facts therefore ride the head as a trailing fragment, after the summary
+ * and outside its ellipsis, because they are the parts a narrow row must never
+ * clip:
+ *  - the scope, taken from the call's own `path` argument. Only `matches`
+ *    shapes take it: a glob's `path` argument *is* its pattern, which the
+ *    summary already shows, so repeating it as a scope would claim a second
+ *    fact out of one argument. A call without `path` searched the workspace
+ *    root — naming no scope is honest, inventing one is not;
+ *  - the count, or "no results" instead of a zero count (a zero count is what
+ *    the empty-state failure reads as, not what it says).
+ *
+ * The counting labels are the {@link searchBlockLabels} adapter the block body
+ * already uses, so the head and the body say the same thing in the same words,
+ * including the "showing N of M" wording of a capped payload.
+ * @module @xiaoso/dsh-tool-plus/web/client/rows/search-card-facts
+ */
+import type { SearchCardMeta } from '../../contract.ts';
+import type { CardTranslate } from '../row-utils.ts';
+/**
+ * The search card's collapsed trailing fragment: the scope the call searched,
+ * then what the search found.
+ * @param args - the call's parsed arguments, or `null` when its head is gone.
+ * @param meta - the Host-projected search metadata (already narrowed).
+ * @param cwd - the session workspace root, for shortening an absolute scope.
+ * @param t - the card translate seat.
+ * @returns the joined fragment, or `null` when there is no fact to add.
+ */
+export declare function searchCardSuffix(args: Record<string, unknown> | null, meta: SearchCardMeta, cwd: string | undefined, t: CardTranslate): string | null;

package/lib/types/web/contract.d.ts

@@ -0,0 +1,249 @@
+/**
+ * Web tool-card contract: the payload this plugin's Host half projects into
+ * `output.presentationMeta` and its browser half narrows back before drawing.
+ *
+ * Dependency-free by design (no React, no cordis, no Node built-ins): the Node
+ * half imports it to build metadata, the browser half imports it to validate
+ * it, and because it carries no React import it can never drag the browser
+ * bundle into the Node build.
+ *
+ * `edit` / `read` / `search` mirror the exact shapes the shipped
+ * `@deepseek-ai/dsh-client-ui-tool` card models accept — a `kind` tag rides on
+ * top, and those models ignore unknown keys — so the same payload stays
+ * readable if this plugin ever stops shadowing those rows. `write`,
+ * `ast_edit` and `terminal` are this plugin's own shapes: the shipped rows have
+ * no equivalent (their write card is a diff card; ours is a content preview,
+ * matching the OMP card the model already sees).
+ *
+ * Everything here is defensive: a card never throws. The browser half turns any
+ * malformed, oversized or foreign payload into `null`, and the row falls back
+ * to the generic shell.
+ *
+ * @module @xiaoso/dsh-tool-plus/web/contract
+ */
+/**
+ * Cell-shadowing rank of every card entry this plugin registers.
+ *
+ * The shipped `tool.call.toolview` entries all register at the default
+ * priority 0, and the lowest live entry of a cell renders. A large negative
+ * constant keeps this plugin first even if a future release starts ranking its
+ * own rows below zero — the gap is deliberate, not a tuned value.
+ */
+export declare const CARD_TAKEOVER_PRIORITY = -1000;
+/**
+ * Wire tool names whose `tool.call.toolview` cell this plugin renders.
+ *
+ * `ast_grep` / `ast_edit` are this plugin's own tool names (no shipped entry
+ * claims those keys), so registering them is purely additive; the other six
+ * shadow a shipped row.
+ */
+export declare const CARD_TOOL_KEYS: readonly ["bash", "read", "write", "edit", "grep", "glob", "ast_grep", "ast_edit"];
+/** One of {@link CARD_TOOL_KEYS}. */
+export type CardToolKey = (typeof CARD_TOOL_KEYS)[number];
+/**
+ * Cap on the serialized `edit` metadata. The engine's unified diff is already
+ * bounded per file but unbounded across files; past this budget whole trailing
+ * files are dropped, and once nothing is left the call falls back to the
+ * generic shell rather than writing an oversized session entry.
+ */
+export declare const EDIT_META_MAX_BYTES: number;
+/** Cap on the `ast_edit` change preview (the engine's own display text). */
+export declare const AST_EDIT_META_MAX_BYTES: number;
+/** Cap on the serialized `read` metadata (the returned window's lines). */
+export declare const READ_META_MAX_BYTES: number;
+/**
+ * Cap on the serialized search metadata. Same value and meaning as the shipped
+ * search card's own `searchMetaMaxBytes`.
+ */
+export declare const SEARCH_META_MAX_BYTES: number;
+/** UTF-8 byte length of `text`, without allocating an encoder. */
+export declare function utf8ByteLength(text: string): number;
+/** UTF-8 byte length of a value's JSON form; the unit every cap above uses. */
+export declare function jsonByteLength(value: unknown): number;
+/**
+ * Longest prefix of `text` that fits in `cap` UTF-8 bytes, never splitting a
+ * surrogate pair.
+ * @param text - the text to bound.
+ * @param cap - the byte budget.
+ * @returns `text` when it already fits, otherwise its longest fitting prefix.
+ */
+export declare function capText(text: string, cap: number): string;
+/**
+ * Drop entries from the tail until the payload `wrap(retained)` serializes
+ * within `cap`.
+ *
+ * `wrap` receives the retained slice only, so the caller measures the real
+ * payload — including its fixed fields — and a single oversized entry ends as
+ * an empty list rather than an oversized one.
+ * @param items - the ordered entries to bound.
+ * @param cap - byte budget for `wrap`'s result.
+ * @param wrap - builds the payload that would be emitted for a retained slice.
+ * @returns the retained head, in input order.
+ */
+export declare function capTail<T>(items: readonly T[], cap: number, wrap: (retained: readonly T[]) => unknown): T[];
+/** One file's change, in the shape the shipped diff card consumes. */
+export type CardDiffHunk = {
+    path: string;
+    /** Prior content, or `null` for a new file / an overwrite. */
+    oldText: string | null;
+    /** Content after the change. */
+    newText: string;
+};
+/** One line of a read window, in the shape `ReadBlock` consumes. */
+export type CardReadLine = {
+    number: number;
+    /** The line's text, without its newline. */
+    text: string;
+};
+/** One matched line inside a {@link CardSearchFileGroup}. */
+export type CardSearchMatchLine = {
+    /** 1-based line number of the match within its file. */
+    lineNumber: number;
+    /** The matched line's text. */
+    line: string;
+};
+/** One file's grouped matches, in first-seen order. */
+export type CardSearchFileGroup = {
+    /** The file the matches belong to (display path). */
+    path: string;
+    /** The file's matched lines, in output order. */
+    matches: CardSearchMatchLine[];
+};
+/** `write` card metadata: a content preview, so only the header needs data. */
+export type WriteCardMeta = {
+    kind: 'write';
+    /** The written file's model-facing path. */
+    path: string;
+    /** Grammar hint for the preview; omitted when the path names no language. */
+    lang?: string;
+    /** The write set the file's executable bit; omitted otherwise. */
+    madeExecutable?: boolean;
+};
+/** `edit` card metadata: the engine's own unified diff, already computed. */
+export type EditCardMeta = {
+    kind: 'edit';
+    /** One entry per applied hunk, in file order; never empty. */
+    diffs: CardDiffHunk[];
+};
+/** `ast_edit` card metadata: the engine's change preview plus its counters. */
+export type AstEditCardMeta = {
+    kind: 'ast_edit';
+    /** The engine's display text for the applied replacements. */
+    preview: string;
+    /** Files touched, with their replacement counts. */
+    files: {
+        path: string;
+        count: number;
+    }[];
+    /** Total replacements applied. */
+    replacements: number;
+    /** Whether the edit was applied (`false` previews a dry run). */
+    applied: boolean;
+};
+/** `read` card metadata, in the shape the shipped read card consumes. */
+export type ReadCardMeta = {
+    kind: 'read';
+    /** The read file's path, selector already stripped. */
+    path: string;
+    /** 1-based first line of the returned window. */
+    offset: number;
+    /** The returned window's lines, strictly increasing by number. */
+    lines: CardReadLine[];
+    /** Total line count in the file (the window's last line when unknown). */
+    totalLines: number;
+    /** Grammar hint for the file; omitted when the path names no language. */
+    lang?: string;
+};
+/** `grep` / `ast_grep` search metadata. */
+export type SearchMatchesCardMeta = {
+    kind: 'search';
+    shape: 'matches';
+    /** Matched lines grouped by file, in first-seen order. */
+    files: CardSearchFileGroup[];
+    /** Whether the payload was capped (the counts below are pre-cap totals). */
+    truncated: boolean;
+    /** Total matches the search found before capping. */
+    total: number;
+};
+/** `glob` search metadata. */
+export type SearchPathsCardMeta = {
+    kind: 'search';
+    shape: 'paths';
+    /** The discovered paths, in result order. */
+    paths: string[];
+    /** Whether the payload was capped (the counts below are pre-cap totals). */
+    truncated: boolean;
+    /** Total paths the search found before capping. */
+    total: number;
+};
+/** Search metadata: one card, two `shape`-discriminated forms. */
+export type SearchCardMeta = SearchMatchesCardMeta | SearchPathsCardMeta;
+/** `bash` metadata for a foreground call that ran to completion. */
+export type TerminalForegroundCardMeta = {
+    kind: 'terminal';
+    mode: 'foreground';
+    /** Settled exit code; `null` when the process died from a timeout/abort. */
+    exitCode: number | null;
+    /** The command hit its deadline. */
+    timedOut: boolean;
+    /** The call was cancelled before the command settled. */
+    aborted: boolean;
+    /** The working directory the command actually ran in, when known. */
+    workingDir?: string;
+};
+/** `bash` metadata for a call handed off to a background job. */
+export type TerminalBackgroundCardMeta = {
+    kind: 'terminal';
+    mode: 'background';
+    /** The managed job's id. */
+    jobId: string;
+};
+/** `bash` metadata: the run state the terminal card's status pill needs. */
+export type TerminalCardMeta = TerminalForegroundCardMeta | TerminalBackgroundCardMeta;
+/** Any card metadata this plugin emits. */
+export type CardMeta = WriteCardMeta | EditCardMeta | AstEditCardMeta | ReadCardMeta | SearchCardMeta | TerminalCardMeta;
+/**
+ * Narrow opaque metadata to a {@link WriteCardMeta}.
+ * @param meta - the result node's `meta` field.
+ * @returns the narrowed metadata, or `null` when it is not a usable write card.
+ */
+export declare function narrowWriteCardMeta(meta: unknown): WriteCardMeta | null;
+/**
+ * Narrow opaque metadata to an {@link EditCardMeta}.
+ *
+ * Mirrors the shipped diff card's own validation (a hunk needs a non-blank
+ * `path`, an explicit `null` or string `oldText`, and a string `newText`) and
+ * additionally rejects a payload past {@link EDIT_META_MAX_BYTES}.
+ * @param meta - the result node's `meta` field.
+ * @returns the narrowed metadata, or `null` when it is not a usable diff card.
+ */
+export declare function narrowEditCardMeta(meta: unknown): EditCardMeta | null;
+/**
+ * Narrow opaque metadata to an {@link AstEditCardMeta}.
+ * @param meta - the result node's `meta` field.
+ * @returns the narrowed metadata, or `null` when it is not a usable preview.
+ */
+export declare function narrowAstEditCardMeta(meta: unknown): AstEditCardMeta | null;
+/**
+ * Narrow opaque metadata to a {@link ReadCardMeta}.
+ *
+ * Mirrors the shipped read card's own validation: a 1-based `offset`, lines
+ * strictly increasing in `number` and never past `totalLines`. A window whose
+ * lines were all elided therefore narrows to a card with an empty body, not to
+ * a malformed one.
+ * @param meta - the result node's `meta` field.
+ * @returns the narrowed metadata, or `null` when it is not a usable read card.
+ */
+export declare function narrowReadCardMeta(meta: unknown): ReadCardMeta | null;
+/**
+ * Narrow opaque metadata to a {@link SearchCardMeta}.
+ * @param meta - the result node's `meta` field.
+ * @returns the narrowed metadata, or `null` when it is not a usable search card.
+ */
+export declare function narrowSearchCardMeta(meta: unknown): SearchCardMeta | null;
+/**
+ * Narrow opaque metadata to a {@link TerminalCardMeta}.
+ * @param meta - the result node's `meta` field.
+ * @returns the narrowed metadata, or `null` when it is not a usable terminal card.
+ */
+export declare function narrowTerminalCardMeta(meta: unknown): TerminalCardMeta | null;

package/lib/types/web/host/ast-edit.d.ts

@@ -0,0 +1,10 @@
+import type { AstEditCardMeta } from '../contract.ts';
+/**
+ * Project the ast_edit engine's result into card metadata.
+ * @param details - the engine's `displayContent` / `fileReplacements` /
+ *   `totalReplacements` / `applied` fields (the adapter's value carries the
+ *   same names).
+ * @returns the ast_edit card metadata, or `null` when the call previews no
+ *   replacement or produced no preview text.
+ */
+export declare function projectAstEditCardMeta(details: unknown): AstEditCardMeta | null;

package/lib/types/web/host/bash.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Host projection for the `bash` terminal card.
+ *
+ * The call's output value is already the structured shape this card needs, so
+ * nothing is read back from the session and nothing is recomputed: the
+ * presentation metadata is a lossless narrowing of that value.
+ *
+ * Two properties matter to the card:
+ *  - a `timeoutMs: 0` call (the documented way to disable the deadline) is a
+ *    perfectly valid call; the shipped terminal card treats the option as
+ *    illegal and drops the whole card, so the run state cannot come from the
+ *    arguments;
+ *  - a timed-out or aborted run has no exit code of its own, and its result text
+ *    (`[timed out after …]`, `[exit code: null]`) is not something the shipped
+ *    card parses — the run state has to travel as data.
+ *
+ * @module @xiaoso/dsh-tool-plus/web/host/bash
+ */
+import type { TerminalCardMeta } from '../contract.ts';
+/**
+ * Project a bash result value into terminal-card metadata.
+ *
+ * Every emitted field is a plain JSON scalar and no key is ever set to
+ * `undefined`: the metadata rides `presentationMeta`, where a non-lossless
+ * payload turns a successful call into a failed one. An unrecognized value
+ * yields `null`, which simply leaves the row on the generic shell.
+ * @param value - the tool's own output value (foreground or background arm).
+ * @returns the card metadata, or `null` when the value is not a usable bash result.
+ */
+export declare function bashCardMeta(value: unknown): TerminalCardMeta | null;

package/lib/types/web/host/edit.d.ts

@@ -0,0 +1,33 @@
+import type { EditCardMeta } from '../contract.ts';
+/** One hunk of a numbered diff, gutter stripped. */
+export interface ParsedDiffHunk {
+    /** Removed rows plus context rows, in diff order. */
+    oldLines: string[];
+    /** Added rows plus context rows, in diff order. */
+    newLines: string[];
+    /** Whether the hunk carries at least one removed or added row. */
+    changed: boolean;
+}
+/**
+ * Parse an engine diff body into display hunks.
+ *
+ * Boundaries: a `@@ … @@` header, a blank gap row (the engine's own
+ * non-contiguity marker), or a line-number break after a change (how joined
+ * per-entry diffs and skipped context regions read). Hunks without a change are
+ * dropped — they would render as an empty diff.
+ * @param diff - `details.diff` / `details.perFileResults[].diff`.
+ * @returns the hunks, in diff order; empty when nothing parses.
+ */
+export declare function parseNumberedDiffHunks(diff: string): ParsedDiffHunk[];
+/**
+ * Project the edit engine's result details into card metadata.
+ *
+ * Multi-file results (`perFileResults`) are read file by file; single-file
+ * results use `path` + `diff`. The payload is capped at
+ * {@link EDIT_META_MAX_BYTES} by dropping whole trailing files; when nothing is
+ * left the call projects to `null` and falls back to the generic shell rather
+ * than writing an oversized session entry.
+ * @param details - the engine's `EditToolDetails` (or the adapter's value).
+ * @returns the edit card metadata, or `null` when there is no usable diff.
+ */
+export declare function projectEditCardMeta(details: unknown): EditCardMeta | null;

package/lib/types/web/host/read.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Host projection for the `read` card: the OMP engine already hands the renderer
+ * a prefix-free window (`details.displayContent` —
+ * `{text, startLine, lineNumbers?}`) exactly so the UI can draw its own gutter,
+ * and that is what the shipped read card consumes
+ * (`{kind:'read', path, offset, lines, totalLines, lang?}`).
+ *
+ * Three details drive the projection:
+ *  - the card path must be the file, never the model-facing argument: the OMP
+ *    argument carries an inline selector (`src/foo.ts:5-16,40-80`, `:raw`), so
+ *    the selector is stripped from whatever path source wins;
+ *  - `lineNumbers[i] === null` marks an elided span (the body renders `…`); such
+ *    entries carry no file line number and must be dropped, or the card's
+ *    "strictly increasing" rule breaks;
+ *  - only local, text-like reads take the card. Images, directories, internal
+ *    URLs (`skill://`, `conflict://N`, …), web URLs, SQLite, archives and
+ *    converted documents all fall back to the generic shell.
+ *
+ * The projection is bounded: past {@link READ_META_MAX_BYTES} whole trailing
+ * lines are dropped, and an empty window projects to `null` rather than to an
+ * empty card.
+ *
+ * @module @xiaoso/dsh-tool-plus/web/host/read
+ */
+import type { ReadCardMeta } from '../contract.ts';
+/**
+ * Strip the model-facing inline selector from a read target, leaving the file
+ * path the card should show.
+ *
+ * Handles `:5-16,40-80`, `:raw`, `:50+150`, `:conflicts` and the SQLite/archive
+ * sub-selectors (`db.sqlite:table:key`), plus the `file://` form the engine
+ * itself expands. Windows drive letters survive.
+ * @param target - the raw read target (`args.path`, or a resolved path).
+ * @returns the path without its selector.
+ */
+export declare function stripReadSelector(target: string): string;
+/**
+ * Project a read result value into read-card metadata.
+ *
+ * Every emitted field is plain JSON and no key is ever `undefined`: the metadata
+ * rides `presentationMeta`, where a non-lossless payload turns a successful call
+ * into a failed one. A non-text read, or a window without a single numbered
+ * line, yields `null` and leaves the row on the generic shell.
+ * @param args - the tool's arguments (only `path` is read).
+ * @param value - the tool's output value, as the adapter projects it.
+ * @returns the card metadata, or `null` when this read does not take the card.
+ */
+export declare function readCardMeta(args: unknown, value: unknown): ReadCardMeta | null;

package/lib/types/web/host/search.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Host projection for the `grep` / `ast_grep` / `glob` search cards.
+ *
+ * The engines already render the display text the TUI used to read: the grouped
+ * file output (`# dir/` / `## file.ts#<tag>` headers) followed by code-frame
+ * body lines (`*12│text` for a match, ` 12│text` for context, `…` for a gap).
+ * That text is the only place the matched *line numbers* live — `details` only
+ * carries per-file counts — so the card is rebuilt by parsing it with the same
+ * `classifyGroupedLines` helper the TUI renderers used, then reading each
+ * `formatCodeFrameLine` gutter back.
+ *
+ * Everything is defensive and bounded:
+ *  - an engine that explicitly reports zero (a `matchCount` of `0`, or an empty
+ *    `paths` array backed by a zero count) is a *known empty result*: it projects
+ *    to the empty card the client already renders, so the same tool never shows
+ *    two different shells;
+ *  - a display that yields no file group at all projects to `null` unless that
+ *    zero was reported (the row then falls back to the generic shell — the result
+ *    text stays fully visible);
+ *  - the payload is capped at {@link SEARCH_META_MAX_BYTES} by dropping trailing
+ *    groups/paths, with `truncated` raised and `total` left at its pre-cap value.
+ *
+ * @module @xiaoso/dsh-tool-plus/web/host/search
+ */
+import type { SearchMatchesCardMeta, SearchPathsCardMeta } from '../contract.ts';
+/**
+ * Project a `grep` / `ast_grep` result value into grouped-matches card metadata.
+ *
+ * @param input - the tool's output value: `displayContent`, `cwd`, `files`,
+ *   `matchCount` and `truncated` as the adapters project them.
+ * @returns the card metadata, or `null` when no file group could be parsed.
+ */
+export declare function searchMatchesCardMeta(input: unknown): SearchMatchesCardMeta | null;
+/**
+ * Project a `glob` result value into path-list card metadata.
+ *
+ * @param input - the tool's output value: `paths`, `fileCount`, `total` and `truncated`.
+ * @returns the card metadata, or `null` when the value is not a glob result (no
+ *   `paths` key, or an empty one the engine never backed with a zero count).
+ */
+export declare function searchPathsCardMeta(input: unknown): SearchPathsCardMeta | null;

package/lib/types/web/host/write.d.ts

@@ -0,0 +1,13 @@
+import type { WriteCardMeta } from '../contract.ts';
+/**
+ * Project the write tool's result (and its call arguments) into card metadata.
+ *
+ * The path is the engine's resolved target when it has one, falling back to the
+ * authored `args.path` (matching the value the adapter already emits). A blank
+ * or missing path projects to `null`; an unrecognized extension omits `lang`
+ * instead of writing `undefined`.
+ * @param details - the engine's `resolvedPath` / the adapter's value (`path`).
+ * @param args - the tool call arguments (`path`), used only as a fallback.
+ * @returns the write card metadata, or `null` when no usable path is present.
+ */
+export declare function projectWriteCardMeta(details: unknown, args?: unknown): WriteCardMeta | null;

package/lib/{types-PVueGi9S.mjs → types-DT9vgZ3S.mjs}

@@ -1,6 +1,6 @@
 import { installBunShim as __installBunShim } from "./bun-shim.mjs";
 __installBunShim();
-import { c as combineSignals } from "./src-BwW51vA5.mjs";
+import { c as combineSignals } from "./src-DUUqyo9y.mjs";
 import { t as ToolAbortError } from "./tool-errors-DoyxivAR.mjs";
 import { scheduler } from "node:timers/promises";
 //#region src/tools/omp/web/scrapers/types.ts

package/lib/{utils-CUPhpw9A.mjs → utils-BMmwLB0f.mjs}

@@ -1,7 +1,7 @@
 import { installBunShim as __installBunShim } from "./bun-shim.mjs";
 __installBunShim();
-import { F as $flag, N as $env, _ as parseStreamingJson, b as debug, g as parseJsonWithRepair } from "./src-BwW51vA5.mjs";
-import { r as ValidationError } from "./error-CORgGg5a.mjs";
+import { F as $flag, N as $env, _ as parseStreamingJson, b as debug, g as parseJsonWithRepair } from "./src-DUUqyo9y.mjs";
+import { r as ValidationError } from "./error-DdCn4m1q.mjs";
 import { n as classifyModel } from "./taxonomy-DSIM99rS.mjs";
 import { i as getBundledProviders, r as getBundledModels } from "./models-DnXMYGcJ.mjs";
 import { t as buildModelReferenceIndex } from "./reference-CtvM4zLU.mjs";