@dsh-ft/dsh-fft-settings 0.0.0-stage → 0.5.1

package/lib/core/shell.d.ts

@@ -0,0 +1,59 @@
+import type { ReactNode } from 'react';
+import type { PropsRenderSlots, PropsRuntime, SlotCore, SlotMap } from '@deepseek-ai/dsh-client-ui-slots';
+import { FTSHARE_SETTINGS_CARD_SLOT } from './contract.js';
+/** Section slot this seam contributes into; declared by the settings shell. */
+declare const FTSHARE_SETTINGS_SECTION_NAME: "settings.section";
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface SlotMap {
+        /** One card inside the FTShare settings section; `order` sets its position. */
+        'ftshare.settings.card': {
+            kind: 'list';
+            scope: 'root';
+            owner: FtshareSettingsCardOwnerProps;
+        };
+    }
+}
+/** Owner share of a card: the section supplies no card-specific props. */
+export interface FtshareSettingsCardOwnerProps {
+    /** Marker field: card owner props are intentionally empty. */
+    children?: never;
+}
+/**
+ * The slice of the renderer-owned slots service this seam uses.
+ *
+ * `register` IS the ui-slots registration signature (the runtime registry
+ * reuses it verbatim, adding disposal through the caller's fiber); `inject`
+ * is the runtime wrapper's declaration-lifetime hook, which is why it is
+ * mirrored structurally here.
+ */
+export interface FtshareSettingsSlotsService {
+    readonly register: SlotCore['register'];
+    /** Run `callback` for each declaration lifetime of `key`. */
+    inject(key: keyof SlotMap & string, callback: () => () => void): () => void;
+}
+/**
+ * Browser context the section shell requires: the renderer's slots service.
+ * A card that needs more (its own services, invalidation events) declares the
+ * extra members on its own context type.
+ */
+export interface FtshareSettingsShellContext {
+    slots: FtshareSettingsSlotsService;
+}
+/** Composed props of the section entry: the shell's owner share plus its declared child render. */
+export type FtshareSettingsSectionProps = PropsRuntime<typeof FTSHARE_SETTINGS_SECTION_NAME> & PropsRenderSlots<typeof FTSHARE_SETTINGS_CARD_SLOT>;
+/**
+ * The settings section shell: core CSS variables, the section chrome, and the
+ * single render site every card appears at. Cards own everything inside it.
+ */
+export declare function FtshareSettingsSection({ renderSlot }: FtshareSettingsSectionProps): ReactNode;
+/**
+ * Declare the card slot and contribute the section that renders it.
+ *
+ * Declaring the child slot is what authorizes the render site; a card
+ * registering through {@link FTSHARE_SETTINGS_CARD_SLOT} before this runs waits
+ * for the declaration instead of failing.
+ * @param ctx - client context carrying the renderer's slots service.
+ * @returns idempotent disposer for the section and its declaration.
+ */
+export declare function registerSettingsSection(ctx: FtshareSettingsShellContext): () => void;
+export {};

package/lib/core/shell.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { FTSHARE_SETTINGS_CARD_SLOT, FTSHARE_SETTINGS_SECTION } from './contract.js';
+import { SETTINGS_CSS } from './styles.js';
+/** Section slot this seam contributes into; declared by the settings shell. */
+const FTSHARE_SETTINGS_SECTION_NAME = 'settings.section';
+/**
+ * The settings section shell: core CSS variables, the section chrome, and the
+ * single render site every card appears at. Cards own everything inside it.
+ */
+export function FtshareSettingsSection({ renderSlot }) {
+    return _jsxs(_Fragment, { children: [_jsx("style", { children: SETTINGS_CSS }), renderSlot(FTSHARE_SETTINGS_CARD_SLOT, {})] });
+}
+/**
+ * Declare the card slot and contribute the section that renders it.
+ *
+ * Declaring the child slot is what authorizes the render site; a card
+ * registering through {@link FTSHARE_SETTINGS_CARD_SLOT} before this runs waits
+ * for the declaration instead of failing.
+ * @param ctx - client context carrying the renderer's slots service.
+ * @returns idempotent disposer for the section and its declaration.
+ */
+export function registerSettingsSection(ctx) {
+    return ctx.slots.inject(FTSHARE_SETTINGS_SECTION_NAME, () => ctx.slots.register({
+        name: FTSHARE_SETTINGS_SECTION_NAME,
+        ...FTSHARE_SETTINGS_SECTION,
+        children: { [FTSHARE_SETTINGS_CARD_SLOT]: { kind: 'list', scope: 'root' } },
+    }, FtshareSettingsSection));
+}

package/lib/core/styles.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The section shell's styles plus the theme tokens every card reads.
+ *
+ * The shell owns the container, typography, focus ring and link rules that
+ * every card sits inside; a card owns its own CSS and renders it from its own
+ * component, and core never styles card internals.
+ *
+ * The theme layer declares the plugin's `--ftshare-*` tokens once, on
+ * `.ftshare-settings` — the root element every card renders. Surfaces and text
+ * take their value from the host palette: `--dsw-alias-*` is what DSH
+ * publishes for the light, the dark and every registered theme, so one
+ * stylesheet follows the live palette with no script, no `prefers-color-scheme`
+ * copy and no second palette to keep in sync. The literal inside each `var()`
+ * is the fallback for a host that publishes no palette.
+ *
+ * The declarations sit on the card root rather than on `:root` because a
+ * custom property resolves where it is *declared*: `--dsw-alias-*` exists from
+ * `body` downwards, so a value derived from it above `body` would resolve to
+ * nothing and fall back. Consequence: the place to pin a look is the host
+ * palette itself (`ctx.theme.register` / `ctx.theme.overrideTokens`), not these
+ * names.
+ *
+ * `--ftshare-accent*` is the plugin's own brand and has no host equivalent. The
+ * values come from the FT brand layer's `--ft-*` tokens (`src/brand.ts`), with
+ * the same literal as the fallback so the card keeps its colors when that layer
+ * is absent. The fill and its ink are scheme-invariant;
+ * `--ftshare-accent-on-surface` mixes the same yellow towards the host's text
+ * colour, so the brand stays legible as the 11px eyebrow and as the focus ring
+ * on either surface.
+ */
+export declare const SETTINGS_CSS = "\n.ftshare-settings { --ftshare-text:var(--dsw-alias-label-primary,#f4f4f5); --ftshare-muted:var(--dsw-alias-label-secondary,#aeb2bd); --ftshare-panel:var(--dsw-alias-settings-card-fill,#292a30); --ftshare-border:var(--dsw-alias-settings-card-stroke,#44464f); --ftshare-control:var(--dsw-alias-border-l4,#696c77); --ftshare-input:var(--dsw-alias-bg-layer-1,#1d1e23); --ftshare-link:var(--dsw-alias-link,#d8c4fc); --ftshare-error:var(--dsw-alias-state-error-primary,#ffb5ad); --ftshare-accent:var(--ft-accent,#f0c433); --ftshare-accent-ink:var(--ft-accent-ink,#171717); --ftshare-accent-on-surface:color-mix(in srgb,var(--ftshare-accent) 50%,var(--dsw-alias-label-primary,#f4f4f5)); }\n.ftshare-settings { color:var(--ftshare-text); max-width:760px; font-size:14px; line-height:1.6; }\n.ftshare-settings * { box-sizing:border-box; }\n.ftshare-settings h2 { font-size:26px; margin:4px 0 8px; }\n.ftshare-settings h3 { font-size:15px; margin:0 0 12px; }\n.ftshare-settings p { margin:8px 0; color:var(--ftshare-muted); }\n.ftshare-settings header { display:flex; justify-content:space-between; align-items:flex-start; gap:20px; margin-bottom:20px; }\n.ftshare-settings small { display:block; color:var(--ftshare-muted); font-size:12px; margin:5px 0 12px; }\n.ftshare-settings :is(button,input,a):focus-visible { outline:2px solid var(--ftshare-accent-on-surface); outline-offset:3px; }\n.ftshare-settings a { color:var(--ftshare-link); }\n@media(max-width:540px) { .ftshare-settings header { flex-direction:column; gap:10px; } }\n";

package/lib/core/styles.js

@@ -0,0 +1,43 @@
+/**
+ * The section shell's styles plus the theme tokens every card reads.
+ *
+ * The shell owns the container, typography, focus ring and link rules that
+ * every card sits inside; a card owns its own CSS and renders it from its own
+ * component, and core never styles card internals.
+ *
+ * The theme layer declares the plugin's `--ftshare-*` tokens once, on
+ * `.ftshare-settings` — the root element every card renders. Surfaces and text
+ * take their value from the host palette: `--dsw-alias-*` is what DSH
+ * publishes for the light, the dark and every registered theme, so one
+ * stylesheet follows the live palette with no script, no `prefers-color-scheme`
+ * copy and no second palette to keep in sync. The literal inside each `var()`
+ * is the fallback for a host that publishes no palette.
+ *
+ * The declarations sit on the card root rather than on `:root` because a
+ * custom property resolves where it is *declared*: `--dsw-alias-*` exists from
+ * `body` downwards, so a value derived from it above `body` would resolve to
+ * nothing and fall back. Consequence: the place to pin a look is the host
+ * palette itself (`ctx.theme.register` / `ctx.theme.overrideTokens`), not these
+ * names.
+ *
+ * `--ftshare-accent*` is the plugin's own brand and has no host equivalent. The
+ * values come from the FT brand layer's `--ft-*` tokens (`src/brand.ts`), with
+ * the same literal as the fallback so the card keeps its colors when that layer
+ * is absent. The fill and its ink are scheme-invariant;
+ * `--ftshare-accent-on-surface` mixes the same yellow towards the host's text
+ * colour, so the brand stays legible as the 11px eyebrow and as the focus ring
+ * on either surface.
+ */
+export const SETTINGS_CSS = `
+.ftshare-settings { --ftshare-text:var(--dsw-alias-label-primary,#f4f4f5); --ftshare-muted:var(--dsw-alias-label-secondary,#aeb2bd); --ftshare-panel:var(--dsw-alias-settings-card-fill,#292a30); --ftshare-border:var(--dsw-alias-settings-card-stroke,#44464f); --ftshare-control:var(--dsw-alias-border-l4,#696c77); --ftshare-input:var(--dsw-alias-bg-layer-1,#1d1e23); --ftshare-link:var(--dsw-alias-link,#d8c4fc); --ftshare-error:var(--dsw-alias-state-error-primary,#ffb5ad); --ftshare-accent:var(--ft-accent,#f0c433); --ftshare-accent-ink:var(--ft-accent-ink,#171717); --ftshare-accent-on-surface:color-mix(in srgb,var(--ftshare-accent) 50%,var(--dsw-alias-label-primary,#f4f4f5)); }
+.ftshare-settings { color:var(--ftshare-text); max-width:760px; font-size:14px; line-height:1.6; }
+.ftshare-settings * { box-sizing:border-box; }
+.ftshare-settings h2 { font-size:26px; margin:4px 0 8px; }
+.ftshare-settings h3 { font-size:15px; margin:0 0 12px; }
+.ftshare-settings p { margin:8px 0; color:var(--ftshare-muted); }
+.ftshare-settings header { display:flex; justify-content:space-between; align-items:flex-start; gap:20px; margin-bottom:20px; }
+.ftshare-settings small { display:block; color:var(--ftshare-muted); font-size:12px; margin:5px 0 12px; }
+.ftshare-settings :is(button,input,a):focus-visible { outline:2px solid var(--ftshare-accent-on-surface); outline-offset:3px; }
+.ftshare-settings a { color:var(--ftshare-link); }
+@media(max-width:540px) { .ftshare-settings header { flex-direction:column; gap:10px; } }
+`;

package/lib/core/transport.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Host half of the settings transport.
+ *
+ * One exact route on the shared `/api` carrier: the carrier owns the Host/Origin
+ * fence and browser authentication, so this layer only decodes the call, bounds
+ * the body and returns the result envelope. Registering through
+ * `connection.rpc.handle` instead would read `webServer` through the context
+ * property proxy, whose resolution is ancestor-only and therefore fails for a
+ * plugin mounted beside the Web server.
+ */
+import type { RpcHandler, SettingsRoute } from './rpc-core.js';
+/**
+ * Build the exact Fetch route served by the connection carrier.
+ * @param options - the settings call handler.
+ * @returns route definition ready for `connection.fetch.register`.
+ */
+export declare function createSettingsRoute({ handler }: {
+    readonly handler: RpcHandler;
+}): SettingsRoute;

package/lib/core/transport.js

@@ -0,0 +1,80 @@
+/**
+ * Host half of the settings transport.
+ *
+ * One exact route on the shared `/api` carrier: the carrier owns the Host/Origin
+ * fence and browser authentication, so this layer only decodes the call, bounds
+ * the body and returns the result envelope. Registering through
+ * `connection.rpc.handle` instead would read `webServer` through the context
+ * property proxy, whose resolution is ancestor-only and therefore fails for a
+ * plugin mounted beside the Web server.
+ */
+import { FTSHARE_SETTINGS_MAX_BODY_BYTES, FTSHARE_SETTINGS_ROUTE } from './contract.js';
+const invalidRequest = () => ({
+    ok: false,
+    error: { code: 'bad_request', message: '请求参数不正确', details: {} },
+});
+/**
+ * Build the exact Fetch route served by the connection carrier.
+ * @param options - the settings call handler.
+ * @returns route definition ready for `connection.fetch.register`.
+ */
+export function createSettingsRoute({ handler }) {
+    return {
+        path: FTSHARE_SETTINGS_ROUTE,
+        methods: ['POST'],
+        requestBody: 'buffered',
+        fetch: async (request) => {
+            const body = await readJsonBody(request);
+            if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+                return json(400, invalidRequest());
+            }
+            const call = body;
+            const endpoint = typeof call.endpoint === 'string' ? call.endpoint : '';
+            return json(200, await handler(endpoint, call.payload, request.signal));
+        },
+    };
+}
+/** Read and parse the JSON body; oversized, malformed or interrupted reads return undefined. */
+async function readJsonBody(request) {
+    const reader = request.body?.getReader();
+    if (reader === undefined)
+        return undefined;
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > FTSHARE_SETTINGS_MAX_BODY_BYTES) {
+                await reader.cancel();
+                return undefined;
+            }
+            chunks.push(value);
+        }
+    }
+    catch {
+        // A client-side abort only means this request lost its body; nothing else to read.
+        return undefined;
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    try {
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        // A non-JSON body has the same single outcome: invalid request parameters.
+        return undefined;
+    }
+}
+function json(status, payload) {
+    return new Response(JSON.stringify(payload), {
+        status,
+        headers: { 'content-type': 'application/json' },
+    });
+}

package/lib/default-preset.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Claim the finance preset as the default once per installation.
+ *
+ * The bundle patch already carries `default: ft-finance` on the preset
+ * registry row, which decides every session on a machine that never chose a
+ * default. A machine whose user *did* choose one keeps that choice, because
+ * `selectedDefault` outranks `default` — this module overrides it exactly once,
+ * then records the claim so a later user choice is never touched again.
+ *
+ * The write goes through the settings service, the same path the settings page
+ * uses: only volatile fields are writable there, so the patch this module hands
+ * over carries `selectedDefault` and nothing else. The row it lands in is wider
+ * than that patch — the service writes the effective config's non-volatile keys
+ * alongside the volatile change, so `default: ft-finance` is copied into the
+ * profile row too. Because it is still the one change this plugin ever makes to
+ * the user's own profile patch, the file is copied into this plugin's data
+ * directory first, and a claim without that copy never happens.
+ * @module @dsh-ft/dsh-fft-settings/default-preset
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** The preset this bundle wants as the default. */
+export declare const DEFAULT_PRESET_ID = "ft-finance";
+/** Id of the profile entry that owns the preset registry's config. */
+export declare const REGISTRY_ENTRY_ID = "agent-preset-registry";
+/** Data directory this plugin owns under the DSH home. */
+export declare const DATA_DIR_NAME = ".dsh-fft-settings";
+/** File whose presence means the claim already happened on this machine. */
+export declare const CLAIM_FILE_NAME = "default-preset.json";
+/** Snapshot of the profile patch, taken before this module's single write. */
+export declare const BACKUP_FILE_NAME = "cordis.patch.yml.bak";
+/**
+ * Record that this installation claimed the default, once.
+ * @param home - the DSH home the plugin writes its own data into.
+ * @returns the claim file path.
+ */
+export declare function claimFilePath(home?: string): string;
+/**
+ * Snapshot path for the profile patch.
+ * @param home - the DSH home the plugin writes its own data into.
+ * @returns the snapshot file path.
+ */
+export declare function backupFilePath(home?: string): string;
+/**
+ * Make `ft-finance` the default unless this machine already made a claim.
+ *
+ * Every step that cannot complete skips silently and retries on the next start:
+ * a missing registry or settings service, a preset that is not registered yet,
+ * and a failed write all leave no claim file behind. Nothing here may fail the
+ * plugin's activation.
+ * @param ctx - the plugin's host context.
+ */
+export declare function installDefaultPresetOnce(ctx: Context): void;

package/lib/default-preset.js

@@ -0,0 +1,121 @@
+/**
+ * Claim the finance preset as the default once per installation.
+ *
+ * The bundle patch already carries `default: ft-finance` on the preset
+ * registry row, which decides every session on a machine that never chose a
+ * default. A machine whose user *did* choose one keeps that choice, because
+ * `selectedDefault` outranks `default` — this module overrides it exactly once,
+ * then records the claim so a later user choice is never touched again.
+ *
+ * The write goes through the settings service, the same path the settings page
+ * uses: only volatile fields are writable there, so the patch this module hands
+ * over carries `selectedDefault` and nothing else. The row it lands in is wider
+ * than that patch — the service writes the effective config's non-volatile keys
+ * alongside the volatile change, so `default: ft-finance` is copied into the
+ * profile row too. Because it is still the one change this plugin ever makes to
+ * the user's own profile patch, the file is copied into this plugin's data
+ * directory first, and a claim without that copy never happens.
+ * @module @dsh-ft/dsh-fft-settings/default-preset
+ */
+import { existsSync } from 'node:fs';
+import { copyFile, mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { resolveDshHome } from './features/logs/home.js';
+/** The preset this bundle wants as the default. */
+export const DEFAULT_PRESET_ID = 'ft-finance';
+/** Id of the profile entry that owns the preset registry's config. */
+export const REGISTRY_ENTRY_ID = 'agent-preset-registry';
+/** Data directory this plugin owns under the DSH home. */
+export const DATA_DIR_NAME = '.dsh-fft-settings';
+/** File whose presence means the claim already happened on this machine. */
+export const CLAIM_FILE_NAME = 'default-preset.json';
+/** Snapshot of the profile patch, taken before this module's single write. */
+export const BACKUP_FILE_NAME = 'cordis.patch.yml.bak';
+/**
+ * Record that this installation claimed the default, once.
+ * @param home - the DSH home the plugin writes its own data into.
+ * @returns the claim file path.
+ */
+export function claimFilePath(home = resolveDshHome()) {
+    return join(home, DATA_DIR_NAME, CLAIM_FILE_NAME);
+}
+/**
+ * Snapshot path for the profile patch.
+ * @param home - the DSH home the plugin writes its own data into.
+ * @returns the snapshot file path.
+ */
+export function backupFilePath(home = resolveDshHome()) {
+    return join(home, DATA_DIR_NAME, BACKUP_FILE_NAME);
+}
+/**
+ * Make `ft-finance` the default unless this machine already made a claim.
+ *
+ * Every step that cannot complete skips silently and retries on the next start:
+ * a missing registry or settings service, a preset that is not registered yet,
+ * and a failed write all leave no claim file behind. Nothing here may fail the
+ * plugin's activation.
+ * @param ctx - the plugin's host context.
+ */
+export function installDefaultPresetOnce(ctx) {
+    ctx.inject(['settings', 'agentPresets'], (scope) => {
+        const registry = scope.get('agentPresets');
+        const settings = scope.get('settings');
+        if (registry === undefined || settings === undefined)
+            return;
+        const profile = scope.get('profileContext');
+        void claimDefaultPreset(registry, settings, profile, ctx)
+            .catch((error) => {
+            ctx.logger.warn('dsh-fft-settings: could not claim the default preset', error);
+        });
+    });
+}
+/**
+ * Perform the one-time claim, snapshotting the file it is about to change.
+ * @param registry - the live preset registry.
+ * @param settings - the settings writer.
+ * @param profile - the profile context, absent in a context that has no patch file.
+ * @param ctx - the plugin context, used for the claim log line.
+ */
+async function claimDefaultPreset(registry, settings, profile, ctx) {
+    const file = claimFilePath();
+    if (existsSync(file))
+        return;
+    // An unregistered preset would pin an id that resolves to nothing, so the
+    // claim waits for the composition that defines it.
+    const presets = await registry.list();
+    if (!presets.some(preset => preset.id === DEFAULT_PRESET_ID))
+        return;
+    let backup;
+    if (registry.defaultId !== DEFAULT_PRESET_ID) {
+        // Insurance first: the editor writes atomically and rolls back a failed
+        // reconcile, but this write still lands in the user's own profile patch, so
+        // a claim is only recorded once the snapshot exists.
+        if (profile !== undefined)
+            backup = await snapshotProfilePatch(profile.patchPath);
+        await settings.update(REGISTRY_ENTRY_ID, { selectedDefault: DEFAULT_PRESET_ID });
+        ctx.logger.info(`dsh-fft-settings: ${DEFAULT_PRESET_ID} is now the default preset`);
+    }
+    await mkdir(dirname(file), { recursive: true });
+    const claim = { preset: DEFAULT_PRESET_ID, at: new Date().toISOString(), ...(backup === undefined ? {} : { backup }) };
+    await writeFile(file, `${JSON.stringify(claim, null, 2)}\n`);
+}
+/**
+ * Copy the profile patch into this plugin's data directory, once.
+ *
+ * A failed copy throws, and the caller aborts the claim: the write must not
+ * happen without its snapshot. The first copy wins, so a retry after a failed
+ * write still holds the state from before the very first attempt. A missing
+ * patch file — a profile that never wrote anything — needs no copy.
+ * @param patchPath - the profile's own `cordis.patch.yml`.
+ * @returns the snapshot path, or `undefined` when there was nothing to copy.
+ */
+async function snapshotProfilePatch(patchPath) {
+    if (!existsSync(patchPath))
+        return undefined;
+    const snapshot = backupFilePath();
+    if (existsSync(snapshot))
+        return snapshot;
+    await mkdir(dirname(snapshot), { recursive: true });
+    await copyFile(patchPath, snapshot);
+    return snapshot;
+}

package/lib/features/api-key/card.d.ts

@@ -0,0 +1,24 @@
+import { type ReactNode } from 'react';
+import { type SubscribeChanges, type ApiKeyPublicApi } from './contract.js';
+import type { FtshareSettingsShellContext } from '../../core/shell.js';
+/**
+ * Browser context this card requires: the shell's slots service plus the
+ * invalidations that make a cached credential status stale.
+ */
+export interface ApiKeyCardContext extends FtshareSettingsShellContext {
+    remote: {
+        $on(event: string, listener: (ref: string) => void): () => void;
+    };
+    on(event: 'connection/reset', listener: () => void): () => void;
+}
+/**
+ * Contribute the built-in API Key card through the same slot a third-party
+ * card uses. Nothing about it is privileged: same declaration, same options.
+ * @param ctx - client context carrying the renderer's slots service.
+ * @returns idempotent disposer for the card registration.
+ */
+export declare function registerApiKeyCard(ctx: ApiKeyCardContext): () => void;
+export declare function ApiKeyCard({ api, subscribeChanges }: {
+    readonly api: ApiKeyPublicApi;
+    readonly subscribeChanges?: SubscribeChanges;
+}): ReactNode;

package/lib/features/api-key/card.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useMemo, useState, useSyncExternalStore } from 'react';
+import { FTSHARE_API_KEY_REF, FTSHARE_CREDENTIAL_EVENTS } from './contract.js';
+import { FTSHARE_SETTINGS_CARD_SLOT } from '../../core/contract.js';
+import { FtshareSettingsModel } from './model.js';
+import { createApiKeyClient } from './client-api.js';
+import { createSettingsTransport } from '../../core/client-transport.js';
+import { API_KEY_CARD_CSS } from './styles.js';
+/**
+ * Contribute the built-in API Key card through the same slot a third-party
+ * card uses. Nothing about it is privileged: same declaration, same options.
+ * @param ctx - client context carrying the renderer's slots service.
+ * @returns idempotent disposer for the card registration.
+ */
+export function registerApiKeyCard(ctx) {
+    return ctx.slots.inject(FTSHARE_SETTINGS_CARD_SLOT, () => ctx.slots.register({ name: FTSHARE_SETTINGS_CARD_SLOT, id: 'apiKey', order: 10 }, createApiKeyCard(ctx)));
+}
+/** Bind the card's adapters; subscriptions are acquired in the component's effect. */
+function createApiKeyCard(ctx) {
+    const api = createApiKeyClient(createSettingsTransport());
+    const subscribeChanges = listener => {
+        const disposers = FTSHARE_CREDENTIAL_EVENTS.map(event => ctx.remote.$on(event, ref => { if (ref === FTSHARE_API_KEY_REF)
+            listener(); }));
+        disposers.push(ctx.on('connection/reset', listener));
+        return () => { for (const dispose of disposers)
+            dispose(); };
+    };
+    return () => _jsx(ApiKeyCard, { api: api, subscribeChanges: subscribeChanges });
+}
+export function ApiKeyCard({ api, subscribeChanges }) {
+    const model = useMemo(() => new FtshareSettingsModel(api), [api]);
+    const { status, busy, message, statusError, save } = useSyncExternalStore(model.subscribe, model.getSnapshot, model.getSnapshot);
+    const [draft, setDraft] = useState('');
+    useEffect(() => model.connect(subscribeChanges), [model, subscribeChanges]);
+    const disabled = busy || !status?.writable;
+    const configure = async () => { if (await model.configureAndTest(draft))
+        setDraft(''); };
+    return _jsxs(_Fragment, { children: [_jsx("style", { children: API_KEY_CARD_CSS }), _jsxs("section", { className: "ftshare-settings", "aria-label": "FTShare \u8BBE\u7F6E", "aria-busy": busy, children: [_jsx("header", { children: _jsxs("div", { children: [_jsx("span", { className: "ftshare-eyebrow", children: "FTSHARE / API KEY" }), _jsx("h2", { children: "\u8BBF\u95EE\u51ED\u636E" })] }) }), _jsx("p", { children: "\u76EE\u524D\u96C6\u6210 FTShare \u6570\u636E\u6E90\u3002" }), status && !status.writable && _jsx("p", { children: "\u5F53\u524D\u6765\u6E90\u4E3A\u53EA\u8BFB\uFF0C\u53EF\u6D4B\u8BD5\u8FDE\u63A5\uFF1B\u4FEE\u6539\u5BC6\u94A5\u8BF7\u5230\u5BF9\u5E94\u6765\u6E90\u64CD\u4F5C\u3002" }), _jsxs("div", { className: "ftshare-card", children: [_jsx("label", { htmlFor: "ftshare-api-key", children: "FTShare API Key" }), _jsx("input", { id: "ftshare-api-key", type: "password", value: draft, placeholder: status?.configured ? status.maskedValue ?? '••••••••' : '请输入 API Key', onChange: e => setDraft(e.target.value), disabled: disabled, autoComplete: "new-password", maxLength: 512 }), _jsxs("div", { className: "ftshare-actions", children: [_jsx("button", { className: "primary", type: "button", onClick: () => void configure(), disabled: disabled || !draft.trim(), children: "\u914D\u7F6E\u5E76\u6D4B\u8BD5" }), _jsx("button", { type: "button", onClick: () => void model.testConnection(), disabled: busy || !status, children: "\u6D4B\u8BD5\u5F53\u524D\u8FDE\u63A5" }), _jsx("button", { type: "button", onClick: () => void model.clear(), disabled: disabled || !status?.configured, children: "\u6E05\u9664\u5DF2\u4FDD\u5B58\u5BC6\u94A5" }), _jsx("button", { type: "button", onClick: () => void model.refresh(), disabled: busy, title: "\u91CD\u65B0\u8BFB\u53D6\u5DF2\u4FDD\u5B58\u7684\u914D\u7F6E\u548C\u4E0A\u6B21\u68C0\u6D4B\u7ED3\u679C\uFF0C\u4E0D\u4F1A\u53D1\u8D77\u8054\u7F51\u68C0\u6D4B", children: "\u91CD\u65B0\u8BFB\u53D6\u72B6\u6001" }), _jsx("a", { href: "https://ftai.chat/me/profile?tab=api-key", target: "_blank", rel: "noreferrer", children: "\u83B7\u53D6 API Key \u2197" })] }), draft && _jsx("small", { children: "\u201C\u6D4B\u8BD5\u5F53\u524D\u8FDE\u63A5\u201D\u4F7F\u7528\u5DF2\u751F\u6548\u7684\u5BC6\u94A5\uFF0C\u4E0D\u6D4B\u8BD5\u8F93\u5165\u6846\u5185\u5C1A\u672A\u4FDD\u5B58\u7684\u5185\u5BB9\u3002" }), busy && _jsx("p", { role: "status", children: "\u6B63\u5728\u5904\u7406\uFF0C\u8BF7\u7A0D\u5019\u2026" })] }), _jsxs("div", { className: "ftshare-card", "aria-live": "polite", children: [_jsx("h3", { children: "\u9A8C\u8BC1\u7ED3\u679C" }), _jsxs("dl", { children: [save && _jsxs("div", { className: "ftshare-result", children: [_jsx("dt", { children: "\u672C\u6B21\u4FDD\u5B58" }), _jsx("dd", { children: save.message })] }), _jsxs("div", { className: "ftshare-result", children: [_jsx("dt", { children: "\u8FDC\u7AEF\u670D\u52A1" }), _jsx("dd", { children: status?.validation.remote.message ?? '状态待确认' })] }), _jsxs("div", { className: "ftshare-result", children: [_jsx("dt", { children: "API Key" }), _jsx("dd", { children: status?.validation.apiKey.message ?? '状态待确认' })] }), status?.validation.testedAt && _jsxs("div", { className: "ftshare-result", children: [_jsx("dt", { children: "\u6D4B\u8BD5\u65F6\u95F4" }), _jsx("dd", { children: new Date(status.validation.testedAt).toLocaleString() })] })] }), _jsx("small", { children: "\u8282\u5047\u65E5\u6216\u6536\u76D8\u540E\u7684\u7A7A\u6570\u636E\u4E0D\u5F71\u54CD\u9A8C\u8BC1\u3002" })] }), message && _jsx("p", { role: "status", children: message }), statusError && _jsx("p", { className: "ftshare-error", role: "alert", children: statusError })] })] });
+}

package/lib/features/api-key/client-api.d.ts

@@ -0,0 +1,4 @@
+import type { ApiKeyPublicApi } from './contract.js';
+import { type ClientTransport } from '../../core/rpc-core.js';
+/** Browser adapter deliberately has no resolve/createEnvironment method. */
+export declare function createApiKeyClient(transport: ClientTransport): ApiKeyPublicApi;

package/lib/features/api-key/client-api.js

@@ -0,0 +1,11 @@
+import { callSettingsRpc } from '../../core/rpc-core.js';
+/** Browser adapter deliberately has no resolve/createEnvironment method. */
+export function createApiKeyClient(transport) {
+    async function call(method, payload = {}) {
+        return callSettingsRpc(transport, 'apiKey', method, payload);
+    }
+    return {
+        describe: () => call('describe'), set: value => call('set', { value }), clear: () => call('clear'),
+        configureAndTest: value => call('configureAndTest', { value }), testConnection: () => call('testConnection'), getValidationStatus: () => call('getValidationStatus'),
+    };
+}

package/lib/features/api-key/contract.d.ts

@@ -0,0 +1,69 @@
+/**
+ * API Key namespace contract: the credential reference and lifecycle events,
+ * the status/validation vocabulary, and the two faces the namespace exposes
+ * (the browser-safe subset and the host-only superset).
+ *
+ * It merges its own line into the generic {@link FtshareSettingsNamespaces}
+ * merge point, so `ctx.ftshareSettings.apiKey` keeps its existing type for
+ * every consumer.
+ */
+export declare const FTSHARE_API_KEY_REF: "FTSHARE_API_KEY";
+export declare const FTSHARE_CREDENTIAL_EVENTS: readonly ["credentials/reference-updated"];
+export declare const API_KEY_METHODS: readonly ["describe", "set", "clear", "configureAndTest", "testConnection", "getValidationStatus"];
+export type ApiKeyMethod = typeof API_KEY_METHODS[number];
+export type SubscribeChanges = (listener: () => void) => () => void;
+export interface CredentialStatus {
+    configured: boolean;
+    writable: boolean;
+    source?: string;
+}
+export type ProbeState = 'available' | 'auth_required' | 'auth_failed' | 'permission_denied' | 'quota_exceeded' | 'rate_limited' | 'network_error' | 'timeout' | 'upstream_error' | 'invalid_response' | 'not_run';
+export interface ProbeResult {
+    status: ProbeState;
+    message: string;
+}
+export interface ValidationResult {
+    status: 'not_tested' | 'not_run' | 'passed' | 'partial' | 'failed' | 'superseded';
+    remote: ProbeResult;
+    apiKey: ProbeResult;
+    testedAt?: string;
+}
+export interface ApiKeyStatus extends CredentialStatus {
+    /** Display only. Fixed mask plus last four characters; never submit as a Key. */
+    maskedValue?: string;
+    revision: number;
+    validation: ValidationResult;
+}
+export interface ConfigureResult {
+    save: {
+        status: 'saved' | 'failed';
+        code?: 'invalid_input' | 'read_only' | 'save_failed';
+        message: string;
+    };
+    validation: ValidationResult;
+}
+/** Local syntax validation, never an assertion of upstream validity. */
+export declare function normalizeApiKey(input: string): string;
+export declare function untested(status?: 'not_tested' | 'not_run' | 'superseded', message?: string): ValidationResult;
+/** Everything the browser adapter may call; `resolve`/`createEnvironment` are not here. */
+export interface ApiKeyPublicApi {
+    describe(): Promise<ApiKeyStatus>;
+    set(value: string): Promise<void>;
+    clear(): Promise<void>;
+    configureAndTest(value: string): Promise<ConfigureResult>;
+    testConnection(): Promise<ValidationResult>;
+    getValidationStatus(): Promise<ValidationResult>;
+}
+/** The host namespace object: the public API plus the secret-bearing host methods. */
+export interface ApiKeySettings extends ApiKeyPublicApi {
+    readonly credentialRef: typeof FTSHARE_API_KEY_REF;
+    /** Host only. Re-resolve per operation; never send this value to browsers. */
+    resolve(): Promise<string | undefined>;
+    createEnvironment(base?: Readonly<Record<string, string | undefined>>): Promise<Record<string, string | undefined>>;
+    subscribe: SubscribeChanges;
+}
+declare module '../../core/contract.js' {
+    interface FtshareSettingsNamespaces {
+        apiKey: ApiKeySettings;
+    }
+}

package/lib/features/api-key/contract.js

@@ -0,0 +1,24 @@
+/**
+ * API Key namespace contract: the credential reference and lifecycle events,
+ * the status/validation vocabulary, and the two faces the namespace exposes
+ * (the browser-safe subset and the host-only superset).
+ *
+ * It merges its own line into the generic {@link FtshareSettingsNamespaces}
+ * merge point, so `ctx.ftshareSettings.apiKey` keeps its existing type for
+ * every consumer.
+ */
+export const FTSHARE_API_KEY_REF = 'FTSHARE_API_KEY';
+export const FTSHARE_CREDENTIAL_EVENTS = ['credentials/reference-updated'];
+export const API_KEY_METHODS = ['describe', 'set', 'clear', 'configureAndTest', 'testConnection', 'getValidationStatus'];
+/** Local syntax validation, never an assertion of upstream validity. */
+export function normalizeApiKey(input) {
+    const value = input.trim();
+    if (!value)
+        throw new Error('请输入 API Key');
+    if (value.length > 512 || /[\x00-\x1f\x7f]/.test(value))
+        throw new Error('API Key 长度不能超过 512 个字符，且不能包含控制字符');
+    return value;
+}
+export function untested(status = 'not_tested', message = '尚未测试') {
+    return { status, remote: { status: 'not_run', message }, apiKey: { status: 'not_run', message } };
+}

package/lib/features/api-key/host.d.ts

@@ -0,0 +1,17 @@
+import { type CredentialRef } from '@deepseek-ai/dsh-credentials';
+import { type ApiKeySettings } from './contract.js';
+import type { FeatureLogger } from './logging.js';
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        'credentials/reference-updated'(ref: CredentialRef): void;
+    }
+}
+/**
+ * Build the `apiKey` module, closing over the plugin's named logger.
+ *
+ * 工厂化与 `createLogsModule` 一致：插件入口在 `apply` 里取一次 `ctx.logger()`
+ * （无参 = 插件名）再传进来，因此 feature 不依赖模块级单例，也不认识 cordis。
+ * @param logger - 可选具名 logger；省略时本模块不写任何日志（既有调用方不变）。
+ * @returns 可交给 `ctx.ftshareSettings.modules.register` 的模块。
+ */
+export declare function createApiKeyModule(logger?: FeatureLogger): import("../../core/module-registry.js").SettingsModule<"apiKey", ApiKeySettings>;