@nexrall/code-core 1.4.76 → 1.4.78

package/dist/plugins/configStore.js

@@ -0,0 +1,253 @@
+"use strict";
+// ─── Plugin config values store (S24) ────────────────────────────────────────
+//
+// Where a plugin's userConfig VALUES live:
+//
+//   • non-sensitive → `pluginConfigs.<plugin>.<key>` in a settings file
+//     (managed → user → project → local → `--settings`, read merged; the LAST
+//     tier wins per key, matching every other settings read in the codebase).
+//     Written to the tier you choose — default: the scope the plugin is
+//     installed in, so a project plugin configures itself in the project.
+//   • sensitive → `~/.nexrall/plugin-secrets.json` (0600), keyed the same way.
+//     Claude Code uses the OS credential store here; the CLI has no such
+//     integration, so this is a dedicated 0600 file instead — stated plainly
+//     rather than implied to be a keychain.
+//   • nothing set → the manifest default (resolvePluginConfig reports which).
+//
+// Resolution order per key: secrets → settings → default. An INVALID value at
+// a higher precedence does not win: it is reported (resolvePluginConfig's
+// `invalid`) and resolution continues to the next source, so a typo in
+// settings cannot silently break a working default.
+//
+// This module reads/writes the disk; the schema and substitution half is pure
+// (userConfig.ts).
+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.readPluginSecrets = readPluginSecrets;
+exports.pluginConfigsFromSettings = pluginConfigsFromSettings;
+exports.resolvePluginConfig = resolvePluginConfig;
+exports.savePluginConfig = savePluginConfig;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const rules_1 = require("../permissions/rules");
+const userConfig_1 = require("./userConfig");
+// NOTE (import graph): this module deliberately does NOT use
+// util/settingsFile's writeSetting — that module imports agent/hooks, and
+// hooks imports plugins/resolve → this file; using it would close a cycle.
+// The atomic write below is the same temp-file+rename shape, minus the
+// ConfigChange observer hook (pluginConfig edits do not fire it yet).
+function secretsPath() {
+    return path.join(os.homedir(), '.nexrall', 'plugin-secrets.json');
+}
+/** The settings file a scoped write targets (mirror of util/settingsFile's settingsPath). */
+function tierFile(workDir, scope) {
+    return scope === 'project'
+        ? path.join(workDir, '.nexrall', 'settings.json')
+        : path.join(os.homedir(), '.nexrall', 'settings.json');
+}
+/** Atomic top-level-key write: temp file + rename, so an interrupted write cannot half-JSON a settings file. */
+function writeTierSetting(workDir, scope, key, value) {
+    const file = tierFile(workDir, scope);
+    let existing = {};
+    if (fs.existsSync(file)) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+                existing = parsed;
+            else
+                return { ok: false, path: file, error: 'the file is valid JSON but not an object' };
+        }
+        catch (e) {
+            return { ok: false, path: file, error: `could not parse it: ${e.message}` };
+        }
+    }
+    const next = { ...existing };
+    if (value === undefined)
+        delete next[key];
+    else
+        next[key] = value;
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const tmp = `${file}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n', 'utf-8');
+        fs.renameSync(tmp, file);
+        return { ok: true, path: file };
+    }
+    catch (e) {
+        return { ok: false, path: file, error: e.message };
+    }
+}
+/** The whole secrets file ({} when absent/unreadable/malformed). */
+function readPluginSecrets() {
+    try {
+        const j = JSON.parse(fs.readFileSync(secretsPath(), 'utf-8'));
+        if (!j || typeof j !== 'object' || Array.isArray(j))
+            return {};
+        return j;
+    }
+    catch {
+        return {};
+    }
+}
+/** Write the secrets file 0600. Best-effort: a read-only home must not crash a save that the settings half may still complete. */
+function writePluginSecrets(map) {
+    const file = secretsPath();
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const tmp = `${file}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(map, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+        fs.renameSync(tmp, file);
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, error: e.message };
+    }
+}
+/**
+ * `pluginConfigs` from every settings tier, merged per plugin per key
+ * (last tier wins — the same direction loadSettings uses for `raw`).
+ */
+function pluginConfigsFromSettings(workDir) {
+    const out = {};
+    for (const { raw } of (0, rules_1.settingsTiersRaw)(workDir)) {
+        const pc = raw.pluginConfigs;
+        if (!pc || typeof pc !== 'object' || Array.isArray(pc))
+            continue;
+        for (const [plugin, bag] of Object.entries(pc)) {
+            if (!bag || typeof bag !== 'object' || Array.isArray(bag))
+                continue;
+            out[plugin] = { ...(out[plugin] ?? {}), ...bag };
+        }
+    }
+    return out;
+}
+/** Resolve every declared option to its effective value. Pure reads. */
+function resolvePluginConfig(workDir, pluginName, options) {
+    const secrets = readPluginSecrets()[pluginName] ?? {};
+    const fromSettings = pluginConfigsFromSettings(workDir)[pluginName] ?? {};
+    const values = {};
+    const sources = {};
+    const invalid = [];
+    for (const option of options) {
+        let found = false;
+        for (const [source, bag] of [
+            ['secret', secrets],
+            ['settings', fromSettings],
+        ]) {
+            if (!(option.key in bag))
+                continue;
+            const err = (0, userConfig_1.validateUserConfigValue)(option, bag[option.key]);
+            if (err) {
+                invalid.push({ key: option.key, source, error: err });
+                continue; // a broken higher-precedence value must not mask a working lower one
+            }
+            values[option.key] = bag[option.key];
+            sources[option.key] = source;
+            found = true;
+            break;
+        }
+        if (found)
+            continue;
+        if (option.default !== undefined) {
+            values[option.key] = option.default;
+            sources[option.key] = 'default';
+        }
+    }
+    const missing = options.filter((o) => o.required === true && !(o.key in values)).map((o) => o.key);
+    return { values, sources, missing, invalid };
+}
+/**
+ * Validate + save values. Unknown keys are errors (a typo must not create a
+ * silent no-op entry), as are values that fail their option's validation. The
+ * two halves land in different stores (see the file header).
+ */
+function savePluginConfig(workDir, pluginName, options, values, opts = {}) {
+    const byKey = new Map(options.map((o) => [o.key, o]));
+    const errors = [];
+    const plain = {};
+    const secret = {};
+    for (const [key, value] of Object.entries(values)) {
+        const option = byKey.get(key);
+        if (!option) {
+            errors.push(`"${key}" is not a declared option of plugin "${pluginName}"`);
+            continue;
+        }
+        const bad = (0, userConfig_1.validateUserConfigValue)(option, value);
+        if (bad) {
+            errors.push(`${key}: ${bad}`);
+            continue;
+        }
+        if (option.sensitive)
+            secret[key] = value;
+        else
+            plain[key] = value;
+    }
+    if (errors.length)
+        return { ok: false, errors };
+    const result = { ok: true, errors: [] };
+    if (Object.keys(secret).length) {
+        const map = readPluginSecrets();
+        map[pluginName] = { ...(map[pluginName] ?? {}), ...secret };
+        const w = writePluginSecrets(map);
+        if (!w.ok)
+            return { ok: false, errors: [`could not write the secrets file: ${w.error}`] };
+        result.wroteSecrets = true;
+    }
+    if (Object.keys(plain).length) {
+        const scope = opts.scope ?? 'user';
+        // Read the TARGET tier file's pluginConfigs and merge — the write replaces the
+        // whole top-level key, so passing a partial object would drop other plugins.
+        const file = tierFile(workDir, scope);
+        let tierPc = {};
+        try {
+            const j = JSON.parse(fs.readFileSync(file, 'utf-8'));
+            const pc = j?.pluginConfigs;
+            if (pc && typeof pc === 'object' && !Array.isArray(pc)) {
+                tierPc = pc;
+            }
+        }
+        catch {
+            /* no file yet, or unreadable — start from an empty map; the writer refuses a corrupt file itself */
+        }
+        const merged = { ...tierPc, [pluginName]: { ...(tierPc[pluginName] ?? {}), ...plain } };
+        const w = writeTierSetting(workDir, scope, 'pluginConfigs', merged);
+        if (!w.ok)
+            return { ok: false, errors: [`could not write settings: ${w.error}`] };
+        result.wroteSettings = w.path;
+    }
+    return result;
+}
+//# sourceMappingURL=configStore.js.map

package/dist/plugins/files.d.ts

@@ -0,0 +1,10 @@
+export declare const FILE_CANDIDATES: {
+    readonly manifest: readonly ["plugin.json", string];
+    readonly hooks: readonly ["hooks.json", string];
+    readonly mcp: readonly ["mcp.json", ".mcp.json"];
+};
+/** First existing candidate path for a component, or null. */
+export declare function resolvePluginFile(dir: string, kind: keyof typeof FILE_CANDIDATES): string | null;
+/** The plugin's manifest as a parsed object (null when absent/malformed/not an object). */
+export declare function readPluginManifest(dir: string): Record<string, unknown> | null;
+//# sourceMappingURL=files.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/plugins/files.ts"],"names":[],"mappings":"AAeA,eAAO,MAAM,eAAe;;;;CAIlB,CAAC;AAEX,8DAA8D;AAC9D,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,eAAe,GAAG,MAAM,GAAG,IAAI,CAUhG;AAED,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAS9E"}

package/dist/plugins/files.js

@@ -0,0 +1,85 @@
+"use strict";
+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.FILE_CANDIDATES = void 0;
+exports.resolvePluginFile = resolvePluginFile;
+exports.readPluginManifest = readPluginManifest;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// ─── Component file locations ────────────────────────────────────────────────
+//
+// Extracted from plugins/index.ts (S24) so the modules that PARSE a plugin's
+// files without loading it — userConfig schema reading, `nex plugin validate`,
+// the config store — can resolve paths without importing the loader (which
+// imports them back: a cycle).
+//
+// SECURITY: `hooks` and `mcp` here are code-execution surfaces. Every reader
+// (plugins/index.ts, installer.ts's inspectPluginDir, validate.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.
+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;
+}
+/** The plugin's manifest as a parsed object (null when absent/malformed/not an object). */
+function readPluginManifest(dir) {
+    const file = resolvePluginFile(dir, 'manifest');
+    if (!file)
+        return null;
+    try {
+        const j = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        return j && typeof j === 'object' && !Array.isArray(j) ? j : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=files.js.map

package/dist/plugins/index.d.ts

@@ -1,3 +1,4 @@
+export { FILE_CANDIDATES, resolvePluginFile, readPluginManifest } from './files';
 export interface PluginInfo {
     /** Directory name (or plugin.json "name" when present). */
     name: string;
@@ -13,26 +14,6 @@ export interface PluginInfo {
 export declare function isPluginDisabled(dir: string): boolean;
 /** Toggle a plugin on/off. Idempotent — enabling an already-enabled plugin is a no-op. */
 export declare function setPluginDisabled(dir: string, disabled: boolean): void;
-/**
- * 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.
- */
-export declare const FILE_CANDIDATES: {
-    readonly manifest: readonly ["plugin.json", string];
-    readonly hooks: readonly ["hooks.json", string];
-    readonly mcp: readonly ["mcp.json", ".mcp.json"];
-};
-/** First existing candidate path for a component, or null. */
-export declare function resolvePluginFile(dir: string, kind: keyof typeof FILE_CANDIDATES): string | null;
 /**
  * Discover installed plugins (project scope shadows global on name clash).
  *
@@ -65,7 +46,7 @@ export declare function pluginAssetDirs(workDir: string, kind: 'commands' | 'age
  * 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`).
  */
-export declare function pluginHooks(workDir: string): Record<string, unknown[]>;
+export declare function pluginHooks(workDir: string, transform?: (entry: unknown, plugin: string) => unknown): Record<string, unknown[]>;
 /** MCP server maps declared by ENABLED plugins: { serverName → config } (first plugin wins on clash).
  *
  * A stdio server from a plugin gets NEXRALL_PLUGIN_DATA in its environment, pointing at the
@@ -73,5 +54,5 @@ export declare function pluginHooks(workDir: string): Record<string, unknown[]>;
  * 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.
  */
-export declare function pluginMcpServers(workDir: string): Record<string, unknown>;
+export declare function pluginMcpServers(workDir: string, transform?: (cfg: unknown, plugin: string) => unknown): Record<string, unknown>;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugins/index.ts"],"names":[],"mappings":"AAuCA,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC5B,6EAA6E;IAC7E,QAAQ,EAAE,OAAO,CAAC;CACnB;AAYD,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAMrD;AAED,0FAA0F;AAC1F,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI,CAWtE;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe;;;;CAIlB,CAAC;AAEX,8DAA8D;AAC9D,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,eAAe,GAAG,MAAM,GAAG,IAAI,CAUhG;AA+CD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAKzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAM7G;AAED,gGAAgG;AAChG,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,EAAE,CAWjG;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAoBtE;AAeD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkBzE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugins/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAoCjF,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC5B,6EAA6E;IAC7E,QAAQ,EAAE,OAAO,CAAC;CACnB;AAYD,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAMrD;AAED,0FAA0F;AAC1F,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI,CAWtE;AAsDD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAKzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAM7G;AAED,gGAAgG;AAChG,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,EAAE,CAWjG;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,GACtD,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CA4B3B;AAeD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,GACpD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuBzB"}

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"}