dsh-web-search-pro 0.2.0 → 0.2.3

package/lib/types/cli/spec.d.ts

@@ -0,0 +1,269 @@
+/**
+ * Declarative CLI adapter spec (dev-plan M12): what a standalone command-line tool is, which of its commands the plugin
+ * may run, and how its output maps to search sources. Pure data plus validation, no Node imports, so the settings card
+ * (client bundle) validates `cliAdapters` with the very function the server uses.
+ *
+ * The read-only guarantee lives here and applies to built-in and user-defined specs alike:
+ *  - argv is an array of tokens, never a shell string (the runner spawns without a shell);
+ *  - a spec declares `allowedSubcommands`, and every command word its argv uses (the leading literal tokens before the
+ *    first flag or placeholder) must be in that list;
+ *  - no command word, declared subcommand or flag may match the global deny-list (login, post, delete*, like, ...,
+ *    and the flags that make a CLI read browser cookies or carry secrets in argv).
+ * @module web-search-pro/cli/spec
+ */
+export declare const OUTPUT_FORMATS: readonly ["json", "ndjson", "yaml", "text"];
+export type OutputFormat = typeof OUTPUT_FORMATS[number];
+/** How far a spec has been checked against the real tool (recorded in the spec and shown in `sources.status`). */
+export declare const CLI_VERIFICATIONS: readonly ["live", "contract-only", "docs-only"];
+export type CliVerification = typeof CLI_VERIFICATIONS[number];
+/**
+ * The short honest tag shown next to a backend that was not verified with a real search ("detected and configured" is not "works"),
+ * or undefined for `live` and for backends that are not CLI specs.
+ */
+export declare function verificationTag(status: string): string | undefined;
+/** The verification word of a user-defined spec: it is unverified by definition and says so in every result it returns. */
+export declare const USER_DEFINED = "user-defined";
+/** The honest label a custom CLI's results and chain entries carry. */
+export declare const USER_DEFINED_TAG = "user-defined, not verified by the plugin (\u7528\u6237\u81EA\u5B9A\u4E49\uFF0C\u672A\u7ECF\u63D2\u4EF6\u9A8C\u8BC1)";
+/** Confidence of a custom CLI whose spec gives none: below the built-in sources (1), because nothing here checked its output. */
+export declare const DEFAULT_CUSTOM_CONFIDENCE = 0.5;
+/** Default and largest size of a whole-output result's text, in characters (`output.lines.maxChars`). */
+export declare const WHOLE_OUTPUT_DEFAULT_CHARS = 2000;
+export declare const WHOLE_OUTPUT_MAX_CHARS = 8000;
+/** Scheme of the stand-in link of a whole-output result (`cli://<id>?q=<query>`): not a web page, so nothing fetches it. */
+export declare const WHOLE_OUTPUT_SCHEME = "cli://";
+export declare const CLI_ERROR_CODES: readonly ["CLI_NOT_FOUND", "CLI_CONTRACT_MISMATCH", "CLI_NOT_LOGGED_IN", "ENGINE_EMPTY", "CLI_FAILED"];
+export type CliErrorCode = typeof CLI_ERROR_CODES[number];
+/**
+ * One piece of a joined field: a path, optionally with text put before / after the value, a `{ template }` over the item (dropped
+ * when a placeholder is empty), or a `{ time }` path whose text is read as a time (see {@link FieldSource}) and dropped when it is not one.
+ */
+export type JoinPart = string | {
+    path: string;
+    prefix?: string;
+    suffix?: string;
+} | {
+    template: string;
+} | {
+    time: string;
+    prefix?: string;
+    suffix?: string;
+};
+/** `{ template }` fills `{path}` placeholders from the item and yields nothing when one is empty; `when` makes it apply to one kind of item. */
+export interface TemplateSource {
+    template: string;
+    when?: {
+        path: string;
+        equals: string | number | boolean;
+    };
+}
+/**
+ * Where a field of a source comes from, for one parsed item:
+ *  - a dotted path (`data.title`, `items.0.url`);
+ *  - a list of paths and templates: the first non-empty one wins;
+ *  - `{ template }`: `{path}` placeholders over the item, dropped when any of them is empty;
+ *  - `{ join }`: the non-empty parts joined with `sep` (default ` | `);
+ *  - `{ epoch }`: a Unix timestamp (seconds) as an ISO date; `{ date }`: the date part (first 10 characters) of an ISO timestamp;
+ *  - `{ time }`: a time text the tool prints (ISO, the X API's `created_at`, `2026-10-27`, `08-26`, `3小时前`, `昨天 10:20`, ...) as an
+ *    ISO date or timestamp, and nothing when the text is none of the exactly known formats (see cli/time-text.ts).
+ * A dotted path may hold a `key=value` segment that picks the first element of an array with that field value
+ * (`note_card.corner_tag_info.type=publish_time.text`).
+ */
+export type FieldSource = string | readonly (string | TemplateSource)[] | TemplateSource | {
+    join: readonly JoinPart[];
+    sep?: string;
+} | {
+    epoch: string;
+} | {
+    date: string;
+} | {
+    time: string;
+};
+export interface CliOutputSpec {
+    format: OutputFormat;
+    /** json / yaml: dotted path of the item array; absent = the root array, else the first array-valued property. */
+    itemsPath?: string;
+    /** json / yaml: every entry must hold, else the output is a failure (a versioned envelope's `ok` and `schema_version`). */
+    expect?: readonly {
+        path: string;
+        equals: string | number | boolean;
+    }[];
+    /** Paths of the tool's own error text, read when `expect` fails (first non-empty one). */
+    errorPaths?: readonly string[];
+    /**
+     * text: how a line becomes an item (`tsv`: tab separated columns; `url-lines`: lines holding a URL, `url` + `title`; `whole`: the
+     * whole stdout is ONE result, for a tool that prints just a block of text: its text capped at `maxChars` (default
+     * {@link WHOLE_OUTPUT_DEFAULT_CHARS}) with a note when it was cut, the title "<id>: <query>" and the link `cli://<id>?q=<query>`).
+     */
+    lines?: {
+        mode: 'tsv';
+        columns: readonly string[];
+    } | {
+        mode: 'url-lines';
+    } | {
+        mode: 'whole';
+        maxChars?: number;
+    };
+    /** Required (with `url`) for every mode except `whole`, which maps nothing. */
+    fields?: {
+        url?: FieldSource;
+        title?: FieldSource;
+        snippet?: FieldSource;
+        publishedAt?: FieldSource;
+    };
+    /** Items whose `path` equals the value are not results at all and are not counted as skipped (xhs: `model_type` is `hot_query` for the suggestion cards its result list also carries). */
+    skipWhen?: {
+        path: string;
+        equals: string | number | boolean;
+    };
+    /** Strip HTML tags from title and snippet. */
+    stripTags?: boolean;
+    /** Values read as "empty" (`None`). */
+    emptyValues?: readonly string[];
+    /** Longest snippet kept (default 400). */
+    snippetMax?: number;
+    /** Longest title kept (default 300). */
+    titleMax?: number;
+    /** Drop items without a title (a line that is not a result). */
+    requireTitle?: boolean;
+}
+/**
+ * How a tool reports a failed command in its machine-readable format (a YAML / JSON payload on stderr, else stdout), and what
+ * each of its error codes means. A listed code is mapped to a structured plugin error; a code that is not listed keeps the
+ * tool's own message (`<tool> search failed: [CODE] message`).
+ */
+export interface CliErrorCodesSpec {
+    /** Dotted path of the tool's error code in the failure payload (`error.code`). */
+    codePath: string;
+    /** Dotted path of its message (`error.message`). */
+    messagePath?: string;
+    /** Codes that mean "not logged in" (CLI_NOT_LOGGED_IN). */
+    notLoggedIn?: readonly string[];
+    /** Exit codes that mean "not logged in" when the output carries no readable code. */
+    notLoggedInExit?: readonly number[];
+    /** Codes that mean "no results" (ENGINE_EMPTY). */
+    empty?: readonly string[];
+    /** Codes that mean the site answered with a web page or blocked the request: risk control, IP block, login wall (CLI_FAILED, said so). */
+    blocked?: readonly string[];
+    /** Case-insensitive fragments of the tool's message that mean the same (a JSON parse error on an HTML page: `Unexpected token '<'`). */
+    blockedPatterns?: readonly string[];
+    /** Codes that mean the tool cannot reach its browser (CLI_FAILED, not retryable). */
+    unavailable?: readonly string[];
+    /** Codes that mean a timeout (ENGINE_TIMEOUT). */
+    timeout?: readonly string[];
+    /** Codes that mean the tool rejected its arguments (CLI_CONTRACT_MISMATCH: the adapter does not match this version). */
+    usage?: readonly string[];
+}
+export interface CliSearchSpec {
+    /**
+     * Arguments after the binary. `{query}` and `{count}` are the placeholders; a token may embed one (`ytsearch{count}:{query}`).
+     * A token that is exactly `{terms}` expands to the query split into one argv token per word (double quotes keep a phrase together):
+     * for tools that join their positional arguments themselves and would otherwise quote a one-token query as an exact phrase (`gh search`).
+     */
+    argv: readonly string[];
+    /** Largest `{count}` sent (the search call's count is clamped to 1..maxCount). */
+    maxCount?: number;
+    /**
+     * Extra results asked of the tool beyond the count (`{count}` becomes count + overfetch), for tools whose list can hold entries the
+     * mapper must drop (bili: courses and series without a link). The mapper still returns at most `count`.
+     */
+    overfetch?: number;
+    output: CliOutputSpec;
+    /** Case-insensitive fragments of the tool's output that mean "no results" rather than a failure. */
+    emptyWhen?: readonly string[];
+    /** Case-insensitive fragments of the tool's output that mean "not logged in" (maps to CLI_NOT_LOGGED_IN). */
+    notLoggedInPatterns?: readonly string[];
+    /** The tool's structured error codes (checked before the fragments above). */
+    errorCodes?: CliErrorCodesSpec;
+}
+export interface CliProbeSpec {
+    versionArgs: readonly string[];
+    /** `X.Y.Z` the detected version must reach. */
+    minVersion?: string;
+    helpArgs: readonly string[];
+    /** Fragments the help output must contain: the subcommands and flags that prove this is the tool the spec describes. */
+    mustContain: readonly string[];
+    /** Appended to the reason when `mustContain` is not met (which version is known to have the contract, for example). */
+    contractHint?: string;
+}
+export interface CliLoginSpec {
+    /** What the user runs themselves (`xhs login`); never run by the plugin. */
+    command?: string;
+    /** What the user does, in words, when the tool takes its login from somewhere the plugin cannot run (the login of the user's own Chrome): shown instead of a command. One of `command` / `hint` is required. */
+    hint?: string;
+    /** Home-relative files that exist once the user has logged in. Only their existence is checked, never their content. */
+    savedCredentialPaths?: readonly string[];
+    /** The tool reads the browser's cookies by itself when it has no saved login: then it is never run without one. */
+    readsBrowserCookiesWithoutLogin?: boolean;
+}
+export interface CliAdapterSpec {
+    id: string;
+    /** Command names tried in order on PATH. */
+    bins: readonly string[];
+    /** What the package is called, which can differ from the command (`pip install pyzhihu-cli` runs `zhihu`). */
+    packageNote: string;
+    /**
+     * Platform ids the spec serves: the platforms whose backend chain it may sit in (`platformBackends.<platform>`). A user spec is
+     * also a platform of its own, `custom-cli:<id>`, and may list none when it is a general `engine`.
+     */
+    platforms: readonly string[];
+    /** User specs only: also a general search engine, listed in `engines` as `custom-cli:<id>` (fused and de-duplicated with the others). */
+    engine?: boolean;
+    /** User specs only: 0..1, default {@link DEFAULT_CUSTOM_CONFIDENCE}. `sources.confidence.custom-cli:<id>` overrides it. */
+    confidence?: number;
+    probe: CliProbeSpec;
+    /** Every command word the argv templates use. */
+    allowedSubcommands: readonly string[];
+    search: CliSearchSpec;
+    /** Per-platform overrides of `search` (gh serves github, github-issues and github-code with different commands). */
+    searches?: Readonly<Record<string, CliSearchSpec>>;
+    read?: CliSearchSpec;
+    env: {
+        required?: readonly string[];
+        passthrough?: readonly string[];
+        set?: Readonly<Record<string, string>>;
+    };
+    needsLogin: boolean;
+    login?: CliLoginSpec;
+    timeoutMs: number;
+    maxOutputBytes: number;
+    /** Built-ins only: how far the spec was checked. User-defined specs carry none (they are unverified by definition). */
+    verification?: {
+        status: CliVerification;
+        version?: string;
+        date?: string;
+        note?: string;
+    };
+}
+/** Command words that write, log in, or change local or remote state. Matched exactly, or as `<word>-...` / `<word>_...`. */
+export declare const DENIED_SUBCOMMANDS: readonly string[];
+/** Command words denied by prefix alone (`delete`, `delete-note`, `deleteNote`, `remove...`). */
+export declare const DENIED_PREFIXES: readonly string[];
+/** Flags (without leading dashes) that read browser cookies or carry credentials in argv. */
+export declare const DENIED_FLAGS: readonly string[];
+/** The command words of an argv: leading literal tokens before the first flag or placeholder token. */
+export declare function commandWords(argv: readonly string[]): string[];
+/** Problems of one argv template with respect to the read-only guard (empty = fine). */
+export declare function argvProblems(argv: readonly string[], allowed: readonly string[], where: string): string[];
+export interface CliSpecValidation {
+    ok: boolean;
+    errors: string[];
+    spec?: CliAdapterSpec;
+}
+/**
+ * Validate one adapter spec (built-in or user-defined). Never throws. A user-defined spec (`origin: 'user'`) may not carry a
+ * `verification` (it is unverified by definition) and its `platforms` are ignored: it is registered as `custom-cli:<id>`.
+ */
+export declare function validateCliAdapterSpec(raw: unknown, origin?: 'builtin' | 'user'): CliSpecValidation;
+/** Validate the `cliAdapters` setting: the valid specs by id and the problems of the rest (an invalid entry is ignored, never fatal). */
+export declare function resolveCliAdapters(input: unknown): {
+    specs: Map<string, CliAdapterSpec>;
+    diagnostics: string[];
+};
+/** Search spec of one platform: the platform's override, else the default. */
+export declare function searchSpecFor(spec: CliAdapterSpec, platform: string): CliSearchSpec;
+export declare function compareVersions(left: string, right: string): number;
+/** The first `X.Y.Z` (or `X.Y`) in a tool's version output. */
+export declare function parseVersion(output: string): string | undefined;
+/** `platformBackends`: ordered backend ids per platform. Pure shape check; ids are checked against the known backends by the caller. */
+export declare function platformBackendProblems(input: unknown): string[];

package/lib/types/cli/time-text.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Conservative parsing of the time texts CLI tools print (a field source `{ time }` of the adapter spec): an exact format is
+ * turned into an ISO date or timestamp, anything else gives nothing, so a result never carries a guessed time. Pure; the clock is
+ * a parameter. Chinese relative and calendar texts are read in China time (UTC+8), which is what the sites print.
+ *  - ISO 8601 (`2026-10-27T08:38:08Z`, with or without a zone offset or fraction) -> normalized timestamp;
+ *  - the `created_at` of the X API (`Tue Oct 27 08:38:08 +0000 2026`) -> timestamp;
+ *  - `YYYY-MM-DD` -> that date; `MM-DD` -> the latest such date that is not after today (a date in the future means last year);
+ *  - `N分钟前` / `N小时前` -> timestamp (now minus N); `N天前` -> date; `昨天 HH:MM` -> timestamp (China time).
+ * @module web-search-pro/cli/time-text
+ */
+/** The text as an ISO date (`YYYY-MM-DD`) or timestamp, or undefined when it is not one of the formats above. */
+export declare function normalizeTimeText(raw: string, now?: number): string | undefined;

package/lib/types/cli/trial.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The trial run of a custom CLI spec (settings card, "Try it"): what a search with the draft spec would do, shown before it is saved.
+ * It is a real run, not a simulation: the spec is validated by the rule every spec goes through (the read-only guard, no shell, no
+ * credentials in argv), the command is probed (version and help only), then ONE search for the sample query runs through the same
+ * runner with the spec's own timeout and output cap. The first results and the tool's own words come back; secrets are redacted,
+ * a login is never run, and nothing is stored.
+ * @module web-search-pro/cli/trial
+ */
+import { type runCli } from '../util.ts';
+import type { TrialResult } from '../rpc-types.ts';
+export interface TrialOptions {
+    /** `enableCliBackends`: with it off no custom command runs, trial or search. */
+    enabled: boolean;
+    signal?: AbortSignal;
+    /** Test seams. */
+    run?: typeof runCli;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function trialCli(id: string, rawSpec: unknown, query: string, options: TrialOptions): Promise<TrialResult>;

package/lib/types/client/SettingsCard.d.ts

@@ -1,2 +1,18 @@
+/**
+ * The Web Search Pro settings card, as the Plugins page renders it.
+ *
+ * The page owns the card frame (its title, disclosure and artwork come from the slot registration), so this component renders
+ * only what goes inside: the one-liner for `view: 'summary'`, and for `view: 'page'` a status summary, twelve groups (only
+ * "Common" open) and a save bar that stays in view.
+ *
+ *   Common · Search order · Sources · Custom CLI · Reading and evidence · Scoring model · Built-in web tool route ·
+ *   Runtime and backends · Network and cache · Ranking weights · Agent changes · Advanced: text mode and raw JSON
+ *
+ * Each group is its own module (`group-*.tsx`) built from the controls in `ui-kit.tsx`: the Host's own switches, buttons,
+ * badges, dialogs and help bubbles, plus the few controls the Host has no component for. Every public config field has
+ * exactly one entry in the groups (test/settings-card-render.test.ts counts them); the text of the last group is a view of
+ * the same fields, not a second place they live.
+ * @module web-search-pro/client/SettingsCard
+ */
 import type { SettingsCardProps } from './index.ts';
-export declare function SettingsCard(props: SettingsCardProps): string | import("react").JSX.Element | null;
+export declare function SettingsCard(props: SettingsCardProps): import("react").JSX.Element;

package/lib/types/client/agent-mark.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The mark beside a setting that an agent changed with `config.*`: "Changed by agent", whose tooltip says what the agent set, what the
+ * configuration holds, why and when, and (outside the cramped list rows) the two buttons that settle it: adopt the value into the
+ * configuration, or revoke it. The data is the plugin's overlay, read once over the card's RPC channel when the panel opens and again
+ * on the refresh button (see group-agent.tsx).
+ * @module web-search-pro/client/agent-mark
+ */
+import type { OverlayItem } from '../overlay-types.ts';
+import type { Card } from './field-rows.tsx';
+/** The overlay item of a key in the card's state, or undefined. */
+export declare function useOverlayItem(card: Card, key: string): OverlayItem | undefined;
+/** One sentence for the tooltip: the value the agent set, the one in the configuration, the reason, who and when. */
+export declare function agentTip(t: Card['t'], item: OverlayItem): string;
+/**
+ * `compact` shows the tag only (list rows have no room for buttons; the "Agent changes" group holds them); otherwise the tag is followed
+ * by "Adopt into configuration" and "Revoke".
+ */
+export declare function AgentMark({ card, itemKey, compact }: {
+    card: Card;
+    itemKey: string;
+    compact?: boolean;
+}): import("react").JSX.Element | null;

package/lib/types/client/card-frame.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The frame around the groups: the status summary on top (with the warnings dialog) and the save bar at the bottom.
+ *
+ * The Host's `SettingsForm` offers one save button below the controls. This card needs the bar to stay in view while a long
+ * page scrolls, to say how many edits are waiting, and to offer "Discard", so the frame is built here; the behaviors a
+ * settings form has are kept: it says so when the settings are not served or read-only, and it drops the staged edits when
+ * the page is left.
+ * @module web-search-pro/client/card-frame
+ */
+import { type ReactNode } from 'react';
+import { type ChainInput } from '../default-chain.ts';
+import { type Card } from './field-rows.tsx';
+import type { WebSearchCardState } from './form.ts';
+/** What the default chain rule reads from the staged settings: the list, the preferences, the ready common sources, the policy. */
+export declare function chainInputOf(snapshot: Pick<WebSearchCardState, 'fields' | 'credentials'>): ChainInput;
+/** The chain a plain search would try, from the staged settings; undefined when the draft leaves nothing to try. */
+export declare function chainOf(snapshot: Pick<WebSearchCardState, 'fields' | 'credentials'>): string[] | undefined;
+/**
+ * The chain a plain search tries once the agent's changes (engines, priority, disabled of the overlay) are on top of the staged settings,
+ * by the same rule; undefined while the agent changed none of the three, an empty list when it would leave nothing to try.
+ */
+export declare function agentChainOf(snapshot: Pick<WebSearchCardState, 'fields' | 'credentials' | 'server'>): string[] | undefined;
+/** Everything the warnings badge counts: what the validation says about a field, and the rubric problems. */
+export declare function warningsOf(snapshot: WebSearchCardState, t: Card['t']): string[];
+export declare function SummaryBar({ card }: {
+    card: Card;
+}): import("react").JSX.Element;
+export declare function SaveBar({ card }: {
+    card: Card;
+}): import("react").JSX.Element;
+/** The page frame: nothing but a notice while the settings are not served; the staged edits are dropped when the page is left. */
+export declare function Frame({ card, children }: {
+    card: Card;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/lib/types/client/cli-form.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The form side of the custom CLI editor: a `cliAdapters` entry (the JSON spec) as the fields of the edit dialog and back. Two
+ * views of one object: the form writes the keys it has controls for onto a copy of the spec and leaves every other key as it
+ * was (searches, read, env, login, errorCodes, a field mapping that is not a plain path), and the JSON box edits the whole spec.
+ * Validation is `validateCliAdapterSpec`, the function the server registers specs with; its messages are sorted to the field they
+ * are about. `allowedSubcommands` is derived from the command words of the argv templates, never typed.
+ * Pure: no Host, no DOM.
+ * @module web-search-pro/client/cli-form
+ */
+import { WHOLE_OUTPUT_DEFAULT_CHARS, type OutputFormat } from '../cli/spec.ts';
+type Json = Record<string, unknown>;
+/** The result fields the form maps, in display order; each takes a dotted path into one item of the tool's output. */
+export declare const FIELD_KEYS: readonly ["url", "title", "snippet", "publishedAt"];
+export type FieldKey = typeof FIELD_KEYS[number];
+/** How a plain text tool's lines become items (`whole` is a switch of its own). */
+export declare const LINE_MODES: readonly ["url-lines", "tsv"];
+export type LineMode = typeof LINE_MODES[number];
+export interface CliForm {
+    /** The key in `cliAdapters` (`custom-cli:<id>` everywhere else). */
+    id: string;
+    /** The command: a name on PATH, never a path. */
+    bin: string;
+    /** The argument template, one token per entry; `{query}`, `{count}` and `{terms}` are filled in. */
+    argv: string[];
+    format: OutputFormat;
+    /** Text output only: the whole stdout is one result (no field mapping). */
+    whole: boolean;
+    wholeMax: string;
+    /** json / yaml: dotted path of the result array (empty = the root array or the first array found). */
+    itemsPath: string;
+    linesMode: LineMode;
+    /** tsv: the column names, comma separated. */
+    columns: string;
+    /** A plain dotted path per result field; a mapping that is more than a path is kept as it is and listed in `complex`. */
+    fields: Record<FieldKey, string>;
+    complex: FieldKey[];
+    timeoutMs: string;
+    maxOutputBytes: string;
+    /** The purposes: a general search engine, and/or the platforms whose backend chain it may sit in. */
+    engine: boolean;
+    platforms: string[];
+    /** Empty = the default (0.5). */
+    confidence: string;
+    packageNote: string;
+    /** The probe: the help command (space separated) and the fragments its output must contain. */
+    helpArgs: string;
+    mustContain: string[];
+}
+/** The spec a new entry starts from: a JSON-printing tool mapped url / title / snippet. The form fills the command in. */
+export declare function newSpec(): Json;
+/** The example of the dialog: `echo`, whose whole output is the result (no field mapping), a way to see the pieces work without a real tool. */
+export declare function echoSpec(): Json;
+/** The form fields of a spec (plain or not): everything the dialog shows, as text. */
+export declare function specToForm(id: string, raw: unknown): CliForm;
+/** The command words the argv templates of a spec use, in order, without repeats: what `allowedSubcommands` must list. */
+export declare function derivedSubcommands(spec: Json): string[];
+/**
+ * The spec the form describes, built on `base` (the entry as it was: every key the form has no control for is kept). Nothing is
+ * validated here; a value that is not what its box wants is written as typed so `validateCliAdapterSpec` names it.
+ */
+export declare function formToSpec(form: CliForm, base?: Json): Json;
+/** The names of the dialog's fields that an error message can be about. */
+export type ErrorField = 'id' | 'bin' | 'argv' | 'format' | 'itemsPath' | 'lines' | 'fields' | FieldKey | 'timeoutMs' | 'maxOutputBytes' | 'platforms' | 'engine' | 'confidence' | 'packageNote' | 'probe' | 'general';
+/** Sort the validator's messages (`cliAdapters.<id>.<path>: ...`) to the dialog field they are about. */
+export declare function errorsByField(id: string, errors: readonly string[]): Partial<Record<ErrorField, string[]>>;
+export interface CliCheck {
+    spec: Json;
+    /** The validator's messages (empty = valid). */
+    errors: string[];
+    byField: Partial<Record<ErrorField, string[]>>;
+    ok: boolean;
+}
+/** Build the spec of a form and validate it the way the server does; `taken` are the ids of the other entries (a new id may not repeat one). */
+export declare function checkForm(form: CliForm, base: Json, taken?: readonly string[]): CliCheck;
+/** Validate a spec (the JSON view): the server's function, plus the one rule only the editor has (an id is not used twice). */
+export declare function checkSpec(id: string, spec: Json, taken?: readonly string[]): CliCheck;
+/** The confidence the entry has: its own, else the default. */
+export declare const confidenceOfForm: (form: CliForm) => number;
+export { WHOLE_OUTPUT_DEFAULT_CHARS };
+/** The JSON text of a spec as the dialog's raw box prints it. */
+export declare const specText: (spec: Json) => string;
+/** The spec a raw JSON text holds, or the reason it is not one. */
+export declare function parseSpecText(text: string): {
+    spec: Json;
+} | {
+    error: string;
+};
+/** The `cliAdapters` object of the staged text (empty text = no entries); undefined when it is not an object. */
+export declare function adaptersOf(text: string): Json | undefined;
+/**
+ * The `cliAdapters` text with entry `id` set to `spec` (a new key goes last), or removed when `spec` is undefined. The other
+ * entries are kept as they were. The object with no entries comes back as the empty text, which the form model stores as "not set".
+ * Undefined when the current text is not an object (the raw JSON box has to be fixed first).
+ */
+export declare function withAdapter(text: string, id: string, spec: Json | undefined): string | undefined;
+/** A free id for a copy or a new entry: `base`, `base-2`, `base-3`, ... */
+export declare function freeId(base: string, taken: readonly string[]): string;

package/lib/types/client/field-docs.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The comment printed in front of every key of the text view ("Advanced: text mode"), in the language of the card: what the
+ * setting is for, its allowed values or range, its default, and the risk when there is one. Comment lines start with `#`, so
+ * the text stays valid YAML and a round trip never reads a comment as data. Pure (it imports only config-groups.ts): the text view and the
+ * tests read it, and the client bundle includes it. Nothing here names a secret value: keys are only ever referenced by name.
+ * @module web-search-pro/client/field-docs
+ */
+export type DocLang = 'en' | 'zh';
+/** The doc of a config field in a language; undefined only for a field the card does not know. */
+export declare function fieldDoc(field: string, lang?: DocLang | string): string | undefined;
+/** The docs of the groups of keys and the header of the text view. */
+export declare function textViewDocs(lang?: DocLang | string): {
+    header: readonly string[];
+    group: Readonly<Record<string, string>>;
+};

package/lib/types/client/field-keys.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Which dictionary entry names a field, which fields carry a `?` text of their own, and the facts about the sources the
+ * card lists. Pure data (no imports): the rows, the text view and the tests all read it.
+ * @module web-search-pro/client/field-keys
+ */
+import { type ConfigGroupId } from '../config-groups.ts';
+export declare function labelKey(field: string): string;
+/** The fields whose dictionary has a `<key>Help` text (a longer explanation behind the `?`). */
+export declare const WITH_HELP: ReadonlySet<string>;
+/** `?` text applies to the generic budget keys too. */
+export declare const hasHelp: (field: string) => boolean;
+/** Dictionary key of the sentence saying why a start-up-only field needs a plugin restart (restart.ts lists the fields). */
+export declare function restartWhyKey(field: string): string;
+export type SourceTier = 'paid' | 'free-quota' | 'anonymous';
+/** One source the "Sources" list shows and its edit dialog is made of. */
+export interface SourceDef {
+    id: string;
+    name: string;
+    tier: SourceTier;
+    /** "常用": the plugin's recommended source (pinned to the registry descriptors by a test). */
+    common?: boolean;
+    /** The write-only key of the source (`CredentialId`), and the field naming the credential / variable it is stored under. */
+    credential?: string;
+    envField?: string;
+    defaultEnv?: string;
+    baseUrlField?: string;
+    /** Other fields the dialog holds, in order. */
+    extra?: readonly string[];
+    /** The request budget of the source (`sources.budget.<id>.total|daily`). */
+    budget?: boolean;
+}
+export declare const SOURCE_DEFS: readonly SourceDef[];
+/** Fields of a source dialog in display order (the key itself is a credential, not a field). */
+export declare function sourceFields(def: SourceDef): string[];
+/** Fields shown as JSON objects, each in its own dialog: the field, the group it sits in. */
+export declare const JSON_FIELDS: readonly {
+    field: string;
+    group: 'judge' | 'runtime' | 'platform' | 'advanced';
+}[];
+/** Group of the text view of any field: the group of its top-level key (see config-groups.ts, the one list of the layout). */
+export declare function textGroupOf(field: string): ConfigGroupId;

package/lib/types/client/field-rows.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Rows for the configuration fields the groups edit, wired to the card's staged form state.
+ *
+ * One component per control kind (switch, select, text, number, list of ids). Each is the single entry of its field: it renders
+ * `data-wsp-field="<field>"`, which test/settings-card-render.test.ts counts, and it reads the label, the one-line hint and the
+ * optional `?` text from the dictionary by the field's name (`<key>`, `<key>Hint`, `<key>Help`, see field-keys.ts).
+ * @module web-search-pro/client/field-rows
+ */
+import type { SettingsCardProps } from './index.ts';
+import type { CardFieldState, WebSearchCardState } from './form.ts';
+import { fill } from './fill.ts';
+import { type RowLabels, type SelectOption } from './ui-kit.tsx';
+export type Card = SettingsCardProps;
+export type Translator = Card['t'];
+export type LabelKey = Parameters<Translator>[0];
+export { fill };
+export declare function rowLabels(t: Translator): RowLabels;
+/** The id of a field's control, tied to its label. */
+export declare const controlId: (field: string) => string;
+/** The units a number field is written with. */
+declare const UNIT_KEYS: {
+    readonly ms: "unitMs";
+    readonly sec: "unitSeconds";
+    readonly chars: "unitChars";
+    readonly count: "unitCount";
+    readonly tokens: "unitTokens";
+    readonly days: "unitDays";
+    readonly rounds: "unitCount";
+};
+export type Unit = keyof typeof UNIT_KEYS;
+export interface FieldProps {
+    card: Card;
+    /** The setting field this row is the entry of. */
+    field: string;
+    /** Replaces the dictionary hint. */
+    hint?: string;
+    placeholder?: string;
+    /** Replaces the dictionary label. */
+    label?: string;
+    /** A short warning badge beside the label. */
+    risk?: string;
+    /** Hide the "overridden" badge and reset: for fields whose "default" is a computed one. */
+    code?: boolean;
+}
+/** How many of these fields carry an override: the number a group's badge shows. */
+export declare function useOverriddenCount(card: Card, fields: readonly string[]): number;
+/** The staged state of a field. */
+export declare const stateOf: (snapshot: WebSearchCardState, field: string) => CardFieldState | undefined;
+export declare function useField(card: Card, field: string): {
+    state: CardFieldState;
+    disabled: boolean;
+    edit: (text: string) => void;
+    reset: () => void;
+};
+/** A boolean field as a switch. */
+export declare function SwitchRow(props: FieldProps): import("react").JSX.Element;
+/** An enumerated field as a drop-down. */
+export declare function SelectRow(props: FieldProps & {
+    options: readonly SelectOption[];
+}): import("react").JSX.Element;
+/** A free-text field. */
+export declare function TextRow(props: FieldProps): import("react").JSX.Element;
+/** A number field with its unit written after the input. */
+export declare function NumberRow(props: FieldProps & {
+    unit?: Unit;
+}): import("react").JSX.Element;
+declare const parseList: (text: string) => string[];
+/** A comma-separated list (engine ids, domains) as removable chips with an add box. */
+export declare function ListRow(props: FieldProps): import("react").JSX.Element;
+export { parseList };

package/lib/types/client/fill.d.ts

@@ -0,0 +1,2 @@
+/** Fill `{name}` placeholders of a dictionary entry. */
+export declare const fill: (text: string, values: Record<string, string | number>) => string;