@jianxx/dsh-cc-plugin-loader 0.1.0

package/lib/mcp.js

@@ -0,0 +1,64 @@
+/**
+ * Mount a Claude Code plugin's MCP servers.
+ *
+ * Collects server definitions from the manifest inline `mcpServers` record or
+ * an `.mcp.json` file, then registers each through the optional `mcp` guest
+ * seam. Tool naming (`mcp__<server>__<tool>`) is the seam's responsibility.
+ * When the seam is absent the component is reported skipped, never failed.
+ *
+ * @module
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { ComponentTally } from "./seams.js";
+/**
+ * Collect and register a plugin's MCP servers through the optional seam.
+ * @param options - plugin root, manifest, and the mcp seam.
+ * @returns mounted disposers and per-component counts.
+ */
+export function mountMcpServers(options) {
+    const tally = new ComponentTally('mcpServers');
+    const disposers = [];
+    if (options.mcp === undefined) {
+        tally.addSkipped('mcp seam "mcp" is not mounted');
+        return { disposers, tally };
+    }
+    const servers = collectServers(options.pluginRoot, options.manifest);
+    const entries = Object.entries(servers);
+    if (entries.length === 0) {
+        tally.addSkipped('plugin declares no MCP servers');
+        return { disposers, tally };
+    }
+    for (const [name, config] of entries) {
+        disposers.push(options.mcp.registerServer(name, config));
+        tally.addLoaded();
+    }
+    return { disposers, tally };
+}
+/** Combine inline and file-backed MCP server definitions. */
+function collectServers(pluginRoot, manifest) {
+    const servers = {};
+    if (manifest.mcpServersPath !== undefined) {
+        const path = resolve(pluginRoot, manifest.mcpServersPath);
+        Object.assign(servers, readMcpJson(path));
+    }
+    for (const [name, config] of Object.entries(manifest.mcpServers)) {
+        servers[name] = config;
+    }
+    return servers;
+}
+/** Read an `.mcp.json` file's `mcpServers` key (absent/invalid yields none). */
+function readMcpJson(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        const servers = parsed['mcpServers'];
+        if (typeof servers === 'object' && servers !== null && !Array.isArray(servers)) {
+            return servers;
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=mcp.js.map

package/lib/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEnC,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAuB3C;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,OAA+B;IAC7D,MAAM,KAAK,GAAG,IAAI,cAAc,CAAC,YAAY,CAAC,CAAA;IAC9C,MAAM,SAAS,GAAmB,EAAE,CAAA;IACpC,IAAI,OAAO,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAC9B,KAAK,CAAC,UAAU,CAAC,+BAA+B,CAAC,CAAA;QACjD,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAA;IAC7B,CAAC;IACD,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;IACpE,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;IACvC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,KAAK,CAAC,UAAU,CAAC,gCAAgC,CAAC,CAAA;QAClD,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAA;IAC7B,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACrC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAA;QACxD,KAAK,CAAC,SAAS,EAAE,CAAA;IACnB,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAA;AAC7B,CAAC;AAED,6DAA6D;AAC7D,SAAS,cAAc,CAAC,UAAkB,EAAE,QAA0B;IACpE,MAAM,OAAO,GAA4C,EAAE,CAAA;IAC3D,IAAI,QAAQ,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QAC1C,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAA;QACzD,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC,CAAA;IAC3C,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QACjE,OAAO,CAAC,IAAI,CAAC,GAAG,MAAiC,CAAA;IACnD,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC;AAED,gFAAgF;AAChF,SAAS,WAAW,CAAC,IAAY;IAC/B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAA4B,CAAA;QAChF,MAAM,OAAO,GAAG,MAAM,CAAC,YAAY,CAAC,CAAA;QACpC,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YAC/E,OAAO,OAAkD,CAAA;QAC3D,CAAC;QACD,OAAO,EAAE,CAAA;IACX,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAA;IACX,CAAC;AACH,CAAC"}

package/lib/seams.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Optional host seams a CC plugin loader mounts onto, plus the structural
+ * report accumulator.
+ *
+ * The loader is deliberately peer-style: it consults each component's host
+ * seam through `ctx.get(...)` and skips (with a reason) rather than throwing
+ * when a seam is absent, so a deployment can mount a plugin without every
+ * extension point present. `mcp` and `hooks` have no harness-owned service
+ * today; this module declares their guest contract so a host can satisfy it.
+ *
+ * @module
+ */
+import type { ComponentKind, ComponentResult } from './types.ts';
+/** A guest MCP seam: registers one named server for tool discovery. */
+export interface McpSeam {
+    /**
+     * Register one MCP server. The server-qualified public tool names
+     * (`mcp__<server>__<tool>`) are the seam's naming responsibility.
+     * @param name - unique server name.
+     * @param config - server transport configuration.
+     * @returns the exact disposer that unregisters the server.
+     */
+    registerServer(name: string, config: Record<string, unknown>): () => void;
+}
+/** A guest hooks seam: injects a plugin's Claude Code hooks. */
+export interface HooksSeam {
+    /**
+     * Merge a plugin's translated hooks into the bridge. The value is the
+     * canonical `ClaudeCodeHookConfig` shape the bridge consumes.
+     * @param pluginName - the plugin owning the hooks, for namespacing.
+     * @param config - the parsed per-event `MatcherGroup[]` map.
+     * @returns the exact disposer that removes the injected hooks.
+     */
+    mergePluginHooks(pluginName: string, config: unknown): () => void;
+}
+/** Probe a guest seam by key, returning `undefined` when the host lacks it. */
+export declare function probe<X>(value: X | undefined): X | undefined;
+/** Accumulates loaded/skipped/failed counts and reasons for one component. */
+export declare class ComponentTally {
+    private readonly kind;
+    private loaded;
+    private skipped;
+    private failed;
+    private readonly reasons;
+    /**
+     * Construct a tally for one component kind.
+     * @param kind - the component this tally measures.
+     */
+    constructor(kind: ComponentKind);
+    /** Record one component as mounted. */
+    addLoaded(): void;
+    /** Record one component as skipped, with the reason. */
+    addSkipped(reason: string): void;
+    /** Record one component as failed, with the reason. */
+    addFailed(reason: string): void;
+    /** Build the final per-component result. */
+    result(): ComponentResult;
+}
+//# sourceMappingURL=seams.d.ts.map

package/lib/seams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seams.d.ts","sourceRoot":"","sources":["../src/seams.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEhE,uEAAuE;AACvE,MAAM,WAAW,OAAO;IACtB;;;;;;OAMG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,IAAI,CAAA;CAC1E;AAED,gEAAgE;AAChE,MAAM,WAAW,SAAS;IACxB;;;;;;OAMG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,CAAA;CAClE;AAED,+EAA+E;AAC/E,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,GAAG,CAAC,GAAG,SAAS,CAE5D;AAED,8EAA8E;AAC9E,qBAAa,cAAc;IAUb,OAAO,CAAC,QAAQ,CAAC,IAAI;IATjC,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,OAAO,CAAI;IACnB,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IAEvC;;;OAGG;gBAC0B,IAAI,EAAE,aAAa;IAEhD,uCAAuC;IACvC,SAAS,IAAI,IAAI;IAIjB,wDAAwD;IACxD,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAKhC,uDAAuD;IACvD,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK/B,4CAA4C;IAC5C,MAAM,IAAI,eAAe;CAS1B"}

package/lib/seams.js

@@ -0,0 +1,56 @@
+/**
+ * Optional host seams a CC plugin loader mounts onto, plus the structural
+ * report accumulator.
+ *
+ * The loader is deliberately peer-style: it consults each component's host
+ * seam through `ctx.get(...)` and skips (with a reason) rather than throwing
+ * when a seam is absent, so a deployment can mount a plugin without every
+ * extension point present. `mcp` and `hooks` have no harness-owned service
+ * today; this module declares their guest contract so a host can satisfy it.
+ *
+ * @module
+ */
+/** Probe a guest seam by key, returning `undefined` when the host lacks it. */
+export function probe(value) {
+    return value;
+}
+/** Accumulates loaded/skipped/failed counts and reasons for one component. */
+export class ComponentTally {
+    kind;
+    loaded = 0;
+    skipped = 0;
+    failed = 0;
+    reasons = [];
+    /**
+     * Construct a tally for one component kind.
+     * @param kind - the component this tally measures.
+     */
+    constructor(kind) {
+        this.kind = kind;
+    }
+    /** Record one component as mounted. */
+    addLoaded() {
+        this.loaded += 1;
+    }
+    /** Record one component as skipped, with the reason. */
+    addSkipped(reason) {
+        this.skipped += 1;
+        this.reasons.push(reason);
+    }
+    /** Record one component as failed, with the reason. */
+    addFailed(reason) {
+        this.failed += 1;
+        this.reasons.push(reason);
+    }
+    /** Build the final per-component result. */
+    result() {
+        return {
+            kind: this.kind,
+            loaded: this.loaded,
+            skipped: this.skipped,
+            failed: this.failed,
+            reasons: this.reasons,
+        };
+    }
+}
+//# sourceMappingURL=seams.js.map

package/lib/seams.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seams.js","sourceRoot":"","sources":["../src/seams.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA4BH,+EAA+E;AAC/E,MAAM,UAAU,KAAK,CAAI,KAAoB;IAC3C,OAAO,KAAK,CAAA;AACd,CAAC;AAED,8EAA8E;AAC9E,MAAM,OAAO,cAAc;IAUI;IATrB,MAAM,GAAG,CAAC,CAAA;IACV,OAAO,GAAG,CAAC,CAAA;IACX,MAAM,GAAG,CAAC,CAAA;IACD,OAAO,GAAa,EAAE,CAAA;IAEvC;;;OAGG;IACH,YAA6B,IAAmB;QAAnB,SAAI,GAAJ,IAAI,CAAe;IAAG,CAAC;IAEpD,uCAAuC;IACvC,SAAS;QACP,IAAI,CAAC,MAAM,IAAI,CAAC,CAAA;IAClB,CAAC;IAED,wDAAwD;IACxD,UAAU,CAAC,MAAc;QACvB,IAAI,CAAC,OAAO,IAAI,CAAC,CAAA;QACjB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IAC3B,CAAC;IAED,uDAAuD;IACvD,SAAS,CAAC,MAAc;QACtB,IAAI,CAAC,MAAM,IAAI,CAAC,CAAA;QAChB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IAC3B,CAAC;IAED,4CAA4C;IAC5C,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAA;IACH,CAAC;CACF"}

package/lib/settings.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Mount a Claude Code plugin's settings.
+ *
+ * Filters the manifest `settings` record to the allowlisted keys (mirroring
+ * Claude Code's keep-list) and writes them through the optional `settings`
+ * guest seam under a plugin-scoped namespace. When the seam is absent the
+ * component is reported skipped, never failed.
+ *
+ * @module
+ */
+import type { CcPluginManifest } from './types.ts';
+import { ComponentTally } from './seams.ts';
+/** Settings keys Claude Code keeps when merging a plugin's settings. */
+export declare const SETTINGS_ALLOWLIST: readonly ["agent"];
+/** The settings seam: writes one plugin-scoped namespace of values. */
+export interface SettingsSeam {
+    /**
+     * Write a plugin's allowlisted settings.
+     * @param name - the plugin-scoped namespace.
+     * @param value - the allowlisted settings to merge.
+     * @returns the exact disposer that removes the written section.
+     */
+    set(name: string, value: Record<string, unknown>): () => void;
+}
+/** Options for mounting one plugin's settings. */
+export interface MountSettingsOptions {
+    /** The parsed manifest, whose `settings` record is written. */
+    readonly manifest: CcPluginManifest;
+    /** The settings seam (probed; `undefined` to skip settings). */
+    readonly settings: SettingsSeam | undefined;
+}
+/**
+ * Filter and write a plugin's settings through the optional seam.
+ * @param options - manifest and the settings seam.
+ * @returns mounted disposers and per-component counts.
+ */
+export declare function mountSettings(options: MountSettingsOptions): {
+    disposers: (() => void)[];
+    tally: ComponentTally;
+};
+//# sourceMappingURL=settings.d.ts.map

package/lib/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE3C,wEAAwE;AACxE,eAAO,MAAM,kBAAkB,oBAAqB,CAAA;AAEpD,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,IAAI,CAAA;CAC9D;AAED,kDAAkD;AAClD,MAAM,WAAW,oBAAoB;IACnC,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,CAAA;CAC5C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG;IAAE,SAAS,EAAE,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,CAejH"}

package/lib/settings.js

@@ -0,0 +1,44 @@
+/**
+ * Mount a Claude Code plugin's settings.
+ *
+ * Filters the manifest `settings` record to the allowlisted keys (mirroring
+ * Claude Code's keep-list) and writes them through the optional `settings`
+ * guest seam under a plugin-scoped namespace. When the seam is absent the
+ * component is reported skipped, never failed.
+ *
+ * @module
+ */
+import { ComponentTally } from "./seams.js";
+/** Settings keys Claude Code keeps when merging a plugin's settings. */
+export const SETTINGS_ALLOWLIST = ['agent'];
+/**
+ * Filter and write a plugin's settings through the optional seam.
+ * @param options - manifest and the settings seam.
+ * @returns mounted disposers and per-component counts.
+ */
+export function mountSettings(options) {
+    const tally = new ComponentTally('settings');
+    const disposers = [];
+    if (options.settings === undefined) {
+        tally.addSkipped('settings seam "settings" is not mounted');
+        return { disposers, tally };
+    }
+    const allowed = allowlist(options.manifest.settings);
+    if (Object.keys(allowed).length === 0) {
+        tally.addSkipped('plugin declares no allowlisted settings');
+        return { disposers, tally };
+    }
+    disposers.push(options.settings.set(options.manifest.name, allowed));
+    tally.addLoaded();
+    return { disposers, tally };
+}
+/** Keep only the allowlisted keys from a settings section. */
+function allowlist(settings) {
+    const result = {};
+    for (const key of SETTINGS_ALLOWLIST) {
+        if (settings[key] !== undefined)
+            result[key] = settings[key];
+    }
+    return result;
+}
+//# sourceMappingURL=settings.js.map

package/lib/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE3C,wEAAwE;AACxE,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,OAAO,CAAU,CAAA;AAqBpD;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,OAA6B;IACzD,MAAM,KAAK,GAAG,IAAI,cAAc,CAAC,UAAU,CAAC,CAAA;IAC5C,MAAM,SAAS,GAAmB,EAAE,CAAA;IACpC,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACnC,KAAK,CAAC,UAAU,CAAC,yCAAyC,CAAC,CAAA;QAC3D,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAA;IAC7B,CAAC;IACD,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;IACpD,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtC,KAAK,CAAC,UAAU,CAAC,yCAAyC,CAAC,CAAA;QAC3D,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAA;IAC7B,CAAC;IACD,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAA;IACpE,KAAK,CAAC,SAAS,EAAE,CAAA;IACjB,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAA;AAC7B,CAAC;AAED,8DAA8D;AAC9D,SAAS,SAAS,CAAC,QAA2C;IAC5D,MAAM,MAAM,GAA4B,EAAE,CAAA;IAC1C,KAAK,MAAM,GAAG,IAAI,kBAAkB,EAAE,CAAC;QACrC,IAAI,QAAQ,CAAC,GAAG,CAAC,KAAK,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAA;IAC9D,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC"}

package/lib/skill-semantics.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Consumer-side wiring of Claude Code skill semantics onto harness seams.
+ *
+ * The skill-claude-code package translates frontmatter into pure metadata; this
+ * module is the consumer that turns that metadata into actionable registrations
+ * at mount time: an `allowed-tools` allow-list into a scoped `tools.restrict()`,
+ * `paths` into a path activator, `context: fork` into subagent routing, and a
+ * MCP source into a forced-off inline shell. Each piece is effect-scoped and
+ * returns a disposer so unmounting the plugin recalls everything.
+ *
+ * @module
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type CcSkillMetadata } from '@jianxx/dsh-cc-skill-loader';
+import type { ToolRestriction } from '@jianxx/dsh-cc-tools';
+import type { SkillDefinition } from '@deepseek-ai/dsh-skill';
+/** The agent-scope surface a skill needs to apply a scoped tool restriction. */
+export interface AgentScope {
+    /** Scoped tool registry; `restrict` masks global tools for this agent. */
+    tools: {
+        /**
+         * Restrict the global tools visible to this agent scope.
+         * @param filter - the `allow`/`deny` mask to apply.
+         * @returns the exact disposer that lifts the restriction.
+         */
+        restrict(filter: ToolRestriction): () => void;
+    };
+}
+/** How a skill's body executes when activated. */
+export type SkillExecution = 'inline' | 'fork';
+/** The resolved activation descriptor a host consumes for one skill. */
+export interface SkillActivation {
+    /** Scoped tool restriction to apply on activation, or `undefined` when none. */
+    readonly restriction: ToolRestriction | undefined;
+    /** Whether the skill's body runs in a subagent or inline. */
+    readonly execution: SkillExecution;
+    /** Whether inline shell substitution is forbidden (MCP-sourced or `shell: false`). */
+    readonly forbidInlineShell: boolean;
+}
+/** The provider label RUNTIME skills using this loader carry. */
+export declare const PROVIDER = "cc-plugin-loader";
+/**
+ * Resolve the tool restriction for a skill from its `allowed-tools` allow-list.
+ * Names are translated leniently; unknown names are dropped with a diagnostic
+ * (routed to `console.warn`) rather than crashing the session.
+ * @param metadata - the skill's translated CC metadata.
+ * @returns an allow-only restriction, or `undefined` when nothing to restrict.
+ */
+export declare function skillToolRestriction(metadata: CcSkillMetadata): ToolRestriction | undefined;
+/**
+ * Resolve how a skill executes, honoring `context: fork` and the availability
+ * of the subagent seam. A `fork` skill degrades to inline when the subagent
+ * seam is absent so it still activates rather than failing.
+ * @param metadata - the skill's translated CC metadata.
+ * @param subagentsPresent - whether the subagent seam is mounted.
+ * @returns `'fork'` when the skill demands fork and the seam exists, else `'inline'`.
+ */
+export declare function resolveSkillExecution(metadata: CcSkillMetadata, subagentsPresent: boolean): SkillExecution;
+/**
+ * Whether a skill forbids inline shell substitution. A `shell: false` field, or
+ * an MCP-sourced skill (marked `shell: false` by its producer because it cannot
+ * run a local shell), must not open an inline shell.
+ * @param metadata - the skill's translated CC metadata.
+ * @returns whether inline shell is forbidden.
+ */
+export declare function forbidsInlineShell(metadata: CcSkillMetadata): boolean;
+/**
+ * Build the full activation descriptor for a skill, mirroring the four
+ * consumer-side wires. Pure and deterministic so it is directly testable.
+ * @param metadata - the skill's translated CC metadata.
+ * @param subagentsPresent - whether the subagent seam is mounted.
+ * @returns the resolved activation descriptor.
+ */
+export declare function activationFor(metadata: CcSkillMetadata, subagentsPresent: boolean): SkillActivation;
+/**
+ * Register a skill's path-conditional activator on `fs/observed`. The returned
+ * disposer is folder-scoped and effect-safe through `ctx.on(...)`.
+ * @param ctx - active context carrying the `fs/observed` event.
+ * @param skill - the loaded skill definition (carries CC metadata).
+ * @param projectRoot - the project/plugin root whose touched files activate the skill.
+ * @returns the exact disposer that removes the activator.
+ */
+export declare function registerSkillPathActivator(ctx: Context, skill: SkillDefinition, projectRoot: string): () => void;
+/**
+ * Apply a skill's `allowed-tools` restriction to a scoped agent. Returns the
+ * restriction disposer, or a no-op when the skill carries no restriction.
+ * @param metadata - the skill's translated CC metadata.
+ * @param agent - the scoped agent whose tool surface to mask.
+ * @returns the disposer that lifts the restriction.
+ */
+export declare function applySkillRestriction(metadata: CcSkillMetadata, agent: AgentScope): () => void;
+//# sourceMappingURL=skill-semantics.d.ts.map

package/lib/skill-semantics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-semantics.d.ts","sourceRoot":"","sources":["../src/skill-semantics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,6BAA6B,CAAA;AACpC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAE7D,gFAAgF;AAChF,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,KAAK,EAAE;QACL;;;;WAIG;QACH,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,IAAI,CAAA;KAC9C,CAAA;CACF;AAED,kDAAkD;AAClD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,MAAM,CAAA;AAE9C,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,WAAW,EAAE,eAAe,GAAG,SAAS,CAAA;IACjD,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;IAClC,sFAAsF;IACtF,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAA;CACpC;AAED,iEAAiE;AACjE,eAAO,MAAM,QAAQ,qBAAqB,CAAA;AAE1C;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,eAAe,GAAG,eAAe,GAAG,SAAS,CAK3F;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,eAAe,EACzB,gBAAgB,EAAE,OAAO,GACxB,cAAc,CAGhB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAErE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,EAAE,gBAAgB,EAAE,OAAO,GAAG,eAAe,CAMnG;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,eAAe,EACtB,WAAW,EAAE,MAAM,GAClB,MAAM,IAAI,CAUZ;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,eAAe,EACzB,KAAK,EAAE,UAAU,GAChB,MAAM,IAAI,CAIZ"}

package/lib/skill-semantics.js

@@ -0,0 +1,98 @@
+/**
+ * Consumer-side wiring of Claude Code skill semantics onto harness seams.
+ *
+ * The skill-claude-code package translates frontmatter into pure metadata; this
+ * module is the consumer that turns that metadata into actionable registrations
+ * at mount time: an `allowed-tools` allow-list into a scoped `tools.restrict()`,
+ * `paths` into a path activator, `context: fork` into subagent routing, and a
+ * MCP source into a forced-off inline shell. Each piece is effect-scoped and
+ * returns a disposer so unmounting the plugin recalls everything.
+ *
+ * @module
+ */
+import { ccPathMatcher, ccRestriction, registerPathActivator, } from '@jianxx/dsh-cc-skill-loader';
+/** The provider label RUNTIME skills using this loader carry. */
+export const PROVIDER = 'cc-plugin-loader';
+/**
+ * Resolve the tool restriction for a skill from its `allowed-tools` allow-list.
+ * Names are translated leniently; unknown names are dropped with a diagnostic
+ * (routed to `console.warn`) rather than crashing the session.
+ * @param metadata - the skill's translated CC metadata.
+ * @returns an allow-only restriction, or `undefined` when nothing to restrict.
+ */
+export function skillToolRestriction(metadata) {
+    return ccRestriction(metadata.allowedTools, (message) => {
+        // No logging seam reaches here; surface dropped-name diagnostics on stderr.
+        console.warn(`[cc-plugin-loader] ${message}`);
+    });
+}
+/**
+ * Resolve how a skill executes, honoring `context: fork` and the availability
+ * of the subagent seam. A `fork` skill degrades to inline when the subagent
+ * seam is absent so it still activates rather than failing.
+ * @param metadata - the skill's translated CC metadata.
+ * @param subagentsPresent - whether the subagent seam is mounted.
+ * @returns `'fork'` when the skill demands fork and the seam exists, else `'inline'`.
+ */
+export function resolveSkillExecution(metadata, subagentsPresent) {
+    if (metadata.executionContext !== 'fork')
+        return 'inline';
+    return subagentsPresent ? 'fork' : 'inline';
+}
+/**
+ * Whether a skill forbids inline shell substitution. A `shell: false` field, or
+ * an MCP-sourced skill (marked `shell: false` by its producer because it cannot
+ * run a local shell), must not open an inline shell.
+ * @param metadata - the skill's translated CC metadata.
+ * @returns whether inline shell is forbidden.
+ */
+export function forbidsInlineShell(metadata) {
+    return metadata.shell === false;
+}
+/**
+ * Build the full activation descriptor for a skill, mirroring the four
+ * consumer-side wires. Pure and deterministic so it is directly testable.
+ * @param metadata - the skill's translated CC metadata.
+ * @param subagentsPresent - whether the subagent seam is mounted.
+ * @returns the resolved activation descriptor.
+ */
+export function activationFor(metadata, subagentsPresent) {
+    return {
+        restriction: skillToolRestriction(metadata),
+        execution: resolveSkillExecution(metadata, subagentsPresent),
+        forbidInlineShell: forbidsInlineShell(metadata),
+    };
+}
+/**
+ * Register a skill's path-conditional activator on `fs/observed`. The returned
+ * disposer is folder-scoped and effect-safe through `ctx.on(...)`.
+ * @param ctx - active context carrying the `fs/observed` event.
+ * @param skill - the loaded skill definition (carries CC metadata).
+ * @param projectRoot - the project/plugin root whose touched files activate the skill.
+ * @returns the exact disposer that removes the activator.
+ */
+export function registerSkillPathActivator(ctx, skill, projectRoot) {
+    const metadata = skill.metadata;
+    const paths = metadata?.paths ?? [];
+    if (paths.length === 0) {
+        return () => { };
+    }
+    return registerPathActivator(ctx, {
+        projects: [{ root: projectRoot, matcher: ccPathMatcher(paths), skillNames: [skill.name] }],
+        onActivate: () => { },
+    });
+}
+/**
+ * Apply a skill's `allowed-tools` restriction to a scoped agent. Returns the
+ * restriction disposer, or a no-op when the skill carries no restriction.
+ * @param metadata - the skill's translated CC metadata.
+ * @param agent - the scoped agent whose tool surface to mask.
+ * @returns the disposer that lifts the restriction.
+ */
+export function applySkillRestriction(metadata, agent) {
+    const restriction = skillToolRestriction(metadata);
+    if (restriction === undefined)
+        return () => { };
+    return agent.tools.restrict(restriction);
+}
+//# sourceMappingURL=skill-semantics.js.map

package/lib/skill-semantics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-semantics.js","sourceRoot":"","sources":["../src/skill-semantics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EACL,aAAa,EACb,aAAa,EACb,qBAAqB,GAEtB,MAAM,6BAA6B,CAAA;AA8BpC,iEAAiE;AACjE,MAAM,CAAC,MAAM,QAAQ,GAAG,kBAAkB,CAAA;AAE1C;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAyB;IAC5D,OAAO,aAAa,CAAC,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAe,EAAQ,EAAE;QACpE,4EAA4E;QAC5E,OAAO,CAAC,IAAI,CAAC,sBAAsB,OAAO,EAAE,CAAC,CAAA;IAC/C,CAAC,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CACnC,QAAyB,EACzB,gBAAyB;IAEzB,IAAI,QAAQ,CAAC,gBAAgB,KAAK,MAAM;QAAE,OAAO,QAAQ,CAAA;IACzD,OAAO,gBAAgB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAA;AAC7C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAyB;IAC1D,OAAO,QAAQ,CAAC,KAAK,KAAK,KAAK,CAAA;AACjC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,QAAyB,EAAE,gBAAyB;IAChF,OAAO;QACL,WAAW,EAAE,oBAAoB,CAAC,QAAQ,CAAC;QAC3C,SAAS,EAAE,qBAAqB,CAAC,QAAQ,EAAE,gBAAgB,CAAC;QAC5D,iBAAiB,EAAE,kBAAkB,CAAC,QAAQ,CAAC;KAChD,CAAA;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CACxC,GAAY,EACZ,KAAsB,EACtB,WAAmB;IAEnB,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAuC,CAAA;IAC9D,MAAM,KAAK,GAAG,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAA;IACnC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,GAAG,EAAE,GAAE,CAAC,CAAA;IACjB,CAAC;IACD,OAAO,qBAAqB,CAAC,GAAG,EAAE;QAChC,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1F,UAAU,EAAE,GAAG,EAAE,GAAE,CAAC;KACrB,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,QAAyB,EACzB,KAAiB;IAEjB,MAAM,WAAW,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAA;IAClD,IAAI,WAAW,KAAK,SAAS;QAAE,OAAO,GAAG,EAAE,GAAE,CAAC,CAAA;IAC9C,OAAO,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAA;AAC1C,CAAC"}

package/lib/skills.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Mount a Claude Code plugin's skills.
+ *
+ * Discovers `SKILL.md` skills in the plugin's standard `skills/` directory and
+ * any inline manifest `skills` paths, parses each with the skill-claude-code
+ * frontmatter translator, registers it on the skill registry as a runtime
+ * skill, and wires the consumer-side activation semantics (allowed-tools,
+ * `context: fork`, `paths`, MCP-source shell). Every registration is a Cordis
+ * effect so unmounting the plugin recalls it.
+ *
+ * @module
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { CcPluginManifest } from './types.ts';
+import { ComponentTally } from './seams.ts';
+/** Skills live under this directory in a plugin root, when present. */
+export declare const STANDARD_SKILLS_DIR = "skills";
+/** The skill registry seam that accepts runtime skill registrations. */
+export interface SkillsSeam {
+    /**
+     * Register a runtime skill definition.
+     * @param skill - the skill definition to register.
+     * @returns the exact disposer that unregisters the skill.
+     */
+    register(skill: unknown): () => void;
+}
+/** Options for mounting one plugin's skills. */
+export interface MountSkillsOptions {
+    /** Active context carrying the `fs/observed` event for path activation. */
+    readonly ctx: Context;
+    /** The plugin root directory; standard `skills/` resolves against it. */
+    readonly pluginRoot: string;
+    /** The parsed manifest, whose `skills` paths add extra skill roots. */
+    readonly manifest: CcPluginManifest;
+    /** The skill registry seam (probed; `undefined` to skip skills). */
+    readonly skills: SkillsSeam | undefined;
+    /** The subagent seam presence (drives `context: fork` routing). */
+    readonly subagentsPresent: boolean;
+}
+/**
+ * Discover and register a plugin's skills, wiring activation semantics.
+ * @param options - plugin root, manifest, and the skill/subagent seams.
+ * @returns mounted disposers and per-component counts.
+ */
+export declare function mountSkills(options: MountSkillsOptions): Promise<{
+    disposers: (() => void)[];
+    tally: ComponentTally;
+}>;
+//# sourceMappingURL=skills.d.ts.map

package/lib/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAUlD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAG3C,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,WAAW,CAAA;AAE3C,wEAAwE;AACxE,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,IAAI,CAAA;CACrC;AAED,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;IACrB,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAA;IACvC,mEAAmE;IACnE,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAA;CACnC;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC;IAAE,SAAS,EAAE,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,CAAC,CA+C5H"}