@huanlin/dsh-plugin-interpreters 0.1.0

package/lib/gateway.js

@@ -0,0 +1,163 @@
+/**
+ * gateway.ts — host-side HTTP gateway exposing the `interpreters` config to
+ * the browser through a self-hosted `/interpreters/api` route.
+ *
+ * The DSH typertGateway `/api` RPC dispatch was the original channel
+ * (TypertRemoteService + @Remote), but the host's SRC discovery
+ * (ctx.reflect.props enumeration) is not claiming plugin-owned service
+ * endpoints on the current dsh snapshot. The self-hosted HTTP route
+ * mirrors the better-sidebar pattern: `ctx.webServer.register` claims a
+ * prefix route, the handler reads/writes the settings seam in-process
+ * (no wire-layer allowlist gate), and the browser reaches it through
+ * `fetch('/interpreters/api/<method>')`.
+ *
+ * Route shape:
+ *   POST /interpreters/api/get  → { ok: true, value: { config: ResolvedConfig } }
+ *   POST /interpreters/api/set  body: { patch: Partial<Config> }
+ *                                → { ok: true, value: { config: ResolvedConfig } }
+ * Errors carry { ok: false, error: { code, message } }.
+ *
+ * @module dsh-interpreters/gateway
+ */
+import { resolveConfig, } from './config.js';
+import { SETTINGS_NAMESPACE, } from './settings.js';
+/** HTTP route prefix owning every interpreters API request. */
+const API_PREFIX = '/interpreters/api';
+/** Config keys the `set` endpoint accepts (allow-list; unknown keys are dropped). */
+const ALLOWED_KEYS = new Set(['pythonPath', 'nodePath', 'timeoutMs']);
+/**
+ * Register the `/interpreters/api` HTTP route on the host's web server.
+ *
+ * The route reads/writes the `interpreters` settings namespace in-process
+ * through the bridge + `ctx.settings`. The settings service is optional:
+ * when absent, `get` degrades to the entry source and `set` returns a
+ * clear error.
+ * @param ctx - host context carrying `webServer`.
+ * @param bridge - the settings bridge the route reads through.
+ */
+export function registerHttpGateway(ctx, bridge) {
+    let settings;
+    ctx.inject(['settings'], (sctx) => {
+        settings = sctx.settings;
+        return () => { settings = undefined; };
+    });
+    ctx.effect(() => ctx.webServer.register({
+        kind: 'prefix',
+        path: API_PREFIX,
+        handler: async (req, res) => {
+            if (req.method !== 'POST') {
+                writeJson(res, 405, envelopeError('method-not-allowed', 'POST only'));
+                return;
+            }
+            const pathname = new URL(req.url ?? '/', 'http://dsh.internal').pathname;
+            const method = pathname.startsWith(`${API_PREFIX}/`)
+                ? pathname.slice(`${API_PREFIX}/`.length)
+                : undefined;
+            if (method === undefined || method.includes('/')) {
+                writeJson(res, 404, envelopeError('not-found', 'unknown interpreters API method'));
+                return;
+            }
+            try {
+                const body = await readJsonBody(req);
+                if (method === 'get') {
+                    const config = resolveConfig(bridge.source());
+                    writeJson(res, 200, envelopeOk({ config }));
+                }
+                else if (method === 'set') {
+                    const result = await handleSet(body, settings, bridge);
+                    writeJson(res, 200, envelopeOk(result));
+                }
+                else {
+                    writeJson(res, 404, envelopeError('not-found', `unknown interpreters API method "${method}"`));
+                }
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                writeJson(res, 500, envelopeError('internal', message));
+            }
+        },
+    }), 'dsh-interpreters: /interpreters/api routes');
+}
+/**
+ * Handle the `set` method: validate the patch, write the user layer, return
+ * the new resolved config.
+ * @param body - the parsed JSON body from the request.
+ * @param settings - the live settings service (undefined when unavailable).
+ * @param bridge - the settings bridge for reading the source.
+ * @returns the new resolved config view.
+ * @throws when the settings service is unavailable.
+ */
+export async function handleSet(body, settings, bridge) {
+    const patch = extractPatch(body);
+    if (Object.keys(patch).length === 0) {
+        return { config: resolveConfig(bridge.source()) };
+    }
+    if (settings === undefined) {
+        throw new Error('interpreters: settings service is unavailable — configuration cannot be written');
+    }
+    await settings.update(SETTINGS_NAMESPACE, patch);
+    return { config: resolveConfig(bridge.source()) };
+}
+/**
+ * Extract and validate the patch from the request body.
+ *
+ * JSON wire boundary: null = "delete" (filtered), undefined never crosses
+ * JSON. Unknown keys are dropped (the settings service is non-strict and
+ * would otherwise store them). Light type guards constrain paths to
+ * strings and timeout to a finite number.
+ * @param body - the parsed JSON body.
+ * @returns the normalized patch (only known, well-typed keys).
+ */
+export function extractPatch(body) {
+    if (!isObject(body))
+        return {};
+    const raw = Reflect.get(body, 'patch');
+    if (!isObject(raw))
+        return {};
+    const normalized = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!ALLOWED_KEYS.has(key))
+            continue;
+        if (value === null || value === undefined)
+            continue;
+        if (key === 'timeoutMs') {
+            if (typeof value !== 'number' || !Number.isFinite(value))
+                continue;
+        }
+        else {
+            if (typeof value !== 'string')
+                continue;
+        }
+        normalized[key] = value;
+    }
+    return normalized;
+}
+/** Read and parse a JSON body from a node:http request. */
+async function readJsonBody(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    const text = Buffer.concat(chunks).toString('utf8');
+    if (text === '')
+        return {};
+    return JSON.parse(text);
+}
+/** Write a JSON response envelope. */
+function writeJson(res, status, body) {
+    const json = JSON.stringify(body);
+    res.writeHead(status, { 'content-type': 'application/json' });
+    res.end(json);
+}
+/** Build a success envelope. */
+function envelopeOk(value) {
+    return { ok: true, value };
+}
+/** Build an error envelope. */
+function envelopeError(code, message) {
+    return { ok: false, error: { code, message } };
+}
+/** Narrow unknown to a non-null object. */
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}

package/lib/index.js

@@ -0,0 +1,58 @@
+/**
+ * index.ts — dsh-interpreters host plugin entry.
+ *
+ * Registers two model-facing tools (`run_python`, `run_node`) whose
+ * descriptions embed the configured interpreter paths. The paths persist
+ * through the settings seam under the `interpreters` namespace in
+ * `$DSH_HOME/settings.yaml`; runtime edits dispose and re-register the tools
+ * so the model immediately sees the updated path. The browser reaches the
+ * same namespace through a self-hosted `/interpreters/api` HTTP route
+ * (the DSH settings RPC domain only serves allowlisted namespaces to
+ * configuration clients, so this plugin exposes its own route through
+ * `ctx.webServer.register`, bypassing the wire-layer allowlist by calling
+ * the settings seam in-process).
+ *
+ * Architecture:
+ *   - `installInterpretersSettings` registers the namespace and exposes a
+ *     `source()` thunk + `onChange()` subscription.
+ *   - `registerHttpGateway` claims `/interpreters/api/get|set` and
+ *     reads/writes through the bridge + `ctx.settings` in-process.
+ *   - The tool registration is re-run on every `bridge.onChange` notification
+ *     so the model-visible description tracks the live interpreter path.
+ *   - Headless assemblies without a settings provider fall back to the
+ *     composition config (no persistence, no live reload, the `set`
+ *     endpoint returns a clear "settings service unavailable" error).
+ *
+ * @module @huanlin/dsh-plugin-interpreters
+ */
+import { resolveConfig } from './config.js';
+import { registerHttpGateway } from './gateway.js';
+import { installInterpretersSettings } from './settings.js';
+import { registerTools } from './tools.js';
+export { Config, resolveConfig } from './config.js';
+export { registerHttpGateway } from './gateway.js';
+export { SETTINGS_NAMESPACE } from './settings.js';
+export const name = 'dsh-interpreters';
+export const inject = ['tools', 'webServer'];
+/**
+ * Plugin body: register tools with the composition config, then swap to
+ * settings-resolved config when the settings service mounts, and expose the
+ * config through a `/interpreters/api/get|set` HTTP route.
+ * @param ctx - host context carrying `tools` and `webServer`.
+ * @param config - resolved composition config (seed).
+ */
+export function apply(ctx, config = {}) {
+    ctx.logger('dsh-interpreters').info('apply() called, config=', JSON.stringify(config));
+    const bridge = installInterpretersSettings(ctx, config);
+    let disposeTools = registerTools(ctx, resolveConfig(bridge.source()));
+    // Live re-register on every committed settings change so the model-visible
+    // tool description tracks the live interpreter path.
+    bridge.onChange(() => {
+        disposeTools?.();
+        disposeTools = registerTools(ctx, resolveConfig(bridge.source()));
+    });
+    // Register the HTTP gateway; the /interpreters/api route claims get/set.
+    registerHttpGateway(ctx, bridge);
+    ctx.logger('dsh-interpreters').info('http gateway registered at /interpreters/api');
+    ctx.effect(() => () => { disposeTools?.(); }, 'dsh-interpreters: cleanup');
+}

package/lib/runner.js

@@ -0,0 +1,120 @@
+/**
+ * runner.ts — subprocess execution for `run_python` / `run_node` tools.
+ *
+ * Spawns the interpreter with `-` (read code from stdin), writes the code
+ * to stdin, and collects stdout/stderr with a 1 MB cap per stream.
+ * Honours `AbortSignal` and a timeout — both kill the process and report
+ * the outcome in the canonical result (C5: non-ideal states are values,
+ * not thrown errors).
+ *
+ * @module dsh-interpreters/runner
+ */
+import { spawn } from 'node:child_process';
+/** Maximum captured bytes per stream (stdout / stderr). */
+const MAX_OUTPUT_BYTES = 1024 * 1024;
+/**
+ * Execute `code` by piping it into `executable -` (stdin).
+ *
+ * @param executable - interpreter path (e.g. `python`, `node`, or an absolute path).
+ * @param code - source code to pipe via stdin.
+ * @param cwd - optional working directory.
+ * @param timeoutMs - wall-clock budget; the process is killed with SIGKILL on expiry.
+ * @param signal - caller-owned abort signal; aborting kills the process.
+ * @returns a {@link RunResult} describing the outcome.
+ */
+export function runCode(executable, code, cwd, timeoutMs, signal) {
+    return new Promise((resolve) => {
+        const start = Date.now();
+        if (signal.aborted) {
+            resolve({ ok: false, exit_code: -1, stdout: '', stderr: '', duration_ms: 0, timed_out: false, cancelled: true });
+            return;
+        }
+        let child;
+        try {
+            child = spawn(executable, ['-'], { cwd, windowsHide: true });
+        }
+        catch (error) {
+            resolve({
+                ok: false,
+                exit_code: -1,
+                stdout: '',
+                stderr: `Failed to spawn "${executable}": ${String(error)}`,
+                duration_ms: Date.now() - start,
+                timed_out: false,
+                cancelled: false,
+            });
+            return;
+        }
+        let stdout = '';
+        let stderr = '';
+        let stdoutCapped = false;
+        let stderrCapped = false;
+        let timedOut = false;
+        const append = (buf, target) => {
+            const str = buf.toString('utf8');
+            if (target === 'stdout') {
+                if (stdout.length + str.length > MAX_OUTPUT_BYTES && !stdoutCapped) {
+                    stdout += str.slice(0, MAX_OUTPUT_BYTES - stdout.length);
+                    stdoutCapped = true;
+                }
+                else if (!stdoutCapped) {
+                    stdout += str;
+                }
+            }
+            else {
+                if (stderr.length + str.length > MAX_OUTPUT_BYTES && !stderrCapped) {
+                    stderr += str.slice(0, MAX_OUTPUT_BYTES - stderr.length);
+                    stderrCapped = true;
+                }
+                else if (!stderrCapped) {
+                    stderr += str;
+                }
+            }
+        };
+        child.stdout?.on('data', (d) => append(d, 'stdout'));
+        child.stderr?.on('data', (d) => append(d, 'stderr'));
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGKILL');
+        }, timeoutMs);
+        const onAbort = () => {
+            clearTimeout(timer);
+            child.kill('SIGKILL');
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        const finish = (exitCode) => {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', onAbort);
+            if (stdoutCapped)
+                stdout += '\n[stdout truncated at 1 MB]';
+            if (stderrCapped)
+                stderr += '\n[stderr truncated at 1 MB]';
+            resolve({
+                ok: exitCode === 0 && !timedOut && !signal.aborted,
+                exit_code: exitCode ?? -1,
+                stdout,
+                stderr,
+                duration_ms: Date.now() - start,
+                timed_out: timedOut,
+                cancelled: signal.aborted,
+            });
+        };
+        child.on('error', (error) => {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', onAbort);
+            resolve({
+                ok: false,
+                exit_code: -1,
+                stdout,
+                stderr: stderr + (stderr !== '' ? '\n' : '') + String(error),
+                duration_ms: Date.now() - start,
+                timed_out: false,
+                cancelled: signal.aborted,
+            });
+        });
+        child.on('close', (code) => finish(code));
+        child.stdin?.on('error', () => { });
+        child.stdin?.write(code, 'utf8');
+        child.stdin?.end();
+    });
+}

package/lib/settings.js

@@ -0,0 +1,83 @@
+/**
+ * settings.ts — host-side bridge between the `interpreters` settings namespace
+ * and the plugin's other halves (tool registration + RPC gateway).
+ *
+ * The composition `Config` (cordis.patch.yml) is the first-boot seed; once the
+ * `ctx.settings` service mounts, the user-editable layer takes over and live
+ * re-registration follows every committed change. Headless assemblies without
+ * a settings provider fall back to the composition config (no persistence, no
+ * live reload).
+ *
+ * The bridge pattern mirrors `dsh-advisor/src/settings.ts`: a `source()` thunk
+ * the gateway reads in-process, plus an `onChange()` subscription the host
+ * entry uses to re-register the tools. This avoids any wire-layer allowlist
+ * (the DSH settings RPC domain only serves a fixed namespace set to browser
+ * configuration clients; the gateway bypasses it through `/api`).
+ *
+ * @module dsh-interpreters/settings
+ */
+import { settingsNamespace } from '@deepseek-ai/dsh-settings';
+import { Config } from './config.js';
+/** Settings namespace under which interpreter paths persist. */
+export const SETTINGS_NAMESPACE = settingsNamespace('interpreters');
+/**
+ * Mirror of the dsh-settings internal `isUnloading` guard. The cordis const
+ * enum for fiber state is erased at compile time, so the literal states are
+ * matched numerically: 4 = DISPOSED, 5 = UNLOADING.
+ */
+function isUnloading(ctx) {
+    const state = ctx.fiber?.state;
+    return state === 4 || state === 5;
+}
+/**
+ * Install the `interpreters` settings namespace and return the bridge.
+ *
+ * The settings service is reached through `ctx.inject(['settings'], ...)` so a
+ * composition without a settings provider still loads the plugin (entry-source
+ * fallback, no persistence). Multi-fiber dedupe is handled by catching the
+ * `"already registered"` rejection — host composition may mount several
+ * concurrent fibers of this plugin, and only the first registration owns the
+ * namespace.
+ * @param ctx - host context.
+ * @param entry - composition-layer config (cordis.patch.yml seed).
+ * @returns the bridge the gateway and tool re-registration consume.
+ */
+export function installInterpretersSettings(ctx, entry) {
+    const listeners = new Set();
+    let source = () => entry;
+    const notify = () => {
+        for (const listener of [...listeners])
+            listener();
+    };
+    ctx.inject(['settings'], (sctx) => {
+        let scope;
+        try {
+            scope = sctx.settings.register(SETTINGS_NAMESPACE, Config, { base: entry });
+        }
+        catch (error) {
+            // Multi-fiber dedupe: the first registration owns the namespace; later
+            // fibers stay on the entry source and emit no notifications of their own.
+            if (!(error instanceof Error) || !error.message.includes('already registered'))
+                throw error;
+            ctx.logger('dsh-interpreters').debug('settings namespace already registered — entry-source fallback');
+            return;
+        }
+        source = () => scope.get();
+        sctx.effect(() => () => {
+            if (isUnloading(ctx))
+                return;
+            source = () => entry;
+            notify();
+        });
+        notify();
+        scope.watch(() => {
+            if (isUnloading(ctx))
+                return;
+            notify();
+        });
+    });
+    return {
+        source: () => source(),
+        onChange: (cb) => { listeners.add(cb); },
+    };
+}

package/lib/tools.js

@@ -0,0 +1,110 @@
+/**
+ * tools.ts — `run_python` and `run_node` model-facing tools.
+ *
+ * Conventions (per plugin-development-guide.md §3):
+ *   C4 — execute returns a canonical JSON value; render is a separate pure projection.
+ *   C5 — timeout and cancellation are non-ideal business outcomes, represented in
+ *        the value (timed_out / cancelled) rather than thrown.
+ *   C6 — exec.signal is forwarded to the subprocess via runCode().
+ *   C10 — no UI-specific formats in the canonical value.
+ *
+ * The tool `description` is computed from the resolved config at registration
+ * time so the model sees the interpreter path. Settings changes dispose the
+ * old registration and re-register with the fresh description (host index.ts).
+ *
+ * @module dsh-interpreters/tools
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { runCode } from './runner.js';
+/**
+ * Build the model-visible description for `run_python`, embedding the
+ * configured interpreter path so the model knows exactly which executable
+ * will be invoked.
+ */
+export function buildPythonDescription(cfg) {
+    return 'Execute Python code and return stdout, stderr, and exit code. '
+        + 'Code is passed via stdin (`' + cfg.pythonPath + ' -`), so there is no '
+        + 'command-line length limit. '
+        + 'The Python interpreter is located at: ' + cfg.pythonPath + '\n'
+        + 'Use the optional `cwd` parameter to set the working directory.';
+}
+/**
+ * Build the model-visible description for `run_node`, embedding the
+ * configured interpreter path.
+ */
+export function buildNodeDescription(cfg) {
+    return 'Execute Node.js code and return stdout, stderr, and exit code. '
+        + 'Code is passed via stdin (`' + cfg.nodePath + ' -`), so there is no '
+        + 'command-line length limit. '
+        + 'The Node.js interpreter is located at: ' + cfg.nodePath + '\n'
+        + 'Use the optional `cwd` parameter to set the working directory.';
+}
+function textRender(fn) {
+    return (_args, value) => [{ type: 'text', text: fn(value) }];
+}
+export function renderRunCodeOutput(value) {
+    const lines = [];
+    lines.push(`Exit code: ${value.exit_code} (${value.duration_ms}ms)`);
+    if (value.timed_out)
+        lines.push('Process was killed after exceeding the timeout.');
+    if (value.cancelled)
+        lines.push('Process was cancelled by an abort signal.');
+    if (value.stdout)
+        lines.push(`--- stdout ---\n${value.stdout}`);
+    if (value.stderr)
+        lines.push(`--- stderr ---\n${value.stderr}`);
+    return lines.join('\n');
+}
+const parametersSchema = {
+    code: { type: 'string', required: true, description: 'The code to execute.' },
+    cwd: { type: 'string', description: 'Optional working directory for the process.' },
+};
+const outputSchema = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        ok: { type: 'boolean', required: true, description: 'True if the process exited with code 0.' },
+        exit_code: { type: 'integer', required: true, description: 'Process exit code (-1 if the process failed to start).' },
+        stdout: { type: 'string', required: true, description: 'Captured stdout output.' },
+        stderr: { type: 'string', required: true, description: 'Captured stderr output.' },
+        duration_ms: { type: 'integer', required: true, description: 'Wall-clock execution time in milliseconds.' },
+        timed_out: { type: 'boolean', required: true, description: 'True if the process was killed due to timeout.' },
+        cancelled: { type: 'boolean', required: true, description: 'True if the process was killed due to an abort signal.' },
+    },
+};
+/**
+ * Register `run_python` and `run_node` tools with descriptions that embed
+ * the interpreter paths from `cfg`. Returns a disposer that unregisters
+ * both tools — call it before re-registering with a fresh config.
+ */
+export function registerTools(ctx, cfg) {
+    const disposers = [];
+    disposers.push(ctx.tools.register(defineTool({
+        name: 'run_python',
+        description: buildPythonDescription(cfg),
+        parameters: parametersSchema,
+        output: {
+            schema: outputSchema,
+            render: textRender(renderRunCodeOutput),
+        },
+        execute: async (args, exec) => {
+            const a = args;
+            return runCode(cfg.pythonPath, a.code, a.cwd, cfg.timeoutMs, exec.signal);
+        },
+    })));
+    disposers.push(ctx.tools.register(defineTool({
+        name: 'run_node',
+        description: buildNodeDescription(cfg),
+        parameters: parametersSchema,
+        output: {
+            schema: outputSchema,
+            render: textRender(renderRunCodeOutput),
+        },
+        execute: async (args, exec) => {
+            const a = args;
+            return runCode(cfg.nodePath, a.code, a.cwd, cfg.timeoutMs, exec.signal);
+        },
+    })));
+    return () => { for (const dispose of disposers)
+        dispose(); };
+}

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

@@ -0,0 +1,42 @@
+/**
+ * InterpretersCard — the `settings.plugin.item` card for the interpreters
+ * configuration.
+ *
+ * Self-drawn chrome replicating the upstream `PluginCard` contract: the
+ * upstream client value face exports no reusable card component, so this
+ * card draws its own collapsible `<li>` with the same header button (name
+ * over description, dirty pill, rotating chevron, aria) and divided body
+ * (readOnly notice, form fields, footer with failed/saved message +
+ * Discard/Save). Three fields (pythonPath, nodePath, timeoutMs) are staged
+ * through the card's controller; save commits them through the
+ * `/api/interpreters/set` gateway channel.
+ *
+ * @module dsh-interpreters/client/InterpretersCard
+ */
+import { type ReactNode } from 'react';
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react';
+import { InterpretersCardController, type InterpretersCardState } from './store.ts';
+import type { InterpretersKey } from './locales.ts';
+/** Injected dependencies of {@link InterpretersCard} (slot `inject`). */
+export interface InterpretersCardInjected {
+    /** The card controller (loaded on mount, refreshed on pushed invalidations). */
+    controller: InterpretersCardController;
+    /** uSES subscription hook bound to the store. */
+    useSnapshot: SnapshotSelectorHook<InterpretersCardState>;
+}
+/** Props the renderer binds for the card. */
+export type InterpretersCardProps = PropsRuntime<'settings.plugin.item'> & PropsLocale<'interpreters'> & InjectFace<InterpretersCardInjected>;
+/**
+ * Render the interpreters card inside the plugin-config section, replicating
+ * the upstream PluginCard chrome.
+ * @param props - slot-delivered injected dependencies and the synthesized t seat.
+ * @returns the card.
+ */
+export declare function InterpretersCard(props: InterpretersCardProps): ReactNode;
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The interpreters card copy. */
+        'interpreters': InterpretersKey;
+    }
+}

package/lib/types/client/InterpretersCard.js

@@ -0,0 +1,74 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * InterpretersCard — the `settings.plugin.item` card for the interpreters
+ * configuration.
+ *
+ * Self-drawn chrome replicating the upstream `PluginCard` contract: the
+ * upstream client value face exports no reusable card component, so this
+ * card draws its own collapsible `<li>` with the same header button (name
+ * over description, dirty pill, rotating chevron, aria) and divided body
+ * (readOnly notice, form fields, footer with failed/saved message +
+ * Discard/Save). Three fields (pythonPath, nodePath, timeoutMs) are staged
+ * through the card's controller; save commits them through the
+ * `/api/interpreters/set` gateway channel.
+ *
+ * @module dsh-interpreters/client/InterpretersCard
+ */
+import { useState } from 'react';
+import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives';
+import { formatFieldNumber, formatFieldText, } from "./store.js";
+import styles from './InterpretersCard.module.css';
+/**
+ * Render the interpreters card inside the plugin-config section, replicating
+ * the upstream PluginCard chrome.
+ * @param props - slot-delivered injected dependencies and the synthesized t seat.
+ * @returns the card.
+ */
+export function InterpretersCard(props) {
+    const { controller, useSnapshot, t } = props;
+    const state = useSnapshot(snapshot => snapshot);
+    // Load-on-mount: the plugin-config page mounts the card lazily when the
+    // user opens the settings panel, so the first mount triggers the first
+    // gateway load.
+    if (state.status === 'idle')
+        void controller.load();
+    // Disclosure is card-local USER state (upstream rationale): the healthy
+    // card starts collapsed and opens on the header click only. The degraded
+    // (unavailable) card renders its notice body ALWAYS visible, so `open` is
+    // DERIVED from the current snapshot.
+    const [userOpen, setUserOpen] = useState(false);
+    const degraded = state.status === 'ready' && !state.available;
+    const open = userOpen || degraded;
+    const title = t('title');
+    const header = (_jsxs("button", { type: "button", className: styles.header, "aria-expanded": open, "aria-label": `${t(open ? 'collapse' : 'expand')}: ${title}`, 
+        // While degraded the derived open is forced true, so the click must be
+        // a no-op — toggling userOpen would silently latch it and pre-open the
+        // recovered form.
+        onClick: () => { if (!degraded)
+            setUserOpen(!userOpen); }, children: [_jsxs("span", { className: styles.headText, children: [_jsx("span", { className: styles.name, children: title }), _jsx("span", { className: styles.description, children: t('intro') })] }), state.dirty ? _jsx("span", { className: styles.pending, children: t('unsaved') }) : null, _jsx(IconChevronDownOutline14, { className: open ? `${styles.chevron} ${styles.chevronOpen}` : styles.chevron })] }));
+    let body;
+    if (degraded) {
+        // The gateway channel is down or the namespace is not served to this
+        // client — render the explicit notice and never offer Save.
+        body = (_jsxs("div", { className: styles.body, children: [_jsx("p", { className: styles.notice, role: "status", children: t('namespaceUnavailable') }), _jsx("div", { className: styles.footer, children: _jsx("button", { type: "button", className: styles.discard, onClick: () => { void controller.load(); }, children: t('retry') }) })] }));
+    }
+    else if (state.status === 'ready') {
+        const { draft, writable, applyState } = state;
+        const saving = applyState.kind === 'saving';
+        const busy = !writable || saving;
+        const saveDisabled = !state.dirty || saving || !writable;
+        const discardDisabled = !state.dirty || saving;
+        const errorText = applyState.kind === 'error' ? applyState.message : undefined;
+        body = (_jsxs("div", { className: styles.body, children: [!writable ? _jsx("p", { className: styles.readOnly, role: "status", children: t('readOnly') }) : null, applyState.kind === 'saved' ? _jsx("p", { className: styles.savedNotice, role: "status", children: t('save') }) : null, _jsxs("div", { className: styles.form, children: [_jsx(Field, { id: "plugin-config-interpreters-python", label: t('pythonPath'), hint: t('pythonHelp'), text: formatFieldText(draft.pythonPath), disabled: busy, onEdit: (text) => { controller.edit('pythonPath', text); } }), _jsx(Field, { id: "plugin-config-interpreters-node", label: t('nodePath'), hint: t('nodeHelp'), text: formatFieldText(draft.nodePath), disabled: busy, onEdit: (text) => { controller.edit('nodePath', text); } }), _jsx(Field, { id: "plugin-config-interpreters-timeout", label: t('timeoutMs'), hint: t('timeoutHelp'), text: formatFieldNumber(draft.timeoutMs), numeric: true, disabled: busy, onEdit: (text) => { controller.edit('timeoutMs', text); } })] }), _jsxs("div", { className: styles.footer, children: [errorText === undefined ? null : _jsx("p", { className: styles.failed, role: "status", children: errorText }), _jsx("button", { type: "button", className: styles.discard, disabled: discardDisabled, onClick: () => { controller.discard(); }, children: t('discard') }), _jsx("button", { type: "button", className: styles.save, disabled: saveDisabled, onClick: () => { controller.save(); }, children: t(saving ? 'saving' : 'save') })] })] }));
+    }
+    else {
+        // Loading (or the idle→loading transition): the header alone — an open
+        // card shows an empty body.
+        body = _jsx("div", { className: styles.body });
+    }
+    return (_jsxs("li", { className: open ? `${styles.card} ${styles.cardOpen}` : styles.card, children: [header, open ? body : null] }));
+}
+/** One staged field control (text or numeric). */
+function Field(props) {
+    return (_jsxs("div", { className: styles.field, children: [_jsx("label", { className: styles.fieldLabel, htmlFor: props.id, children: props.label }), _jsx("input", { id: props.id, className: styles.input, type: props.numeric ? 'number' : 'text', ...props.numeric ? { inputMode: 'numeric' } : {}, value: props.text, disabled: props.disabled, onChange: (event) => { props.onEdit(event.target.value); } }), _jsx("p", { className: styles.hint, children: props.hint })] }));
+}