@nanmicoder/dsh-skills-hub 0.0.1 → 0.0.3

package/lib/skills/management.js

@@ -1,10 +1,31 @@
-/** Local management only addresses entries freshly discovered inside configured user roots. */
+/**
+ * Local skill management: one discovered entry at a time.
+ *
+ * Every function here starts from a key, never from a client-supplied path: the
+ * roots are re-scanned on each call, and only an entry that scan just produced
+ * can be read or removed. A path that arrives from the browser is therefore
+ * always interpreted *inside* an entry this process has already vouched for.
+ *
+ * The detail read is what the panel's local skill page renders: the SKILL.md
+ * document, its raw frontmatter block and a bounded inventory of the skill's own
+ * files. Nothing here consults a market provider — an installed skill stays
+ * readable with the network down.
+ */
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import { readBoundedText } from "./read-text.js";
 import { randomUUID } from 'node:crypto';
 import { MarketInstallError } from "../market/install-service.js";
+import { detectMarketLanguage } from "../market/types.js";
 import { scanInstalledSkills } from "./installed.js";
+import { readBoundedText } from "./read-text.js";
+/** Largest SKILL.md the local detail endpoint returns, matching the market preview policy. */
+const MAX_DOCUMENT_BYTES = 2 * 1024 * 1024;
+/** Largest single document the browser may pull into the file viewer. */
+const MAX_PREVIEW_BYTES = 300 * 1024;
+/** Frontmatter kept for the metadata panel; a pathological header cannot fill it. */
+const MAX_FRONTMATTER_BYTES = 16 * 1024;
+/** Entries listed for one skill before the walk stops. */
+const MAX_LISTED_FILES = 500;
 async function resolveEntry(roots, key) {
     if (!/^[a-f0-9]{64}$/.test(key))
         throw new MarketInstallError(400, 'BAD_REQUEST', 'Invalid installed skill key');
@@ -13,15 +34,172 @@ async function resolveEntry(roots, key) {
         throw new MarketInstallError(404, 'MARKET_NOT_INSTALLED', 'Installed skill no longer exists');
     return entry;
 }
+/**
+ * Raw frontmatter block, kept as YAML text.
+ *
+ * Parsing it into structure would mean shipping a YAML reader for a panel that
+ * only needs to *show* the header, and the market detail's structured panel is
+ * fed by upstream JSON this plugin does not have for a hand-written skill. The
+ * verbatim block is also what the file actually contains, so nothing is lost.
+ */
+export function extractFrontmatter(markdown) {
+    const text = markdown.startsWith('\uFEFF') ? markdown.slice(1) : markdown;
+    const lines = text.split(/\r?\n/);
+    if (lines[0]?.trim() !== '---')
+        return null;
+    for (let index = 1; index < lines.length; index++) {
+        const marker = (lines[index] ?? '').trim();
+        if (marker !== '---' && marker !== '...')
+            continue;
+        const block = lines.slice(1, index).join('\n').trim();
+        return block === '' ? null : block.slice(0, MAX_FRONTMATTER_BYTES);
+    }
+    // Unterminated header: the document is ordinary Markdown, as the browser's
+    // strip helper already assumes.
+    return null;
+}
+/**
+ * Inventory one entry's own files.
+ *
+ * The walk never leaves the entry: directories are descended, symlinked entries
+ * are listed as nothing at all, and the provenance sidecar (a dot-file, like
+ * every other dot-entry) is skipped because it is plugin bookkeeping rather than
+ * installed payload. A flat skill is a single file and reports itself.
+ */
+export async function listEntryFiles(item) {
+    const stats = await fs.stat(item.dirPath);
+    if (!stats.isDirectory()) {
+        return [{ path: path.basename(item.dirPath), size: stats.size, language: detectMarketLanguage(item.dirPath) }];
+    }
+    const files = [];
+    const pending = [''];
+    while (pending.length > 0 && files.length < MAX_LISTED_FILES) {
+        const relativeDir = pending.pop();
+        if (relativeDir === undefined)
+            break;
+        const absoluteDir = relativeDir === '' ? item.dirPath : path.join(item.dirPath, relativeDir);
+        let entries;
+        try {
+            entries = await fs.readdir(absoluteDir, { withFileTypes: true });
+        }
+        catch {
+            // Raced with a concurrent removal — list what is still there.
+            continue;
+        }
+        entries.sort((left, right) => left.name.localeCompare(right.name));
+        for (const entry of entries) {
+            if (files.length >= MAX_LISTED_FILES)
+                break;
+            if (entry.name.startsWith('.'))
+                continue;
+            const relative = relativeDir === '' ? entry.name : `${relativeDir}/${entry.name}`;
+            if (entry.isDirectory()) {
+                pending.push(relative);
+                continue;
+            }
+            // `isFile()` excludes symlinks: a linked file is not part of the payload.
+            if (!entry.isFile())
+                continue;
+            try {
+                const fileStats = await fs.lstat(path.join(absoluteDir, entry.name));
+                if (!fileStats.isFile())
+                    continue;
+                files.push({ path: relative, size: fileStats.size, language: detectMarketLanguage(entry.name) });
+            }
+            catch {
+                // Raced with a concurrent removal.
+            }
+        }
+    }
+    files.sort((left, right) => left.path.localeCompare(right.path));
+    return files;
+}
+/**
+ * Validate one browser-supplied relative path.
+ *
+ * Absolute paths, `..` segments, empty segments and NUL are rejected outright;
+ * the caller then proves containment against the entry's real path, so a
+ * traversal cannot be smuggled in through either spelling or a symlink.
+ */
+function requireRelativePath(value) {
+    const normalized = value.replace(/\\/g, '/').replace(/^\.\//, '');
+    if (normalized === '' || normalized.includes('\0') || path.isAbsolute(normalized)) {
+        throw new MarketInstallError(400, 'BAD_REQUEST', 'Invalid skill file path');
+    }
+    const segments = normalized.split('/');
+    if (segments.some(segment => segment === '' || segment === '.' || segment === '..')) {
+        throw new MarketInstallError(400, 'BAD_REQUEST', 'Invalid skill file path');
+    }
+    return segments.join('/');
+}
+/** Whether `candidate` is `root` itself or sits underneath it. */
+function contains(root, candidate) {
+    return candidate === root || candidate.startsWith(root.endsWith(path.sep) ? root : `${root}${path.sep}`);
+}
+/** Read the SKILL.md document plus the entry inventory the local detail page renders. */
 export async function readInstalledSkill(roots, key) {
     const item = await resolveEntry(roots, key);
     const stats = await fs.stat(item.dirPath);
     const file = stats.isDirectory() ? path.join(item.dirPath, 'SKILL.md') : item.dirPath;
-    const content = await readBoundedText(file, 2 * 1024 * 1024);
+    const content = await readBoundedText(file, MAX_DOCUMENT_BYTES);
     if (content.truncated) {
         throw new MarketInstallError(413, 'FILE_TOO_LARGE', 'Skill preview exceeds 2 MB');
     }
-    return { item, markdown: content.text };
+    return {
+        item,
+        markdown: content.text,
+        frontmatter: extractFrontmatter(content.text),
+        files: await listEntryFiles(item),
+    };
+}
+/**
+ * Read one file of one entry.
+ *
+ * A flat skill exposes exactly itself — never its siblings in the same root —
+ * and a directory bundle exposes only what resolves back inside its own real
+ * path, so a symlink planted in the tree cannot turn this endpoint into an
+ * arbitrary-file reader.
+ */
+export async function readInstalledFile(roots, key, requested) {
+    const item = await resolveEntry(roots, key);
+    const relative = requireRelativePath(requested);
+    const stats = await fs.stat(item.dirPath);
+    let documentPath;
+    if (stats.isDirectory()) {
+        const base = await fs.realpath(item.dirPath);
+        const candidate = path.resolve(base, relative);
+        if (!contains(base, candidate))
+            throw new MarketInstallError(400, 'BAD_REQUEST', 'Invalid skill file path');
+        let resolved;
+        try {
+            resolved = await fs.realpath(candidate);
+        }
+        catch {
+            throw new MarketInstallError(404, 'MARKET_NOT_INSTALLED', 'Skill file no longer exists');
+        }
+        if (!contains(base, resolved)) {
+            throw new MarketInstallError(400, 'BAD_REQUEST', 'Skill file escapes its directory');
+        }
+        documentPath = resolved;
+    }
+    else {
+        if (relative !== path.basename(item.dirPath)) {
+            throw new MarketInstallError(400, 'BAD_REQUEST', 'Invalid skill file path');
+        }
+        documentPath = await fs.realpath(item.dirPath);
+    }
+    const documentStats = await fs.stat(documentPath);
+    if (!documentStats.isFile())
+        throw new MarketInstallError(400, 'BAD_REQUEST', 'Skill file is not a document');
+    const content = await readBoundedText(documentPath, MAX_PREVIEW_BYTES);
+    return {
+        path: relative,
+        content: content.text,
+        language: detectMarketLanguage(relative),
+        size: documentStats.size,
+        // Truncation is not an error: the browser labels the partial document.
+        truncated: content.truncated,
+    };
 }
 /** Rename the selected entry out of discovery before deletion. Symlink targets are never removed. */
 export async function removeInstalledSkill(roots, key, allowUninstall) {

package/lib/skills/root.js

@@ -49,7 +49,7 @@ function expandHomePath(value) {
  * blank `$DSH_HOME` is treated as unset so a stray empty variable can never
  * resolve the harness home to the current working directory.
  */
-function resolveDshHome(configured) {
+export function resolveDshHome(configured) {
     if (typeof configured === 'string' && configured.trim() !== '') {
         return path.resolve(expandHomePath(configured.trim()));
     }

package/lib/types/catalog/catalog.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Curated catalogue — the marketplace's home list.
+ *
+ * The upstream registries hold ~80k ClawHub and ~110k SkillHub skills; nobody
+ * chooses from that. The home list is instead a few hundred skills reviewed in
+ * this repository (`catalog/curation.json`) and snapshotted by
+ * `scripts/catalog-refresh.mjs` into `skills.json`, which ships with the plugin.
+ *
+ * Only the *list* comes from the snapshot. Opening a card, reading a file and
+ * installing still go to the owning registry (through the usual cache), so a
+ * reader never installs the snapshot's version of anything.
+ */
+import { type MarketCategory, type MarketSource, type NormalizedSkill, type SecurityStatus } from '../market/types.ts';
+export type CatalogEntry = {
+    source: MarketSource;
+    slug: string;
+    /** Registry owner; disambiguates ClawHub slugs shared by several authors. */
+    owner: string;
+    name: string;
+    /** Reader-facing summary (zh-CN). */
+    summary: string;
+    /** Original upstream summary, kept for English readers and search. */
+    summaryEn?: string;
+    /** Key into `categories`. */
+    category: string;
+    tags: string[];
+    /** Editor's pick: listed first and marked on the card. */
+    featured?: boolean;
+    stats: {
+        downloads: number;
+        installs?: number;
+        stars?: number;
+    };
+    version?: string;
+    updatedAt?: number;
+    iconUrl?: string;
+    security: SecurityStatus;
+    /** Why the security verdict is what it is, when it is not clean. */
+    securityNote?: string;
+    requiresApiKey?: boolean;
+    license?: string;
+};
+export type CatalogFile = {
+    version: 1;
+    /** Epoch millis of the upstream reads behind this snapshot. */
+    generatedAt: number;
+    categories: Array<{
+        key: string;
+        name: string;
+        nameEn: string;
+    }>;
+    skills: CatalogEntry[];
+};
+export declare function getCatalog(): CatalogFile;
+export declare function catalogEntryFor(source: MarketSource, slug: string): CatalogEntry | undefined;
+/** Category bar entries, in editorial order, with how many skills each holds. */
+export declare function catalogCategories(): Array<MarketCategory & {
+    count: number;
+}>;
+/** ClawHub owners the catalogue pins, for the provider's slug disambiguation. */
+export declare function catalogClawhubOwners(): Array<readonly [string, string]>;
+export declare function catalogEntryToSkill(entry: CatalogEntry): NormalizedSkill;
+/**
+ * Entries matching every whitespace-separated term, in catalogue order.
+ *
+ * A name/slug hit ranks above a summary or tag hit: typing a skill's name
+ * should put that skill first, not the one that mentions it most.
+ */
+export declare function filterCatalog(params: {
+    q?: string;
+    category?: string;
+    source?: 'all' | MarketSource;
+}): CatalogEntry[];

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

@@ -9,7 +9,7 @@
  * never a value from the Host's `src/market/*`, which would drag Node code into
  * the browser bundle (contract §2).
  */
-import type { MarketFileContent, MarketListResult, MarketSource, NormalizedSkill, NormalizedSkillDetail, SecurityStatus, SourceStatusInfo } from '../market/types.ts';
+import type { MarketCategoriesResult, MarketFileContent, MarketListResult, MarketSource, NormalizedSkill, NormalizedSkillDetail, SecurityStatus, SourceStatusInfo } from '../market/types.ts';
 /**
  * Structural mirror of the Host's `InstalledSkillRecord`
  * (`src/skills/installed.ts`, contract §5.2).
@@ -29,6 +29,8 @@ export interface InstalledSkillRecord {
     id: string;
     source: MarketSource | 'local';
     slug: string;
+    /** Registry author recorded at install time, when known. */
+    owner?: string;
     name: string;
     dirName: string;
     dirPath: string;
@@ -43,6 +45,10 @@ export interface InstalledSkillRecord {
 /** List query accepted by `GET /api/skills-hub/skills`. */
 export interface MarketQuery {
     q?: string;
+    /** `catalog` (default): the curated list. `market`: live upstream search. */
+    scope?: 'catalog' | 'market';
+    /** Catalogue category key; `'all'` (or absent) means no category filter. */
+    category?: string;
     source: 'all' | MarketSource;
     security: 'all' | SecurityStatus;
     installed: 'all' | 'installed' | 'installable';
@@ -68,14 +74,21 @@ export declare class SkillsHubApiError extends Error {
  */
 export declare function isAbortError(error: unknown): boolean;
 /** Search the catalogue (market sources) — the remote list page. */
-export declare function fetchMarketList(query: MarketQuery, signal?: AbortSignal): Promise<MarketListResult>;
+export declare function fetchMarketList(query: MarketQuery, signal?: AbortSignal, options?: {
+    refresh?: boolean;
+}): Promise<MarketListResult>;
+/** The category bar's entries (curated catalogue), with the snapshot's provenance. */
+export declare function fetchMarketCategories(signal?: AbortSignal): Promise<MarketCategoriesResult>;
 /** One skill's full detail plus the health of the source that served it. */
-export declare function fetchSkillDetail(id: string, signal?: AbortSignal): Promise<{
+export declare function fetchSkillDetail(id: string, signal?: AbortSignal, options?: {
+    refresh?: boolean;
+    owner?: string;
+}): Promise<{
     skill: NormalizedSkillDetail;
     sourceStatus: SourceStatusInfo;
 }>;
 /** One file of a skill, for the Files tab. */
-export declare function fetchSkillFile(id: string, path: string, signal?: AbortSignal): Promise<MarketFileContent>;
+export declare function fetchSkillFile(id: string, path: string, signal?: AbortSignal, owner?: string): Promise<MarketFileContent>;
 /** Health of every market source, refreshed independently of the list. */
 export declare function fetchSourceStatus(signal?: AbortSignal): Promise<Record<MarketSource, SourceStatusInfo>>;
 /**
@@ -85,7 +98,7 @@ export declare function fetchSourceStatus(signal?: AbortSignal): Promise<Record<
  */
 export declare function fetchInstalled(signal?: AbortSignal): Promise<InstalledSkillRecord[]>;
 /** Install a market skill into the local skills directory. */
-export declare function installSkill(id: string): Promise<{
+export declare function installSkill(id: string, owner?: string): Promise<{
     installedPath: string;
     skill: NormalizedSkill;
 }>;
@@ -94,11 +107,35 @@ export declare function uninstallSkill(id: string): Promise<{
     removedPath: string;
     skill: NormalizedSkill;
 }>;
-/** Preview the exact local copy without consulting a market provider. */
-export declare function fetchInstalledDetail(key: string, signal?: AbortSignal): Promise<{
+/**
+ * One file of an installed skill, as the file tab lists it.
+ *
+ * `language` is the Host's mapping from the file extension and `size` is the
+ * real size on disk, so a truncated preview still reports the document it came
+ * from rather than the bytes that fit through the endpoint.
+ */
+export interface InstalledFileEntry {
+    path: string;
+    size: number;
+    language: string;
+}
+/**
+ * The local skill page's payload.
+ *
+ * `markdown` is the whole SKILL.md (frontmatter included) and `frontmatter` is
+ * that same header as YAML text: the market detail's structured metadata panel
+ * is fed by upstream JSON, and a hand-written skill has no such record.
+ */
+export interface InstalledSkillDetail {
     item: InstalledSkillRecord;
     markdown: string;
-}>;
+    frontmatter: string | null;
+    files: InstalledFileEntry[];
+}
+/** Preview the exact local copy without consulting a market provider. */
+export declare function fetchInstalledDetail(key: string, signal?: AbortSignal): Promise<InstalledSkillDetail>;
+/** One file of an installed skill; the Host validates the key and contains the path. */
+export declare function fetchInstalledFile(key: string, path: string, signal?: AbortSignal): Promise<MarketFileContent>;
 /** Remove a specifically selected local entry after the management UI confirmation. */
 export declare function removeInstalled(key: string): Promise<{
     item: InstalledSkillRecord;

package/lib/types/client/components/CategoryBar.d.ts

@@ -0,0 +1,13 @@
+import type { MarketCategory } from '../../market/types.ts';
+/**
+ * Category chips above the curated catalogue.
+ *
+ * The categories are the catalogue's own, so every chip has skills behind it
+ * and its count is exact. Rendered only once they loaded.
+ */
+export declare function CategoryBar(props: {
+    categories: MarketCategory[];
+    active: string;
+    disabled: boolean;
+    onSelect: (category: string) => void;
+}): JSX.Element | null;

package/lib/types/client/components/FilterBar.d.ts

@@ -8,6 +8,10 @@ import type { MarketFilters } from '../state.ts';
  * platform keyboard behaviour, a real label association, and renders inside a
  * 720px panel without a portal.
  *
+ * The search field is a draft: typing only edits local state, and the query is
+ * submitted on Enter (or when the field is emptied/cleared). Enter during IME
+ * composition confirms the candidate and must not submit.
+ *
  * The result count is announced through a visually hidden live region instead
  * of being printed twice: the visible count lives in the home header, and a
  * screen reader still hears it change when a filter narrows the list.

package/lib/types/client/components/InstallConfirmDialog.d.ts

@@ -1,25 +1,34 @@
-import type { MarketSource, SecurityStatus } from '../../market/types.ts';
+import type { MarketSource, NormalizedSkillDetail, SecurityStatus } from '../../market/types.ts';
 /** The subset of a skill the confirmation needs; the caller owns the source object. */
 export interface InstallConfirmSkill {
     id: string;
     name: string;
     source: MarketSource;
     version?: string;
+    iconUrl?: string;
     securityStatus: SecurityStatus;
     authorName: string;
+    /**
+     * The loaded detail, when the dialog was opened from the detail page: only
+     * then are the skill's files known, and with them what it will be able to do.
+     */
+    detail?: NormalizedSkillDetail;
+    /**
+     * When the catalogue data behind this dialog was read from upstream, if it
+     * came from a snapshot. Installing is a trust decision, so the confirmation
+     * cannot present a cached security verdict as a fresh one.
+     */
+    snapshotAt?: number;
 }
 /**
- * Install confirmation.
+ * Install confirmation (design: install dialog of the detail page).
  *
- * Mounted only while a confirmation is pending — the frozen props carry no
- * `skill | null` and no `open`, so the caller's conditional render *is* the
- * open state (the optional `open` prop exists only for a caller that prefers
- * to keep the element mounted).
- *
- * Escape and mask-click closing come from `Modal` itself; while `busy` both
- * are neutralised and the buttons are disabled, because an install already in
- * flight cannot be recalled and a dialog that vanishes mid-request reads as a
- * cancel that never happened.
+ * Mounted only while a confirmation is pending. A skill that is not scanned
+ * clean (flagged or unknown) needs an explicit acknowledgement before the
+ * confirm button arms: installing is a trust decision about a third party, and
+ * the dialog says so instead of making it a reflex click. Escape and mask-click
+ * come from `Modal`; while `busy` both are neutralised, because an install in
+ * flight cannot be recalled.
  */
 export declare function InstallConfirmDialog(props: {
     skill: InstallConfirmSkill;

package/lib/types/client/components/InstalledSkillDetail.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Installed skill detail page.
+ *
+ * The list's "view" affordance used to open a 380px confirmation-style modal,
+ * which is the wrong container for a document: SKILL.md is a page of prose with
+ * tables and code, and the marketplace already answers the same question with a
+ * full-panel page. This page is that same reading surface (`SkillDetailShell`),
+ * fed by the filesystem instead of a provider.
+ *
+ * What it deliberately does *not* do is pretend a local skill is a market
+ * entry. There is no author, download count or security report to show, so
+ * those rows are absent rather than zero. Where the two identities do meet —
+ * a skill installed from a market, proven by its `.skills-hub.json` sidecar —
+ * the page links to the market detail instead of duplicating it, which keeps
+ * upstream data upstream and this page readable with the network down.
+ */
+import { type InstalledSkillRecord } from '../api.ts';
+export declare function InstalledSkillDetail(props: {
+    item: InstalledSkillRecord;
+    onBack: () => void;
+    onUninstall: (item: InstalledSkillRecord) => void;
+    /** Open the same skill's market page; only offered for market provenance. */
+    onOpenMarket: (id: string, owner?: string) => void;
+}): JSX.Element;

package/lib/types/client/components/InstalledSkills.d.ts

@@ -1,3 +1,20 @@
-export declare function InstalledSkills({ onChanged }: {
+/**
+ * Installed skills: the local inventory and its reading page.
+ *
+ * Two views, one component. The detail page replaces the list *inside* this
+ * component rather than in `MarketPage`, so the list is never unmounted: the
+ * search query, the loaded rows and the scroll position are all still there when
+ * the reader comes back. That is also why the selected row is stored as a key
+ * and resolved against the current rows — a refresh that drops the entry closes
+ * the page instead of leaving it pointing at something that no longer exists.
+ *
+ * Removal stays a confirmation modal on purpose: it is a short yes/no about a
+ * destructive action, which is exactly what the primitive's dialog is for. The
+ * skill's *content* is not, which is why it moved to a page.
+ */
+export declare function InstalledSkills(props: {
+    /** A removal changed the local inventory; the market half refreshes too. */
     onChanged: () => void;
+    /** Open the market page of a skill that came from a market. */
+    onOpenMarket: (id: string, owner?: string) => void;
 }): JSX.Element;

package/lib/types/client/components/MarkdownView.d.ts

@@ -1,4 +1,10 @@
-/** Self-contained GFM rendering for untrusted marketplace and local skill docs. */
+/**
+ * Self-contained GFM rendering for untrusted marketplace and local skill docs.
+ *
+ * Raw HTML is skipped and external links are opened with `noopener noreferrer`;
+ * the typography lives in the detail shell so a rendered document looks the same
+ * in the overview tab and in the file viewer.
+ */
 export declare function MarkdownView({ content }: {
     content: string;
 }): JSX.Element;

package/lib/types/client/components/MarketSkillDetail.d.ts

@@ -0,0 +1,34 @@
+import type { NormalizedSkillDetail } from '../../market/types.ts';
+import type { MarketController, MarketState } from '../state.ts';
+import { type Translate } from '../locale-context.tsx';
+import { type Capability } from '../skill-insights.ts';
+/** Compact counts: 482069 → 482.1k. */
+export declare function formatCount(value: number): string;
+/** Upstream timestamps are epoch millis; render as an ISO date (stable across locales). */
+export declare function formatDate(timestamp: number | undefined): string;
+/** Only absolute http(s) links from upstream may become an `href`. */
+export declare function safeUrl(url: string | undefined): string | undefined;
+/** One capability, phrased with its evidence. */
+export declare function capabilityText(t: Translate, capability: Capability): {
+    title: string;
+    detail: string;
+};
+/** Capabilities and triggers, derived once per detail. */
+export declare function useSkillInsights(detail: NormalizedSkillDetail): {
+    capabilities: Capability[];
+    triggers: string[];
+};
+/**
+ * Market skill detail page.
+ *
+ * Owns no data: tab, selected file and file contents live in `MarketState`.
+ * Upstream facts (stats, version, scans, files) come from the live detail; the
+ * catalogue adds category and the Chinese summary. "What this skill does" and
+ * "when it triggers" are read off its own SKILL.md and file list by explicit
+ * rules (`skill-insights.ts`) and are hidden when no rule fires.
+ */
+export declare function MarketSkillDetail(props: {
+    detail: NormalizedSkillDetail;
+    state: MarketState;
+    controller: MarketController;
+}): JSX.Element;

package/lib/types/client/components/SkillAvatar.d.ts

@@ -8,7 +8,7 @@ import type { MarketSource } from '../../market/types.ts';
  */
 export declare function SkillAvatar(props: {
     name: string;
-    source: MarketSource;
+    source: MarketSource | 'local';
     iconUrl?: string;
     size: number;
 }): JSX.Element;

package/lib/types/client/components/SkillDetailShell.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The detail surface shared by the market catalogue and the installed inventory
+ * (design: "技能市场重构 – 详情页").
+ *
+ * Both pages answer the same question — "what is inside this skill?" — and the
+ * only real difference is where the facts come from: an upstream provider or the
+ * filesystem. The shell therefore owns everything that is *layout*: breadcrumb,
+ * identity header, stats strip, underlined tabs, the grey canvas, and the
+ * document/side-rail columns. Callers compose the header pieces and the active
+ * tab's content, and keep their own tab state (the market page in
+ * `MarketState`, the local page in component state).
+ */
+import { type ReactNode } from 'react';
+import type { SecurityStatus } from '../../market/types.ts';
+/** The shell's stylesheet, for callers composing shell-shaped fragments. */
+export declare const detailStyles: Record<string, string>;
+export interface DetailTab<K extends string> {
+    key: K;
+    label: string;
+    /** Small trailing marker: a count, or a warning dot. */
+    badge?: ReactNode;
+}
+export declare function SkillDetailShell<K extends string>(props: {
+    /** Identity of the rendered subject; changing it moves focus to the heading. */
+    focusKey: string;
+    onBack: () => void;
+    /** Breadcrumb root: the list this page was opened from. */
+    backLabel: string;
+    avatar: ReactNode;
+    name: string;
+    version?: string;
+    /** One line of "by author · source · licence · updated" facts. */
+    meta?: ReactNode;
+    summary?: string;
+    chips?: ReactNode;
+    actions?: ReactNode;
+    stats?: Array<{
+        label: string;
+        value: string;
+    }>;
+    tabs: Array<DetailTab<K>>;
+    activeTab: K;
+    onTabChange: (tab: K) => void;
+    /** Notes above the tab content (snapshot age, location, warnings). */
+    notice?: ReactNode;
+    children: ReactNode;
+}): JSX.Element;
+/** Document column plus side rail; the rail moves below on a narrow panel. */
+export declare function DetailColumns(props: {
+    main: ReactNode;
+    side: ReactNode;
+}): JSX.Element;
+export declare function SideCard(props: {
+    title: string;
+    extra?: ReactNode;
+    children: ReactNode;
+}): JSX.Element;
+export declare function InfoRow(props: {
+    label: string;
+    value: ReactNode;
+    mono?: boolean;
+}): JSX.Element;
+/** Count in a tab label ("文件 15"). */
+export declare function TabCount(props: {
+    value: number;
+}): JSX.Element;
+type ChipTone = 'plain' | 'ok' | 'warn' | 'blue';
+export declare function Chip(props: {
+    tone?: ChipTone;
+    title?: string;
+    children: ReactNode;
+}): JSX.Element;
+/** Upstream scan verdict, shared by the cards, the detail header and the install dialog. */
+export declare function SecurityChip(props: {
+    status: SecurityStatus;
+    short?: boolean;
+}): JSX.Element;
+/**
+ * Keeps the detail layout stable while its request is in flight: the same
+ * boxes as the real page rather than a spinner, so the page changes shape once.
+ */
+export declare function SkillDetailSkeleton({ onBack, backLabel }: {
+    onBack: () => void;
+    backLabel?: string;
+}): JSX.Element;
+export {};