@nexrall/code-core 1.4.77 → 1.4.78

package/dist/permissions/rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/permissions/rules.ts"],"names":[],"mappings":"AAwBA,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,eAAe,CAAC;IAC7B,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAED,wBAAgB,mBAAmB,IAAI,MAAM,CAQ5C;AAsBD,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAEjE;AAQD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,IAAI,CAE5E;AACD,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAEnE;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CA8B5D;AAqJD;;oEAEoE;AACpE,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,MAAM,GACd,MAAM,GAAG,IAAI,CAEf;AAYD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOtD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,MAAM,GACd,kBAAkB,GAAG,IAAI,CAK3B"}
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/permissions/rules.ts"],"names":[],"mappings":"AA0BA,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,eAAe,CAAC;IAC7B,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAED,wBAAgB,mBAAmB,IAAI,MAAM,CAQ5C;AAsBD,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAEjE;AAQD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,IAAI,CAE5E;AACD,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAEnE;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CA8B5D;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,CAcvG;AAsMD;;oEAEoE;AACpE,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,MAAM,GACd,MAAM,GAAG,IAAI,CAEf;AAYD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOtD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,MAAM,GACd,kBAAkB,GAAG,IAAI,CAK3B"}

package/dist/permissions/rules.js

@@ -38,12 +38,15 @@ exports.setSessionRules = setSessionRules;
 exports.setSessionSettings = setSessionSettings;
 exports.getSessionSettings = getSessionSettings;
 exports.loadSettings = loadSettings;
+exports.settingsTiersRaw = settingsTiersRaw;
 exports.matchedAllowRule = matchedAllowRule;
 exports.isBroadAllowRule = isBroadAllowRule;
 exports.evaluatePermission = evaluatePermission;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
+const modePolicy_1 = require("./modePolicy");
+const destructiveTokens_1 = require("./destructiveTokens");
 function managedSettingsPath() {
     // Tests (and a sandboxed doctor run) point this at a fixture. Checked first so it
     // can never be shadowed by a real machine-level file.
@@ -120,6 +123,31 @@ function loadSettings(workDir) {
     merged.deny.push(...sessionRules.deny);
     return { permissions: merged, raw };
 }
+/**
+ * S25b: the raw object of every settings tier, in precedence order (managed →
+ * user → project → local → `--settings` session settings). For resolvers where
+ * the STRICTEST value must win regardless of tier — `maxEffortLevel` (a cap can
+ * only be tightened by a lower-precedence file, never loosened), and anything
+ * with the same one-way semantics added later. `loadSettings().raw` cannot serve
+ * those: it merges with LAST-wins, which is the opposite direction.
+ */
+function settingsTiersRaw(workDir) {
+    const files = [
+        ['managed', managedSettingsPath()],
+        ['user', path.join(os.homedir(), '.nexrall', 'settings.json')],
+        ['project', path.join(workDir, '.nexrall', 'settings.json')],
+        ['local', path.join(workDir, '.nexrall', 'settings.local.json')],
+    ];
+    const out = [];
+    for (const [tier, file] of files) {
+        const obj = readJson(file);
+        if (obj)
+            out.push({ tier, raw: obj });
+    }
+    if (sessionSettings)
+        out.push({ tier: 'session', raw: sessionSettings });
+    return out;
+}
 // ─── Rule matching ──────────────────────────────────────────────────────────
 function parseRule(rule) {
     const m = /^([A-Za-z0-9_]+)\((.*)\)$/.exec(rule.trim());
@@ -180,8 +208,21 @@ function matchPattern(pattern, value) {
     }
     return value === pattern;
 }
-/** Map a tool's input to the string(s) a rule pattern should match against. */
-function matchValues(tool, input, workDir) {
+/** The command line of a bash-family call: `command`, falling back to the `cmd`
+ * alias every other reader accepts (destructive guard, CLI handler). */
+function bashCommand(input) {
+    const v = input.command ?? input.cmd;
+    return typeof v === 'string' ? v : '';
+}
+/** Map a tool's input to the string(s) a rule pattern should match against.
+ *
+ * S25f: deny/ask matching ALSO sees a path's real identity behind symlinks —
+ * Claude Code 2.1.289 fixed exactly this class ("Read deny rules not applying
+ * to files @-mentioned, changed, or selected in the IDE through a symlink").
+ * The allow path skips those views (`followSymlinks: false`): an exception
+ * stays as NARROW as it was written — the same asymmetry the unwrapped bash
+ * views in destructiveTokens use. */
+function matchValues(tool, input, workDir, followSymlinks = false) {
     const str = (v) => (typeof v === 'string' ? v : '');
     const vals = [];
     const pushPath = (p) => {
@@ -192,10 +233,36 @@ function matchValues(tool, input, workDir) {
             vals.push(path.relative(workDir, p));
         else
             vals.push(path.resolve(workDir, p));
+        if (!followSymlinks)
+            return;
+        const abs = path.resolve(workDir, p);
+        try {
+            const real = fs.realpathSync(abs);
+            if (real !== abs)
+                vals.push(real, path.relative(workDir, real));
+        }
+        catch {
+            // A path being CREATED through a symlinked directory: resolve the parent.
+            try {
+                const realDir = fs.realpathSync(path.dirname(abs));
+                const realAbs = path.join(realDir, path.basename(abs));
+                vals.push(realAbs, path.relative(workDir, realAbs));
+            }
+            catch {
+                /* neither exists: nothing to resolve */
+            }
+        }
     };
     switch (tool) {
+        // The whole bash family, matching modePolicy.BASH_TOOLS: the executor emits
+        // `bash`, and run_command / execute_command are the same tool accepted
+        // everywhere else (destructive guard, CLI handler). A `Bash(…)` rule must
+        // not silently skip a call that arrives under one of those names — the
+        // "looks configured and isn't" failure class the task rules had.
         case 'bash':
-            vals.push(str(input.command));
+        case 'run_command':
+        case 'execute_command':
+            vals.push(bashCommand(input));
             break;
         case 'move_file':
             pushPath(str(input.source));
@@ -241,7 +308,7 @@ function ruleMatches(rule, tool, input, workDir, opts) {
         Read: ['read_file', 'list_directory', 'search_files', 'glob', 'notebook_read'],
         Edit: ['edit_file', 'multi_edit', 'write_file', 'notebook_edit'],
         Write: ['write_file', 'write_docx', 'write_xlsx', 'write_pptx'],
-        Bash: ['bash'],
+        Bash: ['bash', 'run_command', 'execute_command'],
         WebFetch: ['fetch_url'],
         Image: ['generate_image', 'stock_photo'],
     };
@@ -255,15 +322,30 @@ function ruleMatches(rule, tool, input, workDir, opts) {
     // "Bash(npm run test:*)" allow rule straight past the user prompt.
     // Deny rules stay aggressive (they SHOULD match chained commands), and a
     // bare "Bash" allow (pattern === null) is an explicit "allow everything".
-    if (opts?.forAllow && tool === 'bash' && pattern !== null && pattern !== '' && pattern !== '*') {
-        const cmd = typeof input.command === 'string' ? input.command : '';
+    if (opts?.forAllow && modePolicy_1.BASH_TOOLS.has(tool) && pattern !== null && pattern !== '' && pattern !== '*') {
+        const cmd = bashCommand(input);
         // newline / ; / && / || / | / trailing & / command-substitution / backtick
         if (/[\r\n;`]|&&|\|\||\||&\s*$|\$\(/.test(cmd))
             return false;
     }
     if (pattern === null || pattern === '' || pattern === '*')
         return true;
-    return matchValues(tool, input, workDir).some((v) => matchPattern(pattern, v));
+    if (matchValues(tool, input, workDir, !opts?.forAllow).some((v) => matchPattern(pattern, v)))
+        return true;
+    // Deny / ask rules must also see the command BEHIND a costume: env
+    // assignments (`TZ="$HOME" rm -rf build` — Claude Code's own fix class,
+    // 2.1.288/289), wrappers (`sudo`, `env`, `nice`, `timeout`, `xargs`, shell
+    // `-c`, `eval`), compound separators (`;` `&&` `||` `|`) and `$(…)` /
+    // backtick bodies. The destructive guard has always read these spellings
+    // (destructiveTokens); a user's deny rule must not be the one thing a
+    // prefix can skip.
+    //
+    // ALLOW deliberately stays exact — an exception is only as WIDE as it was
+    // written, and env vars can execute code (NODE_OPTIONS, LD_PRELOAD…), so
+    // `FOO=x npm run test` must not ride `Bash(npm run test:*)` without asking.
+    if (opts?.forAllow || !modePolicy_1.BASH_TOOLS.has(tool))
+        return false;
+    return (0, destructiveTokens_1.unwrappedViews)(bashCommand(input)).some((v) => matchPattern(pattern, v));
 }
 /** The first ALLOW rule that matches this call, or null. S20's classifier gate
  * reads this to tell a NARROW pre-approval (wins, no review) from a BROAD one

package/dist/plugins/configStore.d.ts

@@ -0,0 +1,43 @@
+import { type UserConfigOption } from './userConfig';
+type SecretMap = Record<string, Record<string, unknown>>;
+/** The whole secrets file ({} when absent/unreadable/malformed). */
+export declare function readPluginSecrets(): SecretMap;
+/**
+ * `pluginConfigs` from every settings tier, merged per plugin per key
+ * (last tier wins — the same direction loadSettings uses for `raw`).
+ */
+export declare function pluginConfigsFromSettings(workDir: string): Record<string, Record<string, unknown>>;
+export interface ResolvedPluginConfig {
+    /** key → effective value (valid sources only, default included). */
+    values: Record<string, unknown>;
+    /** key → where the value came from. */
+    sources: Record<string, 'secret' | 'settings' | 'default'>;
+    /** required options with no value anywhere (not even a default). */
+    missing: string[];
+    /** Values that failed validation, with their source — reported, not used. */
+    invalid: Array<{
+        key: string;
+        source: 'secret' | 'settings';
+        error: string;
+    }>;
+}
+/** Resolve every declared option to its effective value. Pure reads. */
+export declare function resolvePluginConfig(workDir: string, pluginName: string, options: UserConfigOption[]): ResolvedPluginConfig;
+export interface SavePluginConfigResult {
+    ok: boolean;
+    /** Nothing was written when this is non-empty. */
+    errors: string[];
+    /** Paths actually written. */
+    wroteSettings?: string;
+    wroteSecrets?: boolean;
+}
+/**
+ * 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).
+ */
+export declare function savePluginConfig(workDir: string, pluginName: string, options: UserConfigOption[], values: Record<string, unknown>, opts?: {
+    scope?: 'user' | 'project';
+}): SavePluginConfigResult;
+export {};
+//# sourceMappingURL=configStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"configStore.d.ts","sourceRoot":"","sources":["../../src/plugins/configStore.ts"],"names":[],"mappings":"AA2BA,OAAO,EAA2B,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAmD9E,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEzD,oEAAoE;AACpE,wBAAgB,iBAAiB,IAAI,SAAS,CAQ7C;AAgBD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAWlG;AAED,MAAM,WAAW,oBAAoB;IACnC,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC,CAAC;IAC3D,oEAAoE;IACpE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6EAA6E;IAC7E,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,QAAQ,GAAG,UAAU,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/E;AAED,wEAAwE;AACxE,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,gBAAgB,EAAE,GAC1B,oBAAoB,CA+BtB;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,OAAO,CAAC;IACZ,kDAAkD;IAClD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,8BAA8B;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAO,GACxC,sBAAsB,CAkDxB"}

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