@opscompass/skills 0.1.0 → 0.2.1

package/README.md

@@ -75,4 +75,12 @@ Report query errors as errors, not as an empty inventory. Authentication failure
 
 ## Oracle licensing evidence
 
-The Oracle Licensing Skill's included entitlement fixtures and `fake_entitlements_api.js` helper are synthetic examples for local testing. They do not query a live entitlement service, establish license ownership, or prove compliance. Use real customer-provided entitlement evidence for an assessment, and identify missing evidence explicitly. Follow the [Oracle Licensing Skill](./skills/opscompass-oracle-licensing/SKILL.md) for the assessment workflow.
+The Oracle Licensing Skill reads the latest persisted OpsCompass periodic Oracle assessment through `oracle-assessment.js`; it does not recalculate an assessment or use synthetic fixture payloads. The selected OpsCompass CLI must be installed, authenticated, and able to read a saved assessment. The helper returns a complete JSON page for one section (`entitlements`, `summary`, `license-usage-summary`, or `deployment-details`), mapping each section to the selected CLI's `get-oracle-assessment-{section}` operation.
+
+For standalone use, request every page for every needed section. Pin the local `assessmentId` returned by the first response on all later pages and sections, replacing any initial MLSS assessment selector. Advance `--offset` by `--limit` until the section's returned array is shorter than the limit; request one more page when a page is exactly full. The default limit is 100. Preserve the returned assessment metadata and nested entitlement details, and identify missing customer/licensing evidence explicitly. This saved periodic assessment is distinct from `get-oracle-current-entitlements`.
+
+```sh
+node node_modules/@opscompass/skills/skills/opscompass-oracle-licensing/scripts/oracle-assessment.js entitlements --cli opscompass --company YOUR_COMPANY --account YOUR_ACCOUNT --limit 100 --offset 0
+```
+
+In a host integration, the `opscompass_oracle_licensing_assessment` tool uses the host-selected CLI context rather than a model-selected executable. Follow the [Oracle Licensing Skill](./skills/opscompass-oracle-licensing/SKILL.md) for evidence boundaries and the complete workflow.

package/manifest.json

@@ -2,10 +2,10 @@
   "schemaVersion": 1,
   "scope": "public",
   "name": "@opscompass/skills",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "source": {
     "repository": "https://gitlab.com/opscompass-hob/opscompass-ai/opscompassai.git",
-    "revision": "3a8fb700e740024080bfb4d2863784cca0254581",
+    "revision": "e71529c9bf8952fa65fc291216a07c54e15e29ad",
     "dirty": false
   },
   "skills": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opscompass/skills",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Public OpsCompass Skills with portable compiled tools and runtime assets",
   "license": "UNLICENSED",
   "type": "module",

package/skills/opscompass-oracle-licensing/.opscompass-runtime/tools/opsc-cli-context.js

@@ -0,0 +1,34 @@
+import os from "node:os";
+import path from "node:path";
+const CLI_COMMANDS = [
+    "opscompass",
+    "opscompassdev",
+    "opscompassdemo",
+];
+/** Resolve standalone CLI identity; embedded callers supply their trusted context directly. */
+export function resolveCliContext(cliCommand) {
+    if (cliCommand !== undefined && !CLI_COMMANDS.includes(cliCommand)) {
+        throw new Error(`--cli must be one of: ${CLI_COMMANDS.join(", ")}.`);
+    }
+    const override = process.env.OPSCOMPASS_CLI_ENTRYPOINT;
+    const recognizedOverride = override !== undefined && CLI_COMMANDS.includes(override);
+    const selectedCommand = cliCommand ?? (recognizedOverride ? override : "opscompass");
+    // An explicit identity wins over an ambient command, while a local executable
+    // override may run that identity. Never infer an environment from a file path.
+    const cliEntryPoint = override && !recognizedOverride ? override : selectedCommand;
+    return {
+        cliEntryPoint,
+        cliCommand: selectedCommand,
+        opscompassHome: path.join(os.homedir(), `.${selectedCommand}`),
+    };
+}
+export function resolveCliInvocation(context, args) {
+    return {
+        executable: context.cliInvocation?.executable ?? context.cliEntryPoint,
+        args: [...(context.cliInvocation?.args ?? []), ...args],
+        env: {
+            ...(context.cliInvocation?.env ?? process.env),
+            OPSCOMPASS_CLI_ENTRYPOINT: context.cliEntryPoint,
+        },
+    };
+}

package/skills/opscompass-oracle-licensing/.opscompass-runtime/tools/opsc-cli.js

@@ -0,0 +1,102 @@
+import { spawn } from "node:child_process";
+import { resolveCliInvocation } from "./opsc-cli-context.js";
+const MAX_TIMEOUT_SECONDS = 120;
+const MAX_OUTPUT_BYTES = 100_000;
+export async function runCli(context, args) {
+    if (context.signal.aborted)
+        throw new Error("Opscompass command aborted.");
+    const invocation = resolveCliInvocation(context, args);
+    const child = spawn(invocation.executable, invocation.args, {
+        shell: false,
+        cwd: context.workspaceRoot,
+        // The host-selected executable must win over ambient standalone overrides.
+        env: {
+            ...invocation.env,
+            ELECTRON_RUN_AS_NODE: "1",
+            OPSCOMPASS_STUDIO: "1",
+        },
+        stdio: ["ignore", "pipe", "pipe"],
+        detached: process.platform !== "win32",
+    });
+    const stdout = [];
+    const stderr = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let timedOut = false;
+    const collect = (chunks, chunk, outputBytes) => {
+        if (outputBytes >= MAX_OUTPUT_BYTES)
+            return outputBytes;
+        const bounded = chunk.subarray(0, MAX_OUTPUT_BYTES - outputBytes);
+        chunks.push(bounded);
+        return outputBytes + bounded.length;
+    };
+    child.stdout?.on("data", (chunk) => {
+        stdoutBytes = collect(stdout, chunk, stdoutBytes);
+    });
+    child.stderr?.on("data", (chunk) => {
+        stderrBytes = collect(stderr, chunk, stderrBytes);
+    });
+    let graceTimer;
+    const forceKill = () => {
+        try {
+            if (process.platform !== "win32" && child.pid)
+                process.kill(-child.pid, "SIGKILL");
+            else
+                child.kill("SIGKILL");
+        }
+        catch {
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                // The child may have exited between termination attempts.
+            }
+        }
+    };
+    const kill = () => {
+        try {
+            const sent = process.platform !== "win32" && child.pid
+                ? process.kill(-child.pid, "SIGTERM")
+                : child.kill("SIGTERM");
+            if (process.platform !== "win32" && sent && graceTimer === undefined) {
+                graceTimer = setTimeout(forceKill, 5_000);
+            }
+        }
+        catch {
+            forceKill();
+        }
+    };
+    const result = new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.once("close", (code) => {
+            const output = Buffer.concat(stdout).toString("utf8");
+            const diagnostic = Buffer.concat(stderr).toString("utf8");
+            if (context.signal.aborted)
+                reject(new Error("Opscompass command aborted."));
+            else if (timedOut)
+                reject(new Error(`Opscompass command timed out after ${MAX_TIMEOUT_SECONDS} seconds.`));
+            else if (code !== 0)
+                reject(new Error(diagnostic.trim() ||
+                    output.trim() ||
+                    `Opscompass command failed with exit code ${code}.`));
+            else
+                resolve(output);
+        });
+    });
+    const timeout = setTimeout(() => {
+        timedOut = true;
+        kill();
+    }, MAX_TIMEOUT_SECONDS * 1_000);
+    if (context.signal.aborted)
+        kill();
+    else
+        context.signal.addEventListener("abort", kill, { once: true });
+    try {
+        return await result;
+    }
+    finally {
+        clearTimeout(timeout);
+        clearTimeout(graceTimer);
+        context.signal.removeEventListener("abort", kill);
+    }
+}

package/skills/opscompass-oracle-licensing/SKILL.md

@@ -97,12 +97,15 @@ Review available entitlement evidence for:
 - applicability to workloads in scope
 - missing or ambiguous entitlement records
 
-Only for illustrative local testing, not for a customer assessment, installed Skill fixture responses can be generated with:
-- `node scripts/fake_entitlements_api.js deployment-details`
-- `node scripts/fake_entitlements_api.js license-usage-map`
-- `node scripts/fake_entitlements_api.js overall-compliance`
+Use `opscompass_oracle_licensing_assessment` for actual licensing-assessment evidence. It reads persisted Opscompass assessment data through the selected CLI; it does not calculate an assessment or fetch live-current entitlements. The four `section` values are `entitlements`, `summary`, `license-usage-summary`, and `deployment-details`. Each call returns one complete CLI JSON page, including the assessment metadata, pagination, section array, and nested details. Preserve the returned envelope and provenance; do not summarize away entitlement details or evidence sources before analysis.
 
-Those commands read static payloads from `api/entitlement-deployment/`, `api/entitlement-usage/`, and `api/entitlement-compliance/`. They do not query a live entitlement service and must never fill missing customer evidence or establish license ownership/compliance. From the Skills source repository root after building, use `.compiled/skills/licensing/opscompass-oracle-licensing/scripts/fake_entitlements_api.js` instead of the installed `scripts/` path.
+Fetch every page of all four sections. Start at `offset: 0`, using the default `limit: 100` unless a different page size is useful. Continue by adding the returned `pagination.limit` to the offset until that section's array contains fewer rows than the limit. If a page is exactly full, request the next page even if it may be empty; an empty section array is a valid final page. Use the returned local `assessmentId` on every subsequent page and section. `mlssAssessmentId` is a different identifier namespace and may select the first page only; replace it with the returned local `assessmentId` immediately. `account` is an opaque string, including when it looks numeric.
+
+The assessment tool accepts optional `company` and `account` scope, and at most one of `assessmentId` or `mlssAssessmentId`. In embedded use, the trusted host context selects the executable and environment; never accept a model-selected `--cli`. Standalone `scripts/oracle-assessment.js` accepts the section and matching kebab-case flags, plus `--cli opscompass|opscompassdev|opscompassdemo`. Do not substitute `get-oracle-current-entitlements`: it is a separate command and does not represent this persisted assessment.
+
+If company or account is omitted, the selected CLI may use its own saved defaults; explicitly provide scope when needed to establish the assessment boundary. Blank or malformed explicit values must fail rather than silently fall back to a saved default.
+
+Treat this source as the latest persisted periodic assessment, not a recalculation or proof of present-day entitlements. Record the selected CLI identity, company/account scope, local `assessmentId`, assessment name, and any source/as-of date actually returned. Distinguish an assessment's as-of date from the retrieval date; if freshness is unknown, say so. Entitlement rows and `entitlementDetails` are evidence with provenance, not independently verified proof of purchased rights.
 
 6. Analyze current-state exposure.
 Assess:
@@ -159,6 +162,9 @@ For Oracle on VMware or Nutanix, workload-to-infrastructure correlation is manda
 
 Lead with licensing risk and business-impacting recommendations, not raw inventory.
 
+- Record the selected Opscompass CLI identity, company/account scope, assessment name, local `assessmentId`, and source/as-of date when returned. Distinguish the latest persisted periodic assessment from recalculation or live-current entitlement data, and distinguish its as-of date from retrieval time.
+- Save final user-facing assessment artifacts under `Documents/` with the existing Documents write tool. Claim a saved artifact only after the write succeeds.
+
 Structure the final answer in this order when possible:
 
 1. Assessment summary

package/skills/opscompass-oracle-licensing/references/evidence-model.md

@@ -2,7 +2,7 @@
 
 Use this file when you need to reason about what evidence is required for an Oracle Optimized License Assessment focused on AWS Oracle target-state optimization.
 
-Record the selected OpsCompass environment, company scope, and evidence provenance. Use the authoritative host context when supplied; otherwise use the Resources helpers' selected standalone CLI/home. Never combine another environment's defaults or credentials into the assessment. Command previews (`execute: false`) are not collected evidence, and failed retrievals must be recorded as gaps with their actual cause rather than assumed to be expired login.
+Record the selected OpsCompass CLI environment, company/account scope, and evidence provenance. For persisted assessment evidence, retain the returned local `assessmentId`, assessment name, relevant returned date, section, and page offsets. Keep the source/as-of date separate from retrieval time; if freshness cannot be established, say so. Never combine another environment's defaults or credentials into the assessment. Command previews (`execute: false`) are not collected evidence, and failed retrievals must be recorded as gaps with their actual cause rather than assumed to be expired login.
 
 ## Workload Identity
 
@@ -56,7 +56,7 @@ Try to establish:
 
 If entitlement evidence is incomplete, the assessment must say so explicitly.
 
-Use explicit user-provided entitlement records or evidence from sources the user authorizes for this assessment. Record their provenance, terms, quantities, and applicability to the workloads in scope. Observed feature usage and compliance findings do not by themselves establish purchased licenses or contractual rights. Bundled `api/entitlement-*` fixtures and `fake_entitlements_api.js` output are illustrative static examples, not customer records or a live API; never use them to fill entitlement gaps or support a customer compliance conclusion.
+Use `opscompass_oracle_licensing_assessment` or its standalone CLI to retrieve the actual persisted assessment pages for `entitlements`, `summary`, `license-usage-summary`, and `deployment-details`. Each call returns one complete JSON page. Fetch every page, pin the returned local `assessmentId` on all pages and sections after the first response, and continue until a section array is shorter than the returned `pagination.limit`; fetch an empty page if the prior page was exactly full. `mlssAssessmentId` selects an initial assessment in a separate identifier namespace; replace it with the returned local `assessmentId`. The data is the latest persisted periodic assessment, not a recalculation or live-current entitlement query. `get-oracle-current-entitlements` is separate and must not be substituted. Preserve the full metadata, `entReviewName`, nested `entitlementDetails`, and any provenance rather than extracting only conclusions. User-authorized assessment data is evidence with provenance, not by itself proof of purchased rights.
 
 ## AWS Target-State Evidence
 
@@ -88,3 +88,7 @@ For each conclusion, distinguish:
 - directly established evidence
 - strong inference
 - partial conclusion because key evidence is missing
+
+## Provenance, Freshness, And Artifacts
+
+Record the selected CLI identity, actual company/account scope, local assessment ID, assessment name, source/as-of date when returned, and retrieved sections/pages. Distinguish the assessment's as-of date from retrieval time and state when freshness is unknown. Save final user-facing assessment artifacts under `Documents/` with the existing Documents write tool, and report them as saved only after the write succeeds.

package/skills/opscompass-oracle-licensing/references/report-structure.md

@@ -34,9 +34,13 @@ Use this file when the user wants a written OLA-style assessment focused on opti
 - Include current host hardware/core evidence when available, because current Oracle environments are often licensed by CPU core.
 - If compute, host hardware, or hosting evidence is missing, say the Oracle licensing conclusion is partial.
 - If entitlement evidence is missing, say the Oracle licensing conclusion is partial.
-- State the selected OpsCompass environment and company scope with evidence provenance. Do not present another environment's results or defaults as evidence for the selected scope.
-- Distinguish executed evidence collection from command previews (`execute: false`). Report retrieval failures and their actual causes as evidence gaps, not automatically as expired login.
-- Base entitlement comparisons on explicit user-provided or user-authorized records. Keep usage signals separate from purchased rights; bundled fixtures and fake entitlement API output are illustrative only and must not support customer findings.
+- Record the selected Opscompass CLI identity, company/account scope, returned local `assessmentId`, assessment name, and source/as-of date when present. Keep retrieval time distinct from the assessment's as-of date and state when freshness is unknown.
+- Identify the report as based on the latest persisted periodic assessment, not a recalculation or live-current entitlements. Do not substitute `get-oracle-current-entitlements`.
+- Retrieve all pages of `entitlements`, `summary`, `license-usage-summary`, and `deployment-details`; after the first response, use its local `assessmentId` for every section/page, even if selection began with `mlssAssessmentId`.
+- Continue pagination by the returned `pagination.limit` until the section array is shorter than the limit; request an empty final page when the preceding page is exactly full.
+- Preserve the complete page metadata, entitlement `entitlementDetails`, and provenance. Usage/compliance evidence does not establish purchased rights.
+- Base entitlement comparisons on explicit user-provided or user-authorized records, and name missing customer evidence rather than treating saved assessment output as proof of entitlement.
+- Save the final user-facing report under `Documents/` with the existing Documents write tool; claim it is saved only after the write succeeds.
 
 ## Recommended Finding Format
 

package/skills/opscompass-oracle-licensing/scripts/oracle-assessment.js

@@ -0,0 +1,284 @@
+import { isMainModule } from "../.opscompass-runtime/tools/cli-entrypoint.js";
+import { resolveCliContext } from "../.opscompass-runtime/tools/opsc-cli-context.js";
+import { runCli } from "../.opscompass-runtime/tools/opsc-cli.js";
+export const ASSESSMENT_SECTIONS = [
+    "entitlements",
+    "summary",
+    "license-usage-summary",
+    "deployment-details",
+];
+const SECTION_FIELDS = {
+    entitlements: "assessmentEntitlements",
+    summary: "assessmentSummary",
+    "license-usage-summary": "licenseUsageSummary",
+    "deployment-details": "deploymentDetails",
+};
+const SECTION_FIELD_NAMES = Object.values(SECTION_FIELDS);
+const ASSESSMENT_METADATA = [
+    "assessmentId",
+    "assessmentName",
+    "currencyCode",
+    "expectedDiscount",
+    "deployMapId",
+    "entReviewId",
+];
+const PRODUCT_FIELDS = ["masterProductId", "productString", "licenseMetric", "licenseLevel", "limitation"];
+// WHY: A successful CLI exit is not proof that quantities or nested licensing evidence were returned completely.
+const ROW_FIELDS = {
+    entitlements: [...PRODUCT_FIELDS, "entReviewProductId", "entitlementId", "quantity", "notes", "entitlementDetails"],
+    summary: [...PRODUCT_FIELDS, "assessmentProductId", "deployedQuantity", "entitledQuantity", "availableQuantity", "lineListPrice", "lineDiscountPrice", "lineTotalPrice", "comments"],
+    "license-usage-summary": [...PRODUCT_FIELDS, "deployMapProductId", "quantity", "comments", "deployMapProductDetails"],
+    "deployment-details": ["deployMapId", "deploymentInstanceId", "physicalMachineName", "virtualMachineName", "instanceName", "productEdition", "productVersion", "dbCreationDate", "deploymentDetails"],
+};
+const NESTED_DETAILS = {
+    entitlements: { field: "entitlementDetails", fields: ["orderNumber", "csi", "supportRenewalNumber", "quantity", "supportStartDate", "supportExpirationDate", "supportPrice", "currencyCode", "comments"] },
+    "license-usage-summary": { field: "deployMapProductDetails", fields: ["datacenterName", "clusterName", "physicalMachineId", "physicalMachineName", "totalSocketsInUse", "totalCoresInUse", "coreFactor", "minQuantity", "quantity"] },
+    "deployment-details": { field: "deploymentDetails", fields: ["masterProductId", "productString", "featureId", "featureString", "detectedUsages", "firstUsageDate", "lastUsageDate", "isExcluded", "notes"] },
+};
+function requireFields(value, fields) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Oracle assessment contains an invalid evidence record.");
+    for (const field of fields) {
+        if (!Object.hasOwn(value, field))
+            throw new Error(`Oracle assessment evidence is missing ${field}.`);
+    }
+}
+const INPUT_FIELDS = {
+    section: true,
+    company: true,
+    account: true,
+    assessmentId: true,
+    mlssAssessmentId: true,
+    limit: true,
+    offset: true,
+};
+function optionalString(input, name) {
+    if (!Object.hasOwn(input, name))
+        return undefined;
+    const value = input[name];
+    if (typeof value !== "string" ||
+        value.trim() === "" ||
+        /^\s*--/.test(value) ||
+        value.includes("\0")) {
+        throw new Error(`${name} must be a non-empty string value.`);
+    }
+    return value;
+}
+function optionalPositiveInteger(input, name) {
+    if (!Object.hasOwn(input, name))
+        return undefined;
+    const value = input[name];
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1)
+        throw new Error(`${name} must be a positive safe integer.`);
+    return value;
+}
+export function parseAssessmentInput(input) {
+    if (input === null || typeof input !== "object" || Array.isArray(input))
+        throw new Error("Assessment input must be an object.");
+    const values = input;
+    for (const key of Object.keys(values)) {
+        if (!Object.hasOwn(INPUT_FIELDS, key))
+            throw new Error(`Unknown assessment input: ${key}.`);
+    }
+    if (!Object.hasOwn(values, "section"))
+        throw new Error("section is required.");
+    if (typeof values.section !== "string" ||
+        !ASSESSMENT_SECTIONS.includes(values.section)) {
+        throw new Error(`section must be one of: ${ASSESSMENT_SECTIONS.join(", ")}.`);
+    }
+    const company = optionalString(values, "company");
+    const account = optionalString(values, "account");
+    const assessmentId = optionalPositiveInteger(values, "assessmentId");
+    const mlssAssessmentId = optionalPositiveInteger(values, "mlssAssessmentId");
+    if (assessmentId !== undefined && mlssAssessmentId !== undefined)
+        throw new Error("assessmentId and mlssAssessmentId are mutually exclusive.");
+    const limit = Object.hasOwn(values, "limit") ? values.limit : 100;
+    if (typeof limit !== "number" ||
+        !Number.isSafeInteger(limit) ||
+        limit < 1 ||
+        limit > 500) {
+        throw new Error("limit must be an integer from 1 through 500.");
+    }
+    const offset = Object.hasOwn(values, "offset") ? values.offset : 0;
+    if (typeof offset !== "number" ||
+        !Number.isSafeInteger(offset) ||
+        offset < 0) {
+        throw new Error("offset must be a nonnegative safe integer.");
+    }
+    return {
+        section: values.section,
+        ...(company === undefined ? {} : { company }),
+        ...(account === undefined ? {} : { account }),
+        ...(assessmentId === undefined ? {} : { assessmentId }),
+        ...(mlssAssessmentId === undefined ? {} : { mlssAssessmentId }),
+        limit,
+        offset,
+    };
+}
+function buildCommand(request) {
+    const args = [
+        "license-manager",
+        `get-oracle-assessment-${request.section}`,
+    ];
+    for (const [name, value] of [
+        ["company", request.company],
+        ["account", request.account],
+        ["assessment-id", request.assessmentId],
+        ["mlss-assessment-id", request.mlssAssessmentId],
+        ["limit", request.limit],
+        ["offset", request.offset],
+    ]) {
+        if (value !== undefined)
+            args.push(`--${name}`, String(value));
+    }
+    return args;
+}
+function validatePage(text, request) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error("Oracle assessment CLI returned invalid or truncated JSON.");
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error("Oracle assessment CLI returned an incomplete assessment page.");
+    const page = parsed;
+    if (Object.hasOwn(page, "error") || page.success === false)
+        throw new Error("Oracle assessment CLI returned an error response.");
+    for (const field of ASSESSMENT_METADATA) {
+        if (!Object.hasOwn(page, field))
+            throw new Error(`Oracle assessment page is missing ${field}.`);
+    }
+    if (typeof page.assessmentId !== "number" ||
+        !Number.isSafeInteger(page.assessmentId) ||
+        page.assessmentId < 1) {
+        throw new Error("Oracle assessment page has an invalid local assessmentId.");
+    }
+    if (request.assessmentId !== undefined &&
+        page.assessmentId !== request.assessmentId) {
+        throw new Error("Oracle assessment CLI returned a different assessmentId.");
+    }
+    if (typeof page.assessmentName !== "string")
+        throw new Error("Oracle assessment page has an invalid assessmentName.");
+    const sectionField = SECTION_FIELDS[request.section];
+    for (const field of SECTION_FIELD_NAMES) {
+        if (field !== sectionField && Object.hasOwn(page, field))
+            throw new Error(`Oracle assessment CLI returned the wrong section instead of ${sectionField}.`);
+    }
+    const rows = page[sectionField];
+    if (!Array.isArray(rows) || rows.length > request.limit)
+        throw new Error(`Oracle assessment page has an invalid ${sectionField} array.`);
+    if (request.section === "entitlements" &&
+        typeof page.entReviewName !== "string") {
+        throw new Error("Oracle assessment entitlement page is missing entReviewName.");
+    }
+    if ((request.section === "license-usage-summary" || request.section === "deployment-details") && typeof page.deployMapName !== "string")
+        throw new Error("Oracle assessment page is missing deployMapName.");
+    const nested = NESTED_DETAILS[request.section];
+    for (const row of rows) {
+        requireFields(row, ROW_FIELDS[request.section]);
+        if (nested) {
+            const details = row[nested.field];
+            if (!Array.isArray(details))
+                throw new Error(`Oracle assessment evidence has invalid ${nested.field}.`);
+            for (const detail of details)
+                requireFields(detail, nested.fields);
+        }
+    }
+    if (page.pagination === null ||
+        typeof page.pagination !== "object" ||
+        Array.isArray(page.pagination)) {
+        throw new Error("Oracle assessment page is missing pagination metadata.");
+    }
+    const pagination = page.pagination;
+    if (pagination.limit !== request.limit ||
+        pagination.offset !== request.offset) {
+        throw new Error("Oracle assessment page pagination does not match the request.");
+    }
+}
+export async function readAssessmentPage(request, context) {
+    const output = await runCli(context, buildCommand(request));
+    validatePage(output, request);
+    return output;
+}
+function parseCliInteger(value, name) {
+    if (!/^\d+$/.test(value))
+        throw new Error(`${name} must be an integer.`);
+    const number = Number(value);
+    if (!Number.isSafeInteger(number))
+        throw new Error(`${name} must be a safe integer.`);
+    return number;
+}
+function parseCliArgs(argv) {
+    const input = {};
+    const seen = new Set();
+    let section;
+    let cliCommand;
+    const flags = {
+        "--company": "company",
+        "--account": "account",
+        "--assessment-id": "assessmentId",
+        "--mlss-assessment-id": "mlssAssessmentId",
+        "--limit": "limit",
+        "--offset": "offset",
+        "--cli": "cli",
+    };
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        if (arg.startsWith("--")) {
+            const key = Object.hasOwn(flags, arg) ? flags[arg] : undefined;
+            if (key === undefined)
+                throw new Error(`Unknown option: ${arg}.`);
+            if (seen.has(arg))
+                throw new Error(`Option ${arg} may be specified only once.`);
+            seen.add(arg);
+            const value = argv[++index];
+            if (value === undefined || value.startsWith("--"))
+                throw new Error(`Option ${arg} requires a value.`);
+            if (key === "cli")
+                cliCommand = value;
+            else if (key === "assessmentId" ||
+                key === "mlssAssessmentId" ||
+                key === "limit" ||
+                key === "offset") {
+                input[key] = parseCliInteger(value, arg);
+            }
+            else
+                input[key] = value;
+        }
+        else if (section === undefined)
+            section = arg;
+        else
+            throw new Error(`Unexpected argument: ${arg}.`);
+    }
+    if (section === undefined)
+        throw new Error("An assessment section is required.");
+    input.section = section;
+    return {
+        request: parseAssessmentInput(input),
+        ...(cliCommand === undefined ? {} : { cliCommand }),
+    };
+}
+export async function main(argv = process.argv.slice(2)) {
+    if (argv.length === 1 && argv[0] === "--help") {
+        process.stdout.write("Usage: oracle-assessment.js <section> [--company <name>] [--account <value>] [--assessment-id <id> | --mlss-assessment-id <id>] [--limit <1-500>] [--offset <n>] [--cli opscompass|opscompassdev|opscompassdemo]\n");
+        return 0;
+    }
+    try {
+        const { request, cliCommand } = parseCliArgs(argv);
+        const context = {
+            ...resolveCliContext(cliCommand),
+            workspaceRoot: process.cwd(),
+            signal: new AbortController().signal,
+        };
+        process.stdout.write(await readAssessmentPage(request, context));
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+if (isMainModule(import.meta.url))
+    process.exitCode = await main();

package/skills/opscompass-oracle-licensing/scripts/oracle-assessment.tool.js

@@ -0,0 +1,32 @@
+import { ASSESSMENT_SECTIONS, parseAssessmentInput, readAssessmentPage, } from "./oracle-assessment.js";
+export const oracleAssessmentTool = {
+    name: "opscompass_oracle_licensing_assessment",
+    label: "Oracle licensing assessment evidence",
+    description: "Read one page from a persisted Opscompass Oracle license assessment section.",
+    promptSnippet: "Fetch persisted Opscompass Oracle licensing assessment evidence",
+    promptGuidelines: [
+        "This reads the latest persisted periodic assessment; it does not recalculate an assessment or return live current entitlements.",
+        "Fetch every page for all four sections. After the first response, pin its local assessmentId for all pages and sections, including when the first selector was mlssAssessmentId.",
+        "Advance offset by pagination.limit until the returned section array is shorter than the limit; request an empty page when the last page is exactly full.",
+        "Preserve the returned assessment metadata, nested entitlementDetails, and provenance; usage signals do not establish purchased rights.",
+    ],
+    parameters: {
+        type: "object",
+        properties: {
+            section: { type: "string", enum: [...ASSESSMENT_SECTIONS] },
+            company: { type: "string" },
+            account: { type: "string" },
+            assessmentId: { type: "integer", minimum: 1 },
+            mlssAssessmentId: { type: "integer", minimum: 1 },
+            limit: { type: "integer", minimum: 1, maximum: 500 },
+            offset: { type: "integer", minimum: 0 },
+        },
+        required: ["section"],
+        additionalProperties: false,
+    },
+    async execute(input, context) {
+        const request = parseAssessmentInput(input);
+        const output = await readAssessmentPage(request, context);
+        return { content: [{ type: "text", text: output }] };
+    },
+};

package/skills/opscompass-oracle-licensing/scripts/tools.js

@@ -1,2 +1,3 @@
-import { fakeEntitlementsApiTool } from "./fake-entitlements-api.tool.js";
-export const tools = [fakeEntitlementsApiTool];
+import { oracleAssessmentTool } from "./oracle-assessment.tool.js";
+export const supportsCliInvocation = true;
+export const tools = [oracleAssessmentTool];

package/skills/opscompass-resources/.opscompass-runtime/tools/opsc-cli-context.js

@@ -22,3 +22,13 @@ export function resolveCliContext(cliCommand) {
         opscompassHome: path.join(os.homedir(), `.${selectedCommand}`),
     };
 }
+export function resolveCliInvocation(context, args) {
+    return {
+        executable: context.cliInvocation?.executable ?? context.cliEntryPoint,
+        args: [...(context.cliInvocation?.args ?? []), ...args],
+        env: {
+            ...(context.cliInvocation?.env ?? process.env),
+            OPSCOMPASS_CLI_ENTRYPOINT: context.cliEntryPoint,
+        },
+    };
+}