@dsh-cove/dsh-web-all 0.0.0-stage → 0.4.3

package/lib/types/host/services/web-search-kaon/index.js

@@ -0,0 +1,114 @@
+/**
+ * Kaon Router 检索服务域 —— 向 `ctx.web` 注册 `kaon-router` search provider。
+ *
+ * ## 为什么注册是「只要 web 在就注册」
+ *
+ * profile patch 把 `@deepseek-ai/dsh-web` 的 `searchProvider` pin 成 `kaon-router`。
+ * seam 在指定了 id 时只用该 id：provider 缺席报
+ * `WEB_PROVIDER_CONFIGURED_MISSING`，注册了但 `available()` 为假报
+ * `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`——两者都会让 `web_search` 整体不可用。
+ * 因此这里选择「只要 web 服务在就注册」：key 缺失属于运行期错误，由 provider
+ * 按次给出 `WEB_PROVIDER_CREDENTIAL_MISSING`，并点名该配的凭据引用。
+ *
+ * 要彻底关掉本域，必须**同时**把 `searchProvider` 改回 `deepseek-official`
+ * （见 cordis.patch.yml 的注释），只删这一段会留下一个指向不存在 provider 的 pin。
+ *
+ * ## 为什么用局部 inject
+ *
+ * 0.2 严格注入下，插件只能访问自己 inject 声明过的服务。这里用
+ * `ctx.inject(['web'], …)` / `ctx.inject(['credentials'], …)` 等待，而不是把
+ * 它们写进 web-all 的全局 inject：那会让整个全家桶在缺少这些服务的 profile 里挂掉。
+ *
+ * ## 配置读取
+ *
+ * `web-search-kaon` 是聚合 Config 里的一个 volatile 命名空间；provider 拿到的是
+ * **读取函数**而非快照，端点/模型/次数上限的热更新立即生效，无需重挂插件。
+ *
+ * @module web-all/host/services/web-search-kaon
+ */
+import { familyNamespace } from "../family-config.js";
+import { effectiveConfig, WEB_SEARCH_KAON_PROVIDER_ID, WEB_SEARCH_KAON_SETTINGS_NAMESPACE, } from "./contracts.js";
+import { KaonSearchProvider } from "./provider.js";
+/** 可选读取 credentials 缝隙：0.2 严格注入下访问未声明的服务会直接抛错。 */
+function credentialSeamOf(ctx) {
+    try {
+        return ctx.credentials;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 注册 Anthropic 兼容检索 provider。
+ * @param ctx - host plugin context。
+ * @param options - 告警出口与显式配置（测试）。
+ * @returns 卸载回调：注销 provider。
+ */
+export function register(ctx, options = {}) {
+    const warn = options.logger?.warn ?? ((message) => console.warn(message));
+    const readConfig = () => effectiveConfig(options.config ?? familyNamespace(WEB_SEARCH_KAON_SETTINGS_NAMESPACE));
+    const env = options.env ?? ((name) => process.env[name]);
+    // 凭据服务是可选依赖：没有它时 provider 仍注册，key 回落到环境变量或字面 apiKey。
+    let credentials;
+    try {
+        ctx.inject(['credentials'], (cctx) => { credentials = credentialSeamOf(cctx); });
+    }
+    catch {
+        // 该 profile 没有 credentials 服务：静默缺席，不影响注册。
+    }
+    const provider = new KaonSearchProvider(() => {
+        const config = readConfig();
+        return {
+            baseURL: config.baseURL,
+            model: config.model,
+            apiVersion: config.apiVersion,
+            maxTokens: config.maxTokens,
+            maxUses: config.maxUses,
+            includeAnswer: config.includeAnswer,
+            timeoutMs: config.timeoutMs,
+            apiKeyEnv: config.apiKeyEnv,
+            ...config.apiKey !== '' ? { apiKey: config.apiKey } : {},
+            resolveApiKey: async () => {
+                try {
+                    const stored = await credentials?.resolve(config.apiKeyEnv);
+                    if (stored !== undefined && stored.value.length > 0)
+                        return stored.value;
+                }
+                catch {
+                    // 凭据服务拒绝解析（引用不存在/语法非法）时退回环境变量。
+                }
+                const ambient = env(config.apiKeyEnv);
+                return ambient !== undefined && ambient.length > 0 ? ambient : undefined;
+            },
+        };
+    });
+    const initial = readConfig();
+    if (!URL.canParse(initial.baseURL)) {
+        warn(`[web-all:web-search-kaon] baseURL 不是合法 URL（${JSON.stringify(initial.baseURL)}）：`
+            + `web_search 仍被 pin 到 ${WEB_SEARCH_KAON_PROVIDER_ID}，调用会以 WEB_PROVIDER_CONFIGURED_UNAVAILABLE 失败；`
+            + `请在 ${WEB_SEARCH_KAON_SETTINGS_NAMESPACE} 命名空间里改回 Anthropic 兼容端点`);
+    }
+    let disposed = false;
+    let unregister;
+    try {
+        ctx.inject(['web'], (cctx) => {
+            if (disposed)
+                return;
+            const seam = cctx.web;
+            if (seam?.registerSearchProvider === undefined)
+                return;
+            unregister = seam.registerSearchProvider(provider);
+        });
+    }
+    catch (error) {
+        // 组合里没有 web 服务：本域静默缺席，绝不影响全家桶其余能力。
+        warn(`[web-all:web-search-kaon] 等待 web 服务失败，本域缺席：${error instanceof Error ? error.message : String(error)}`);
+        return () => undefined;
+    }
+    return () => {
+        disposed = true;
+        unregister?.();
+    };
+}
+export { effectiveConfig, WEB_SEARCH_KAON_DEFAULT_API_KEY_ENV, WEB_SEARCH_KAON_DEFAULT_BASE_URL, WEB_SEARCH_KAON_DEFAULT_MODEL, WEB_SEARCH_KAON_PROVIDER_ID, WEB_SEARCH_KAON_SETTINGS_NAMESPACE, } from "./contracts.js";
+export { citationSnippets, KaonSearchProvider, mapSearchResponse } from "./provider.js";

package/lib/types/host/services/web-search-kaon/provider.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Kaon Router（Anthropic 兼容 Messages）搜索 provider。
+ *
+ * 一次搜索 = 一次 Messages 请求 + 原生 `web_search_20250305` 服务端工具：代价是
+ * 一个模型回合，回报是结构化结果块。与原生 deepseek provider 的唯一实质差别是
+ * **响应归一化**：本 provider 同时接受标准 Anthropic 形状（`web_search_tool_result`
+ * 条目 + citation 摘录）和 Kaon/Bedrock 形状（没有结果块，只有 citation），
+ * 并且在「模型只是申请调用客户端工具」时给出可操作的报错，而不是假装搜到了东西。
+ *
+ * 配置按**每次搜索**从注入的读取器取，因此 `web-search-kaon` 命名空间的热更新
+ * （端点/模型/次数上限）立即生效，无需重挂插件。
+ *
+ * `available()` 只做本地判断（key 解析器存在、URL 可解析、上限为正整数），
+ * 不发网络请求（seam 的硬要求）。
+ *
+ * @module web-all/host/services/web-search-kaon
+ */
+import { type WebSearchProvider, type WebSearchRequest, type WebSearchResult, type WebSearchSource } from './contracts.ts';
+/** 一次引用位置（Kaon 把命中信息全放在这里）。 */
+export interface CitationLocation {
+    type?: string;
+    url?: string | null;
+    title?: string | null;
+    cited_text?: string | null;
+}
+/** 一个内容块；只消费下方注释里列出的几种。 */
+export interface ContentBlock {
+    type?: string;
+    text?: string | null;
+    name?: string | null;
+    citations?: readonly CitationLocation[] | null;
+    /** `web_search_tool_result` 的载荷：条目数组，或一个错误对象。 */
+    content?: unknown;
+}
+/** `web_search_tool_result` 里的一个可引用条目。 */
+export interface SearchResultItem {
+    type?: string;
+    url?: string | null;
+    title?: string | null;
+    page_age?: string | null;
+}
+/** Anthropic Messages 响应信封（best-effort；字段随上游而变）。 */
+export interface AnthropicResponse {
+    content?: readonly ContentBlock[] | null;
+    stop_reason?: string | null;
+    usage?: {
+        server_tool_use?: {
+            web_search_requests?: number | null;
+        } | null;
+    } | null;
+}
+/** 归一化结果：来源、可选的模型摘要，以及用于诊断的检索事实。 */
+export interface MappedSearchResponse {
+    sources: readonly WebSearchSource[];
+    /** 模型生成的摘要文本（取最长的一段非空 text 块）。 */
+    content?: string;
+    /** 端点侧实际执行的服务端搜索次数（0 表示没搜）。 */
+    searches: number;
+    /** 响应里有 `tool_use(web_search)`：模型申请调用客户端工具，端点没执行搜索。 */
+    clientToolUse: boolean;
+    /** `web_search_tool_result` 自带的错误码（有则整体失败）。 */
+    resultError?: string;
+}
+/** 一次搜索的运行期选项快照。 */
+export interface KaonSearchProviderOptions {
+    /** 端点基址，不含 `/messages`。 */
+    baseURL: string;
+    model: string;
+    apiVersion: string;
+    maxTokens: number;
+    maxUses: number;
+    /** 是否把模型摘要并入 `content`。 */
+    includeAnswer: boolean;
+    timeoutMs: number;
+    /** 字面 key；存在时优先于 {@link resolveApiKey}。 */
+    apiKey?: string;
+    /** 每次搜索解析一次当前 key（凭据服务 / 环境变量）。 */
+    resolveApiKey?: () => Promise<string | undefined>;
+    /** 凭据引用名，只用于报错文案。 */
+    apiKeyEnv?: string;
+    /** 注入的 fetch，测试用。 */
+    fetchImpl?: typeof fetch;
+}
+/** 收集每个 URL 的 citation 摘录（首次出现优先）；标准形状下它才是 snippet 来源。 */
+export declare function citationSnippets(blocks: readonly ContentBlock[]): Map<string, string>;
+/**
+ * 把两种 Anthropic 兼容响应形状统一成 seam 的 `sources[]`。
+ *
+ * 顺序：先走标准结果块（带 `page_age` 与条目级字段），拿不到任何条目时再回落到
+ * citation —— Kaon 的 Claude 路由永远走第二条分支；两条分支都用同一张 citation
+ * 摘录表补 `snippet`，按 URL 去重（`max_uses > 1` 时同一 URL 可能多次出现）。
+ *
+ * @param response - 解析后的 Messages 响应体。
+ * @returns 归一化结果；`searches`/`clientToolUse`/`resultError` 供诊断使用。
+ */
+export declare function mapSearchResponse(response: AnthropicResponse): MappedSearchResponse;
+/** 用 Anthropic 兼容 Messages 端点做检索的 provider。 */
+export declare class KaonSearchProvider implements WebSearchProvider {
+    readonly id = "kaon-router";
+    private readonly resolveOptions;
+    /**
+     * @param resolveOptions - 下一次操作的选项；thunk 而非快照，命名空间热更新因此
+     * 每次搜索都生效，而不必重注册 provider（重注册会让 seam 的选择对用户可见地抖动）。
+     */
+    constructor(resolveOptions: () => KaonSearchProviderOptions);
+    available(): boolean;
+    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+    /** 解析一次操作的 key：字面 key → 凭据服务 → 环境变量。 */
+    private apiKey;
+}
+//# sourceMappingURL=provider.d.ts.map

package/lib/types/host/services/web-search-kaon/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../../../src/host/services/web-search-kaon/provider.ts"],"names":[],"mappings":"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"}

package/lib/types/host/services/web-search-kaon/provider.js

@@ -0,0 +1,244 @@
+/**
+ * Kaon Router（Anthropic 兼容 Messages）搜索 provider。
+ *
+ * 一次搜索 = 一次 Messages 请求 + 原生 `web_search_20250305` 服务端工具：代价是
+ * 一个模型回合，回报是结构化结果块。与原生 deepseek provider 的唯一实质差别是
+ * **响应归一化**：本 provider 同时接受标准 Anthropic 形状（`web_search_tool_result`
+ * 条目 + citation 摘录）和 Kaon/Bedrock 形状（没有结果块，只有 citation），
+ * 并且在「模型只是申请调用客户端工具」时给出可操作的报错，而不是假装搜到了东西。
+ *
+ * 配置按**每次搜索**从注入的读取器取，因此 `web-search-kaon` 命名空间的热更新
+ * （端点/模型/次数上限）立即生效，无需重挂插件。
+ *
+ * `available()` 只做本地判断（key 解析器存在、URL 可解析、上限为正整数），
+ * 不发网络请求（seam 的硬要求）。
+ *
+ * @module web-all/host/services/web-search-kaon
+ */
+import { WebSearchError, WEB_SEARCH_KAON_PROVIDER_ID, } from "./contracts.js";
+/** 归因头；与 provider 行为一起演进。 */
+const USER_AGENT = 'dsh-web-all/web-search-kaon';
+/** 收集每个 URL 的 citation 摘录（首次出现优先）；标准形状下它才是 snippet 来源。 */
+export function citationSnippets(blocks) {
+    const map = new Map();
+    for (const block of blocks) {
+        if (block.type !== 'text')
+            continue;
+        for (const cite of block.citations ?? []) {
+            const url = cite.url ?? '';
+            const text = cite.cited_text ?? '';
+            if (url !== '' && text !== '' && !map.has(url))
+                map.set(url, text);
+        }
+    }
+    return map;
+}
+/** 读出 `web_search_tool_result` 自带的错误（载荷是对象而非数组时）。 */
+function resultErrorOf(block) {
+    const payload = block.content;
+    if (payload === null || typeof payload !== 'object' || Array.isArray(payload))
+        return undefined;
+    const record = payload;
+    if (record.error_code === undefined || record.error_code === null)
+        return undefined;
+    return `${String(record.type ?? 'web_search_tool_result_error')}: ${String(record.error_code)}`;
+}
+/**
+ * 把两种 Anthropic 兼容响应形状统一成 seam 的 `sources[]`。
+ *
+ * 顺序：先走标准结果块（带 `page_age` 与条目级字段），拿不到任何条目时再回落到
+ * citation —— Kaon 的 Claude 路由永远走第二条分支；两条分支都用同一张 citation
+ * 摘录表补 `snippet`，按 URL 去重（`max_uses > 1` 时同一 URL 可能多次出现）。
+ *
+ * @param response - 解析后的 Messages 响应体。
+ * @returns 归一化结果；`searches`/`clientToolUse`/`resultError` 供诊断使用。
+ */
+export function mapSearchResponse(response) {
+    const blocks = response.content ?? [];
+    const searches = response.usage?.server_tool_use?.web_search_requests
+        ?? blocks.filter(block => block.type === 'server_tool_use' && block.name === 'web_search').length;
+    const clientToolUse = blocks.some(block => block.type === 'tool_use' && block.name === 'web_search');
+    const resultError = blocks.filter(block => block.type === 'web_search_tool_result')
+        .map(resultErrorOf)
+        .find(error => error !== undefined);
+    const snippets = citationSnippets(blocks);
+    const sources = [];
+    const seen = new Set();
+    const add = (url, title, snippet, publishedAt) => {
+        const value = url ?? '';
+        if (value === '' || seen.has(value))
+            return;
+        seen.add(value);
+        sources.push({
+            url: value,
+            ...title !== null && title !== undefined && title !== '' ? { title } : {},
+            ...snippet !== null && snippet !== undefined && snippet !== '' ? { snippet } : {},
+            ...publishedAt !== null && publishedAt !== undefined && publishedAt !== '' ? { publishedAt } : {},
+        });
+    };
+    for (const block of blocks) {
+        if (block.type !== 'web_search_tool_result' || !Array.isArray(block.content))
+            continue;
+        for (const item of block.content) {
+            if (item?.type !== 'web_search_result')
+                continue;
+            const url = item.url ?? '';
+            add(url, item.title, snippets.get(url), item.page_age);
+        }
+    }
+    if (sources.length === 0) {
+        for (const block of blocks) {
+            if (block.type !== 'text')
+                continue;
+            for (const cite of block.citations ?? [])
+                add(cite.url, cite.title, cite.cited_text);
+        }
+    }
+    let content;
+    for (const block of blocks) {
+        if (block.type !== 'text')
+            continue;
+        const text = block.text ?? '';
+        if (text.length > (content?.length ?? 0))
+            content = text;
+    }
+    return {
+        sources,
+        ...content !== undefined ? { content } : {},
+        searches,
+        clientToolUse,
+        ...resultError !== undefined ? { resultError } : {},
+    };
+}
+/** 去掉尾斜杠，避免 `baseURL` 以 `/` 结尾时拼出 `//messages`。 */
+function trimTrailingSlash(value) {
+    return value.endsWith('/') ? value.replace(/\/+$/u, '') : value;
+}
+/** 端点与配置引导：把「这是配置问题、改哪里」写进错误里。 */
+function endpointHint(endpoint) {
+    return `\n\nThe web search request used endpoint ${JSON.stringify(endpoint)}. Search endpoint configuration is separate from chat: guide the user to the web-search-kaon settings namespace (Settings > Plugins > Plugin configuration, the web-all entry) or to web-search-kaon.baseURL in the profile cordis.patch.yml. Only the user should change the endpoint.`;
+}
+/** 端点没执行搜索时的可操作报错：区分「模型申请客户端工具」与「搜了但没结果」。 */
+function noResultError(mapped, options) {
+    if (mapped.clientToolUse) {
+        return new WebSearchError(`The endpoint returned a client-side tool_use(web_search) instead of executing the search itself, so model ${JSON.stringify(options.model)} `
+            + 'has no web search results. Native server-side web_search_20250305 is an Anthropic-model feature: on Kaon Router pick a kaon/claude-* model '
+            + '(kaon/deepseek-* and kaon/gemini-* reply with a client tool call). The provider was left pointed at this endpoint on purpose; only the user should change it.', 'WEB_PROVIDER_ERROR');
+    }
+    if (mapped.searches === 0) {
+        return new WebSearchError(`The endpoint executed no server-side web search for model ${JSON.stringify(options.model)} and returned no citeable sources; `
+            + 'the request may not have triggered native web search.', 'WEB_PROVIDER_ERROR');
+    }
+    return new WebSearchError(`The endpoint executed ${mapped.searches} server-side web search(es) but returned no citeable sources.`, 'WEB_PROVIDER_ERROR');
+}
+/** 用 Anthropic 兼容 Messages 端点做检索的 provider。 */
+export class KaonSearchProvider {
+    id = WEB_SEARCH_KAON_PROVIDER_ID;
+    resolveOptions;
+    /**
+     * @param resolveOptions - 下一次操作的选项；thunk 而非快照，命名空间热更新因此
+     * 每次搜索都生效，而不必重注册 provider（重注册会让 seam 的选择对用户可见地抖动）。
+     */
+    constructor(resolveOptions) {
+        this.resolveOptions = resolveOptions;
+    }
+    available() {
+        const options = this.resolveOptions();
+        return ((options.apiKey?.length ?? 0) > 0 || options.resolveApiKey !== undefined)
+            && URL.canParse(options.baseURL)
+            && Number.isInteger(options.maxTokens) && options.maxTokens > 0
+            && Number.isInteger(options.maxUses) && options.maxUses > 0;
+    }
+    async search(request, signal) {
+        const options = this.resolveOptions();
+        // 读经函数而非直接比属性：TS 会把 `signal?.aborted === true` 早退后的属性
+        // 窄化成 false，后续再判同一属性就成了「无重叠比较」。
+        const isAborted = () => signal?.aborted === true;
+        const endpoint = `${trimTrailingSlash(options.baseURL)}/messages`;
+        const apiKey = await this.apiKey(options, signal);
+        if (isAborted())
+            throw abortedError();
+        const body = {
+            model: options.model,
+            max_tokens: options.maxTokens,
+            messages: [{
+                    role: 'user',
+                    content: [{ type: 'text', text: `Perform a web search for the query: ${request.query}` }],
+                }],
+            tools: [{ type: 'web_search_20250305', name: 'web_search', max_uses: options.maxUses }],
+        };
+        const timeout = AbortSignal.timeout(options.timeoutMs);
+        const composed = signal === undefined ? timeout : AbortSignal.any([signal, timeout]);
+        const doFetch = options.fetchImpl ?? fetch;
+        let response;
+        try {
+            response = await doFetch(endpoint, {
+                method: 'POST',
+                redirect: 'error',
+                headers: {
+                    'x-api-key': apiKey,
+                    'authorization': `Bearer ${apiKey}`,
+                    'anthropic-version': options.apiVersion,
+                    'content-type': 'application/json',
+                    'accept': 'application/json',
+                    'user-agent': USER_AGENT,
+                },
+                body: JSON.stringify(body),
+                signal: composed,
+            });
+        }
+        catch (error) {
+            if (isAborted())
+                throw abortedError();
+            if (timeout.aborted)
+                throw new WebSearchError(`Web search timed out after ${options.timeoutMs} ms at ${JSON.stringify(endpoint)}.`, 'WEB_PROVIDER_ERROR');
+            throw new WebSearchError(`Web search request failed: ${String(error)}.${endpointHint(endpoint)}`, 'WEB_PROVIDER_ERROR');
+        }
+        if (!response.ok) {
+            let detail = '';
+            try {
+                const parsed = await response.json();
+                detail = typeof parsed.error === 'string' ? parsed.error : parsed.error?.message ?? parsed.message ?? '';
+            }
+            catch {
+                // 非 JSON 错误体：状态码已经足够定位。
+            }
+            const message = `Web search endpoint error (HTTP ${response.status})${detail === '' ? '' : `: ${detail}`}`;
+            throw new WebSearchError(`${message}${endpointHint(endpoint)}`, 'WEB_PROVIDER_ERROR');
+        }
+        let mapped;
+        try {
+            mapped = mapSearchResponse(await response.json());
+        }
+        catch (error) {
+            throw new WebSearchError(`Web search returned an unprocessable response body: ${String(error)}`, 'WEB_PROVIDER_ERROR');
+        }
+        if (mapped.resultError !== undefined) {
+            throw new WebSearchError(`The endpoint's web search failed: ${mapped.resultError}.`, 'WEB_PROVIDER_ERROR');
+        }
+        if (mapped.sources.length === 0)
+            throw noResultError(mapped, options);
+        return {
+            ...options.includeAnswer && mapped.content !== undefined && mapped.content !== '' ? { content: mapped.content } : {},
+            sources: mapped.sources,
+            truncated: false,
+        };
+    }
+    /** 解析一次操作的 key：字面 key → 凭据服务 → 环境变量。 */
+    async apiKey(options, signal) {
+        if (signal?.aborted === true)
+            throw abortedError();
+        if (options.apiKey !== undefined && options.apiKey.length > 0)
+            return options.apiKey;
+        const resolved = options.resolveApiKey === undefined ? undefined : await options.resolveApiKey();
+        if (resolved !== undefined && resolved.length > 0)
+            return resolved;
+        const ref = options.apiKeyEnv ?? '';
+        throw new WebSearchError(`Web search has no API key for "${ref === '' ? 'the configured credential reference' : ref}"; store it through the credentials service, `
+            + 'export it in the launching environment, or set a literal "apiKey" in the web-search-kaon config.', 'WEB_PROVIDER_CREDENTIAL_MISSING');
+    }
+}
+/** 调用方取消：与原生 provider 的 `WEB_ABORTED` 对齐。 */
+function abortedError() {
+    return new WebSearchError('Web search aborted', 'WEB_ABORTED');
+}

package/lib/types/host/services/worktree/git-runner.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Shared host git subprocess plumbing: the run result shape, the runner seam,
+ * the collected-output cap, and the production runner over the subprocess
+ * service. Packages receive this file as a generated copy via
+ * scripts/sync-shared.mjs; edit the shared source and re-run the sync instead
+ * of editing a copy.
+ *
+ * The context shape is declared structurally so this module stays
+ * self-contained (shared/ has no cordis dependency): any context whose
+ * `subprocess` satisfies SubprocessServiceLike works, which the plugin
+ * contexts do.
+ * @module dsh-web-shared/host/git-runner
+ */
+/** One finished git invocation. */
+export interface GitRunResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+}
+/** The spawn seam the service runs git through (subprocess service in production). */
+export interface GitRunner {
+    run(argv: readonly string[], cwd: string, signal?: AbortSignal): Promise<GitRunResult>;
+}
+/** Collected-output cap for one git command. */
+export declare const OUTPUT_CAP_BYTES: number;
+/** The subprocess service surface this runner consumes (structural). */
+export interface SubprocessServiceLike {
+    spawn(spec: {
+        argv: readonly string[];
+        cwd: string;
+        stdio: {
+            stdin: 'ignore';
+            stdout: {
+                maxBytes: number;
+            };
+            stderr: {
+                maxBytes: number;
+            };
+        };
+        graceMs: number;
+        signal?: AbortSignal;
+    }): {
+        done: Promise<{
+            exitCode: number | null;
+        }>;
+        collected: {
+            stdout?: {
+                readFrom(offset: number): {
+                    text: string;
+                };
+            };
+            stderr?: {
+                readFrom(offset: number): {
+                    text: string;
+                };
+            };
+        };
+    };
+}
+/** Per-package knobs for the shared production runner. */
+export interface GitRunnerOptions {
+    /** Build the full spawn argv from the git args (default ['git', ...argv]). */
+    spawnArgv?: (argv: readonly string[]) => readonly string[];
+    /** degrade turns spawn/run failures into exitCode 127 results instead of throwing. */
+    failureMode?: 'throw' | 'degrade';
+    /** console.error tag for degrade mode. */
+    errorTag?: string;
+}
+/**
+ * Production runner over the subprocess service: one managed child per
+ * command, bounded collect on both streams. A caller-owned AbortSignal reaches
+ * the subprocess tree and remains authoritative even in degrade mode. Degrade
+ * mode keeps the SCM tab showing the friendly "not a git repository" state
+ * instead of a bare 400 when git is missing or the subprocess service fails.
+ * @param ctx - context carrying the subprocess service.
+ * @param options - per-package behavior knobs.
+ * @returns the runner.
+ */
+export declare function subprocessRunner(ctx: {
+    subprocess: SubprocessServiceLike;
+}, options?: GitRunnerOptions): GitRunner;
+//# sourceMappingURL=git-runner.d.ts.map

package/lib/types/host/services/worktree/git-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-runner.d.ts","sourceRoot":"","sources":["../../../../../src/host/services/worktree/git-runner.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;GAYG;AAEH,mCAAmC;AACnC,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf;AAED,sFAAsF;AACtF,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;CACvF;AAED,gDAAgD;AAChD,eAAO,MAAM,gBAAgB,QAAU,CAAA;AAEvC,wEAAwE;AACxE,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,IAAI,EAAE;QACV,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;QACvB,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE;YACL,KAAK,EAAE,QAAQ,CAAA;YACf,MAAM,EAAE;gBAAE,QAAQ,EAAE,MAAM,CAAA;aAAE,CAAA;YAC5B,MAAM,EAAE;gBAAE,QAAQ,EAAE,MAAM,CAAA;aAAE,CAAA;SAC7B,CAAA;QACD,OAAO,EAAE,MAAM,CAAA;QACf,MAAM,CAAC,EAAE,WAAW,CAAA;KACrB,GAAG;QACF,IAAI,EAAE,OAAO,CAAC;YAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;SAAE,CAAC,CAAA;QAC1C,SAAS,EAAE;YACT,MAAM,CAAC,EAAE;gBAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG;oBAAE,IAAI,EAAE,MAAM,CAAA;iBAAE,CAAA;aAAE,CAAA;YACvD,MAAM,CAAC,EAAE;gBAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG;oBAAE,IAAI,EAAE,MAAM,CAAA;iBAAE,CAAA;aAAE,CAAA;SACxD,CAAA;KACF,CAAA;CACF;AAED,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,SAAS,MAAM,EAAE,CAAA;IAC1D,sFAAsF;IACtF,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACjC,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE;IAAE,UAAU,EAAE,qBAAqB,CAAA;CAAE,EAAE,OAAO,GAAE,gBAAqB,GAAG,SAAS,CAoDtH"}

package/lib/types/host/services/worktree/git-runner.js

@@ -0,0 +1,81 @@
+// Generated by scripts/sync-shared.mjs from shared/host/git-runner.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Shared host git subprocess plumbing: the run result shape, the runner seam,
+ * the collected-output cap, and the production runner over the subprocess
+ * service. Packages receive this file as a generated copy via
+ * scripts/sync-shared.mjs; edit the shared source and re-run the sync instead
+ * of editing a copy.
+ *
+ * The context shape is declared structurally so this module stays
+ * self-contained (shared/ has no cordis dependency): any context whose
+ * `subprocess` satisfies SubprocessServiceLike works, which the plugin
+ * contexts do.
+ * @module dsh-web-shared/host/git-runner
+ */
+/** Collected-output cap for one git command. */
+export const OUTPUT_CAP_BYTES = 1 << 20;
+/**
+ * Production runner over the subprocess service: one managed child per
+ * command, bounded collect on both streams. A caller-owned AbortSignal reaches
+ * the subprocess tree and remains authoritative even in degrade mode. Degrade
+ * mode keeps the SCM tab showing the friendly "not a git repository" state
+ * instead of a bare 400 when git is missing or the subprocess service fails.
+ * @param ctx - context carrying the subprocess service.
+ * @param options - per-package behavior knobs.
+ * @returns the runner.
+ */
+export function subprocessRunner(ctx, options = {}) {
+    const spawnArgv = options.spawnArgv ?? ((argv) => ['git', ...argv]);
+    const degrade = options.failureMode === 'degrade';
+    const errorTag = options.errorTag ?? 'git';
+    const failure = (prefix, error) => ({
+        exitCode: 127,
+        stdout: '',
+        stderr: prefix + (error instanceof Error ? error.message : String(error)),
+    });
+    return {
+        async run(argv, cwd, signal) {
+            signal?.throwIfAborted();
+            const spec = {
+                argv: spawnArgv(argv),
+                cwd,
+                stdio: {
+                    stdin: 'ignore',
+                    stdout: { maxBytes: OUTPUT_CAP_BYTES },
+                    stderr: { maxBytes: OUTPUT_CAP_BYTES },
+                },
+                graceMs: 10_000,
+                signal,
+            };
+            if (degrade) {
+                let handle;
+                try {
+                    handle = ctx.subprocess.spawn(spec);
+                }
+                catch (error) {
+                    signal?.throwIfAborted();
+                    console.error('[' + errorTag + '] git spawn failed:', error);
+                    return failure('git: spawn failed: ', error);
+                }
+                try {
+                    const outcome = await handle.done;
+                    signal?.throwIfAborted();
+                    const stdout = handle.collected.stdout?.readFrom(0).text ?? '';
+                    const stderr = handle.collected.stderr?.readFrom(0).text ?? '';
+                    return { exitCode: outcome.exitCode, stdout, stderr };
+                }
+                catch (error) {
+                    signal?.throwIfAborted();
+                    console.error('[' + errorTag + '] git run failed:', error);
+                    return failure('git: run failed: ', error);
+                }
+            }
+            const handle = ctx.subprocess.spawn(spec);
+            const outcome = await handle.done;
+            signal?.throwIfAborted();
+            const stdout = handle.collected.stdout?.readFrom(0).text ?? '';
+            const stderr = handle.collected.stderr?.readFrom(0).text ?? '';
+            return { exitCode: outcome.exitCode, stdout, stderr };
+        },
+    };
+}