@nexrall/code-core 1.4.77 → 1.4.78

package/dist/plugins/index.js

@@ -33,10 +33,9 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FILE_CANDIDATES = void 0;
+exports.readPluginManifest = exports.resolvePluginFile = exports.FILE_CANDIDATES = void 0;
 exports.isPluginDisabled = isPluginDisabled;
 exports.setPluginDisabled = setPluginDisabled;
-exports.resolvePluginFile = resolvePluginFile;
 exports.loadPlugins = loadPlugins;
 exports.findPlugin = findPlugin;
 exports.pluginAssetDirs = pluginAssetDirs;
@@ -46,6 +45,11 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const data_1 = require("./data");
+const files_1 = require("./files");
+var files_2 = require("./files");
+Object.defineProperty(exports, "FILE_CANDIDATES", { enumerable: true, get: function () { return files_2.FILE_CANDIDATES; } });
+Object.defineProperty(exports, "resolvePluginFile", { enumerable: true, get: function () { return files_2.resolvePluginFile; } });
+Object.defineProperty(exports, "readPluginManifest", { enumerable: true, get: function () { return files_2.readPluginManifest; } });
 // ─── Enable / disable ──────────────────────────────────────────────────────────
 //
 // A marker file rather than a registry list, so the on/off state travels WITH
@@ -80,39 +84,13 @@ function setPluginDisabled(dir, disabled) {
     }
 }
 /**
- * Where each single-file component may live, in priority order.
- *
- * Our own layout is checked first so a plugin shipping both is unambiguous, and
- * so this stays additive: nothing that worked before changes behaviour.
- *
- * SECURITY: `hooks` and `mcp` here are code-execution surfaces. Every reader
- * below and `inspectPluginDir` in installer.ts MUST resolve through this same
- * table — if the loader reads a path the inspector does not check, a plugin can
- * run commands that the install-time warning never mentioned. Adding a candidate
- * without updating the inspector is exactly that bug, so the two are pinned
- * together by a test.
+ * Where each single-file component may live, in priority order — moved to
+ * ./files.ts (S24) so parsing-only modules (validate, the config store) can
+ * resolve paths without importing this loader (which imports them back).
+ * Re-exported above for existing callers.
  */
-exports.FILE_CANDIDATES = {
-    manifest: ['plugin.json', path.join('.claude-plugin', 'plugin.json')],
-    hooks: ['hooks.json', path.join('hooks', 'hooks.json')],
-    mcp: ['mcp.json', '.mcp.json'],
-};
-/** First existing candidate path for a component, or null. */
-function resolvePluginFile(dir, kind) {
-    for (const rel of exports.FILE_CANDIDATES[kind]) {
-        const full = path.join(dir, rel);
-        try {
-            if (fs.statSync(full).isFile())
-                return full;
-        }
-        catch {
-            /* try the next candidate */
-        }
-    }
-    return null;
-}
 function readMeta(dir) {
-    const file = resolvePluginFile(dir, 'manifest');
+    const file = (0, files_1.resolvePluginFile)(dir, 'manifest');
     if (!file)
         return {};
     try {
@@ -215,12 +193,12 @@ function pluginAssetDirs(workDir, kind) {
  * processes their NEXRALL_PLUGIN_DATA (see runHookHandler). Both entry forms are stamped:
  * the flat one (the entry IS the handler) and the nested one (each item under `hooks`).
  */
-function pluginHooks(workDir) {
+function pluginHooks(workDir, transform) {
     const merged = {};
     for (const p of loadPlugins(workDir)) {
         if (p.disabled)
             continue;
-        const file = resolvePluginFile(p.dir, 'hooks');
+        const file = (0, files_1.resolvePluginFile)(p.dir, 'hooks');
         if (!file)
             continue;
         try {
@@ -231,7 +209,15 @@ function pluginHooks(workDir) {
             for (const [phase, entries] of Object.entries(hooks)) {
                 if (!Array.isArray(entries))
                     continue;
-                merged[phase] = [...(merged[phase] ?? []), ...entries.map((e) => stampPlugin(e, p.name))];
+                // `transform` (S24) lets plugins/resolve.ts bake each handler's resolved
+                // userConfig env map in, keeping THIS loader free of value resolution.
+                merged[phase] = [
+                    ...(merged[phase] ?? []),
+                    ...entries.map((e) => {
+                        const stamped = stampPlugin(e, p.name);
+                        return transform ? transform(stamped, p.name) : stamped;
+                    }),
+                ];
             }
         }
         catch {
@@ -260,12 +246,12 @@ function stampPlugin(entry, plugin) {
  * this is the only place a server can keep state. A plugin that set the variable itself keeps
  * its own value: an explicit config value is never overridden here.
  */
-function pluginMcpServers(workDir) {
+function pluginMcpServers(workDir, transform) {
     const merged = {};
     for (const p of loadPlugins(workDir)) {
         if (p.disabled)
             continue;
-        const file = resolvePluginFile(p.dir, 'mcp');
+        const file = (0, files_1.resolvePluginFile)(p.dir, 'mcp');
         if (!file)
             continue;
         try {
@@ -273,8 +259,12 @@ function pluginMcpServers(workDir) {
             const j = JSON.parse(raw);
             const servers = (j.mcpServers ?? j);
             for (const [name, cfg] of Object.entries(servers)) {
-                if (!(name in merged))
-                    merged[name] = withPluginDataEnv(cfg, p.name);
+                if (!(name in merged)) {
+                    // `transform` (S24) is where plugins/resolve.ts substitutes
+                    // `${user_config.KEY}`; the data-dir env is added after it.
+                    const resolved = transform ? transform(cfg, p.name) : cfg;
+                    merged[name] = withPluginDataEnv(resolved, p.name);
+                }
             }
         }
         catch {

package/dist/plugins/resolve.d.ts

@@ -0,0 +1,18 @@
+import { type UserConfigOption } from './userConfig';
+export interface PluginResolvedConfig {
+    options: UserConfigOption[];
+    values: Record<string, unknown>;
+}
+/** pluginHooks + each handler's resolved NEXRALL_PLUGIN_OPTION_* env map. */
+export declare function resolvePluginHooks(workDir: string): Record<string, unknown[]>;
+/** pluginMcpServers + `${user_config.KEY}` substitution (sensitive included). */
+export declare function resolvePluginMcpServers(workDir: string): Record<string, unknown>;
+/**
+ * The resolved config of the plugin a skill DIRECTORY belongs to, or null.
+ * Used by skills.ts's expandSkill: a skill under `<plugin>/skills/<name>/` gets
+ * its body substituted with that plugin's NON-SENSITIVE values.
+ */
+export declare function pluginConfigForSkillDir(workDir: string, skillDir: string): PluginResolvedConfig | null;
+/** Substitute one text with a plugin's values, non-sensitive only (skill bodies). */
+export declare function substituteSkillBody(text: string, cfg: PluginResolvedConfig): string;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/plugins/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/plugins/resolve.ts"],"names":[],"mappings":"AAsBA,OAAO,EAKL,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AAGtB,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAcD,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CA2B7E;AAED,iFAAiF;AACjF,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQhF;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAgBtG;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,oBAAoB,GAAG,MAAM,CAEnF"}

package/dist/plugins/resolve.js

@@ -0,0 +1,152 @@
+"use strict";
+// ─── Resolved plugin surfaces (S24) ──────────────────────────────────────────
+//
+// plugins/index.ts stays pure of VALUES: it merges hooks/mcp across plugins and
+// stamps provenance (which plugin a handler/server came from). This module adds
+// the userConfig layer on top — it resolves each plugin's values (configStore)
+// and hands the loader a transform that bakes them into the surfaces:
+//
+//   • hooks    → `pluginOptions`: the NEXRALL_PLUGIN_OPTION_<KEY> env map each
+//     handler's process receives (attached under the entry's both forms, the
+//     same way `plugin` provenance is stamped);
+//   • mcp.json → `${user_config.KEY}` substituted through the whole server
+//     config (sensitive values INCLUDED — a server config is a trusted
+//     execution surface the user explicitly installed);
+//   • skill bodies → non-sensitive values only (see skills.ts's expandSkill);
+//     a sensitive reference stays the literal token rather than entering model
+//     context.
+//
+// Import graph note: this module may import configStore (hooks.ts imports
+// resolve.ts, and configStore deliberately does not import hooks back).
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePluginHooks = resolvePluginHooks;
+exports.resolvePluginMcpServers = resolvePluginMcpServers;
+exports.pluginConfigForSkillDir = pluginConfigForSkillDir;
+exports.substituteSkillBody = substituteSkillBody;
+const path = __importStar(require("path"));
+const index_1 = require("./index");
+const userConfig_1 = require("./userConfig");
+const configStore_1 = require("./configStore");
+/** Per-plugin resolved config for every ENABLED plugin that declares userConfig. */
+function configsByPlugin(workDir) {
+    const out = new Map();
+    for (const p of (0, index_1.loadPlugins)(workDir)) {
+        if (p.disabled)
+            continue;
+        const { options } = (0, userConfig_1.parseUserConfig)((0, index_1.readPluginManifest)(p.dir));
+        if (!options.length)
+            continue;
+        out.set(p.name, { options, values: (0, configStore_1.resolvePluginConfig)(workDir, p.name, options).values });
+    }
+    return out;
+}
+/** pluginHooks + each handler's resolved NEXRALL_PLUGIN_OPTION_* env map. */
+function resolvePluginHooks(workDir) {
+    const configs = configsByPlugin(workDir);
+    if (!configs.size)
+        return (0, index_1.pluginHooks)(workDir);
+    return (0, index_1.pluginHooks)(workDir, (entry, plugin) => {
+        const cfg = configs.get(plugin);
+        if (!cfg)
+            return entry;
+        const env = (0, userConfig_1.pluginOptionEnvMap)(cfg.options, cfg.values);
+        if (!Object.keys(env).length)
+            return entry;
+        if (!entry || typeof entry !== 'object')
+            return entry;
+        const e = entry;
+        // Both entry forms — the same split pluginHooks' stampPlugin walks.
+        if (Array.isArray(e.hooks)) {
+            return {
+                ...e,
+                hooks: e.hooks.map((h) => {
+                    if (!h || typeof h !== 'object')
+                        return h;
+                    const handler = h;
+                    const prior = handler.pluginOptions;
+                    const priors = prior && typeof prior === 'object' && !Array.isArray(prior) ? prior : {};
+                    return { ...handler, pluginOptions: { ...priors, ...env } };
+                }),
+            };
+        }
+        const prior = e.pluginOptions;
+        const priors = prior && typeof prior === 'object' && !Array.isArray(prior) ? prior : {};
+        return { ...e, pluginOptions: { ...priors, ...env } };
+    });
+}
+/** pluginMcpServers + `${user_config.KEY}` substitution (sensitive included). */
+function resolvePluginMcpServers(workDir) {
+    const configs = configsByPlugin(workDir);
+    if (!configs.size)
+        return (0, index_1.pluginMcpServers)(workDir);
+    return (0, index_1.pluginMcpServers)(workDir, (cfg, plugin) => {
+        const c = configs.get(plugin);
+        if (!c)
+            return cfg;
+        return (0, userConfig_1.substituteUserConfigDeep)(cfg, { options: c.options, values: c.values, includeSensitive: true });
+    });
+}
+/**
+ * The resolved config of the plugin a skill DIRECTORY belongs to, or null.
+ * Used by skills.ts's expandSkill: a skill under `<plugin>/skills/<name>/` gets
+ * its body substituted with that plugin's NON-SENSITIVE values.
+ */
+function pluginConfigForSkillDir(workDir, skillDir) {
+    let dir;
+    try {
+        dir = path.resolve(skillDir);
+    }
+    catch {
+        return null;
+    }
+    for (const p of (0, index_1.loadPlugins)(workDir)) {
+        if (p.disabled)
+            continue;
+        const root = path.resolve(p.dir);
+        if (!dir.startsWith(root + path.sep))
+            continue;
+        const { options } = (0, userConfig_1.parseUserConfig)((0, index_1.readPluginManifest)(p.dir));
+        if (!options.length)
+            return null;
+        return { options, values: (0, configStore_1.resolvePluginConfig)(workDir, p.name, options).values };
+    }
+    return null;
+}
+/** Substitute one text with a plugin's values, non-sensitive only (skill bodies). */
+function substituteSkillBody(text, cfg) {
+    return (0, userConfig_1.substituteUserConfig)(text, { options: cfg.options, values: cfg.values, includeSensitive: false }).text;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/plugins/userConfig.d.ts

@@ -0,0 +1,90 @@
+/** Supported value types, matching Claude Code's set. */
+export declare const USER_CONFIG_TYPES: readonly ["string", "number", "boolean", "directory", "file"];
+export type UserConfigType = (typeof USER_CONFIG_TYPES)[number];
+export interface UserConfigOption {
+    /** Identifier: letters, digits, underscores; may not start with a digit. */
+    key: string;
+    type: UserConfigType;
+    /** Label shown in the configuration surface. */
+    title: string;
+    /** Help text: what the value is and what it changes. */
+    description: string;
+    required?: boolean;
+    /** Value used when the user provides nothing. */
+    default?: string | number | boolean | string[];
+    /** For `string`: the values the field accepts (a picker, not free text). */
+    options?: string[];
+    /** For `string`: allows an array of strings. */
+    multiple?: boolean;
+    /** Masks the value and stores it OUT of settings.json (our secrets file). */
+    sensitive?: boolean;
+    /** For `number`: bounds. */
+    min?: number;
+    max?: number;
+}
+export interface UserConfigParseResult {
+    options: UserConfigOption[];
+    /** Schema problems, each naming its key. A plugin with errors has NO usable options. */
+    errors: string[];
+}
+/**
+ * Parse the manifest's `userConfig` block strictly — Claude Code's rule: an
+ * unknown key inside an option is an error. One bad option invalidates the
+ * WHOLE block (all-or-nothing): a plugin half-configured by a typo would be
+ * worse than one that loudly needs its manifest fixed.
+ */
+export declare function parseUserConfig(manifest: Record<string, unknown> | null | undefined): UserConfigParseResult;
+/** Validate one value against its option. Returns an error string, or null when valid. */
+export declare function validateUserConfigValue(option: UserConfigOption, value: unknown): string | null;
+/**
+ * Coerce a CLI-supplied STRING into the option's type (values arrive from
+ * `--config key=value` / `--values-stdin` where everything is text).
+ * `parseNumber` is strict: "12abc" must not become 12.
+ */
+export declare function coerceUserConfigValue(option: UserConfigOption, raw: string): {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+/** Every `${user_config.KEY}` reference in a string, unique and in first-seen order. */
+export declare function findUserConfigRefs(text: string): string[];
+export interface SubstituteResult {
+    text: string;
+    /** Keys that were replaced. */
+    substituted: string[];
+    /** Sensitive keys skipped because the surface does not accept them. */
+    skippedSensitive: string[];
+    /** Referenced keys with no resolvable value (the literal token is left in place). */
+    unresolved: string[];
+}
+/**
+ * Replace `${user_config.KEY}` with resolved values. A reference with no value
+ * keeps its literal token — a visible failure the plugin's author can debug,
+ * never an empty string masquerading as a value. `includeSensitive: false`
+ * (skill bodies) leaves sensitive tokens in place; configStore decides which
+ * values may be exposed where.
+ */
+export declare function substituteUserConfig(text: string, opts: {
+    options: UserConfigOption[];
+    values: Record<string, unknown>;
+    includeSensitive: boolean;
+}): SubstituteResult;
+/** Deep substitution over an object/array graph (MCP server configs). Strings only. */
+export declare function substituteUserConfigDeep(value: unknown, opts: {
+    options: UserConfigOption[];
+    values: Record<string, unknown>;
+    includeSensitive: boolean;
+}): unknown;
+/** All `${user_config.KEY}` refs found anywhere in a JSON value graph, unique. */
+export declare function collectUserConfigRefsDeep(value: unknown): string[];
+/** Claude Code's naming rule: `CLAUDE_PLUGIN_OPTION_<KEY>` → ours mirrors it. */
+export declare function pluginOptionEnvKey(key: string): string;
+/**
+ * The env map a plugin's hook processes receive. Only scalar values can ride
+ * an environment variable; an array/object value is skipped (a shell would see
+ * "[object Object]" — worse than absent).
+ */
+export declare function pluginOptionEnvMap(options: UserConfigOption[], values: Record<string, unknown>): Record<string, string>;
+//# sourceMappingURL=userConfig.d.ts.map

package/dist/plugins/userConfig.d.ts.map

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