dsh-skill-hub 0.0.1 → 0.2.0

package/lib/types/client/panel/SourceStatusBadge.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Source check-status badges (up-to-date / updated / deleted / error /
+ * throttled / unverified). Shared by the panel's source-group headers and
+ * the skill detail view.
+ *
+ * In the group headers the badge doubles as the re-check affordance: it
+ * shows a clickable "检查更新" badge before the first check, "检查中…" while
+ * checking, and the status badge (clickable again to re-check) afterwards.
+ */
+import type { JSX } from 'react';
+import type { SourceCheckResult } from '../../protocol.ts';
+export declare function SourceStatusBadge(props: {
+    check: SourceCheckResult | undefined;
+    /** 正在检查该来源（显示「检查中…」）。 */
+    checking?: boolean;
+    /** 提供后徽章区域可点击触发检查（组头用；详情页有自己的检查按钮）。 */
+    onCheck?: () => void;
+}): JSX.Element | null;

package/lib/types/client/panel/SourcesView.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Sources tab: the flat skill list or the grouped view (one card per
+ * upstream collection with check/sync/follow-delete actions and the
+ * tri-state switch, plus the uncategorized "personal" card).
+ */
+import type { JSX } from 'react';
+import type { SkillHubState } from './useSkillHub.ts';
+export declare function SourcesView(props: {
+    hub: SkillHubState;
+}): JSX.Element;

package/lib/types/client/panel/TagEditorView.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Full-page tag (scene) editor: rename / delete header, member checkbox
+ * lists (enabled + disabled skills), and the save-members action. Pure
+ * presentation — the draft state lives in the panel and arrives as props.
+ */
+import type { JSX } from 'react';
+import type { CatalogResponse, SkillTag } from '../../protocol.ts';
+export interface TagEditorViewProps {
+    tag: SkillTag;
+    /** Current name draft (panel-owned). */
+    editName: string;
+    /** Current member-checkbox draft (panel-owned). */
+    membersDraft: ReadonlySet<string>;
+    /** Current member-list search text (panel-owned). */
+    editSearch: string;
+    catalog: CatalogResponse | null;
+    tagBusy: boolean;
+    onBack: () => void;
+    onEditName: (value: string) => void;
+    onEditSearch: (value: string) => void;
+    onToggleMember: (name: string, checked: boolean) => void;
+    /** Rename with the current draft (disabled while blank). */
+    onRename: () => void;
+    /** Delete this tag (hidden for the default scene). */
+    onDelete: () => void;
+    /** Persist the current member draft and leave the editor. */
+    onSaveMembers: () => void;
+}
+export declare function TagEditorView(props: TagEditorViewProps): JSX.Element;

package/lib/types/client/panel/dialogs.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Shared dialog family for the panel: one overlay shell plus the specific
+ * dialogs (group-close conflict, sync/delete confirm, branch picker, and
+ * market sync selection). Every dialog closes on outside click and keeps
+ * the same role/aria shell; the panel owns all dialog state.
+ */
+import { type JSX } from 'react';
+import type { CollectionGroup, SkillTag } from '../../protocol.ts';
+/** A group-close conflict waiting for the user's decision. */
+export interface ConflictDialogState {
+    /** Group key: 'tag:<id>' or 'col:<name>'. */
+    key: string;
+    name: string;
+    /** Conflicting skill names (enabled here and in other groups). */
+    conflicts: string[];
+}
+/** A destructive/sync confirmation waiting for the user's decision. */
+export interface ConfirmDialogState {
+    kind: 'sync' | 'delete';
+    repo: string;
+    /** Skills the action applies to. */
+    skills: string[];
+}
+/** Branch picker shown when a repo has no release and no pinned ref. */
+export interface BranchChoiceState {
+    repo: string;
+    branches: string[];
+    selected: string;
+}
+/** Post-sync skill update dialog: which tracked skills to refresh. */
+export interface MarketSyncDialogState {
+    repo: string;
+    ref: string;
+    skills: string[];
+    selected: ReadonlySet<string>;
+}
+/** Simple confirm dialog: title + text + optional skill list + cancel/confirm. */
+export declare function ConfirmDialog(props: {
+    title: string;
+    text: string;
+    /** Optional skill names listed between the text and the buttons. */
+    items?: readonly string[];
+    confirmLabel: string;
+    /** Danger-styled confirm button (destructive actions). */
+    danger?: boolean;
+    onCancel: () => void;
+    onConfirm: () => void;
+}): JSX.Element;
+/** Group-close conflict: which skills stay on, and which other groups also enable them. */
+export declare function ConflictDialog(props: {
+    dialog: ConflictDialogState;
+    tags: readonly SkillTag[];
+    collections: readonly CollectionGroup[];
+    onClose: () => void;
+    onKeepOn: () => void;
+    onCloseAll: () => void;
+}): JSX.Element;
+/** Branch picker for a repo without releases (pins the ref, then rescans). */
+export declare function BranchChoiceDialog(props: {
+    choice: BranchChoiceState;
+    busy: boolean;
+    onSelect: (branch: string) => void;
+    onCancel: () => void;
+    onConfirm: () => void;
+}): JSX.Element;
+/** Post-sync selection: which tracked skills to batch-update to the new version. */
+export declare function MarketSyncDialog(props: {
+    dialog: MarketSyncDialogState;
+    busy: boolean;
+    onToggle: (name: string, checked: boolean) => void;
+    onCancel: () => void;
+    onConfirm: () => void;
+}): JSX.Element;

package/lib/types/client/panel/format.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared display helpers for the panel views (skill rows, detail view, and
+ * dialogs): dot color styling, relative/absolute time text, and commit-SHA
+ * shortening. Kept in one place so the views render identically.
+ */
+import type { CSSProperties } from 'react';
+/** Dot inline style from the user-chosen color (undefined keeps the CSS default). */
+export declare function dotStyle(color: string | undefined): CSSProperties | undefined;
+/** Localized relative-time text for a Unix-ms timestamp. */
+export declare function relativeTimeText(ms: number): string;
+/** Localized absolute time for the detail meta (e.g. "2026/8/16 11:00:00"). */
+export declare function formatDateTime(ms: number): string;
+/** Short form of a commit SHA for display. */
+export declare function shortSha(sha: string): string;

package/lib/types/client/panel/useSkillHub.d.ts

@@ -0,0 +1,183 @@
+/**
+ * useSkillHub — the panel's state owner. Everything the skill hub panel
+ * knows (catalog, groups, sources, market, dialogs, drafts) plus every
+ * async flow lives here; the panel itself only renders. All hooks run
+ * unconditionally at the top, so the panel may early-return for the detail
+ * and tag-editor views without violating the rules of hooks.
+ */
+import { type FormEvent } from 'react';
+import type { CatalogResponse, CatalogSkill, DisabledSkill, GroupsResponse, HubConfig, MarketSourceRecord, RepoDiscoverResponse, RepoImportResponse, SkillDetail, SkillTag, SourceCheckResult, SourcesResponse, UpdateCheckResponse, WritableRoot } from '../../protocol.ts';
+import type { SkillHubApi } from '../api.ts';
+import { type SortKey, type GroupSwitchState } from '../grouping.ts';
+import type { BranchChoiceState, ConfirmDialogState, ConflictDialogState, MarketSyncDialogState } from './dialogs.tsx';
+/** One-shot self-update check state. */
+type UpdateState = {
+    status: 'idle';
+} | {
+    status: 'checking';
+} | {
+    status: 'ready';
+    data: UpdateCheckResponse;
+} | {
+    status: 'error';
+    message: string;
+};
+/** Repo scanner/import state (drives the market source preview). */
+type RepoDiscoverState = {
+    status: 'idle';
+} | {
+    status: 'scanning';
+} | {
+    status: 'ready';
+    data: RepoDiscoverResponse;
+} | {
+    status: 'error';
+    message: string;
+};
+/** Market sources list state. */
+type MarketState = {
+    status: 'loading' | 'ready' | 'error';
+    repos: MarketSourceRecord[];
+};
+/** The hook's result: the panel's complete state + action surface. */
+export type SkillHubState = ReturnType<typeof useSkillHub>;
+export declare function useSkillHub(api: SkillHubApi): {
+    catalog: CatalogResponse | null;
+    loading: boolean;
+    loadError: string | null;
+    successBanner: string | null;
+    updateState: UpdateState;
+    repoDiscoverState: RepoDiscoverState;
+    scanningRepo: string | null;
+    repoSelected: ReadonlySet<string>;
+    repoImporting: boolean;
+    repoResult: RepoImportResponse | null;
+    search: string;
+    detail: SkillDetail | null;
+    detailLoading: boolean;
+    busyNames: ReadonlySet<string>;
+    batchBusy: boolean;
+    showForm: boolean;
+    formName: string;
+    formDesc: string;
+    formRoot: WritableRoot;
+    formBusy: boolean;
+    formMessage: {
+        kind: "error" | "success";
+        text: string;
+    } | null;
+    uses: ReadonlyMap<string, {
+        count: number;
+        lastUsed?: number;
+    }>;
+    hubConfig: HubConfig | null;
+    tab: "sources" | "scenes" | "market";
+    skillView: "flat" | "groups";
+    sourceFilter: string;
+    sortKey: SortKey;
+    marketState: MarketState;
+    marketCheck: Readonly<Record<string, {
+        repo: string;
+        ref?: string;
+        latestTag?: string;
+        updateAvailable: boolean;
+        commitSha: string;
+        throttled?: boolean;
+        error?: string;
+    }>>;
+    branchChoice: BranchChoiceState | null;
+    branchBusy: boolean;
+    marketSyncDialog: MarketSyncDialogState | null;
+    syncingMarket: string | null;
+    syncBusy: boolean;
+    newSourceName: string;
+    groupsState: GroupsResponse | null;
+    sourcesState: SourcesResponse | null;
+    sourceCheck: Readonly<Record<string, SourceCheckResult>>;
+    checkingSource: string | null;
+    syncingSource: string | null;
+    conflictDialog: ConflictDialogState | null;
+    confirmDialog: ConfirmDialogState | null;
+    deleteSkillDialog: string | null;
+    confirmClearTrash: boolean;
+    updateAllDialog: boolean;
+    editingTag: SkillTag | null;
+    editName: string;
+    membersDraft: ReadonlySet<string>;
+    newTagName: string;
+    tagBusy: boolean;
+    editSearch: string;
+    collapsedGroups: ReadonlySet<string>;
+    showLegend: boolean;
+    actionNames: Set<string>;
+    viewNames: Set<string>;
+    normalized: string;
+    origins: Record<string, string>;
+    sourceOptions: string[];
+    filtered: CatalogSkill[];
+    sorted: CatalogSkill[];
+    setLoadError: import("react").Dispatch<import("react").SetStateAction<string | null>>;
+    setSuccessBanner: import("react").Dispatch<import("react").SetStateAction<string | null>>;
+    setSearch: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setDetail: import("react").Dispatch<import("react").SetStateAction<SkillDetail | null>>;
+    setShowForm: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setFormName: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setFormDesc: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setFormRoot: import("react").Dispatch<import("react").SetStateAction<WritableRoot>>;
+    setFormMessage: import("react").Dispatch<import("react").SetStateAction<{
+        kind: "error" | "success";
+        text: string;
+    } | null>>;
+    setRepoSelected: import("react").Dispatch<import("react").SetStateAction<ReadonlySet<string>>>;
+    setTab: import("react").Dispatch<import("react").SetStateAction<"sources" | "scenes" | "market">>;
+    setSkillView: import("react").Dispatch<import("react").SetStateAction<"flat" | "groups">>;
+    setSourceFilter: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setSortKey: import("react").Dispatch<import("react").SetStateAction<SortKey>>;
+    setBranchChoice: import("react").Dispatch<import("react").SetStateAction<BranchChoiceState | null>>;
+    setMarketSyncDialog: import("react").Dispatch<import("react").SetStateAction<MarketSyncDialogState | null>>;
+    setNewSourceName: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setConflictDialog: import("react").Dispatch<import("react").SetStateAction<ConflictDialogState | null>>;
+    setConfirmDialog: import("react").Dispatch<import("react").SetStateAction<ConfirmDialogState | null>>;
+    setDeleteSkillDialog: import("react").Dispatch<import("react").SetStateAction<string | null>>;
+    setConfirmClearTrash: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setUpdateAllDialog: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setEditingTag: import("react").Dispatch<import("react").SetStateAction<SkillTag | null>>;
+    setEditName: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setMembersDraft: import("react").Dispatch<import("react").SetStateAction<ReadonlySet<string>>>;
+    setNewTagName: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setEditSearch: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setShowLegend: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    toggleGroupCollapse: (key: string) => void;
+    checkUpdate: () => Promise<void>;
+    loadMarket: () => Promise<void>;
+    openDetail: (name: string) => Promise<void>;
+    toggle: (skill: CatalogSkill, enabled: boolean) => Promise<void>;
+    enableDisabled: (record: DisabledSkill) => Promise<void>;
+    batchToggleNames: (names: string[], enabled: boolean) => Promise<void>;
+    toggleGroup: (key: string, name: string, view: GroupSwitchState) => void;
+    resolveConflict: (closeAll: boolean) => Promise<void>;
+    runConfirmed: () => Promise<void>;
+    checkSources: (repo?: string) => Promise<void>;
+    requestSync: (repo: string, skills: string[]) => void;
+    requestDelete: (repo: string, skills: string[]) => void;
+    restoreTrash: (name: string) => Promise<void>;
+    clearTrash: () => Promise<void>;
+    requestDeleteSkill: (name: string) => void;
+    runDeleteSkill: () => Promise<void>;
+    createTag: (event: FormEvent) => Promise<void>;
+    deleteTag: (id: string) => Promise<void>;
+    saveTag: (id: string, name: string, memberNames: string[] | null) => Promise<void>;
+    addSource: (input: string) => Promise<void>;
+    addMarketSource: () => Promise<void>;
+    removeMarketSource: (repo: string) => Promise<void>;
+    scanRepo: (input: string) => Promise<void>;
+    confirmBranchChoice: () => Promise<void>;
+    toggleRepoSelected: (path: string, checked: boolean) => void;
+    importRepo: () => Promise<void>;
+    checkMarket: () => Promise<void>;
+    syncMarketSource: (repo: string) => Promise<void>;
+    confirmMarketSync: () => Promise<void>;
+    updateAll: () => Promise<void>;
+    create: (event: FormEvent) => Promise<void>;
+};
+export {};

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

@@ -0,0 +1,81 @@
+/**
+ * Shared chrome for the plugin settings card, aligned with the official
+ * dsh-client-ui-settings-plugins PluginCard design language: the same tokens,
+ * disclosure header, field rhythm, and copy. Renders nothing while the
+ * namespace is unavailable — a deployment that does not compose the owning
+ * plugin should show no trace of it.
+ */
+import { type ReactElement } from 'react';
+import type { CardShell } from './settings-form.ts';
+/** Card-level chrome props. */
+export interface PluginSettingsCardProps {
+    /** Locale translator for the owning plugin's namespace. */
+    t: (key: string) => string;
+    /** Locale key of the card title. */
+    titleKey: string;
+    /** Locale key of the card description. */
+    descriptionKey: string;
+    /** The form shell state. */
+    state: CardShell;
+    onSave: () => void;
+    onDiscard: () => void;
+    children?: ReactElement | ReactElement[];
+}
+/**
+ * Render one plugin settings card.
+ * @param props - the plugin's copy keys, its form state, and its controls.
+ * @returns the card, or nothing while the namespace is still loading.
+ */
+export declare function PluginSettingsCard(props: PluginSettingsCardProps): ReactElement | null;
+/** One staged boolean field: 继承 / 开 / 关. */
+export interface BooleanFieldProps {
+    id: string;
+    label: string;
+    hint: string;
+    inheritLabel: string;
+    onLabel: string;
+    offLabel: string;
+    overriddenLabel: string;
+    resetLabel: string;
+    disabled: boolean;
+    text: string;
+    overridden: boolean;
+    onEdit: (text: string) => void;
+    onReset: () => void;
+}
+export declare function BooleanField(props: BooleanFieldProps): ReactElement;
+/**
+ * A compact sliding switch for the card's master enable/disable control.
+ * An empty text value means the field inherits its default; the switch still
+ * reflects the effective default and becomes an explicit override on click.
+ */
+export interface SwitchFieldProps {
+    label: string;
+    hint: string;
+    disabled: boolean;
+    text: string;
+    overridden: boolean;
+    overriddenLabel: string;
+    resetLabel: string;
+    onEdit: (text: string) => void;
+    onReset: () => void;
+}
+export declare function SwitchField(props: SwitchFieldProps): ReactElement;
+/** One staged color field: a native color picker plus the hex draft text. */
+export interface ColorFieldProps {
+    id: string;
+    label: string;
+    hint: string;
+    inheritLabel: string;
+    overriddenLabel: string;
+    resetLabel: string;
+    disabled: boolean;
+    /** Effective hex (#rrggbb) when overridden; empty string means inherit. */
+    text: string;
+    /** The default color the picker shows while inheriting (per-field). */
+    defaultColor: string;
+    overridden: boolean;
+    onEdit: (text: string) => void;
+    onReset: () => void;
+}
+export declare function ColorField(props: ColorFieldProps): ReactElement;

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

@@ -0,0 +1,95 @@
+/**
+ * Settings-card form machinery, vendored from the dsh-web-ui family bucket
+ * (packages/dsh-task-board/src/client/settings-form.ts) and re-typed. Stages
+ * one card's edits over one settings namespace and writes them on save.
+ *
+ * The Host is the only authority on whether a value was accepted — its
+ * validators own the constraints no schema can express — so the outcome is
+ * read back from the section rather than predicted here. A save that did not
+ * land keeps its drafts, so the user can correct them instead of retyping.
+ */
+/** One editable field spec: formatting plus text parsing. */
+export interface FieldSpec {
+    field: string;
+    format: (value: unknown) => string;
+    parse: (text: string) => {
+        kind: 'set';
+        value: unknown;
+    } | {
+        kind: 'clear';
+    } | undefined;
+}
+/** A boolean field, edited through true/false draft text. */
+export declare function booleanField(field: string): FieldSpec;
+/** A #rrggbb color field, edited through hex draft text. */
+export declare function colorField(field: string): FieldSpec;
+/** Card-level state the chrome renders. */
+export interface CardShell {
+    available: boolean;
+    exposed: boolean;
+    writable: boolean;
+    dirty: boolean;
+    invalid: boolean;
+    saving: boolean;
+    failed: boolean;
+}
+/** One field's state from the effective section and its staged draft. */
+export interface FieldState {
+    text: string;
+    overridden: boolean;
+    invalid: boolean;
+}
+/** The settings scope face the form consumes (subset of SettingsScope<T>). */
+export interface FormScope {
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): {
+        status: string;
+        writable: boolean;
+        value?: Record<string, unknown>;
+        base?: unknown;
+        user?: unknown;
+    };
+    set(field: string, value: unknown): Promise<void>;
+    unset(field: string): Promise<void>;
+}
+/** Stages one card's edits and writes them through the settings transport. */
+export declare class CardForm {
+    private readonly scope;
+    private readonly specs;
+    private readonly staged;
+    private readonly listeners;
+    private saving;
+    private failed;
+    /** @param scope - the bound settings scope for this card's namespace. */
+    constructor(scope: FormScope, specs: FieldSpec[]);
+    /** Publish a projection of this form, rebuilt whenever the scope or a draft changes. */
+    bind<T>(project: () => T): import("@deepseek-ai/dsh-client-runtime/client").SnapshotStore<T>;
+    /** Read the card-level state: what the Host serves, and what a save would do. */
+    shell(): CardShell;
+    /** Read one field's state from the effective section and its staged draft. */
+    field(field: string): FieldState;
+    /** The actions the card's slot registration injects. */
+    actions(): {
+        edit: (field: string, text: string) => void;
+        resetField: (field: string) => void;
+        save: () => void;
+        discard: () => void;
+    };
+    /** Write every staged edit, then re-seed from what the Host accepted. */
+    save(): Promise<void>;
+    /** Every staged edit a save would write, in staging order. */
+    plan(): Array<{
+        field: string;
+        run: (() => Promise<boolean>) | undefined;
+    }>;
+    private clear;
+    private store;
+    private userRecord;
+    private stage;
+    private specOf;
+    private sectionValue;
+    private baseValue;
+    private userLayer;
+    private stored;
+    private publish;
+}

package/lib/types/client/settings-nav-icon.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The settings shell renders section nav icons from a hard-coded id map and
+ * exposes no registrant icon option, so the skill-hub section falls back to
+ * the generic gear. This scoped DOM patch swaps in the official skill icon
+ * whenever the settings dialog re-renders.
+ */
+/** Swap the settings nav gear for the skill icon and keep it in sync. */
+export declare function applySettingsNavIcon(): () => void;

package/lib/types/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * dsh-skill-hub — host half. Mounts the /api/skill-hub route family (full
+ * skill catalog from the official ctx.skills registry, skill detail,
+ * enable/disable toggle, new-skill scaffold) plus a system-prompt
+ * announcement. The browser half (./client) renders the sidebar entry and
+ * the skill hub panel. Everything rides official NPM SDK packages — no dsh
+ * source changes.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from 'schemastery';
+/** Stable cordis plugin name (matches cordis.patch.yml insert id). */
+export declare const name = "skill-hub";
+/** Services required before the skill-hub surfaces can mount. */
+export declare const inject: string[];
+/** Plugin config, validated by the same-named schemastery schema. */
+export interface Config {
+    /** When true (default), a system-prompt section announces the hub to every agent. */
+    announceToAgent?: boolean;
+    /** Master switch for the plugin (routes, prompt section). */
+    enabled?: boolean;
+    /** Show per-skill invocation count chip. Default true. */
+    showUseCount?: boolean;
+    /** Show per-skill last-used relative time. Default true. */
+    showUseTime?: boolean;
+    /** Show group-header usage summaries (count + last used). Default true. */
+    showGroupSummary?: boolean;
+}
+export declare const Config: z<Config>;
+/** Model-facing announcement: plugin presence, capabilities, and limits. */
+export declare const SKILL_HUB_GUIDANCE: string;
+/**
+ * Mount the skill hub routes and announcement.
+ * @param ctx - host plugin context carrying webServer/skills/systemPrompt.
+ * @param config - resolved plugin config (schema defaults applied by the loader).
+ */
+export declare function apply(ctx: Context, config?: Config): void;

package/lib/types/invariant.d.ts

@@ -0,0 +1,3 @@
+/** Invariant companion plugin (no assertions — nothing to check at runtime). */
+/** Provides no assertions: the skill-hub owns no cross-package runtime invariants. */
+export declare function apply(): void;