@nexrall/code-core 1.4.76 → 1.4.78

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":"AA6BA,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,+DAAgE,CAAC;AAC/F,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,cAAc,CAAC;IACrB,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC;IAC/C,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,4BAA4B;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,wFAAwF;IACxF,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAiBD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,qBAAqB,CAkB3G;AA4DD,0FAA0F;AAC1F,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,gBAAgB,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAW/F;AAqBD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,gBAAgB,EACxB,GAAG,EAAE,MAAM,GACV;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAsC7D;AAMD,wFAAwF;AACxF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAIzD;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,uEAAuE;IACvE,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,qFAAqF;IACrF,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,gBAAgB,EAAE,OAAO,CAAA;CAAE,GAChG,gBAAgB,CAsBlB;AAED,uFAAuF;AACvF,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE;IAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,gBAAgB,EAAE,OAAO,CAAA;CAAE,GAChG,OAAO,CAWT;AAED,kFAAkF;AAClF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CASlE;AAID,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,gBAAgB,EAAE,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUxB"}

package/dist/plugins/userConfig.js

@@ -0,0 +1,332 @@
+"use strict";
+// ─── Plugin `userConfig` (S24, Claude Code parity — G24) ─────────────────────
+//
+// A plugin that needs a value from the user (an API endpoint, a token, a log
+// directory) declares it in plugin.json instead of asking the user to edit
+// settings by hand:
+//
+//   "userConfig": {
+//     "api_token": { "type": "string", "title": "API token",
+//                    "description": "…", "sensitive": true }
+//   }
+//
+// Values are resolved by configStore.ts (settings `pluginConfigs` → secrets
+// file → manifest default) and reach the plugin three ways, matching Claude
+// Code's model:
+//
+//   • `${user_config.KEY}` substitution — MCP server configs (sensitive values
+//     included) and skill bodies (non-sensitive only; a sensitive reference is
+//     left as the literal token rather than shipped into model context);
+//   • `NEXRALL_PLUGIN_OPTION_<KEY>` environment variables on every hook
+//     process the plugin ships (KEY uppercased) — the ONLY way a shell-form
+//     hook can read a value, because a shell-form `command` rejects
+//     `${user_config.*}` (the substituted value would be re-parsed by the
+//     shell; validate.ts reports the reference as an error);
+//   • the `nex plugin configure` command and the install-time
+//     `--config key=value` flag, which write values back.
+//
+// This module is PURE (no fs): schema parsing, value validation, substitution
+// and env naming. The store lives in configStore.ts.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USER_CONFIG_TYPES = void 0;
+exports.parseUserConfig = parseUserConfig;
+exports.validateUserConfigValue = validateUserConfigValue;
+exports.coerceUserConfigValue = coerceUserConfigValue;
+exports.findUserConfigRefs = findUserConfigRefs;
+exports.substituteUserConfig = substituteUserConfig;
+exports.substituteUserConfigDeep = substituteUserConfigDeep;
+exports.collectUserConfigRefsDeep = collectUserConfigRefsDeep;
+exports.pluginOptionEnvKey = pluginOptionEnvKey;
+exports.pluginOptionEnvMap = pluginOptionEnvMap;
+/** Supported value types, matching Claude Code's set. */
+exports.USER_CONFIG_TYPES = ['string', 'number', 'boolean', 'directory', 'file'];
+const KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Fields an option object may carry. Anything else is an error (strict object). */
+const KNOWN_FIELDS = new Set([
+    'type',
+    'title',
+    'description',
+    'required',
+    'default',
+    'options',
+    'multiple',
+    'sensitive',
+    'min',
+    'max',
+]);
+/**
+ * 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.
+ */
+function parseUserConfig(manifest) {
+    const raw = manifest?.userConfig;
+    if (raw === undefined)
+        return { options: [], errors: [] };
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { options: [], errors: ['userConfig must be an object of option definitions'] };
+    }
+    const options = [];
+    const errors = [];
+    for (const [key, def] of Object.entries(raw)) {
+        const problems = parseOne(key, def);
+        if (typeof problems === 'string') {
+            errors.push(problems);
+            continue;
+        }
+        options.push(problems);
+    }
+    if (errors.length)
+        return { options: [], errors };
+    return { options, errors };
+}
+/** Parse one option; returns the option or its first error. */
+function parseOne(key, def) {
+    if (!KEY_RE.test(key))
+        return `userConfig "${key}": key must be letters, digits and underscores, not starting with a digit`;
+    if (!def || typeof def !== 'object' || Array.isArray(def))
+        return `userConfig "${key}": must be an object`;
+    const d = def;
+    for (const field of Object.keys(d)) {
+        if (!KNOWN_FIELDS.has(field))
+            return `userConfig "${key}": unknown field "${field}" (allowed: ${[...KNOWN_FIELDS].join(', ')})`;
+    }
+    const type = typeof d.type === 'string' ? d.type : undefined;
+    if (!type || !exports.USER_CONFIG_TYPES.includes(type))
+        return `userConfig "${key}": type must be ${exports.USER_CONFIG_TYPES.join(' | ')}`;
+    if (typeof d.title !== 'string' || !d.title.trim())
+        return `userConfig "${key}": title is required`;
+    if (typeof d.description !== 'string' || !d.description.trim())
+        return `userConfig "${key}": description is required`;
+    for (const boolField of ['required', 'multiple', 'sensitive']) {
+        if (d[boolField] !== undefined && typeof d[boolField] !== 'boolean')
+            return `userConfig "${key}": ${boolField} must be a boolean`;
+    }
+    if (d.options !== undefined) {
+        if (type !== 'string')
+            return `userConfig "${key}": options applies to string fields only (this is ${type})`;
+        if (d.multiple === true)
+            return `userConfig "${key}": options cannot be combined with multiple`;
+        if (d.sensitive === true)
+            return `userConfig "${key}": options cannot be combined with sensitive`;
+        if (!Array.isArray(d.options) || !d.options.length)
+            return `userConfig "${key}": options must be a non-empty array`;
+        for (const o of d.options) {
+            if (typeof o !== 'string' || !o.trim() || o.length > 64 || o.length < 1)
+                return `userConfig "${key}": each option must be a plain label of 1-64 characters`;
+        }
+    }
+    if (d.multiple === true && type !== 'string')
+        return `userConfig "${key}": multiple applies to string fields only`;
+    if (d.min !== undefined || d.max !== undefined) {
+        if (type !== 'number')
+            return `userConfig "${key}": min/max apply to number fields only`;
+        if (d.min !== undefined && typeof d.min !== 'number')
+            return `userConfig "${key}": min must be a number`;
+        if (d.max !== undefined && typeof d.max !== 'number')
+            return `userConfig "${key}": max must be a number`;
+        if (typeof d.min === 'number' && typeof d.max === 'number' && d.min > d.max)
+            return `userConfig "${key}": min is greater than max`;
+    }
+    const option = {
+        key,
+        type,
+        title: d.title,
+        description: d.description,
+        ...(d.required === true ? { required: true } : {}),
+        ...(d.multiple === true ? { multiple: true } : {}),
+        ...(d.sensitive === true ? { sensitive: true } : {}),
+        ...(Array.isArray(d.options) ? { options: [...d.options] } : {}),
+        ...(typeof d.min === 'number' ? { min: d.min } : {}),
+        ...(typeof d.max === 'number' ? { max: d.max } : {}),
+    };
+    if (d.default !== undefined) {
+        const bad = validateUserConfigValue(option, d.default);
+        if (bad)
+            return `userConfig "${key}": default is invalid — ${bad}`;
+        option.default = d.default;
+    }
+    return option;
+}
+/** Validate one value against its option. Returns an error string, or null when valid. */
+function validateUserConfigValue(option, value) {
+    if (option.multiple) {
+        if (!Array.isArray(value))
+            return 'expected an array of strings (multiple)';
+        for (const v of value) {
+            if (typeof v !== 'string')
+                return 'every entry must be a string';
+            const bad = validateSingle(option, v);
+            if (bad)
+                return bad;
+        }
+        return null;
+    }
+    return validateSingle(option, value);
+}
+function validateSingle(option, value) {
+    switch (option.type) {
+        case 'string':
+        case 'directory':
+        case 'file':
+            if (typeof value !== 'string')
+                return `expected a ${option.type}`;
+            if (option.options && !option.options.includes(value))
+                return `must be one of: ${option.options.join(', ')}`;
+            return null;
+        case 'number': {
+            if (typeof value !== 'number' || !Number.isFinite(value))
+                return 'expected a number';
+            if (option.min !== undefined && value < option.min)
+                return `must be at least ${option.min}`;
+            if (option.max !== undefined && value > option.max)
+                return `must be at most ${option.max}`;
+            return null;
+        }
+        case 'boolean':
+            return typeof value === 'boolean' ? null : 'expected true or false';
+    }
+}
+/**
+ * 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.
+ */
+function coerceUserConfigValue(option, raw) {
+    if (option.multiple) {
+        // JSON array, or comma-separated.
+        const text = raw.trim();
+        let arr;
+        if (text.startsWith('[')) {
+            try {
+                arr = JSON.parse(text);
+            }
+            catch (e) {
+                return { ok: false, error: `could not parse as a JSON array: ${e.message}` };
+            }
+        }
+        else {
+            arr = text ? text.split(',').map((s) => s.trim()) : [];
+        }
+        const bad = validateUserConfigValue(option, arr);
+        return bad ? { ok: false, error: bad } : { ok: true, value: arr };
+    }
+    switch (option.type) {
+        case 'string':
+        case 'directory':
+        case 'file': {
+            const bad = validateUserConfigValue(option, raw);
+            return bad ? { ok: false, error: bad } : { ok: true, value: raw };
+        }
+        case 'number': {
+            const t = raw.trim();
+            const n = t === '' ? NaN : Number(t);
+            if (!Number.isFinite(n))
+                return { ok: false, error: `"${raw}" is not a number` };
+            const bad = validateUserConfigValue(option, n);
+            return bad ? { ok: false, error: bad } : { ok: true, value: n };
+        }
+        case 'boolean': {
+            const t = raw.trim().toLowerCase();
+            if (t === 'true' || t === '1' || t === 'yes')
+                return { ok: true, value: true };
+            if (t === 'false' || t === '0' || t === 'no')
+                return { ok: true, value: false };
+            return { ok: false, error: `"${raw}" is not a boolean (true/false)` };
+        }
+    }
+}
+// ─── Substitution ────────────────────────────────────────────────────────────
+const REF_RE = /\$\{user_config\.([A-Za-z_][A-Za-z0-9_]*)\}/g;
+/** Every `${user_config.KEY}` reference in a string, unique and in first-seen order. */
+function findUserConfigRefs(text) {
+    const out = new Set();
+    for (const m of text.matchAll(REF_RE))
+        out.add(m[1]);
+    return [...out];
+}
+/**
+ * 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.
+ */
+function substituteUserConfig(text, opts) {
+    const result = { text, substituted: [], skippedSensitive: [], unresolved: [] };
+    const byKey = new Map(opts.options.map((o) => [o.key, o]));
+    result.text = text.replace(REF_RE, (whole, key) => {
+        const option = byKey.get(key);
+        if (!option) {
+            result.unresolved.push(key);
+            return whole; // undeclared reference: validate.ts reports it; runtime keeps it visible
+        }
+        if (option.sensitive && !opts.includeSensitive) {
+            result.skippedSensitive.push(key);
+            return whole;
+        }
+        const v = opts.values[key];
+        if (v === undefined) {
+            result.unresolved.push(key);
+            return whole;
+        }
+        if (!result.substituted.includes(key))
+            result.substituted.push(key);
+        return Array.isArray(v) ? v.join(', ') : String(v);
+    });
+    return result;
+}
+/** Deep substitution over an object/array graph (MCP server configs). Strings only. */
+function substituteUserConfigDeep(value, opts) {
+    if (typeof value === 'string')
+        return substituteUserConfig(value, opts).text;
+    if (Array.isArray(value))
+        return value.map((v) => substituteUserConfigDeep(v, opts));
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = substituteUserConfigDeep(v, opts);
+        }
+        return out;
+    }
+    return value;
+}
+/** All `${user_config.KEY}` refs found anywhere in a JSON value graph, unique. */
+function collectUserConfigRefsDeep(value) {
+    const out = new Set();
+    const walk = (v) => {
+        if (typeof v === 'string')
+            for (const k of findUserConfigRefs(v))
+                out.add(k);
+        else if (Array.isArray(v))
+            v.forEach(walk);
+        else if (v && typeof v === 'object')
+            Object.values(v).forEach(walk);
+    };
+    walk(value);
+    return [...out];
+}
+// ─── Environment ─────────────────────────────────────────────────────────────
+/** Claude Code's naming rule: `CLAUDE_PLUGIN_OPTION_<KEY>` → ours mirrors it. */
+function pluginOptionEnvKey(key) {
+    return `NEXRALL_PLUGIN_OPTION_${key.toUpperCase()}`;
+}
+/**
+ * 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).
+ */
+function pluginOptionEnvMap(options, values) {
+    const env = {};
+    for (const o of options) {
+        const v = values[o.key];
+        if (v === undefined)
+            continue;
+        if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
+            env[pluginOptionEnvKey(o.key)] = String(v);
+        }
+    }
+    return env;
+}
+//# sourceMappingURL=userConfig.js.map

package/dist/plugins/validate.d.ts

@@ -0,0 +1,14 @@
+import { type UserConfigOption } from './userConfig';
+export interface PluginValidateReport {
+    ok: boolean;
+    dir: string;
+    /** Which manifest file was found (null when none). */
+    manifest: string | null;
+    userConfig: UserConfigOption[];
+    errors: string[];
+    warnings: string[];
+}
+export declare function validatePluginDir(dir: string): PluginValidateReport;
+/** One-line human summary lines for the CLI printer (warnings then errors). */
+export declare function formatValidateReport(r: PluginValidateReport): string[];
+//# sourceMappingURL=validate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/plugins/validate.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAkE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErH,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,OAAO,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,sDAAsD;IACtD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,gBAAgB,EAAE,CAAC;IAC/B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAsBD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CA6HnE;AAED,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,oBAAoB,GAAG,MAAM,EAAE,CAUtE"}