@opscompass/skills 0.1.0

package/skills/opscompass-resources/references/resources-commands.md

@@ -0,0 +1,178 @@
+# OpsCompass Resources `list` + Follow-up Details Reference
+
+Use this file to map workload and infrastructure questions to `opscompass resources list` flags and then inspect selected resources by iterating their ids with follow-up actions like `get-latest-configuration` and `get-compliance`.
+
+This skill is primarily for:
+- Oracle license risk analysis
+- Oracle and SQL Server sprawl analysis
+- tracing workloads to AWS, Azure, VMware, or Nutanix infrastructure
+- identifying misconfiguration from latest configuration data
+
+For Oracle licensing and sprawl work, date-bounded inventory is a standard workflow. Use `resources list` with:
+- `--resource-creation-date-beginning` for created-on-or-after questions
+- `--resource-creation-date-end` for created-before questions
+- both flags together for date-range questions
+
+## Company scope and CLI defaults
+
+- `--company`: Company id or slug. Include it explicitly in final `opscompass resources ...` commands so transcripts show tenant scope.
+- Defaults belong to `<selected-home>/defaults.json`: production uses `~/.opscompass`, dev uses `~/.opscompassdev`, and demo uses `~/.opscompassdemo`. Never fall back to another environment.
+- In embedded use, prefer approved resource tools and `opscompass_resources_defaults` with the authoritative host-supplied CLI entrypoint, command identity, and home. Do not assume global `PATH` or a production session.
+- Standalone `build_resources_command.js` and `list_and_fetch_latest_configs.js` accept `--cli opscompass|opscompassdev|opscompassdemo`; omission defaults to production unless a recognized bare `OPSCOMPASS_CLI_ENTRYPOINT` selects another identity. `OPSCOMPASS_CLI_ENTRYPOINT` may instead be a custom executable path: that retains production identity unless paired with explicit `--cli`. Explicit `--cli` wins over conflicting recognized ambient commands; custom paths can pair with an explicit identity. Pure summarizers process supplied JSON and do not accept `--cli`.
+- For standalone defaults inspection, use the selected CLI's `defaults list-defaults`, for example `opscompassdev defaults list-defaults` for dev.
+- Use the selected CLI's interactive `data-gathering setup` for guided defaults setup, or `defaults set-defaults --company <company> --account <account> --monitoring-configuration-id <id>` only when the user explicitly wants to change local defaults.
+- An explicit `--company` wins over defaults. Helpers can use the selected home's default `company` when it is omitted. Pass `--ignore-defaults --company <company>` to ignore defaults and force explicit scope. A company name does not select the CLI environment.
+- Builder output and tool calls with `execute: false` are previews, not executed queries or evidence. Preserve the selected context when executing a preview.
+- Report actual failures without exposing credentials. Authentication failure may warrant the selected CLI's login guidance; missing scope, authorization denial, invalid arguments, and network/service errors require their own diagnosis, not a generic expired-login response.
+
+## Provider interpretation note
+
+- In Opscompass inventory, `cloud_provider: "mlss"` usually indicates a database or on-prem infrastructure context such as VMware or Nutanix.
+- Do not treat `mlss` by itself as the final infrastructure platform answer when the user is asking what hosts a workload.
+- In this skill, `Oracle` means Oracle database workloads by default, not Oracle Cloud / OCI. Only interpret `Oracle` as Oracle Cloud when the user explicitly asks about Oracle Cloud, OCI, or cloud-provider/platform inventory.
+
+## Follow-up details action
+
+- `get-latest-configuration`: Full latest configuration for one resource.
+- Required for this skill: resolved `--company` and numeric `--id` (from `list` output).
+- In this skill, do not guess ids; get them from a preceding `list` command and iterate as needed.
+- Use the OpsCompass numeric resource `--id` for follow-up actions. Do not substitute `--resource-id` or `--resource-ids`; those are cloud platform resource identifiers and not the same value.
+- Do not use `resources show` for this skill workflow.
+- For Oracle DBs, inspect `document.version` and `document.edition` in the `get-latest-configuration` JSON.
+- For Oracle license-risk questions, do not stop at Oracle config alone if hosting and compute context can be established. Correlate the workload to the infrastructure it runs on.
+- `get-compliance`: Compliance findings array for one resource.
+- Required for this skill: resolved `--company`, numeric `--id` (from `list` output), and `--status`.
+- Builder syntax note: when using `scripts/build_resources_command.js` for compliance, pass `--param status=...` to the builder. The final printed `opscompass resources get-compliance ...` command will use `--status ...`.
+- Allowed `get-compliance --status` values: `open`, `remediated`, `policy-exception`, `mitigation`.
+- For compliance summaries, focus on `checkName`, `checkSeverity`, `errorMessage`, `recommendedAction`, and framework/control names.
+- For Oracle DBs, interpret `get-compliance` results primarily as Oracle license compliance findings unless the user explicitly frames the request differently.
+- For Oracle DB compliance workflows, also inspect `document.version`, `document.edition`, `document.productUsageConcerns`, and concerning `document.parameters` from `get-latest-configuration` so the answer has license context and feature-usage evidence.
+- For Oracle DB compliance workflows, the important output is usually the license-relevant findings themselves, not the raw count of `compliance_problems`. Treat the findings as evidence of feature, option, pack, or parameter usage that may exceed entitlement.
+- For Oracle latest-configuration, non-empty `document.productUsageConcerns` is per-database product/feature usage concern evidence.
+- For Oracle latest-configuration, `document.parameters.*.isConcerning=true` is license-relevant parameter evidence. Example: `CONTROL_MANAGEMENT_PACK_ACCESS=DIAGNOSTIC+TUNING` indicates Diagnostic Pack and Tuning Pack exposure.
+- Do not say per-database Oracle feature usage is unavailable until both `get-compliance --status open` and `get-latest-configuration` have been checked for the database.
+- If a prior `resources list` result already shows non-zero `compliance_problems` for Oracle or SQL Server resources and the user asks for the specific problems, iterate those resource ids with `get-compliance --status open`. Do not stop at the count-level list output.
+- For Oracle on VMware or Nutanix, the hosting path matters: database workload -> VM -> host -> broader platform context. If that chain cannot be established, the Oracle license-risk conclusion is partial.
+- Opscompass does not currently provide compliance checks for VMware vCenter or Nutanix resource types in this workflow. For `vcenter/*` and `Nutanix/*`, focus on `get-latest-configuration`.
+- For VMware investigations, inspect both VM and host `get-latest-configuration` results when movement or placement is relevant, because a VM moving hosts can appear in both resources' latest configuration. The latest-configuration payloads include VM and host ids that can be used to establish those relationships.
+- In `vcenter/host` configs, inspect `document.virtualMachines[]` for hosted VM ids/names and use `document.id`, `document.name`, `document.cluster`, and `document.datacenter` for host context.
+- For VMware vCPU mapping, inspect VM latest-configuration for direct CPU count fields such as `numCpu`, `numCPU`, `cpuCount`, `numCpus`, `vcpuCount`, or nested hardware/config equivalents like `hardware.numCPU` and `hardware.numCoresPerSocket`.
+- For Nutanix investigations, inspect `Nutanix/Vm`, `Nutanix/Host`, and `Nutanix/Cluster` latest configuration results together. Use `vm.document.host.extId`, `vm.document.cluster.extId`, `host.document.extId`, `host.document.cluster.uuid`, and `cluster.document.nodes.nodeList[].nodeUuid` to establish the relationships.
+- For Nutanix host-to-VM mapping, list `Nutanix/Vm` and `Nutanix/Host`, fetch latest configuration for the relevant ids, and map `Nutanix/Vm.document.host.extId` to `Nutanix/Host.document.extId`. Do not treat list output alone as a blocker; latest configuration is the relationship source.
+- For Nutanix vCPU mapping, inspect `document.numSockets`, `document.numCoresPerSocket`, and `document.numThreadsPerCore`, then compute provisioned vCPU as `numSockets * numCoresPerSocket * numThreadsPerCore`.
+- For Oracle and SQL Server workloads on Nutanix, the VM-to-host-to-cluster relationship is part of the workload answer and should be summarized explicitly.
+- If workload and infrastructure names line up, use that as strong supporting evidence for the correlation. Do not require a naming match, and do not treat the absence of one as evidence that the relationship is missing.
+
+## Core list filters
+
+- `--accounts [account_id]`
+- `--ids [12345]` (OpsCompass resource ids)
+- `--resource-ids [cloud-resource-id]` (cloud platform resource ids such as AWS ARNs or Azure resource ids; not the same as the numeric OpsCompass `--id` used in follow-up actions)
+- `--cloud-providers [aws | azure | gcp | microsoft365]`
+- `--resource-types [resource-type-name]` (restricted in this skill to approved resource types)
+- `--region-ids [region-id]`
+- `--tags [tag-value]`
+- `--resource-creation-date-beginning ["YYYY-MM-DD HH:MM:SS.mmm"]`
+- `--resource-creation-date-end ["YYYY-MM-DD HH:MM:SS.mmm"]`
+- `--open-compliance-issues [true | false]`
+- `--unacknowledged-changes [true | false]`
+- `--skip [number]`
+
+## Common request mappings
+
+- "What Oracle licensing risk do I have?" -> treat as Oracle workload plus infrastructure analysis; use Oracle compliance/config plus hosting context
+- "Which Oracle databases were created on or after X?" -> `--resource-creation-date-beginning`, usually with `--resource-types databases/oracle`
+- "Which Oracle databases were created between X and Y?" -> `--resource-creation-date-beginning` plus `--resource-creation-date-end`, usually with `--resource-types databases/oracle`
+- "Which recently created Oracle or SQL Server workloads may be sprawl candidates?" -> start with creation-date filters, then inspect latest config and hosting context
+- "Do I have any Oracle?" -> `--resource-types databases/oracle`
+- "Show me my Oracle" -> `--resource-types databases/oracle`
+- "Do I have Oracle Cloud resources?" -> only then treat it as a provider/platform question
+- "Map Oracle databases to provisioned vCPU cores on Nutanix" -> collect Oracle plus `Nutanix/Vm` latest configurations, then use `scripts/map_oracle_workloads_to_platform_cpus.js`
+- "Map Oracle databases to provisioned vCPU cores on VMware" -> collect Oracle plus `vcenter/virtualMachine` latest configurations, then use `scripts/map_oracle_workloads_to_platform_cpus.js`
+- "Where is this Oracle database hosted and what infrastructure backs it?" -> correlate the Oracle workload to VMware or Nutanix resources instead of stopping at the database record
+- "Which Oracle or SQL Server workloads may be sprawl candidates?" -> list workloads, inspect latest config, and summarize hosting/platform footprint and notable risk signals
+- "What misconfigurations or concerning settings do these Oracle or SQL Server workloads have?" -> inspect latest configuration and compliance where applicable, then summarize the risk-oriented differences
+- "resources created after X" -> `--resource-creation-date-beginning`
+- "resources created before X" -> `--resource-creation-date-end`
+- "resources in account A" -> `--accounts`
+- "AWS resources" -> `--cloud-providers aws`
+- "resources in us-east-1" -> `--region-ids us-east-1`
+- "resources with tag X" -> `--tags`
+- "EC2 instances" -> `--resource-types AWS::EC2::Instance`
+- "Nutanix clusters" -> `--resource-types Nutanix/Cluster`
+- "Nutanix hosts" -> `--resource-types Nutanix/Host`
+- "Nutanix virtual machines" -> `--resource-types Nutanix/Vm`
+- "Map Nutanix hosts to VMs" -> collect `Nutanix/Vm` and `Nutanix/Host` latest configurations, then map `vm.document.host.extId` to `host.document.extId`
+- "Which VMs are running on each Nutanix host?" -> collect `Nutanix/Vm` and `Nutanix/Host` latest configurations, then group VMs by matched host
+- "Nutanix subnets" -> `--resource-types Nutanix/Subnet`
+- "Nutanix volume groups" -> `--resource-types Nutanix/VolumeGroup`
+- "Oracle on Nutanix" -> start with `Nutanix/Vm`, then relate to `Nutanix/Host` and `Nutanix/Cluster`
+- "SQL Server on Nutanix" -> start with `Nutanix/Vm`, then relate to `Nutanix/Host` and `Nutanix/Cluster`
+- "Nutanix compliance" -> explain that Nutanix resources do not currently have compliance checks here; inspect latest configuration instead
+- "VMware hosts" -> `--resource-types vcenter/host`
+- "VMware virtual machines" -> `--resource-types vcenter/virtualMachine`
+- "VMware VM moved hosts" -> inspect both `vcenter/virtualMachine` and `vcenter/host` latest configuration results and use the VM/host ids in those payloads to map the relationship
+- "VMware compliance" -> explain that vCenter resources do not currently have compliance checks here; inspect latest configuration instead
+- "Azure SQL servers" -> `--resource-types Microsoft.Sql/servers`
+- "RDS database instances" -> `--resource-types AWS::RDS::DBInstance`
+- "SQL Server databases" -> `--resource-types databases/mssqlserver`
+- "Oracle databases" -> `--resource-types databases/oracle`
+- "Oracle database compliance" -> usually Oracle license compliance via `get-compliance`
+- "Are these Oracle databases on Nutanix?" -> do not stop at `cloud_provider: "mlss"`; continue workload-to-infrastructure correlation through Nutanix resources
+- "resources with open compliance issues" -> `--open-compliance-issues true`
+- "resources with unacknowledged changes" -> `--unacknowledged-changes true`
+
+## Allowed `--resource-types` in this skill
+
+- `AWS::EC2::Instance`
+- `Microsoft.Sql/servers`
+- `AWS::RDS::DBInstance`
+- `databases/mssqlserver`
+- `databases/oracle`
+- `Nutanix/AuthorizationPolicy`
+- `Nutanix/Cluster`
+- `Nutanix/Host`
+- `Nutanix/Image`
+- `Nutanix/Role`
+- `Nutanix/Subnet`
+- `Nutanix/User`
+- `Nutanix/VirtualSwitch`
+- `Nutanix/Vm`
+- `Nutanix/VolumeGroup`
+- `vcenter/host`
+- `vcenter/virtualMachine`
+
+## Query strategy
+
+- Start with resolved company scope plus one or two filters. If defaults are used, still include `--company <resolved-company>` in the command you run or report.
+- If empty, remove the most restrictive filter (often date range, tag, or type).
+- Add `--skip` only when paging through a known large result set.
+- For large result sets, page deliberately and summarize the aggregate result instead of inspecting one oversized raw response.
+- Choose follow-up actions with this priority:
+  - Oracle license/compliance question -> `get-compliance` plus `get-latest-configuration`, then correlate to infrastructure when possible
+  - Oracle or SQL Server hosting/sprawl/misconfiguration question -> `get-latest-configuration` first, then correlate to infrastructure
+  - VMware or Nutanix question -> `get-latest-configuration`, not `get-compliance`
+  - generic inventory question -> `list`, then only fetch follow-up data if needed
+- For Oracle licensing or sprawl questions scoped to time, start with a date-bounded `resources list` rather than a broad list.
+- When the user wants full details, pick a resource `id` from the list output and run `get-latest-configuration`.
+- When the user wants compliance findings, pick a resource `id` from the list output and run `get-compliance --status ...`.
+- If the conversation was previously focused on VMware or Nutanix and the user pivots to Oracle or SQL Server, re-evaluate intent from scratch and default to `databases/oracle` or `databases/mssqlserver` rather than continuing the prior infrastructure framing.
+- For multiple resources, iterate through the list ids and run `get-latest-configuration` per resource.
+- For multiple compliance checks, iterate through list ids and run `get-compliance --status ...` per resource.
+- If the list output already identified which resources have `compliance_problems > 0`, target those ids first for `get-compliance --status open`.
+- For Oracle compliance checks, pair `get-compliance` with `get-latest-configuration` so version, edition, product usage concerns, and concerning parameters can be included in the summary.
+- For Oracle compliance answers, prioritize the actual findings and their license impact over the count of affected resources unless the user specifically asked for counts.
+- Do not infer that the CLI lacks resource-level compliance detail unless a real `get-compliance` command failed and the error output supports that conclusion.
+- For Oracle license-risk analysis, try to establish where the database is hosted and what underlying compute context applies. If that evidence is missing, say the conclusion is incomplete or partial.
+- For Oracle workload-to-vCPU mapping on Nutanix or VMware, prefer collecting mixed Oracle and VM latest-configuration payloads and running `scripts/map_oracle_workloads_to_platform_cpus.js` instead of extracting CPU fields manually in the model.
+- Do not plan `get-compliance` follow-ups for `vcenter/*` or `Nutanix/*` resource types in normal workflows.
+- For VMware host/VM investigations, prefer collecting latest configuration from both resource types, use VM/host ids from those payloads to establish the relationship, and summarize them together.
+- For host-side VMware summaries, include hosted VM ids/names from `document.virtualMachines[]` when relevant.
+- For Nutanix VM/host/cluster investigations, prefer collecting latest configuration from all three resource types and summarize VM-to-host and VM-to-cluster relationships together.
+- For Nutanix host-to-VM mapping, proceed directly to latest-configuration relationship analysis; do not ask the user to confirm an extra step when the mapping request is explicit.
+- For Nutanix host-to-VM mapping output, distinguish complete inventories from retrieved subsets, include unmapped VMs, and call out duplicate VM names or duplicate resource ids when present.
+- For Oracle and SQL Server on Nutanix, explicitly report which VM, host, and cluster are involved when those relationships can be established.
+- Prefer direct configuration relationships first, then use naming conventions as supporting evidence when they are strong.
+- If the workload inventory shows `cloud_provider: "mlss"`, use that as evidence of database/on-prem context and continue tracing to VMware or Nutanix rather than stopping there.
+- For many configuration results, save/collect JSON and use `scripts/summarize_latest_configuration.js` to compact the data for reasoning across resource types.
+- For repeated list->follow-up workflows, use `scripts/list_and_fetch_latest_configs.js` to run the list, iterate ids, collect configs and/or compliance, and print a compact summary.

package/skills/opscompass-resources/scripts/build-resources-command.tool.js

@@ -0,0 +1,53 @@
+import { runCli } from "../.opscompass-runtime/tools/opsc-cli.js";
+import { buildCommand, commandText, parseParamMap, validateArgs, } from "./build_resources_command.js";
+import { resolveCompany } from "../.opscompass-runtime/tools/index.js";
+export const buildResourcesCommandTool = {
+    name: "opscompass_resources_build_command",
+    label: "build resources command",
+    description: "Build a validated Opscompass resources command without shell interpolation.",
+    parameters: {
+        type: "object",
+        properties: {
+            action: {
+                type: "string",
+                enum: ["list", "get-latest-configuration", "get-compliance"],
+            },
+            company: { type: "string" },
+            id: { type: "string" },
+            params: { type: "array", items: { type: "string" } },
+            execute: { type: "boolean" },
+            ignoreDefaults: { type: "boolean" },
+        },
+        additionalProperties: false,
+    },
+    async execute(input, context) {
+        const value = (input ?? {});
+        const company = resolveCompany(value.company, {
+            ignoreDefaults: value.ignoreDefaults ?? false,
+            context,
+        });
+        const args = {
+            action: value.action ?? "list",
+            company,
+            resourceNumericId: value.id,
+            param: value.params ?? [],
+            execute: value.execute ?? false,
+            ignoreDefaults: value.ignoreDefaults ?? false,
+        };
+        const paramMap = parseParamMap(args.param);
+        validateArgs(args, paramMap);
+        const command = buildCommand(args, paramMap, context);
+        const text = commandText(command);
+        const output = args.execute
+            ? await runCli(context, command.slice(1))
+            : undefined;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: output === undefined ? text : `${text}\n\n${output}`,
+                },
+            ],
+        };
+    },
+};

package/skills/opscompass-resources/scripts/build_resources_command.js

@@ -0,0 +1,240 @@
+import { spawn } from "node:child_process";
+import { isMainModule } from "../.opscompass-runtime/tools/cli-entrypoint.js";
+import { resolveCliContext } from "../.opscompass-runtime/tools/opsc-cli-context.js";
+import { resolveCompany } from "../.opscompass-runtime/tools/opsc-cli-defaults.js";
+export { resolveCompany };
+export const ALLOWED_LIST_PARAMS = new Set([
+    "accounts",
+    "ids",
+    "resource-ids",
+    "cloud-providers",
+    "resource-types",
+    "region-ids",
+    "tags",
+    "resource-creation-date-beginning",
+    "resource-creation-date-end",
+    "open-compliance-issues",
+    "unacknowledged-changes",
+    "skip",
+]);
+export const ALLOWED_LIST_ENUMS = {
+    "cloud-providers": new Set(["aws", "azure", "gcp", "microsoft365"]),
+    "open-compliance-issues": new Set(["true", "false"]),
+    "unacknowledged-changes": new Set(["true", "false"]),
+};
+export const ALLOWED_RESOURCE_TYPES = new Set([
+    "AWS::EC2::Instance",
+    "Microsoft.Sql/servers",
+    "AWS::RDS::DBInstance",
+    "databases/mssqlserver",
+    "databases/oracle",
+    "Nutanix/AuthorizationPolicy",
+    "Nutanix/Cluster",
+    "Nutanix/Host",
+    "Nutanix/Image",
+    "Nutanix/Role",
+    "Nutanix/Subnet",
+    "Nutanix/User",
+    "Nutanix/VirtualSwitch",
+    "Nutanix/Vm",
+    "Nutanix/VolumeGroup",
+    "vcenter/host",
+    "vcenter/virtualMachine",
+]);
+const PARAM_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9-]*=.+$/;
+const DATE_FILTER_KEYS = new Set([
+    "resource-creation-date-beginning",
+    "resource-creation-date-end",
+]);
+const DATE_FILTER_PATTERN = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}$/;
+const ALLOWED_ACTIONS = new Set([
+    "list",
+    "get-latest-configuration",
+    "get-compliance",
+]);
+const ALLOWED_COMPLIANCE_STATUSES = new Set([
+    "open",
+    "remediated",
+    "policy-exception",
+    "mitigation",
+]);
+const sorted = (values) => [...values].sort();
+const shellQuote = (value) => /^[A-Za-z0-9_./:-]+$/.test(value)
+    ? value
+    : `'${value.replaceAll("'", "'\\''")}'`;
+export const commandText = (command) => command.map(shellQuote).join(" ");
+function runCommand(command, context) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(context.cliEntryPoint, command.slice(1), {
+            shell: false,
+            stdio: "inherit",
+        });
+        child.once("error", reject);
+        child.once("close", (code) => resolve(code ?? 1));
+    });
+}
+export function parseKeyValues(rawItems) {
+    return rawItems.map((item) => {
+        if (!PARAM_PATTERN.test(item))
+            throw new Error(`invalid --param '${item}'. Use key=value (example: cloud-providers=aws).`);
+        const index = item.indexOf("=");
+        return [item.slice(0, index), item.slice(index + 1)];
+    });
+}
+export function parseParamMap(rawItems) {
+    const result = new Map();
+    for (const [key, value] of parseKeyValues(rawItems)) {
+        if (!result.has(key))
+            result.set(key, []);
+        result.get(key).push(value);
+    }
+    return result;
+}
+const mapGet = (map, key) => map instanceof Map ? map.get(key) : map[key];
+const mapHas = (map, key) => map instanceof Map ? map.has(key) : Object.hasOwn(map, key);
+const mapEntries = (map) => map instanceof Map ? [...map.entries()] : Object.entries(map);
+const mapSize = (map) => map instanceof Map ? map.size : Object.keys(map).length;
+export function validateArgs(args, paramMap) {
+    if (!ALLOWED_ACTIONS.has(args.action))
+        throw new Error(`unsupported action '${args.action}' (allowed: ${sorted(ALLOWED_ACTIONS).join(", ")}).`);
+    if (!args.company)
+        throw new Error(`resources ${args.action} requires --company.`);
+    if (args.action === "get-latest-configuration") {
+        if (!args.resourceNumericId)
+            throw new Error("resources get-latest-configuration requires --id.");
+        if (mapSize(paramMap))
+            throw new Error("resources get-latest-configuration does not support --param filters.");
+        return;
+    }
+    if (args.action === "get-compliance") {
+        if (!args.resourceNumericId)
+            throw new Error("resources get-compliance requires --id.");
+        const statuses = mapGet(paramMap, "status");
+        if (!statuses?.length)
+            throw new Error("resources get-compliance requires --param status=...");
+        if (statuses.length !== 1)
+            throw new Error("resources get-compliance accepts exactly one --param status=...");
+        if (mapSize(paramMap) !== 1)
+            throw new Error("resources get-compliance only supports --param status=...");
+        const status = statuses[0].trim();
+        if (!ALLOWED_COMPLIANCE_STATUSES.has(status))
+            throw new Error(`invalid value '${status}' for --param status=... (allowed: ${sorted(ALLOWED_COMPLIANCE_STATUSES).join(", ")}).`);
+        return;
+    }
+    if (args.resourceNumericId)
+        throw new Error("resources list does not support top-level --id.");
+    for (const key of mapEntries(paramMap).map(([key]) => key))
+        if (!ALLOWED_LIST_PARAMS.has(key))
+            throw new Error(`unsupported list filter '${key}'. Allowed filters: ${sorted(ALLOWED_LIST_PARAMS).join(", ")}.`);
+    for (const [key, allowed] of Object.entries(ALLOWED_LIST_ENUMS)) {
+        if (!mapHas(paramMap, key))
+            continue;
+        for (const raw of mapGet(paramMap, key))
+            for (const value of raw.split(",")) {
+                const candidate = value.trim();
+                if (!allowed.has(candidate))
+                    throw new Error(`invalid value '${candidate}' for --param ${key}=... (allowed: ${sorted(allowed).join(", ")}).`);
+            }
+    }
+    for (const key of DATE_FILTER_KEYS)
+        for (const raw of mapGet(paramMap, key) ?? []) {
+            if (!DATE_FILTER_PATTERN.test(raw))
+                throw new Error(`invalid date format for --param ${key}=... (expected: YYYY-MM-DD HH:MM:SS.mmm).`);
+            const date = new Date(raw.replace(" ", "T") + "Z");
+            if (Number.isNaN(date.getTime()) ||
+                date.toISOString().slice(0, 23).replace("T", " ") !== raw)
+                throw new Error(`invalid date value for --param ${key}=... (invalid date).`);
+        }
+    for (const raw of mapGet(paramMap, "resource-types") ?? [])
+        for (const value of raw.split(",")) {
+            const candidate = value.trim();
+            if (!ALLOWED_RESOURCE_TYPES.has(candidate))
+                throw new Error(`invalid value '${candidate}' for --param resource-types=... (allowed: ${sorted(ALLOWED_RESOURCE_TYPES).join(", ")}).`);
+        }
+}
+export function buildCommand(args, paramMap, context = resolveCliContext()) {
+    const command = [
+        context.cliCommand,
+        "resources",
+        args.action,
+        "--company",
+        args.company,
+    ];
+    if (["get-latest-configuration", "get-compliance"].includes(args.action)) {
+        command.push("--id", args.resourceNumericId);
+        if (args.action === "get-compliance")
+            for (const [key, values] of mapEntries(paramMap))
+                for (const value of values)
+                    command.push(`--${key}`, value);
+        return command;
+    }
+    for (const [key, values] of mapEntries(paramMap))
+        for (const value of values)
+            command.push(`--${key}`, value);
+    return command;
+}
+function parseArgs(argv) {
+    const args = {
+        action: "list",
+        param: [],
+        execute: false,
+        ignoreDefaults: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const flag = argv[i];
+        if (flag === "--execute")
+            args.execute = true;
+        else if (flag === "--ignore-defaults")
+            args.ignoreDefaults = true;
+        else if (["--action", "--company", "--id", "--cli"].includes(flag)) {
+            if (++i >= argv.length)
+                throw new Error(`argument ${flag}: expected one argument`);
+            const value = argv[i];
+            if (flag === "--action")
+                args.action = value;
+            else if (flag === "--company")
+                args.company = value;
+            else if (flag === "--cli")
+                args.cli = value;
+            else
+                args.resourceNumericId = value;
+        }
+        else if (flag === "--param") {
+            if (++i >= argv.length)
+                throw new Error("argument --param: expected one argument");
+            args.param.push(argv[i]);
+        }
+        else if (flag === "--help" || flag === "-h") {
+            console.log("Build an opscompass resources list/get-latest-configuration/get-compliance command.");
+            process.exit(0);
+        }
+        else
+            throw new Error(`unrecognized arguments: ${flag}`);
+    }
+    return args;
+}
+export async function main(argv = process.argv.slice(2)) {
+    let args;
+    try {
+        args = parseArgs(argv);
+        const context = resolveCliContext(args.cli);
+        args.company = resolveCompany(args.company, {
+            ignoreDefaults: args.ignoreDefaults,
+            context,
+        });
+        const paramMap = parseParamMap(args.param);
+        validateArgs(args, paramMap);
+        const command = buildCommand(args, paramMap, context);
+        console.log(commandText(command));
+        if (!args.execute)
+            return 0;
+        return await runCommand(command, context);
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        return 2;
+    }
+}
+if (isMainModule(import.meta.url)) {
+    process.exitCode = await main();
+}

package/skills/opscompass-resources/scripts/list-and-fetch-latest-configs.tool.js

@@ -0,0 +1,116 @@
+import { main as runWorkflowMain } from "./list_and_fetch_latest_configs.js";
+function appendPositiveInteger(args, flag, value) {
+    if (value === undefined)
+        return;
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        throw new Error(`${flag} must be a positive integer.`);
+    }
+    args.push(flag, String(value));
+}
+function appendBooleanFlag(args, flag, value) {
+    if (value === undefined)
+        return;
+    if (typeof value !== "boolean")
+        throw new Error(`${flag} must be a boolean.`);
+    if (value)
+        args.push(flag);
+}
+export function buildWorkflowArgs(value) {
+    if (typeof value.company !== "string" || !value.company.trim()) {
+        throw new Error("--company is required.");
+    }
+    const params = value.params === undefined ? [] : value.params;
+    if (!Array.isArray(params) ||
+        params.some((param) => typeof param !== "string")) {
+        throw new Error("params must be an array of key=value resource filters.");
+    }
+    const args = ["--company", value.company.trim()];
+    // These --param arguments belong to the workflow helper. Its existing
+    // resource command builder validates each key=value and emits the actual
+    // --<filter> value flags for `resources list`.
+    for (const param of params)
+        args.push("--param", param);
+    appendPositiveInteger(args, "--max-resources", value.maxResources);
+    appendPositiveInteger(args, "--page-size-hint", value.pageSizeHint);
+    appendPositiveInteger(args, "--max-pages", value.maxPages);
+    if (value.complianceStatus !== undefined) {
+        if (typeof value.complianceStatus !== "string" ||
+            !value.complianceStatus.trim()) {
+            throw new Error("--compliance-status must be a non-empty string.");
+        }
+        args.push("--compliance-status", value.complianceStatus.trim());
+    }
+    appendBooleanFlag(args, "--no-configs", value.noConfigs);
+    appendBooleanFlag(args, "--stop-on-error", value.stopOnError);
+    appendBooleanFlag(args, "--verbose", value.verbose);
+    appendBooleanFlag(args, "--ignore-defaults", value.ignoreDefaults);
+    // WHY: a bounded default prevents an omitted caller limit from triggering
+    // an unbounded configuration sweep on large tenants.
+    if (value.maxResources === undefined) {
+        args.push("--max-resources", "100");
+    }
+    return args;
+}
+export function formatCapturedError(values) {
+    return `[error] ${formatConsoleArgs(values)}`;
+}
+function formatConsoleArgs(values) {
+    return values.map((value) => String(value)).join(" ");
+}
+/**
+ * Run the existing list -> configuration/compliance workflow with tool
+ * context, returning the workflow's captured text output.
+ */
+export async function runListAndFetchLatestConfigs(value, context) {
+    const args = buildWorkflowArgs(value);
+    if (context.signal.aborted)
+        throw new Error("Opscompass command aborted.");
+    const lines = [];
+    const capture = {
+        log(...values) {
+            lines.push(formatConsoleArgs(values));
+        },
+        error(...values) {
+            lines.push(formatCapturedError(values));
+        },
+    };
+    const exitCode = await runWorkflowMain(args, capture, {
+        context,
+        workspaceRoot: context.workspaceRoot,
+        signal: context.signal,
+    });
+    const output = lines.join("\n");
+    if (exitCode !== 0) {
+        throw new Error(output.trim() || `Resources workflow failed with exit code ${exitCode}.`);
+    }
+    return output.trim() || "Resources workflow completed without output.";
+}
+export const listAndFetchLatestConfigsTool = {
+    name: "opscompass_resources_list_and_fetch_latest_configs",
+    label: "list and fetch latest configurations",
+    description: "Run the bounded resources inventory workflow and return its JSON output.",
+    parameters: {
+        type: "object",
+        properties: {
+            company: { type: "string" },
+            params: { type: "array", items: { type: "string" } },
+            maxResources: { type: "integer", minimum: 1 },
+            pageSizeHint: { type: "integer", minimum: 1 },
+            maxPages: { type: "integer", minimum: 1 },
+            complianceStatus: { type: "string" },
+            noConfigs: { type: "boolean" },
+            stopOnError: { type: "boolean" },
+            verbose: { type: "boolean" },
+            ignoreDefaults: { type: "boolean" },
+        },
+        required: ["company"],
+        additionalProperties: false,
+    },
+    async execute(input, context) {
+        const value = input && typeof input === "object" && !Array.isArray(input)
+            ? input
+            : {};
+        const output = await runListAndFetchLatestConfigs(value, context);
+        return { content: [{ type: "text", text: output }] };
+    },
+};