raidcom-mcp 0.0.0-stage → 0.1.2

package/dist/recipes.js

@@ -0,0 +1,307 @@
+import { build, checkGlobal } from "./builder.js";
+/** Most commands one request may expand to. */
+export const MAX_COMMANDS = 500;
+// ---------- value expansion ----------
+/** "100-103" → 100..103, "1,2,5" → 1,2,5, "dd:00-dd:0f" → dd:00..dd:0f, a mix of these; other text is kept as is.
+ *  Stops with an error past `max` values, so no input can make it run long or use much memory. */
+export function expandList(input, max = MAX_COMMANDS) {
+    const out = [];
+    const push = (v) => {
+        if (out.length >= max)
+            throw new Error(`the list has more than ${max} values`);
+        out.push(v);
+    };
+    for (const item of Array.isArray(input) ? input : [input]) {
+        if (typeof item === "number") {
+            if (!Number.isFinite(item))
+                throw new Error(`${item} is not a usable value`);
+            push(item);
+            continue;
+        }
+        if (typeof item !== "string")
+            throw new Error(`list values must be strings or numbers, not ${item === null ? "null" : typeof item}`);
+        for (const part of item.split(/[,\s]+/).filter(Boolean)) {
+            // CU:LDEV ranges such as dd:00-dd:0f, as used for mainframe volumes: expanded in the same format
+            const h = /^([0-9a-f]{2}):([0-9a-f]{2})-([0-9a-f]{2}):([0-9a-f]{2})$/i.exec(part);
+            // decimal ranges; 15 digits keeps both ends exact as JavaScript numbers
+            const m = /^(\d{1,15})-(\d{1,15})$/.exec(part);
+            if (h || m) {
+                const a = h ? parseInt(h[1] + h[2], 16) : Number(m[1]);
+                const b = h ? parseInt(h[3] + h[4], 16) : Number(m[2]);
+                if (b < a)
+                    throw new Error(`range "${part}" runs backwards`);
+                if (b - a + 1 > max - out.length)
+                    throw new Error(`range "${part}" has more than ${max} values`);
+                const lower = part === part.toLowerCase();
+                for (let n = a; n <= b; n++) {
+                    if (!h)
+                        push(n);
+                    else {
+                        const x = n.toString(16).padStart(4, "0");
+                        push(`${x.slice(0, 2)}:${x.slice(2)}`[lower ? "toLowerCase" : "toUpperCase"]());
+                    }
+                }
+            }
+            else
+                push(/^\d{1,15}$/.test(part) ? Number(part) : part);
+        }
+    }
+    return out;
+}
+const refs = (s) => [...s.matchAll(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g)].map((m) => m[1]);
+/** A scope value by name. Only the scope's own entries count, so "{constructor}" or "{__proto__}" find nothing. */
+const lookup = (scope, name) => (Object.hasOwn(scope, name) ? scope[name] : undefined);
+const VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Substitutes {name} in a template. Undefined when it names something that has no value. */
+function fill(template, scope) {
+    const whole = /^\{([A-Za-z_][A-Za-z0-9_]*)\}$/.exec(template);
+    if (whole) {
+        const v = lookup(scope, whole[1]);
+        return v === undefined || (Array.isArray(v) && v.length === 0) || v === "" ? undefined : v;
+    }
+    let missing = false;
+    const text = template.replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name) => {
+        const v = lookup(scope, name);
+        if (v === undefined || Array.isArray(v) || v === "") {
+            missing = true;
+            return "";
+        }
+        return String(v);
+    });
+    return missing ? undefined : text;
+}
+/** One concrete option set from a step's templates. An option whose template has no value is left out. */
+function fillOptions(options, scope) {
+    // no prototype, so an option named "__proto__" is an ordinary (and then unknown) option
+    const out = Object.create(null);
+    for (const [flag, raw] of Object.entries(options ?? {})) {
+        if (typeof raw === "boolean") {
+            out[flag] = raw;
+            continue;
+        }
+        const templates = Array.isArray(raw) ? raw : [raw];
+        const values = [];
+        for (const t of templates) {
+            if (t === null || t === undefined)
+                continue;
+            if (typeof t === "number")
+                values.push(t);
+            else {
+                // a template that names a parameter nobody gave contributes nothing, so optional trailing values drop out
+                const v = fill(t, scope);
+                if (v === undefined)
+                    continue;
+                if (Array.isArray(v))
+                    values.push(...v);
+                else
+                    values.push(v);
+            }
+        }
+        if (values.length)
+            out[flag] = values;
+    }
+    return out;
+}
+/** Checks that a step's option values are what a template can be: text, numbers, switches, or lists of these. */
+function checkOptions(options) {
+    if (options === undefined || options === null)
+        return;
+    if (typeof options !== "object" || Array.isArray(options))
+        throw new Error("options must be an object of option names and values");
+    for (const [flag, v] of Object.entries(options)) {
+        const ok = (x) => x === null || typeof x === "string" || typeof x === "number";
+        if (!(ok(v) || typeof v === "boolean" || (Array.isArray(v) && v.every(ok))))
+            throw new Error(`option ${flag}: a value must be text, a number, true/false or a list of text and numbers`);
+    }
+}
+function loopValues(name, spec, params, max) {
+    if (!VAR_NAME.test(name))
+        throw new Error(`"${name}" is not a usable variable name (letters, digits and _)`);
+    let values;
+    if (typeof spec === "string" && Object.hasOwn(params, spec)) {
+        const p = params[spec];
+        values = p === undefined ? [] : Array.isArray(p) ? p : [p];
+        if (values.length > max)
+            throw new Error(`${name} has more than ${max} values`);
+    }
+    else if (typeof spec === "string" || typeof spec === "number" || Array.isArray(spec))
+        values = expandList(spec, max);
+    else
+        throw new Error(`${name} must be a list or a range such as "100-109"`);
+    if (!values.length)
+        throw new Error(`${name} has no values`);
+    return values;
+}
+/** Every variable binding a step runs with, at most `max` of them. */
+function bindings(step, params, max) {
+    let combos = [{}];
+    for (const [what, spec] of [["zip", step.zip], ["foreach", step.foreach]]) {
+        if (spec !== undefined && (spec === null || typeof spec !== "object" || Array.isArray(spec)))
+            throw new Error(`${what} must be an object of variable names and lists`);
+        if (spec && !Object.keys(spec).length)
+            throw new Error(`${what} is empty; leave it out or give at least one variable`);
+    }
+    if (step.zip) {
+        const lists = Object.entries(step.zip).map(([k, v]) => [k, loopValues(k, v, params, max)]);
+        const n = lists[0][1].length;
+        for (const [k, l] of lists)
+            if (l.length !== n)
+                throw new Error(`zip lists must have the same length (${lists[0][0]} has ${n}, ${k} has ${l.length})`);
+        combos = Array.from({ length: n }, (_, i) => Object.fromEntries(lists.map(([k, l]) => [k, l[i]])));
+    }
+    for (const [k, v] of Object.entries(step.foreach ?? {})) {
+        const values = loopValues(k, v, params, max);
+        if (combos.length * values.length > max)
+            throw new Error(`the step would produce more than ${max} commands`);
+        combos = combos.flatMap((c) => values.map((x) => ({ ...c, [k]: x })));
+    }
+    return combos;
+}
+// ---------- scripts ----------
+export function buildScript(catalog, req, params = {}) {
+    const errors = [];
+    const warnings = [];
+    const notes = [];
+    const commands = [];
+    const lines = [];
+    let total = 0;
+    let pendingAsync = false;
+    // The global options are written into lines of their own (HORCMINST, lock, login), so they are checked here, once,
+    // before anything is written, and not only when a command is built.
+    const modelHit = catalog.model(req.model);
+    const gc = checkGlobal(req.global, modelHit?.limits ?? catalog.models.get("generic"), !!modelHit);
+    if (gc.errors.length)
+        return { ok: false, commands: [], errors: gc.errors.map((e) => `global: ${e}`), warnings: [], notes: [] };
+    const inst = gc.instanceFlag ? ` ${gc.instanceFlag}` : "";
+    if (!Array.isArray(req.steps) || !req.steps.length)
+        return { ok: false, commands: [], errors: ["steps must be a non-empty list"], warnings: [], notes: [] };
+    const flushAsync = () => {
+        if (!pendingAsync)
+            return;
+        lines.push(`run raidcom get command_status${inst}`);
+        pendingAsync = false;
+    };
+    req.steps.forEach((step, si) => {
+        const title = step && typeof step === "object" && typeof step.title === "string" ? step.title : undefined;
+        const label = `step ${si + 1}${title ? ` (${title})` : ""}`;
+        let combos;
+        try {
+            if (!step || typeof step !== "object" || typeof step.command !== "string")
+                throw new Error("a step needs a command name, such as {\"command\": \"add ldev\", \"options\": {...}}");
+            checkOptions(step.options);
+            combos = bindings(step, params, MAX_COMMANDS - total);
+        }
+        catch (e) {
+            errors.push(`${label}: ${e.message}`);
+            return;
+        }
+        total += combos.length;
+        if (total > MAX_COMMANDS) {
+            errors.push(`${label}: the script would have more than ${MAX_COMMANDS} commands`);
+            return;
+        }
+        // a step that starts with a command that is not asynchronous first waits for the pending asynchronous ones
+        if (catalog.find(step.command) && !catalog.find(step.command).async)
+            flushAsync();
+        if (title)
+            lines.push("", `# ${title.replace(/[\r\n]+/g, " ")}`);
+        for (const combo of combos) {
+            const scope = { ...params, ...combo };
+            const options = fillOptions(step.options, scope);
+            const r = build(catalog, { command: step.command, options, model: req.model, global: req.global, strict: req.strict });
+            if (!r.ok) {
+                const where = Object.keys(combo).length ? ` with ${Object.entries(combo).map(([k, v]) => `${k}=${v}`).join(", ")}` : "";
+                for (const m of r.errors)
+                    errors.push(`${label}${where}: ${m}`);
+                continue;
+            }
+            for (const w of r.warnings)
+                if (!warnings.includes(`${label}: ${w}`))
+                    warnings.push(`${label}: ${w}`);
+            commands.push({ step: si + 1, title, command: r.command, readOnly: !!r.readOnly, destructive: !!r.destructive, async: !!r.async });
+            if (!r.async && pendingAsync)
+                flushAsync();
+            lines.push(`run ${r.command}`);
+            if (r.async)
+                pendingAsync = true;
+        }
+    });
+    flushAsync();
+    if (!errors.length && !commands.length)
+        errors.push("The script would contain no commands.");
+    if (errors.length)
+        return { ok: false, commands: [], errors, warnings, notes };
+    if (commands.some((c) => c.async))
+        notes.push("Commands that run asynchronously are followed by `raidcom get command_status`; read its output before moving on.");
+    if (commands.some((c) => c.destructive))
+        notes.push("The script contains commands that delete or initialize. Read it through before running it.");
+    const head = ["#!/bin/bash", "# Generated by raidcom-mcp. The server only builds text; it has not run anything on a storage system."];
+    if (req.description)
+        head.push(`# ${req.description.replace(/[\r\n]+/g, " ")}`);
+    head.push("# Review before running. Run it on a host with CCI installed and a running HORCM instance.", "");
+    if (gc.instance !== undefined)
+        head.push(`export HORCMINST=${gc.instance}`);
+    for (const [k, v] of Object.entries(req.env ?? {})) {
+        if (!/^[A-Z][A-Z0-9_]*$/.test(k) || !/^[A-Za-z0-9_.:-]*$/.test(v))
+            throw new Error(`unsafe environment variable ${k}`);
+        head.push(`export ${k}=${v}`);
+    }
+    head.push('run() { "$@" || { echo "FAILED: $*" >&2; exit 1; }; }', "");
+    if (req.login)
+        head.push(`# Set RAIDCOM_USER and RAIDCOM_PASSWORD in your shell; they are not part of this script.`, `run raidcom -login "$RAIDCOM_USER" "$RAIDCOM_PASSWORD"${inst}`);
+    if (req.lock_resource)
+        head.push(`run raidcom lock resource${inst}`);
+    const tail = [""];
+    if (req.lock_resource)
+        tail.push(`run raidcom unlock resource${inst}`);
+    if (req.login)
+        tail.push(`run raidcom -logout${inst}`);
+    return { ok: true, script: [...head, ...lines.filter((l, i) => !(l === "" && i === 0)), ...tail].join("\n") + "\n", commands, errors, warnings, notes };
+}
+/** Checks the parameters of a recipe and returns the values to substitute. */
+function recipeScope(recipe, given, errors) {
+    const scope = {};
+    for (const k of Object.keys(given))
+        if (!Object.hasOwn(recipe.params, k))
+            errors.push(`Unknown parameter "${k}". This recipe takes: ${Object.keys(recipe.params).join(", ") || "none"}.`);
+    for (const [name, spec] of Object.entries(recipe.params)) {
+        const v = given[name];
+        if (v === undefined || v === null || v === "" || (Array.isArray(v) && v.length === 0)) {
+            if (spec.required)
+                errors.push(`Parameter "${name}" is required: ${spec.description}`);
+            continue;
+        }
+        try {
+            if (spec.type === "array") {
+                const list = Array.isArray(v) ? v : [v];
+                scope[name] = spec.range ? expandList(list) : list.flatMap((x) => (typeof x === "string" ? x.split(/[,\s]+/).filter(Boolean) : [x]));
+            }
+            else
+                scope[name] = typeof v === "number" ? v : String(v);
+        }
+        catch (e) {
+            errors.push(`Parameter "${name}": ${e.message}`);
+        }
+    }
+    return scope;
+}
+export function buildRecipe(catalog, id, recipe, given, opts = {}) {
+    const errors = [];
+    const scope = recipeScope(recipe, given, errors);
+    if (errors.length)
+        return { ok: false, recipe: id, commands: [], errors, warnings: [], notes: [] };
+    // a step with `when` runs if all its parameters were given; some but not all is a mistake worth reporting
+    const steps = recipe.steps.filter((s) => {
+        if (!s.when)
+            return true;
+        const names = Array.isArray(s.when) ? s.when : [s.when];
+        const have = names.filter((n) => lookup(scope, n) !== undefined);
+        if (have.length && have.length < names.length)
+            errors.push(`Give ${names.join(" and ")} together (only ${have.join(", ")} was given).`);
+        return have.length === names.length;
+    });
+    if (errors.length)
+        return { ok: false, recipe: id, commands: [], errors, warnings: [], notes: [] };
+    const r = buildScript(catalog, { ...opts, steps, description: opts.description ?? recipe.title, env: recipe.env }, scope);
+    return { ...r, recipe: id, notes: [...r.notes, ...recipe.notes] };
+}

package/dist/search.js

@@ -0,0 +1,157 @@
+// BM25 ranking over the raidcom catalogue, with a confidence signal so the model knows when to build straight
+// away and when to describe candidates first.
+import { commandName } from "./catalog.js";
+// Field weights, applied by repeating tokens (BM25F-lite): a word in the command name says more than one in a
+// long option description.
+const WEIGHTS = { name: 5, summary: 3, flags: 1, optionText: 0.5, examples: 3, questions: 3 };
+const K1 = 1.2;
+const B = 0.75;
+const STOPWORDS = new Set("a an and are as at be by can do does for from give how i in is it me my of on or the this to what when where which with all any please need want would like using use raidcom".split(" "));
+// What people say vs. the words in the catalogue.
+const SYNONYMS = {
+    group: ["grp"], groups: ["grp"],
+    volume: ["ldev"], volumes: ["ldev"], vol: ["ldev"], dpvol: ["ldev", "dp"], disk: ["ldev"], luns: ["lun", "ldev"],
+    hostgroup: ["host_grp"], "host-group": ["host_grp"], iscsi: ["iscsi", "hba_iscsi"], target: ["host_grp", "iscsi"],
+    wwn: ["hba_wwn"], wwpn: ["hba_wwn"], initiator: ["hba_wwn", "hba_iscsi"], hba: ["hba_wwn"],
+    nqn: ["host_nqn"], nvme: ["nvm_subsystem", "namespace", "host_nqn"], namespace: ["namespace", "nvm_subsystem"], subsystem: ["nvm_subsystem"],
+    present: ["lun"], map: ["lun"], mapping: ["lun"], unmap: ["lun"], path: ["lun", "path"], paths: ["lun", "path"],
+    thin: ["dp_pool", "pool", "ldev"], dp: ["dp_pool", "pool"], hdp: ["dp_pool", "pool"], hdt: ["pool"], tiering: ["pool"],
+    capacity: ["ldev", "pool"], space: ["pool"], free: ["ldev", "pool"],
+    fibre: ["port"], fc: ["port"], port: ["port"], ports: ["port"],
+    resize: ["extend"], expand: ["extend"], grow: ["extend", "dp_pool"], enlarge: ["extend"],
+    format: ["initialize"], wipe: ["initialize"], erase: ["initialize"],
+    nickname: ["ldev", "modify"], label: ["modify"], rename: ["modify", "rename"],
+    asynchronous: ["command_status"], async: ["command_status"], status: ["command_status"], progress: ["command_status"], finished: ["command_status"], complete: ["command_status"], completion: ["command_status"],
+    error: ["error_message", "command_status"], errors: ["error_message", "command_status"],
+    lock: ["lock", "resource"], unlock: ["unlock", "resource"], locking: ["lock", "resource"],
+    replication: ["copy_grp", "device_grp", "journal"], mirror: ["copy_grp"], pair: ["copy_grp", "device_grp"], ur: ["journal"], gad: ["quorum", "journal", "copy_grp"], quorum: ["quorum"],
+    snapshot: ["snapshot", "snap_pool"], thinimage: ["snapshot", "snap_pool"], hti: ["snapshot", "snap_pool"],
+    external: ["external_grp", "external_storage"], virtualize: ["external_grp"], virtualization: ["external_grp", "external_storage"],
+    quota: ["qos_grp"], qos: ["qos_grp"], throttle: ["qos_grp", "spm_wwn"], priority: ["spm_wwn", "spm_group"],
+    parity: ["parity_grp"], raid: ["parity_grp"], pg: ["parity_grp"], drive: ["drive"], drives: ["drive"], disks_: ["drive"],
+    cache: ["clpr"], partition: ["clpr"], cpu: ["system"], license: ["license"], licence: ["license"],
+    chap: ["chap_user"], secret: ["chap_user"], password: ["chap_user"],
+    serial: ["system"], model: ["system"], firmware: ["system"], version: ["system"], info: ["system", "get"],
+    inventory: ["get"], report: ["get"], audit: ["get"], list: ["get"], show: ["get"], display: ["get"], view: ["get"], find: ["get"], check: ["get"],
+    remove: ["delete"], destroy: ["delete"], unregister: ["delete"], decommission: ["delete"],
+    create: ["add"], make: ["add"], provision: ["add"], register: ["add"], new: ["add"], attach: ["add"],
+    change: ["modify"], update: ["modify"], edit: ["modify"], set: ["modify"], enable: ["modify"], disable: ["modify"],
+    block: ["modify", "ldev"], restore: ["modify", "ldev"], reclaim: ["modify", "ldev"], zero: ["modify", "ldev"],
+    commanddevice: ["ldev", "modify"], "command-device": ["ldev", "modify"],
+};
+/** The action a request most likely wants, from its verbs. */
+const ACTION_VERBS = {
+    add: ["create", "add", "make", "provision", "register", "new", "attach", "build", "allocate", "assign", "map", "present", "expose", "give"],
+    delete: ["delete", "remove", "destroy", "unregister", "decommission", "drop", "unmap", "detach", "unpresent"],
+    get: ["show", "list", "display", "get", "view", "find", "which", "what", "status", "report", "inventory", "how", "many", "check", "see"],
+    modify: ["change", "update", "modify", "edit", "set", "enable", "disable", "rename", "block", "restore"],
+    extend: ["extend", "expand", "grow", "resize", "enlarge"],
+    initialize: ["format", "initialize", "wipe", "erase", "reformat"],
+    lock: ["lock"], unlock: ["unlock"],
+};
+/** Lower-cased words of a request. Underscores split, so `host_grp` matches "host grp". */
+export function words(text) {
+    return text.toLowerCase().replace(/[_]/g, " ").split(/[^a-z0-9#-]+/).map((w) => w.replace(/^-+|-+$/g, "")).filter(Boolean);
+}
+const stem = (w) => (w.length > 3 && w.endsWith("s") && !w.endsWith("ss") ? w.slice(0, -1) : w);
+function tokenize(text) {
+    return words(text).filter((w) => !STOPWORDS.has(w)).map(stem);
+}
+function intentOf(query) {
+    const w = words(query);
+    for (const [action, verbs] of Object.entries(ACTION_VERBS))
+        if (w.some((x) => verbs.includes(x)))
+            return action;
+    return undefined;
+}
+export class CommandIndex {
+    docs = [];
+    df = new Map();
+    avgLen = 0;
+    constructor(commands, questions = {}) {
+        for (const command of commands) {
+            const name = commandName(command);
+            const tf = new Map();
+            const add = (text, weight) => {
+                for (const t of tokenize(text))
+                    tf.set(t, (tf.get(t) ?? 0) + weight);
+            };
+            add(name, WEIGHTS.name);
+            add(command.object, WEIGHTS.name);
+            add(command.summary, WEIGHTS.summary);
+            add(Object.keys(command.flags).join(" "), WEIGHTS.flags);
+            add(Object.values(command.options).map((o) => o.summary).join(" "), WEIGHTS.optionText);
+            add(command.examples.map((e) => e.text).join(" "), WEIGHTS.examples);
+            add((questions[name] ?? []).join(" "), WEIGHTS.questions);
+            const len = [...tf.values()].reduce((a, b) => a + b, 0);
+            this.docs.push({ command, name, tf, len });
+            for (const t of tf.keys())
+                this.df.set(t, (this.df.get(t) ?? 0) + 1);
+        }
+        this.avgLen = this.docs.reduce((a, d) => a + d.len, 0) / Math.max(this.docs.length, 1);
+    }
+    /** Query terms with synonyms added at half weight. */
+    terms(query) {
+        const out = new Map();
+        for (const w of words(query)) {
+            if (STOPWORDS.has(w))
+                continue;
+            out.set(stem(w), Math.max(out.get(stem(w)) ?? 0, 1));
+            for (const s of Object.hasOwn(SYNONYMS, w) ? SYNONYMS[w] : [])
+                for (const t of tokenize(s))
+                    out.set(t, Math.max(out.get(t) ?? 0, 0.5));
+        }
+        return out;
+    }
+    search(query, opts = {}) {
+        const terms = this.terms(query);
+        const intent = intentOf(query);
+        const N = this.docs.length;
+        const hits = [];
+        for (const d of this.docs) {
+            if (opts.action && d.command.action !== opts.action)
+                continue;
+            if (opts.object && d.command.object !== opts.object)
+                continue;
+            let score = 0;
+            const matched = [];
+            for (const [t, w] of terms) {
+                const f = d.tf.get(t);
+                if (!f)
+                    continue;
+                const df = this.df.get(t) ?? 0;
+                const idf = Math.log(1 + (N - df + 0.5) / (df + 0.5));
+                score += w * idf * ((f * (K1 + 1)) / (f + K1 * (1 - B + (B * d.len) / this.avgLen)));
+                matched.push(t);
+            }
+            if (score <= 0)
+                continue;
+            // The verb in the request decides between `add lun` and `get lun`.
+            if (intent)
+                score *= d.command.action === intent ? 1.35 : 0.8;
+            hits.push({ command: d.command, name: d.name, score, matched });
+        }
+        hits.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+        const limit = opts.limit ?? 10;
+        const top = hits[0];
+        const second = hits[1];
+        let confidence = "low";
+        let reason = "no command matched";
+        if (top) {
+            const lead = second ? top.score / second.score : 10;
+            const coverage = [...terms.entries()].filter(([, w]) => w === 1).filter(([t]) => top.matched.includes(t)).length / Math.max([...terms.values()].filter((w) => w === 1).length, 1);
+            if (lead >= 1.25 && coverage >= 0.6) {
+                confidence = "high";
+                reason = `the top result leads the next by ${lead.toFixed(2)}x and matches most of the request's words`;
+            }
+            // a tie at the top is never better than low, however many words matched
+            else if (lead >= 1.1) {
+                confidence = "medium";
+                reason = `the top result leads by ${lead.toFixed(2)}x and matches ${(coverage * 100).toFixed(0)}% of the request's words`;
+            }
+            else
+                reason = `the top results are close (${lead.toFixed(2)}x) and match ${(coverage * 100).toFixed(0)}% of the request's words`;
+        }
+        return { hits: hits.slice(0, limit), confidence, reason };
+    }
+}

package/dist/tools.js

@@ -0,0 +1,179 @@
+const globalSchema = {
+    type: "object",
+    description: "Settings that apply to the whole command, not to one raidcom option.",
+    properties: {
+        instance: { type: "integer", minimum: 0, description: "CCI instance number: written as -I<n>. Example: 0." },
+        pair_type: { type: "string", enum: ["H", "M", "TC", "SI"], description: "With instance: H or TC for TrueCopy, Universal Replicator and global-active device; M or SI for ShadowImage, Volume Migration and Thin Image." },
+        serial: { type: ["string", "integer"], description: "Storage system serial number (-s), needed when the HORCM file lists several arrays. VSP 5000 series add a leading 5, VSP G1x00 and VSP F1500 a leading 3." },
+        unit: { type: "integer", minimum: 0, description: "Unit ID of the command device (-u)." },
+        fx: { type: "boolean", description: "Print LDEV numbers in hexadecimal (-fx)." },
+        nomsg: { type: "boolean", description: "Suppress messages (-nomsg)." },
+        checkmode: { type: "string", enum: ["precheck"], description: "Check the command without changing the array (-checkmode precheck)." },
+        store: { type: "string", description: "File name for the implementation-check file (-store)." },
+    },
+    additionalProperties: false,
+};
+const modelSchema = {
+    type: "string",
+    description: "Storage model, so values are checked against its limits: vsp-one-b24, vsp-one-b26, vsp-one-b28, vsp-5000, vsp-e590, vsp-e790, vsp-e990, vsp-e1090. Aliases such as B28 or E990 work. " +
+        "Omit it to check against the widest range of any model.",
+};
+const optionsSchema = {
+    type: "object",
+    description: "raidcom options and their values, keyed by option name with or without the leading dash. A value is a string or number; an option that takes several values (for example -port takes a port and an optional host group name) " +
+        "takes an array: {\"-port\": [\"CL1-A-0\", \"esx01\"]}. An option with no value (a switch such as -allports) is true. Example for `add lun`: {\"-port\": [\"CL1-A-0\"], \"-ldev_id\": 200, \"-lun_id\": 1}.",
+    additionalProperties: { type: ["string", "number", "boolean", "array"], items: { type: ["string", "number"] } },
+};
+const strictSchema = {
+    type: "boolean",
+    description: "Default true. The command catalogue is parsed from the manual, whose syntax lines are occasionally incomplete, so a \"needs <option>\" error can be a false alarm. " +
+        "If one looks wrong after reading raidcom_describe_command, retry with strict=false: missing-option errors then become warnings. Unknown options and out-of-range values stay errors.",
+};
+const stepSchema = {
+    type: "object",
+    properties: {
+        title: { type: "string", description: "A short label, written into the script as a comment." },
+        command: { type: "string", description: "Command name, e.g. \"add ldev\"." },
+        options: optionsSchema,
+        foreach: {
+            type: "object",
+            description: "Repeat the step for every value (cartesian product when there are several variables). Variable → list or range: {\"ldev\": \"100-109\"} or {\"port\": [\"CL1-A\", \"CL2-A\"]}. " +
+                "Reference a variable in option values as {ldev}. Example: options {\"-ldev_id\": \"{ldev}\"} with foreach {\"ldev\": \"100-109\"} writes ten commands.",
+            additionalProperties: { type: ["string", "array"], items: { type: ["string", "number"] } },
+        },
+        zip: {
+            type: "object",
+            description: "Like foreach, but the variables advance together and the lists must have the same length: {\"ldev\": \"100-103\", \"lun\": \"0-3\"} pairs LDEV 100 with LUN 0, 101 with 1, and so on.",
+            additionalProperties: { type: ["string", "array"], items: { type: ["string", "number"] } },
+        },
+    },
+    required: ["command"],
+    additionalProperties: false,
+};
+export function tools() {
+    return [
+        {
+            name: "raidcom_list_commands",
+            description: "Find raidcom commands. Use this first when you do not know the exact command name. With no arguments, lists every object (ldev, lun, host_grp, pool, ...) with the actions available on it. " +
+                "With `query` (plain words, e.g. \"map a volume to a host group\", \"grow a pool\", \"show free ldev ids\"), ranks matching commands and rates the confidence of the top result. " +
+                "With `action` and/or `object`, lists exactly those commands. Then call raidcom_describe_command, or raidcom_build_command if you already know the options.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "What you want to do, in plain words." },
+                    action: { type: "string", description: "Only this action: add, delete, get, modify, extend, initialize, set, reset, ..." },
+                    object: { type: "string", description: "Only this object: ldev, lun, host_grp, hba_wwn, pool, dp_pool, port, parity_grp, ..." },
+                    limit: { type: "integer", minimum: 1, maximum: 40, description: "Maximum results for a query (default 10)." },
+                },
+            },
+            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+        },
+        {
+            name: "raidcom_describe_command",
+            description: "Everything needed to build one raidcom command: what it does, which models support it, whether it is read-only, destructive or asynchronous, each syntax form, every option with the number and kind of values it takes " +
+                "(and the words it accepts, where it accepts only a few), and examples. Call it before raidcom_build_command when you are unsure which options a command needs or which of its syntax forms fits the request.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    command: { type: "string", description: "Command name, e.g. \"add lun\" or \"raidcom get ldev\"." },
+                    option: { type: "string", description: "Only describe this option, e.g. \"-ldev_id\"." },
+                },
+                required: ["command"],
+            },
+            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+        },
+        {
+            name: "raidcom_build_command",
+            description: "Build one raidcom command from structured arguments and validate it. Nothing is executed and no storage system is contacted: you get command text to review and run elsewhere. " +
+                "Unknown options, wrong value counts, missing required options, bad port names and out-of-range LDEV, LUN, pool and serial numbers are reported as errors with a fix. " +
+                "Example: {\"command\": \"add ldev\", \"options\": {\"-pool\": 0, \"-ldev_id\": 256, \"-capacity\": \"100G\"}, \"model\": \"vsp-one-b28\", \"global\": {\"instance\": 0}} → `raidcom add ldev -pool 0 -ldev_id 256 -capacity 100G -I0`. " +
+                "For many similar commands use raidcom_build_script, not repeated calls. When the user asks for a command, show them the `command` from the result.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    command: { type: "string", description: "Command name: action and object, e.g. \"add lun\", \"get ldev\", \"modify host_grp\"." },
+                    options: optionsSchema,
+                    model: modelSchema,
+                    global: globalSchema,
+                    strict: strictSchema,
+                },
+                required: ["command"],
+            },
+            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+        },
+        {
+            name: "raidcom_check_command",
+            description: "Validate and explain a raidcom command line the user already has (for example one pasted from a runbook). It is parsed, not executed: shell operators such as ; | & > are refused. " +
+                "Returns the normalised command, what each option means, and every problem found. Credentials after -login are dropped.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    command_line: { type: "string", description: "One raidcom command, e.g. \"raidcom add lun -port CL1-A-0 -ldev_id 200 -lun_id 1\"." },
+                    model: modelSchema,
+                    strict: strictSchema,
+                },
+                required: ["command_line"],
+            },
+            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+        },
+        {
+            name: "raidcom_build_script",
+            description: "Build a shell script of raidcom commands from steps. Each step is a command with options, optionally repeated with `foreach` (every combination) or `zip` (values advance together), so \"create LDEVs 100 to 109 in pool 0, then map each to port CL1-A\" is two steps. " +
+                "Every expanded command is validated; the script is returned only if all of them are valid, otherwise you get the errors per step. The script checks each command's exit status, adds `raidcom get command_status` after asynchronous commands, " +
+                "and can lock the resource group and log in (credentials are read from RAIDCOM_USER and RAIDCOM_PASSWORD in the user's shell, never written into the script). Nothing is executed.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    steps: { type: "array", minItems: 1, items: stepSchema },
+                    model: modelSchema,
+                    global: globalSchema,
+                    strict: strictSchema,
+                    login: { type: "boolean", description: "Add raidcom -login / -logout using $RAIDCOM_USER and $RAIDCOM_PASSWORD." },
+                    lock_resource: { type: "boolean", description: "Wrap the commands in raidcom lock resource / unlock resource. Recommended for changing commands." },
+                    description: { type: "string", description: "A one-line comment for the top of the script." },
+                },
+                required: ["steps"],
+            },
+            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+        },
+        {
+            name: "raidcom_list_recipes",
+            description: "Ready-made workflows: provision volumes to an FC, iSCSI or NVMe/TCP host, create or grow a pool, create a mainframe (3390) pool, extend or delete volumes, create a command device, reclaim zero pages, read-only inventory, copy groups. " +
+                "With no arguments lists them. With `recipe`, shows its parameters and steps. With `query`, ranks recipes by keyword. Use raidcom_build_recipe to turn one into a script.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    recipe: { type: "string", description: "Recipe ID to show in detail, e.g. provision-fc-volumes." },
+                    query: { type: "string", description: "Words describing the task, e.g. \"new ESXi host\"." },
+                },
+            },
+            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+        },
+        {
+            name: "raidcom_build_recipe",
+            description: "Build the script for a recipe from its parameters (see raidcom_list_recipes). Lists such as ldev_ids accept ranges: [\"100-109\"]. " +
+                "Example: recipe provision-fc-volumes with {\"pool\": 0, \"ldev_ids\": [\"100-103\"], \"capacity\": \"100G\", \"ports\": [\"CL1-A\", \"CL2-A\"], \"host_grp\": \"esx01\", \"host_mode\": \"VMWARE_EX\", \"wwns\": [\"210000e08b0256f8\"]}. " +
+                "Returns the script and the individual commands. Nothing is executed.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    recipe: { type: "string", description: "Recipe ID." },
+                    params: { type: "object", description: "Recipe parameters.", additionalProperties: true },
+                    model: modelSchema,
+                    global: globalSchema,
+                    strict: strictSchema,
+                    login: { type: "boolean", description: "Add raidcom -login / -logout using $RAIDCOM_USER and $RAIDCOM_PASSWORD." },
+                    lock_resource: { type: "boolean", description: "Wrap the commands in raidcom lock resource / unlock resource." },
+                },
+                required: ["recipe", "params"],
+            },
+            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+        },
+        {
+            name: "raidcom_model_limits",
+            description: "Valid parameter ranges for a storage model (serial number, LDEV ID, pool ID, LU number, port names), taken from the Command Reference appendices. Without `model`, lists the models.",
+            inputSchema: { type: "object", properties: { model: modelSchema } },
+            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+        },
+    ];
+}