@dsh-cc/plugin-loader 0.5.0

package/lib/commands.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Mount a Claude Code plugin's slash commands.
+ *
+ * Translates manifest `commands` entries (inline content or a source file) into
+ * typed command definitions registered on the commands seam. Each handler
+ * substitutes `$ARGUMENTS` and dispatches the rendered body as a user prompt
+ * on the invoking agent; registration is effect-scoped.
+ *
+ * @module
+ */
+import type { CcPluginManifest } from './types.ts';
+import { ComponentTally } from './seams.ts';
+/** The commands seam: accepts a typed slash-command definition. */
+export interface CommandsSeam {
+    /**
+     * Register one command definition.
+     * @param definition - the command to register.
+     * @returns the exact disposer that removes the command.
+     */
+    register(definition: CommandDefinition): () => void;
+}
+/** The minimal typed command definition this loader emits. */
+export interface CommandDefinition {
+    /** The bare command name (harness registries reject colon names). */
+    readonly name: string;
+    /** Human-readable command description. */
+    readonly description: string;
+    /** Argument placeholder hint, surfaced to the user. */
+    readonly input?: {
+        hint: string;
+    };
+    /** Dispatches the rendered command body as a user prompt on the invoking agent. */
+    readonly handler: (invocation: CommandInvocationLike) => CommandResult | Promise<CommandResult>;
+}
+/** Result shape the loader's command handlers return. */
+/**
+ * Minimal structural view of the upstream command invocation. Duck-typed on
+ * purpose: the loader never imports the commands package directly.
+ */
+export interface CommandInvocationLike {
+    /** The agent the command was executed against; the prompt injection target. */
+    readonly agent: {
+        followup(message: unknown): unknown;
+    };
+    /** Raw argument text following the command name (empty when none given). */
+    readonly rawInput: string;
+}
+export type CommandResult = {
+    readonly kind: 'success';
+    readonly text?: string;
+} | {
+    readonly kind: 'error';
+    readonly text: string;
+};
+/** A plugin command's public summary, using the `plugin:command` display name. */
+export interface CcPluginCommandInfo {
+    /** Display name `plugin:command`, even when both parts are identical. */
+    readonly name: string;
+    /** The plugin's manifest name. */
+    readonly plugin: string;
+    /** Human-readable command description. */
+    readonly description: string;
+    /** Argument placeholder hint, when one is known. */
+    readonly argumentHint?: string;
+}
+/** One mounted plugin command: its public summary plus a direct dispatcher. */
+export interface MountedPluginCommand {
+    /** Public summary (colon display name; served by the host's own channel). */
+    readonly info: CcPluginCommandInfo;
+    /**
+     * Dispatch the rendered command body as a user prompt on the given agent —
+     * the same path the harness-registered bare alias uses.
+     */
+    run(invocation: CommandInvocationLike): CommandResult | Promise<CommandResult>;
+}
+/** Commands live under this directory in a plugin root, when present. */
+export declare const STANDARD_COMMANDS_DIR = "commands";
+/** Options for mounting one plugin's commands. */
+export interface MountCommandsOptions {
+    /** The plugin root directory; inline `source` paths resolve against it. */
+    readonly pluginRoot: string;
+    /** The parsed manifest, whose `commands` field drives registration. */
+    readonly manifest: CcPluginManifest;
+    /** The commands seam (probed; `undefined` to skip commands). */
+    readonly commands: CommandsSeam | undefined;
+}
+/**
+ * Register a plugin's manifest commands.
+ *
+ * Only bare command names reach the host commands seam: harness command
+ * registries validate names against `/^[a-z][a-z0-9_-]*$/` and reject the
+ * `plugin:command` colon form. The colon form stays available through the
+ * returned `mounted` list, for hosts that expose plugin commands on their own
+ * channel (e.g. cc-shell's `CcPluginsService.runPluginCommand`).
+ *
+ * A rejected registration (bare name already taken) skips that one command,
+ * never the whole plugin mount.
+ *
+ * @param options - plugin root, manifest, and the commands seam.
+ * @returns mounted disposers, per-component counts, and the mounted commands.
+ */
+export declare function mountCommands(options: MountCommandsOptions): {
+    disposers: (() => void)[];
+    mounted: MountedPluginCommand[];
+    tally: ComponentTally;
+};
+/**
+ * Substitute `$ARGUMENTS` with the invocation's raw input and steer the
+ * rendered command body into the conversation as a user message — the same
+ * cross-plane seam the upstream `/plan` command uses. Returning success
+ * without `text` keeps the command plane from echoing the body back as a
+ * status row: the injected message itself is the visible artifact.
+ *
+ * `Agent.followup` is async upstream, so a thenable return is awaited and a
+ * rejection is folded into `{ kind: 'error' }` instead of surfacing as an
+ * unhandled rejection (a synchronous throw is caught the same way).
+ */
+export declare function dispatchCommandPrompt(invocation: CommandInvocationLike, body: string): CommandResult | Promise<CommandResult>;
+//# sourceMappingURL=commands.d.ts.map

package/lib/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAa,MAAM,YAAY,CAAA;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE3C,mEAAmE;AACnE,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,iBAAiB,GAAG,MAAM,IAAI,CAAA;CACpD;AAED,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,0CAA0C;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACjC,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,CAAC,UAAU,EAAE,qBAAqB,KAAK,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;CAChG;AAED,yDAAyD;AACzD;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAA;KAAE,CAAA;IACvD,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAErD,kFAAkF;AAClF,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,0CAA0C;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,oDAAoD;IACpD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B;AAED,+EAA+E;AAC/E,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAA;IAClC;;;OAGG;IACH,GAAG,CAAC,UAAU,EAAE,qBAAqB,GAAG,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;CAC/E;AAED,yEAAyE;AACzE,eAAO,MAAM,qBAAqB,aAAa,CAAA;AAE/C,kDAAkD;AAClD,MAAM,WAAW,oBAAoB;IACnC,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,CAAA;CAC5C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG;IAC5D,SAAS,EAAE,CAAC,MAAM,IAAI,CAAC,EAAE,CAAA;IACzB,OAAO,EAAE,oBAAoB,EAAE,CAAA;IAC/B,KAAK,EAAE,cAAc,CAAA;CACtB,CA4CA;AAwDD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,qBAAqB,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAkB7H"}

package/lib/commands.js

@@ -0,0 +1,159 @@
+/**
+ * Mount a Claude Code plugin's slash commands.
+ *
+ * Translates manifest `commands` entries (inline content or a source file) into
+ * typed command definitions registered on the commands seam. Each handler
+ * substitutes `$ARGUMENTS` and dispatches the rendered body as a user prompt
+ * on the invoking agent; registration is effect-scoped.
+ *
+ * @module
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { parseCcFrontmatter, parseCcFrontmatterDocument } from '@dsh-cc/skill-loader';
+import { basename, join, resolve } from 'node:path';
+import { ComponentTally } from "./seams.js";
+/** Commands live under this directory in a plugin root, when present. */
+export const STANDARD_COMMANDS_DIR = 'commands';
+/**
+ * Register a plugin's manifest commands.
+ *
+ * Only bare command names reach the host commands seam: harness command
+ * registries validate names against `/^[a-z][a-z0-9_-]*$/` and reject the
+ * `plugin:command` colon form. The colon form stays available through the
+ * returned `mounted` list, for hosts that expose plugin commands on their own
+ * channel (e.g. cc-shell's `CcPluginsService.runPluginCommand`).
+ *
+ * A rejected registration (bare name already taken) skips that one command,
+ * never the whole plugin mount.
+ *
+ * @param options - plugin root, manifest, and the commands seam.
+ * @returns mounted disposers, per-component counts, and the mounted commands.
+ */
+export function mountCommands(options) {
+    const tally = new ComponentTally('commands');
+    const disposers = [];
+    const mounted = [];
+    if (options.commands === undefined) {
+        tally.addSkipped('commands seam "commands" is not mounted');
+        return { disposers, mounted, tally };
+    }
+    const entries = options.manifest.commandsDeclared
+        ? [...options.manifest.commands]
+        : defaultCommandEntries(options.pluginRoot, tally);
+    if (entries.length === 0) {
+        tally.addSkipped('plugin ships no commands');
+        return { disposers, mounted, tally };
+    }
+    for (const entry of entries) {
+        const rendered = renderCommand(options.pluginRoot, entry);
+        if (rendered.error !== undefined) {
+            tally.addFailed(`command "${entry.name}": ${rendered.error}`);
+            continue;
+        }
+        const hint = entry.argumentHint ?? rendered.argumentHint;
+        const body = rendered.body ?? '';
+        const info = {
+            name: `${options.manifest.name}:${entry.name}`,
+            plugin: options.manifest.name,
+            description: entry.description ?? rendered.description ?? '',
+            ...hint === undefined ? {} : { argumentHint: hint },
+        };
+        const run = (invocation) => dispatchCommandPrompt(invocation, body);
+        try {
+            disposers.push(options.commands.register({
+                name: entry.name,
+                description: info.description,
+                ...hint === undefined ? {} : { input: { hint } },
+                handler: run,
+            }));
+            mounted.push({ info, run });
+            tally.addLoaded();
+        }
+        catch (error) {
+            tally.addSkipped(`bare name "${entry.name}" not registered: ${String(error)}`);
+        }
+    }
+    return { disposers, mounted, tally };
+}
+/**
+ * Scan `commands/*.md` when the manifest omitted `commands`. Nested
+ * subdirectories are skipped with a reason (no silent drop, no colon names).
+ */
+function defaultCommandEntries(pluginRoot, tally) {
+    const dir = join(pluginRoot, STANDARD_COMMANDS_DIR);
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            tally.addSkipped(`skipped nested commands directory "${entry.name}"`);
+            continue;
+        }
+        if (!entry.isFile() && !entry.isSymbolicLink())
+            continue;
+        if (!entry.name.endsWith('.md'))
+            continue;
+        found.push({ name: basename(entry.name, '.md'), source: join(STANDARD_COMMANDS_DIR, entry.name) });
+    }
+    return found;
+}
+/** Resolve a command entry to consumable content, or a failure reason. */
+function renderCommand(pluginRoot, entry) {
+    if (entry.content !== undefined) {
+        return { body: entry.content };
+    }
+    if (entry.source !== undefined) {
+        const path = resolve(pluginRoot, entry.source);
+        try {
+            const raw = readFileSync(path, 'utf8');
+            const document = parseCcFrontmatterDocument(raw);
+            const parsed = parseCcFrontmatter(raw);
+            if (document === undefined || parsed === undefined)
+                return { body: raw };
+            return {
+                body: document.body,
+                ...parsed.description === undefined ? {} : { description: parsed.description },
+                ...parsed.argumentHint === undefined ? {} : { argumentHint: parsed.argumentHint },
+            };
+        }
+        catch (error) {
+            return { error: `could not read command file "${entry.source}": ${String(error)}` };
+        }
+    }
+    return { error: 'has neither "content" nor a readable "source"' };
+}
+/**
+ * Substitute `$ARGUMENTS` with the invocation's raw input and steer the
+ * rendered command body into the conversation as a user message — the same
+ * cross-plane seam the upstream `/plan` command uses. Returning success
+ * without `text` keeps the command plane from echoing the body back as a
+ * status row: the injected message itself is the visible artifact.
+ *
+ * `Agent.followup` is async upstream, so a thenable return is awaited and a
+ * rejection is folded into `{ kind: 'error' }` instead of surfacing as an
+ * unhandled rejection (a synchronous throw is caught the same way).
+ */
+export function dispatchCommandPrompt(invocation, body) {
+    const text = body.split('$ARGUMENTS').join(invocation.rawInput);
+    let scheduled;
+    try {
+        scheduled = invocation.agent.followup(createUserMessage({
+            content: [{ type: 'text', text }],
+            source: { kind: 'user' },
+        }));
+    }
+    catch (error) {
+        return { kind: 'error', text: `could not dispatch command prompt: ${String(error)}` };
+    }
+    if (scheduled === null || scheduled === undefined || typeof scheduled.then !== 'function') {
+        return { kind: 'success' };
+    }
+    return Promise.resolve(scheduled).then(() => ({ kind: 'success' }), (error) => ({ kind: 'error', text: `could not dispatch command prompt: ${String(error)}` }));
+}
+//# sourceMappingURL=commands.js.map

package/lib/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAA;AACrF,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEnD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AA+D3C,yEAAyE;AACzE,MAAM,CAAC,MAAM,qBAAqB,GAAG,UAAU,CAAA;AAY/C;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAAC,OAA6B;IAKzD,MAAM,KAAK,GAAG,IAAI,cAAc,CAAC,UAAU,CAAC,CAAA;IAC5C,MAAM,SAAS,GAAmB,EAAE,CAAA;IACpC,MAAM,OAAO,GAA2B,EAAE,CAAA;IAC1C,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACnC,KAAK,CAAC,UAAU,CAAC,yCAAyC,CAAC,CAAA;QAC3D,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,CAAA;IACtC,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,gBAAgB;QAC/C,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAChC,CAAC,CAAC,qBAAqB,CAAC,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC,CAAA;IACpD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,KAAK,CAAC,UAAU,CAAC,0BAA0B,CAAC,CAAA;QAC5C,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,CAAA;IACtC,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC,CAAA;QACzD,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YACjC,KAAK,CAAC,SAAS,CAAC,YAAY,KAAK,CAAC,IAAI,MAAM,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;YAC7D,SAAQ;QACV,CAAC;QACD,MAAM,IAAI,GAAG,KAAK,CAAC,YAAY,IAAI,QAAQ,CAAC,YAAY,CAAA;QACxD,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,IAAI,EAAE,CAAA;QAChC,MAAM,IAAI,GAAwB;YAChC,IAAI,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,EAAE;YAC9C,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI;YAC7B,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,QAAQ,CAAC,WAAW,IAAI,EAAE;YAC5D,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE;SACpD,CAAA;QACD,MAAM,GAAG,GAAG,CAAC,UAAiC,EAAE,EAAE,CAAC,qBAAqB,CAAC,UAAU,EAAE,IAAI,CAAC,CAAA;QAC1F,IAAI,CAAC;YACH,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBACvC,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE;gBAChD,OAAO,EAAE,GAAG;aACb,CAAC,CAAC,CAAA;YACH,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAA;YAC3B,KAAK,CAAC,SAAS,EAAE,CAAA;QACnB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,KAAK,CAAC,UAAU,CAAC,cAAc,KAAK,CAAC,IAAI,qBAAqB,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QAChF,CAAC;IACH,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,CAAA;AACtC,CAAC;AAED;;;GAGG;AACH,SAAS,qBAAqB,CAAC,UAAkB,EAAE,KAAqB;IACtE,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,EAAE,qBAAqB,CAAC,CAAA;IACnD,IAAI,OAAO,CAAA;IACX,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAA;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAA;IACX,CAAC;IACD,MAAM,KAAK,GAAgB,EAAE,CAAA;IAC7B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,KAAK,CAAC,UAAU,CAAC,sCAAsC,KAAK,CAAC,IAAI,GAAG,CAAC,CAAA;YACrE,SAAQ;QACV,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,EAAE;YAAE,SAAQ;QACxD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,SAAQ;QACzC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,qBAAqB,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACpG,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,0EAA0E;AAC1E,SAAS,aAAa,CAAC,UAAkB,EAAE,KAAgB;IAMzD,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,CAAA;IAChC,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;QAC9C,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;YACtC,MAAM,QAAQ,GAAG,0BAA0B,CAAC,GAAG,CAAC,CAAA;YAChD,MAAM,MAAM,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAA;YACtC,IAAI,QAAQ,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAA;YACxE,OAAO;gBACL,IAAI,EAAE,QAAQ,CAAC,IAAI;gBACnB,GAAG,MAAM,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE;gBAC9E,GAAG,MAAM,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE;aAClF,CAAA;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,EAAE,KAAK,EAAE,gCAAgC,KAAK,CAAC,MAAM,MAAM,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,CAAA;QACrF,CAAC;IACH,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,+CAA+C,EAAE,CAAA;AACnE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CAAC,UAAiC,EAAE,IAAY;IACnF,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAA;IAC/D,IAAI,SAAkB,CAAA;IACtB,IAAI,CAAC;QACH,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,iBAAiB,CAAC;YACtD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;YACjC,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;SACzB,CAAC,CAAC,CAAA;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,sCAAsC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,CAAA;IACvF,CAAC;IACD,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,SAAS,IAAI,OAAQ,SAAgC,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAClH,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAA;IAC5B,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CACpC,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAY,CAAA,EACpC,CAAC,KAAc,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,sCAAsC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CACrG,CAAA;AACH,CAAC"}

package/lib/discovery.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Discover Claude Code plugin roots the way Claude Code actually installs them.
+ *
+ * Default (no `pluginDirs`): the intersection of `enabledPlugins` across the
+ * user/project/local settings cascade and `installed_plugins.json`. Explicit
+ * `pluginDirs` keeps the historical flatten (a root, or its one-level
+ * children, that hold `plugin.json` or `.claude-plugin/plugin.json`). Empty
+ * or null `pluginDirs` disables discovery. Best-effort: unreadable files and
+ * missing install paths skip rather than throw.
+ *
+ * @module
+ */
+/** One discovered plugin root plus the name used to match marketplace overlays. */
+export interface DiscoveredCcPlugin {
+    /** Absolute plugin root (the directory that holds the manifest / components). */
+    readonly root: string;
+    /** Plugin name without `@marketplace`, used as a marketplace-entry hint. */
+    readonly nameHint: string;
+}
+/** Options for one discovery pass. */
+export interface DiscoverCcPluginRootsOptions {
+    /**
+     * Explicit discovery roots. `undefined` (absent) uses installed ∩ enabled;
+     * `[]` or `null` disables discovery; a non-empty list flattens those dirs.
+     */
+    readonly pluginDirs?: readonly string[] | null;
+    /** Claude config home; defaults to `$CLAUDE_CONFIG_DIR` or `~/.claude`. */
+    readonly claudeHome?: string;
+    /** Workspace used for project/local `enabledPlugins`; defaults to `process.cwd()`. */
+    readonly cwd?: string;
+    /** Optional logger for project-scope cwd and skipped bare enablement keys. */
+    readonly log?: {
+        info(message: string): void;
+        warn(message: string): void;
+    };
+}
+/** Nested Claude Code manifest path, preferred over a top-level `plugin.json`. */
+export declare const NESTED_MANIFEST: string;
+/** Legacy / fixture manifest path at the plugin root. */
+export declare const TOP_LEVEL_MANIFEST = "plugin.json";
+/**
+ * Discover plugin roots for the glue to mount.
+ * @param options - explicit dirs or the Claude-home / cwd pair for the default path.
+ * @returns unique `{ root, nameHint }` entries, in discovery order.
+ */
+export declare function discoverCcPluginRoots(options?: DiscoverCcPluginRootsOptions): DiscoveredCcPlugin[];
+/** `$CLAUDE_CONFIG_DIR` if set, otherwise `~/.claude`. */
+export declare function resolveClaudeHome(explicit?: string): string;
+//# sourceMappingURL=discovery.d.ts.map

package/lib/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,mFAAmF;AACnF,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,sCAAsC;AACtC,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAA;IAC9C,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,sFAAsF;IACtF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,CAAC,EAAE;QAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAA;CAC5E;AAED,kFAAkF;AAClF,eAAO,MAAM,eAAe,QAAwC,CAAA;AAEpE,yDAAyD;AACzD,eAAO,MAAM,kBAAkB,gBAAgB,CAAA;AAE/C;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,4BAAiC,GAAG,kBAAkB,EAAE,CAQtG;AAOD,0DAA0D;AAC1D,wBAAgB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAK3D"}

package/lib/discovery.js

@@ -0,0 +1,223 @@
+/**
+ * Discover Claude Code plugin roots the way Claude Code actually installs them.
+ *
+ * Default (no `pluginDirs`): the intersection of `enabledPlugins` across the
+ * user/project/local settings cascade and `installed_plugins.json`. Explicit
+ * `pluginDirs` keeps the historical flatten (a root, or its one-level
+ * children, that hold `plugin.json` or `.claude-plugin/plugin.json`). Empty
+ * or null `pluginDirs` disables discovery. Best-effort: unreadable files and
+ * missing install paths skip rather than throw.
+ *
+ * @module
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+import { resolveLocalSettingsDir } from '@dsh-cc/settings-cascade/local-root';
+/** Nested Claude Code manifest path, preferred over a top-level `plugin.json`. */
+export const NESTED_MANIFEST = join('.claude-plugin', 'plugin.json');
+/** Legacy / fixture manifest path at the plugin root. */
+export const TOP_LEVEL_MANIFEST = 'plugin.json';
+/**
+ * Discover plugin roots for the glue to mount.
+ * @param options - explicit dirs or the Claude-home / cwd pair for the default path.
+ * @returns unique `{ root, nameHint }` entries, in discovery order.
+ */
+export function discoverCcPluginRoots(options = {}) {
+    if (options.pluginDirs === null || isEmptyList(options.pluginDirs))
+        return [];
+    if (options.pluginDirs !== undefined)
+        return flattenPluginDirs(options.pluginDirs);
+    return discoverInstalledEnabled(resolveClaudeHome(options.claudeHome), options.cwd ?? process.cwd(), options.log);
+}
+/** True when an explicit `pluginDirs` list is present and empty. */
+function isEmptyList(value) {
+    return value !== undefined && value.length === 0;
+}
+/** `$CLAUDE_CONFIG_DIR` if set, otherwise `~/.claude`. */
+export function resolveClaudeHome(explicit) {
+    if (explicit !== undefined)
+        return explicit;
+    const fromEnv = process.env.CLAUDE_CONFIG_DIR;
+    if (fromEnv !== undefined && fromEnv.length > 0)
+        return fromEnv;
+    return join(homedir(), '.claude');
+}
+/** Flatten configured dirs: the dir itself, or one-level children that look like plugin roots. */
+function flattenPluginDirs(dirs) {
+    const found = [];
+    const seen = new Set();
+    for (const dir of dirs) {
+        const hint = nameHintFromRoot(dir);
+        if (hint !== undefined) {
+            pushUnique(found, seen, dir, hint);
+            continue;
+        }
+        try {
+            for (const entry of readdirSync(dir, { withFileTypes: true })) {
+                if (!entry.isDirectory())
+                    continue;
+                const child = join(dir, entry.name);
+                const childHint = nameHintFromRoot(child);
+                if (childHint !== undefined)
+                    pushUnique(found, seen, child, childHint);
+            }
+        }
+        catch {
+            // Best-effort: an unreadable discovery root contributes nothing.
+        }
+    }
+    return found;
+}
+/**
+ * Manifest `name` when a nested or top-level plugin.json is present.
+ * Missing files are not a plugin root; unreadable/invalid JSON still is (basename fallback).
+ */
+function nameHintFromRoot(dir) {
+    for (const file of [NESTED_MANIFEST, TOP_LEVEL_MANIFEST]) {
+        const text = readText(join(dir, file));
+        if (text === undefined)
+            continue;
+        const parsed = parseJson(text);
+        if (isRecord(parsed) && typeof parsed['name'] === 'string' && parsed['name'].length > 0)
+            return parsed['name'];
+        return basename(resolve(dir));
+    }
+    return undefined;
+}
+/** Default path: enabledPlugins cascade ∩ installed_plugins.json. */
+function discoverInstalledEnabled(claudeHome, cwd, log) {
+    const enabled = enabledKeys(claudeHome, cwd, log);
+    const installed = readInstalled(join(claudeHome, 'plugins', 'installed_plugins.json'));
+    const found = [];
+    const seen = new Set();
+    for (const key of enabled) {
+        const picked = installed[key];
+        if (picked === undefined || !isDirectory(picked))
+            continue;
+        pushUnique(found, seen, picked, key.slice(0, key.indexOf('@')));
+    }
+    return found;
+}
+/** Keys whose cascaded `enabledPlugins` value is JSON `true`, in first-seen order. */
+function enabledKeys(claudeHome, cwd, log) {
+    const cascade = [
+        { path: join(claudeHome, 'settings.json'), scope: 'user' },
+        { path: join(cwd, '.claude', 'settings.json'), scope: 'project' },
+        {
+            // Claude Code-parity: the *local* settings file is read from the git
+            // main checkout root (linked worktree) or git toplevel (subdirectory
+            // start); the project settings above stay at the launch cwd.
+            path: join(resolveLocalSettingsDir(cwd), '.claude', 'settings.local.json'),
+            scope: 'project',
+        },
+    ];
+    const state = new Map();
+    const order = [];
+    let projectScoped = false;
+    for (const file of cascade) {
+        const parsed = readJson(file.path);
+        if (!isRecord(parsed))
+            continue;
+        const block = parsed['enabledPlugins'];
+        if (!isRecord(block))
+            continue;
+        if (file.scope === 'project' && Object.keys(block).length > 0)
+            projectScoped = true;
+        for (const [key, value] of Object.entries(block)) {
+            if (typeof value !== 'boolean')
+                continue;
+            if (!state.has(key))
+                order.push(key);
+            state.set(key, value);
+        }
+    }
+    if (projectScoped)
+        log?.info(`cc-plugin-loader: project-scope enabledPlugins read from cwd ${cwd}`);
+    const enabled = [];
+    for (const key of order) {
+        if (state.get(key) !== true)
+            continue;
+        if (!key.includes('@')) {
+            log?.warn(`cc-plugin-loader: skipping bare enabledPlugins key "${key}" (expected name@marketplace)`);
+            continue;
+        }
+        enabled.push(key);
+    }
+    return enabled;
+}
+/** Winning `installPath` per `name@marketplace` (latest lastUpdated, then later array element). */
+function readInstalled(path) {
+    const parsed = readJson(path);
+    if (!isRecord(parsed))
+        return {};
+    const plugins = parsed['plugins'];
+    if (!isRecord(plugins))
+        return {};
+    const out = {};
+    for (const [key, raw] of Object.entries(plugins)) {
+        if (!Array.isArray(raw))
+            continue;
+        const picked = pickInstallPath(raw);
+        if (picked !== undefined)
+            out[key] = picked;
+    }
+    return out;
+}
+function pickInstallPath(raw) {
+    let best;
+    for (const [index, item] of raw.entries()) {
+        if (!isRecord(item) || typeof item['installPath'] !== 'string')
+            continue;
+        const candidate = { path: item['installPath'], time: parseTime(item['lastUpdated']), index };
+        if (best === undefined || candidate.time > best.time || (candidate.time === best.time && candidate.index > best.index)) {
+            best = candidate;
+        }
+    }
+    return best?.path;
+}
+function parseTime(value) {
+    if (typeof value !== 'string')
+        return Number.NEGATIVE_INFINITY;
+    const time = Date.parse(value);
+    return Number.isNaN(time) ? Number.NEGATIVE_INFINITY : time;
+}
+function pushUnique(found, seen, root, nameHint) {
+    const resolved = resolve(root);
+    if (seen.has(resolved))
+        return;
+    seen.add(resolved);
+    found.push({ root: resolved, nameHint });
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function readText(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function readJson(path) {
+    const text = readText(path);
+    return text === undefined ? undefined : parseJson(text);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=discovery.js.map

package/lib/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"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"}

package/lib/hooks.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Mount a Claude Code plugin's hooks.
+ *
+ * Reads the plugin's `hooks/hooks.json` (or an inline manifest `hooks`
+ * declaration), validates the structure, and injects the hooks into the
+ * hooks-claude-code bridge through the optional `hooks` guest seam. When the
+ * seam is absent the component is reported skipped, never failed, so a
+ * deployment without the bridge keeps loading the rest of the plugin.
+ *
+ * @module
+ */
+import type { CcPluginManifest } from './types.ts';
+import { ComponentTally } from './seams.ts';
+/** The hooks seam: accepts a plugin's translated per-event hooks. */
+export interface HooksSeam {
+    /**
+     * Merge a plugin's hooks into the bridge.
+     * @param pluginName - the plugin that owns the hooks.
+     * @param config - the per-event hook map (`ClaudeCodeHookConfig` shape).
+     * @returns the exact disposer that removes the injected hooks.
+     */
+    mergePluginHooks(pluginName: string, config: unknown): () => void;
+}
+/** Hooks live under this file in a plugin root, when present. */
+export declare const STANDARD_HOOKS_FILE = "hooks/hooks.json";
+/** Options for mounting one plugin's hooks. */
+export interface MountHooksOptions {
+    /** The plugin root directory; the standard hooks file resolves against it. */
+    readonly pluginRoot: string;
+    /** The parsed manifest; `hooks` supplies an inline or file reference. */
+    readonly manifest: CcPluginManifest;
+    /** The hooks seam (probed; `undefined` to skip hooks). */
+    readonly hooks: HooksSeam | undefined;
+}
+/**
+ * Read and inject a plugin's hooks through the optional seam.
+ * @param options - plugin root, manifest, and the hooks seam.
+ * @returns mounted disposers and per-component counts.
+ */
+export declare function mountHooks(options: MountHooksOptions): {
+    disposers: (() => void)[];
+    tally: ComponentTally;
+};
+//# sourceMappingURL=hooks.d.ts.map

package/lib/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE3C,qEAAqE;AACrE,MAAM,WAAW,SAAS;IACxB;;;;;OAKG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,CAAA;CAClE;AAED,iEAAiE;AACjE,eAAO,MAAM,mBAAmB,qBAAqB,CAAA;AAErD,+CAA+C;AAC/C,MAAM,WAAW,iBAAiB;IAChC,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAAA;CACtC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG;IAAE,SAAS,EAAE,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,CAmB3G"}