@khorsheed/dsh-capability-catalog 0.1.95

package/lib/types/client/mode-model.js

@@ -0,0 +1,140 @@
+/**
+ * The cross-mode comparison model: ONE grid built from every mode's face.
+ *
+ * The section answers two different questions with one grid. A mode-selected
+ * view shows what that mode loads; the comparison shows, for every capability
+ * the instance knows, the modes that load it — which is the question "这个工具
+ * 会在哪些模式下被加载?" and the reason the mode control exists at all.
+ *
+ * Two properties make the comparison trustworthy:
+ *
+ * - A capability's ROW is taken from the deployment default's face when the
+ *   default mode also has it. Every mode registers its own instance of a tool
+ *   (its own description, its own channel attribution), and picking whichever
+ *   mode happened to be read first would make the card's prose depend on roster
+ *   order. The default mode is the one the human sees everywhere else in the
+ *   panel, so it wins whenever it can answer.
+ * - A mode that could not be read contributes NO modes-list and no rows; it is
+ *   reported in `unavailable` instead. "Not loaded in this mode" and "this mode
+ *   could not be read" are different claims, and a union that merged them would
+ *   quietly understate where a capability is available.
+ *
+ * Pure over its input, so the unit tests need no renderer.
+ * @module @khorsheed/dsh-capability-catalog/client/mode-model
+ */
+/**
+ * Resolve the mode ids a capability was found in into chips, in the order the
+ * ids arrive (the roster's own read order). An id the roster no longer supplies
+ * still renders — its own id is the only label left — because dropping it would
+ * hide a mode the comparison actually read.
+ * @param ids - mode ids, in roster order.
+ * @param options - the roster, for display names and the default marker.
+ * @returns one chip per id.
+ */
+export function resolveModeChips(ids, options) {
+    const byId = new Map(options.map(option => [option.id, option]));
+    return ids.map((id) => {
+        const option = byId.get(id);
+        return { id, label: option?.name ?? id, isDefault: option?.isDefault === true };
+    });
+}
+/**
+ * Find the managed skills no readable mode can show.
+ *
+ * The judgement needs no faces: the delivery status already knows which preset
+ * ids a skill declares, which presets the roster supplies, and which of those
+ * failed to resolve a standing scope. A skill whose declared ids are ALL
+ * unreachable is in no mode's face by construction — and a conflicted one is
+ * excluded from delivery entirely, so its managed copy is in no face either.
+ *
+ * An UNSCOPED managed skill (no declared ids) is deliberately NOT an orphan: the
+ * delivery serves it to every preset through the global layer, so every mode
+ * shows it. Treating it as one would put a permanent, wrong diagnostic on screen.
+ * @param skills - the managed rows (`presetScopeStatus().skills`).
+ * @param presets - every preset the roster supplies.
+ * @param failedPresets - preset ids whose standing scope could not be resolved.
+ * @returns the orphan rows, name-sorted.
+ */
+export function orphanManagedSkills(skills, presets, failedPresets) {
+    const known = new Set(presets.map(option => option.id));
+    const failed = new Set(failedPresets);
+    const orphans = [];
+    for (const skill of skills) {
+        if (skill.conflict !== undefined) {
+            orphans.push({
+                name: skill.name,
+                description: skill.description,
+                modelInvocable: skill.modelInvocable,
+                userInvocable: skill.userInvocable,
+                declared: skill.presets,
+                unreachable: [...skill.presets],
+                conflict: skill.conflict,
+            });
+            continue;
+        }
+        if (skill.presets.length === 0)
+            continue;
+        const unreachable = skill.presets.filter(id => !known.has(id) || failed.has(id));
+        if (unreachable.length < skill.presets.length)
+            continue;
+        orphans.push({
+            name: skill.name,
+            description: skill.description,
+            modelInvocable: skill.modelInvocable,
+            userInvocable: skill.userInvocable,
+            declared: skill.presets,
+            unreachable,
+        });
+    }
+    return orphans.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Add one capability to the union, keeping the default mode's row when it has one. */
+function claim(byName, modes, row, preset, isDefault) {
+    const claimed = byName.get(row.name);
+    if (claimed === undefined)
+        byName.set(row.name, { row, fromDefault: isDefault });
+    else if (isDefault && !claimed.fromDefault)
+        byName.set(row.name, { row, fromDefault: true });
+    const listed = modes.get(row.name);
+    if (listed === undefined)
+        modes.set(row.name, [preset]);
+    else if (!listed.includes(preset))
+        listed.push(preset);
+}
+/** Union rows as a name-sorted list (the caller sorts again after filtering). */
+function ordered(byName) {
+    return [...byName.values()].map(claimed => claimed.row).sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Fold every mode's face into one comparison grid.
+ * @param faces - the faces the host read, in roster order.
+ * @returns the union rows, the per-capability mode lists, and the unread modes.
+ */
+export function buildModeComparison(faces) {
+    const skills = new Map();
+    const tools = new Map();
+    const skillModes = new Map();
+    const toolModes = new Map();
+    const unavailable = [];
+    let modes = 0;
+    for (const face of faces) {
+        const label = face.name ?? face.preset;
+        if (face.unavailable !== undefined) {
+            unavailable.push({ preset: face.preset, label, reason: face.unavailable });
+            continue;
+        }
+        modes += 1;
+        for (const skill of face.skills)
+            claim(skills, skillModes, skill, face.preset, face.isDefault);
+        for (const tool of face.tools)
+            claim(tools, toolModes, tool, face.preset, face.isDefault);
+    }
+    return {
+        skills: ordered(skills),
+        tools: ordered(tools),
+        skillModes,
+        toolModes,
+        modes,
+        unavailable,
+    };
+}

package/lib/types/client/preset-display.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Built-in preset display names, localized through the host's own copy keys.
+ *
+ * The four shipped presets (standard/ptc/minimal/cordis) publish NO name of
+ * their own — surfaces are expected to resolve their copy through
+ * `presetDisplayText` from `@deepseek-ai/dsh-agent-preset-registry/display`,
+ * the pure fold the host ships exactly so browser bundles inline it. Rendering
+ * `name ?? id` leaks the raw English ids; this helper routes every roster row
+ * through the fold with this card's own dictionary (the eight preset* keys),
+ * while user-authored presets keep their published names untouched.
+ * @module @khorsheed/dsh-capability-catalog/client/preset-display
+ */
+import type { CapabilityCatalogKey } from './locales.ts';
+/** One roster row or face's identity, as display copy resolution needs it. */
+export interface PresetLike {
+    readonly id: string;
+    readonly name?: string | undefined;
+}
+/** The row's display name: localized built-in copy, else its published name (or id). */
+export declare function presetName(preset: PresetLike, t: (key: CapabilityCatalogKey) => string): string;
+//# sourceMappingURL=preset-display.d.ts.map

package/lib/types/client/preset-display.js

@@ -0,0 +1,20 @@
+/**
+ * Built-in preset display names, localized through the host's own copy keys.
+ *
+ * The four shipped presets (standard/ptc/minimal/cordis) publish NO name of
+ * their own — surfaces are expected to resolve their copy through
+ * `presetDisplayText` from `@deepseek-ai/dsh-agent-preset-registry/display`,
+ * the pure fold the host ships exactly so browser bundles inline it. Rendering
+ * `name ?? id` leaks the raw English ids; this helper routes every roster row
+ * through the fold with this card's own dictionary (the eight preset* keys),
+ * while user-authored presets keep their published names untouched.
+ * @module @khorsheed/dsh-capability-catalog/client/preset-display
+ */
+import { presetDisplayText } from '@deepseek-ai/dsh-agent-preset-registry/display';
+/** The row's display name: localized built-in copy, else its published name (or id). */
+export function presetName(preset, t) {
+    // exactOptionalPropertyTypes: the upstream source type spells `name?: string`,
+    // so an explicit undefined must collapse into an absent property instead.
+    const source = preset.name === undefined ? { id: preset.id } : { id: preset.id, name: preset.name };
+    return presetDisplayText(source, key => t(key)).name;
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Re-query the catalog until a mutation is visible in it.
+ *
+ * The host skill registry is not invalidated by our own writes. The catalog
+ * installs and deletes skills with `node:fs`, while the host's only synchronous
+ * invalidation path is the `fs/observed` event, which the model-facing
+ * filesystem tools raise — a plugin write raises nothing. The registry therefore
+ * catches up when its watcher notices the change (chokidar, 200 ms stability
+ * threshold), a moment AFTER the write resolves. A single refresh fired right
+ * after an install or delete thus returns the pre-change snapshot, and the grid
+ * keeps its stale rows until the panel is reopened.
+ * @module @khorsheed/dsh-capability-catalog/client/settle
+ */
+/** Delay schedule and sleep seam of {@link refreshUntilSettled}. */
+export interface SettleOptions {
+    /** One attempt per entry, plus the immediate one. */
+    readonly delaysMs?: readonly number[];
+    /** How to wait between attempts. */
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Refresh once immediately, then keep re-querying until `settled` accepts the
+ * snapshot or the schedule runs out. The immediate attempt is deliberate: it
+ * preserves the single-refresh behaviour for every mutation the registry
+ * already knows about, and it is the only attempt that can beat the watcher.
+ * @param read - the newest snapshot, or undefined before one lands.
+ * @param refresh - one query; resolves once the store holds its result.
+ * @param settled - accepts the snapshot when the mutation is visible in it.
+ * @param options - delay schedule and sleep seam.
+ * @returns whether the snapshot settled before the schedule ran out.
+ */
+export declare function refreshUntilSettled<T>(read: () => T | undefined, refresh: () => Promise<void>, settled: (value: T) => boolean, options?: SettleOptions): Promise<boolean>;
+/**
+ * The skill names an add-skill result reported. The host joins a multi-skill
+ * install with `', '` (e.g. `--skill '*'`), so the caller cannot treat it as one
+ * name.
+ * @param name - the result's `name` field.
+ */
+export declare function installedNames(name: string | undefined): readonly string[];
+//# sourceMappingURL=settle.d.ts.map

package/lib/types/client/settle.js

@@ -0,0 +1,57 @@
+/**
+ * Re-query the catalog until a mutation is visible in it.
+ *
+ * The host skill registry is not invalidated by our own writes. The catalog
+ * installs and deletes skills with `node:fs`, while the host's only synchronous
+ * invalidation path is the `fs/observed` event, which the model-facing
+ * filesystem tools raise — a plugin write raises nothing. The registry therefore
+ * catches up when its watcher notices the change (chokidar, 200 ms stability
+ * threshold), a moment AFTER the write resolves. A single refresh fired right
+ * after an install or delete thus returns the pre-change snapshot, and the grid
+ * keeps its stale rows until the panel is reopened.
+ * @module @khorsheed/dsh-capability-catalog/client/settle
+ */
+/** Delays between attempts: past the watcher's ~200 ms settle, bounded so the UI never spins. */
+const DEFAULT_DELAYS_MS = [250, 500, 1000, 1500];
+/** Await a real delay; tests inject their own so they never touch the clock. */
+const realSleep = async (ms) => {
+    await new Promise((resolve) => { setTimeout(resolve, ms); });
+};
+/**
+ * Refresh once immediately, then keep re-querying until `settled` accepts the
+ * snapshot or the schedule runs out. The immediate attempt is deliberate: it
+ * preserves the single-refresh behaviour for every mutation the registry
+ * already knows about, and it is the only attempt that can beat the watcher.
+ * @param read - the newest snapshot, or undefined before one lands.
+ * @param refresh - one query; resolves once the store holds its result.
+ * @param settled - accepts the snapshot when the mutation is visible in it.
+ * @param options - delay schedule and sleep seam.
+ * @returns whether the snapshot settled before the schedule ran out.
+ */
+export async function refreshUntilSettled(read, refresh, settled, options = {}) {
+    const delays = options.delaysMs ?? DEFAULT_DELAYS_MS;
+    const sleep = options.sleep ?? realSleep;
+    const accepts = () => {
+        const value = read();
+        return value !== undefined && settled(value);
+    };
+    await refresh();
+    if (accepts())
+        return true;
+    for (const delay of delays) {
+        await sleep(delay);
+        await refresh();
+        if (accepts())
+            return true;
+    }
+    return false;
+}
+/**
+ * The skill names an add-skill result reported. The host joins a multi-skill
+ * install with `', '` (e.g. `--skill '*'`), so the caller cannot treat it as one
+ * name.
+ * @param name - the result's `name` field.
+ */
+export function installedNames(name) {
+    return (name ?? '').split(',').map(part => part.trim()).filter(part => part !== '');
+}

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

@@ -0,0 +1,86 @@
+/**
+ * Slot-facing types of the capability-catalog client half: the settings
+ * section (a standalone nav tab) and its injected data face.
+ */
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { CapabilityCatalogSnapshot, CatalogAddSkillRequest, CatalogDirSkillInfo, CatalogDeleteSkillResult, CatalogMcpServerConfig, CatalogMcpSnapshot, CatalogMcpTool, CatalogModeFace, CatalogPresetOption, CatalogPresetScopeEditResult, CatalogPresetScopeStatus, CatalogSkillDetail, CatalogSkillFileRead } from '@khorsheed/dsh-capability-catalog/types';
+/** A tiny external store holding the last catalog snapshot (re-created on change). */
+export interface CatalogHook {
+    readonly getSnapshot: () => CapabilityCatalogSnapshot | undefined;
+    readonly subscribe: (listener: () => void) => () => void;
+    /** Re-read one mode's face; `presetId` omitted reads the deployment default. */
+    readonly refresh: (presetId?: string) => Promise<void>;
+}
+/** Injected data face of the settings section. */
+export interface CapabilityCatalogInjected {
+    hooks: {
+        /** The catalog snapshot store; the section binds `useCatalog` to it. */
+        catalog: CatalogHook;
+    };
+    /**
+     * Re-fetch the catalog snapshot after a mutation (e.g. add-skill). `presetId`
+     * names the mode the grid is showing, so a mutation never drags the grid back
+     * to the default mode's face.
+     */
+    refresh: (presetId?: string) => Promise<void>;
+    /**
+     * Re-fetch until `settled` accepts the snapshot, on a bounded backoff. Use it
+     * for mutations whose visibility depends on the host's skill watcher (adding
+     * or deleting a skill): the write lands before the registry is invalidated, so
+     * one immediate refresh returns the pre-change snapshot.
+     */
+    refreshSettled: (settled: (snapshot: CapabilityCatalogSnapshot) => boolean, presetId?: string) => Promise<boolean>;
+    /** Load one skill's full detail (content + metadata + credentials) at a mode's scope. */
+    detail: (name: string, presetId?: string) => Promise<CatalogSkillDetail | undefined>;
+    /** Read one skill-bundle file's text content on demand. */
+    readSkillFile: (name: string, path: string, presetId?: string) => Promise<CatalogSkillFileRead | undefined>;
+    /** List the skills inside a local container dir (add-skill chooser). */
+    listDirSkills: (dirPath: string) => Promise<readonly CatalogDirSkillInfo[]>;
+    /** Set one declared credential value. */
+    setCredential: (key: string, value: string) => Promise<boolean>;
+    /** Add a skill via a full request (upload zip/text or clone-from-source). */
+    addSkill: (request: CatalogAddSkillRequest) => Promise<{
+        ok: boolean;
+        error?: string;
+        name?: string;
+        exists?: boolean;
+    }>;
+    /** Delete a catalog-owned file skill (rejects built-in/plugin-provided). */
+    deleteSkill: (name: string, presetId?: string) => Promise<CatalogDeleteSkillResult>;
+    /** Open the host's native directory chooser (the workspace "add" dialog). */
+    pickDirectory: () => Promise<string | null>;
+    /**
+     * Every mode's capability face, for the cross-mode comparison view and for a
+     * detail modal asking where a non-writable skill actually loads. Read once per
+     * session behind a single-flight cache; `force` re-reads after a mutation that
+     * can change a face.
+     */
+    modeFaces: (force?: boolean) => Promise<readonly CatalogModeFace[]>;
+    /** MCP: full management snapshot (servers + tools + credential state). */
+    mcpSnapshot: () => Promise<CatalogMcpSnapshot>;
+    /** MCP: add/replace a server config. */
+    mcpAdd: (config: CatalogMcpServerConfig) => Promise<boolean>;
+    /** MCP: remove a server. */
+    mcpRemove: (serverName: string) => Promise<boolean>;
+    /** MCP: set server-level enable flag. */
+    mcpSetEnabled: (serverName: string, enabled: boolean) => Promise<void>;
+    /** MCP: set one credential value. */
+    mcpSetCredential: (ref: string, value: string) => Promise<boolean>;
+    /** MCP: set one tool's enable flag. */
+    mcpSetToolEnabled: (serverName: string, tool: string, enabled: boolean) => Promise<void>;
+    /** MCP: connect + discover a server's tools. */
+    mcpDiscover: (serverName: string) => Promise<readonly CatalogMcpTool[]>;
+    /** Preset-scoped delivery status of the plugin's managed skill root. */
+    presetScopeStatus: () => Promise<CatalogPresetScopeStatus | undefined>;
+    /** Every preset the roster supplies, for the scope picker. */
+    presetScopeRoster: () => Promise<readonly CatalogPresetOption[]>;
+    /** Declare which presets one managed skill is delivered to. */
+    presetScopeSet: (name: string, presets: readonly string[]) => Promise<CatalogPresetScopeEditResult>;
+    /** Move an installed skill into the managed root with a preset scope. */
+    presetScopeAdopt: (name: string, presets: readonly string[]) => Promise<CatalogPresetScopeEditResult>;
+    /** Move a managed skill back to the user skill root. */
+    presetScopeRelease: (name: string) => Promise<CatalogPresetScopeEditResult>;
+}
+/** Full props of the settings.section entry (a standalone nav tab). */
+export type CapabilityCatalogCardProps = PropsRuntime<'settings.section'> & InjectFace<CapabilityCatalogInjected> & PropsLocale<'capability-catalog'>;
+//# sourceMappingURL=slots.d.ts.map

package/lib/types/client/slots.js

@@ -0,0 +1 @@
+export {};

package/lib/types/envHint.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Skill env hint via `tools/post-execute` — a runtime companion context that
+ * tells the model about any skill's configured credential env mappings.
+ *
+ * The catalog injects credentials as trusted per-execution `DSH_<KEY>` env
+ * vars (see shellEnv.ts), but a skill's own text references the original
+ * `$KEY` name and the model does not derive the alias on its own. This module
+ * observes `tools/post-execute` when the `skill` tool loads a skill and appends
+ * a generic, per-skill note listing each configured mapping, so the model can
+ * use the value without us modifying the user's SKILL.md.
+ *
+ * Generic: it derives the mappings from the loaded skill's own env-decl keys
+ * (decodeEnvDecls) + the credential store, so any future key / skill is
+ * covered. It never touches the skill file or the provider's returned content.
+ * @module @khorsheed/dsh-capability-catalog/envHint
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Subscribe to `tools/post-execute`; appends an env-mapping hint for the
+ * loaded skill. Returns a disposer. Degrades silently when tools/registry/
+ * credentials are absent or the tool is not the skills loader. */
+export declare function installSkillEnvHint(ctx: Context, getScope: () => Promise<unknown | undefined>): void;
+//# sourceMappingURL=envHint.d.ts.map

package/lib/types/envHint.js

@@ -0,0 +1,76 @@
+/**
+ * Skill env hint via `tools/post-execute` — a runtime companion context that
+ * tells the model about any skill's configured credential env mappings.
+ *
+ * The catalog injects credentials as trusted per-execution `DSH_<KEY>` env
+ * vars (see shellEnv.ts), but a skill's own text references the original
+ * `$KEY` name and the model does not derive the alias on its own. This module
+ * observes `tools/post-execute` when the `skill` tool loads a skill and appends
+ * a generic, per-skill note listing each configured mapping, so the model can
+ * use the value without us modifying the user's SKILL.md.
+ *
+ * Generic: it derives the mappings from the loaded skill's own env-decl keys
+ * (decodeEnvDecls) + the credential store, so any future key / skill is
+ * covered. It never touches the skill file or the provider's returned content.
+ * @module @khorsheed/dsh-capability-catalog/envHint
+ */
+import { decodeCredentialDecls, decodeEnvDecls, mergeCredentialDecls, resolveServices } from './skills.js';
+const DSH_PREFIX = 'DSH_';
+/** Subscribe to `tools/post-execute`; appends an env-mapping hint for the
+ * loaded skill. Returns a disposer. Degrades silently when tools/registry/
+ * credentials are absent or the tool is not the skills loader. */
+export function installSkillEnvHint(ctx, getScope) {
+    // Subscribe inside the DEFERRED tools inject — a one-shot ctx.get probe loses
+    // the hint if tools mounts after this plugin (silently degrading it with no
+    // error), while inject fires when the registry appears and never in a
+    // composition without one (dropping only the hint, never the boot).
+    ctx.inject(['tools'], () => {
+        ctx.on('tools/post-execute', (async (exec, _result, next) => {
+            if (exec?.name !== 'skill')
+                return next();
+            const skillName = exec.arguments?.name;
+            if (typeof skillName !== 'string' || skillName.length === 0)
+                return next();
+            const scope = await getScope().catch(() => undefined);
+            const { registry, credentials } = resolveServices(ctx);
+            if (registry === undefined || credentials === undefined)
+                return next();
+            const lookup = scope === undefined ? {} : { scope };
+            let def;
+            try {
+                def = await registry.get(skillName, lookup);
+            }
+            catch {
+                return next();
+            }
+            if (def === undefined)
+                return next();
+            const decls = mergeCredentialDecls(decodeCredentialDecls(def.metadata), decodeEnvDecls(def.content ?? ''));
+            const configured = [];
+            for (const decl of decls) {
+                const info = await credentials.describe(decl.key).catch(() => undefined);
+                if (info?.configured === true)
+                    configured.push(decl.key);
+            }
+            if (configured.length === 0)
+                return next();
+            const lines = [
+                `Runtime credential mapping for ${skillName}:`,
+                ...configured.map(k => `- ${k} is configured; in the model shell it is available as ${DSH_PREFIX}${k}. Use it as ${k}="${DSH_PREFIX}${k}" <command>.`),
+                `Do not search dotenv files or ask the user for this credential, and do not print either variable.`,
+            ];
+            const hint = lines.join('\n');
+            return {
+                kind: 'accept',
+                additionalContexts: [{
+                        id: `capability-catalog-env-hint-${skillName}`,
+                        role: 'user',
+                        content: [{ type: 'text', text: hint }],
+                        // Producer-owned kind: the retired {kind: 'plugin'} wrapper fails the
+                        // rc.1 native source admission at the durable write (turn-killing).
+                        source: { kind: 'capability-catalog', plugin: 'capability-catalog', form: 'env-hint' },
+                    }],
+            };
+        }));
+    });
+}

package/lib/types/import.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Add-skill import: write a skill from a pasted SKILL.md payload or an uploaded
+ * zip archive into the managed skills root and extract its name/frontmatter.
+ *
+ * A skill is a directory bundle (`<name>/SKILL.md` plus optional
+ * `references`/`scripts`/`assets`) or a single flat file, discovered by the
+ * skill-filesystem watcher from one of the managed roots. So "installing" a
+ * skill is just placing it under the root; nothing executes the payload.
+ *
+ * The zip path reads the archive with the dependency-free zip reader
+ * (`./zip.ts`, node:zlib only), locates the `SKILL.md`, derives the kebab-case
+ * `name` from frontmatter, and extracts the bundle under `<root>/<name>/`
+ * (strip the archive's own wrapping folder if present). The clone path resolves
+ * a repo spec — including a whole `npx skills add <repo> --skill <name>` command
+ * copied from a skill's README — clones it into a scratch directory, and lifts
+ * the selected skill bundle(s) into the root.
+ * @module @khorsheed/dsh-capability-catalog/import
+ */
+import type { CatalogAddSkillRequest, CatalogAddSkillResult, CatalogDirSkillInfo } from './types.ts';
+/** Resolve the managed root directory. */
+export declare function managedRoot(root: 'user' | 'project', dshHome: string): string;
+/** Extract the kebab-case `name` and `description` from a SKILL.md body. */
+export declare function resolveSkillNameFromContent(content: string): {
+    name: string;
+    description: string;
+} | undefined;
+/** Read the frontmatter `disable-model-invocation` flag (default model-invocable true). */
+export declare function inferModelInvocable(content: string): boolean;
+/** True when a base64 payload decodes to a ZIP archive (magic bytes). */
+export declare function isZipPayload(payload: string): boolean;
+/**
+ * Add a skill from a base64 SKILL.md text payload into the managed root.
+ * @param request - the add-skill request.
+ * @param dshHome - the dsh home root.
+ */
+export declare function addSkillFromText(request: CatalogAddSkillRequest, dshHome: string): Promise<CatalogAddSkillResult>;
+/**
+ * Add a skill from a base64 ZIP archive payload into the managed root.
+ *
+ * The archive should contain a skill bundle. If the `SKILL.md` sits directly at
+ * the archive root it is extracted as-is; if it sits under a single wrapping
+ * folder that folder is stripped so the bundle lands at `<root>/<name>/`. Path
+ * traversal entries are skipped; the frontmatter name drives the target folder.
+ * @param request - the add-skill request.
+ * @param dshHome - the dsh home root.
+ */
+export declare function addSkillFromZip(request: CatalogAddSkillRequest, dshHome: string): Promise<CatalogAddSkillResult>;
+/**
+ * Add a skill from a base64 payload into the managed root, auto-detecting a
+ * ZIP archive (magic bytes) from a raw SKILL.md text payload.
+ * @param request - the add-skill request.
+ * @param dshHome - the dsh home root.
+ */
+export declare function addSkillFromPayload(request: CatalogAddSkillRequest, dshHome: string): Promise<CatalogAddSkillResult>;
+/** A parsed `command`-channel spec: the source reference plus its `--skill` selections. */
+interface RepoSpec {
+    /** owner/repo or a git URL (a local path is copied before this parse runs). */
+    readonly ref: string;
+    /** Sub-skill names from `--skill`/`-s`, matching the CLI's own greedy values. */
+    readonly skills: readonly string[];
+}
+/**
+ * Parse a `command`-channel spec — `owner/repo`, a git URL, or a whole
+ * `npx skills add <repo> [--skill <name>]… [-g]` command — into its source
+ * reference and `--skill` selections.
+ *
+ * Every flag token is consumed here, never left in the string: the spec used to
+ * be handed to `git clone` after only a prefix and a trailing `-g` were
+ * stripped, so the README form `npx skills add owner/repo --skill name` became
+ * the clone URL `https://github.com/owner/repo --skill name`, which git rejects
+ * as a malformed URL. The recognized set mirrors the `skills` CLI's own `add`
+ * parser (vercel-labs/skills) so a command copied from a skill's README installs
+ * what it says: a flag's value is consumed with it, never glued onto the
+ * reference.
+ * @param spec - the raw spec from the add-skill command channel.
+ */
+export declare function parseRepoSpec(spec: string): RepoSpec | undefined;
+/**
+ * Install a skill by cloning a source repo (owner/repo, a git URL, a host-prefixed
+ * `github.com/owner/repo[/path]`, a copied browser URL, or a whole
+ * `npx skills add <repo> [--skill <name>]` command) into the managed root. This
+ * is the dsh-native "install from source" — a plain `npx skills add` writes into
+ * an external skills dir the dsh filesystem watcher does not scan.
+ *
+ * The clone lands in a scratch directory; the chosen skill bundle (the repo's
+ * only one, `request.skills`, or the command's `--skill` values) is then lifted
+ * to `<managed root>/<frontmatter name>/`. A repo carrying several skills and no
+ * selection is refused with the list rather than installing the shallowest one.
+ * A spec naming a path inside the repo (`…/skills/<name>`) searches only that
+ * path.
+ * @param request - the add-skill request (channel 'command', repo carries the spec).
+ * @param dshHome - the dsh home root.
+ */
+export declare function commandInstall(request: CatalogAddSkillRequest, dshHome: string): Promise<CatalogAddSkillResult>;
+/**
+ * List the skills inside a local dir for the add-skill chooser. If the dir is a
+ * **skill container** (a set of `<name>/SKILL.md` sub-dirs) the sub-skills are
+ * listed as `kind:'child'`; if the dir is **itself a single skill bundle** (a
+ * `SKILL.md` at its root) it is listed as one `kind:'self'` entry so the user can
+ * install the directory as-is. Both shapes are returned when a dir has a root
+ * `SKILL.md` AND child skill dirs.
+ * @param dirPath - the local directory path (may be `~`-prefixed).
+ */
+export declare function listDirSkills(dirPath: string): Promise<readonly CatalogDirSkillInfo[]>;
+export {};
+//# sourceMappingURL=import.d.ts.map