@opscompass/skills 0.1.0

package/skills/opscompass-oracle-licensing/api/entitlement-usage/entitlement-usage.json

@@ -0,0 +1,114 @@
+[
+  {
+    "Product": "Oracle Active Data Guard",
+    "Metric": "Processor",
+    "Limitation": "Full Use",
+    "Limited To": "",
+    "Usage": 16
+  },
+  {
+    "Product": "Oracle Advanced Compression",
+    "Metric": "Processor",
+    "Limitation": "Full Use",
+    "Limited To": "",
+    "Usage": 16
+  },
+  {
+    "Product": "Oracle Advanced Security",
+    "Metric": "Named User Plus",
+    "Limitation": "Limited Use Other",
+    "Limited To": "Test / Dev",
+    "Usage": 400
+  },
+  {
+    "Product": "Oracle Advanced Security",
+    "Metric": "Processor",
+    "Limitation": "Full Use",
+    "Limited To": "",
+    "Usage": 32
+  },
+  {
+    "Product": "Oracle Database Enterprise Edition",
+    "Metric": "Processor",
+    "Limitation": "Full Use",
+    "Limited To": "",
+    "Usage": 32
+  },
+  {
+    "Product": "Oracle Database Enterprise Edition",
+    "Metric": "Named User Plus",
+    "Limitation": "Limited Use Other",
+    "Limited To": "Test / Dev",
+    "Usage": 400
+  },
+  {
+    "Product": "Oracle Database Vault",
+    "Metric": "Named User Plus",
+    "Limitation": "Limited Use Other",
+    "Limited To": "Test / Dev",
+    "Usage": 400
+  },
+  {
+    "Product": "Oracle Database Vault",
+    "Metric": "Processor",
+    "Limitation": "Full Use",
+    "Limited To": "",
+    "Usage": 32
+  },
+  {
+    "Product": "Oracle Diagnostics Pack",
+    "Metric": "Processor",
+    "Limitation": "Full Use",
+    "Limited To": "",
+    "Usage": 16
+  },
+  {
+    "Product": "Oracle Diagnostics Pack",
+    "Metric": "Named User Plus",
+    "Limitation": "Limited Use Other",
+    "Limited To": "Test / Dev",
+    "Usage": 400
+  },
+  {
+    "Product": "Oracle GoldenGate",
+    "Metric": "Processor",
+    "Limitation": "Full Use",
+    "Limited To": "",
+    "Usage": 16
+  },
+  {
+    "Product": "Oracle GoldenGate",
+    "Metric": "Named User Plus",
+    "Limitation": "Limited Use Other",
+    "Limited To": "Test / Dev",
+    "Usage": 400
+  },
+  {
+    "Product": "Oracle Partitioning",
+    "Metric": "Processor",
+    "Limitation": "Full Use",
+    "Limited To": "",
+    "Usage": 16
+  },
+  {
+    "Product": "Oracle Partitioning",
+    "Metric": "Named User Plus",
+    "Limitation": "Limited Use Other",
+    "Limited To": "Test / Dev",
+    "Usage": 400
+  },
+  {
+    "Product": "Oracle Real Application Clusters",
+    "Metric": "Processor",
+    "Limitation": "Full Use",
+    "Limited To": "",
+    "Usage": 32
+  },
+  {
+    "Product": "Oracle Real Application Clusters",
+    "Metric": "Named User Plus",
+    "Limitation": "Limited Use Other",
+    "Limited To": "Test / Dev",
+    "Usage": 400
+  }
+]

package/skills/opscompass-oracle-licensing/assets/mock-entitlements/deployment-details.json

@@ -0,0 +1,61 @@
+{
+  "organization": "OpsCompass Demo",
+  "assessmentScope": "oracle-licensing",
+  "generatedAt": "2026-04-23T00:00:00Z",
+  "deployments": [
+    {
+      "deploymentId": "prod-microchip",
+      "environment": "prod",
+      "platform": "nutanix",
+      "databaseName": "REPP1",
+      "databaseHostname": "NTX-MICROCHIPPROD-LX02",
+      "oracleVersion": "19.0.0.0.0",
+      "oracleEdition": "Enterprise Edition",
+      "vmName": "ntx-microchipprod-lx02",
+      "clusterName": "ntx1-prod-dc1",
+      "hostName": "ntx1-host08-dc1",
+      "provisionedVcpu": 8,
+      "estimatedLicensableCores": 8,
+      "notes": [
+        "Production Oracle workload",
+        "Mapped through Nutanix VM latest configuration"
+      ]
+    },
+    {
+      "deploymentId": "prod-sensor",
+      "environment": "prod",
+      "platform": "nutanix",
+      "databaseName": "REPP2",
+      "databaseHostname": "NTX-SENSORPROD-LX02",
+      "oracleVersion": "19.0.0.0.0",
+      "oracleEdition": "Enterprise Edition",
+      "vmName": "ntx-sensorprod-lx02",
+      "clusterName": "ntx3-prod-dc3",
+      "hostName": "ntx3-host03-dc3",
+      "provisionedVcpu": 16,
+      "estimatedLicensableCores": 16,
+      "notes": [
+        "Production Oracle workload",
+        "Higher CPU footprint than standard 8-vCPU pattern"
+      ]
+    },
+    {
+      "deploymentId": "dev-bandwidth",
+      "environment": "dev",
+      "platform": "nutanix",
+      "databaseName": "RMANCP1",
+      "databaseHostname": "NTX-BANDWIDTHDEV-LX01",
+      "oracleVersion": "19.0.0.0.0",
+      "oracleEdition": "Enterprise Edition",
+      "vmName": "ntx-bandwidthdev-lx01",
+      "clusterName": "ntx2-dev-dc1",
+      "hostName": "ntx2-host02-dc1",
+      "provisionedVcpu": 4,
+      "estimatedLicensableCores": 4,
+      "notes": [
+        "Development Oracle workload",
+        "Candidate for lower licensing priority"
+      ]
+    }
+  ]
+}

package/skills/opscompass-oracle-licensing/assets/mock-entitlements/license-usage-map.json

@@ -0,0 +1,70 @@
+{
+  "organization": "OpsCompass Demo",
+  "assessmentScope": "oracle-licensing",
+  "generatedAt": "2026-04-23T00:00:00Z",
+  "entitlements": [
+    {
+      "licensePoolId": "ee-processor-pool",
+      "licenseMetric": "processor",
+      "licenseType": "Oracle Database Enterprise Edition",
+      "entitledQuantity": 24,
+      "allocatedQuantity": 20,
+      "unallocatedQuantity": 4,
+      "limitedUse": false
+    },
+    {
+      "licensePoolId": "diag-tuning-pack-pool",
+      "licenseMetric": "processor",
+      "licenseType": "Diagnostics Pack + Tuning Pack",
+      "entitledQuantity": 8,
+      "allocatedQuantity": 16,
+      "unallocatedQuantity": -8,
+      "limitedUse": false
+    }
+  ],
+  "usageMap": [
+    {
+      "deploymentId": "prod-microchip",
+      "databaseName": "REPP1",
+      "assignedLicensePoolIds": [
+        "ee-processor-pool",
+        "diag-tuning-pack-pool"
+      ],
+      "consumedQuantity": {
+        "Oracle Database Enterprise Edition": 8,
+        "Diagnostics Pack + Tuning Pack": 8
+      },
+      "featureSignals": [
+        "CONTROL_MANAGEMENT_PACK_ACCESS=DIAGNOSTIC+TUNING"
+      ]
+    },
+    {
+      "deploymentId": "prod-sensor",
+      "databaseName": "REPP2",
+      "assignedLicensePoolIds": [
+        "ee-processor-pool",
+        "diag-tuning-pack-pool"
+      ],
+      "consumedQuantity": {
+        "Oracle Database Enterprise Edition": 16,
+        "Diagnostics Pack + Tuning Pack": 16
+      },
+      "featureSignals": [
+        "CONTROL_MANAGEMENT_PACK_ACCESS=DIAGNOSTIC+TUNING"
+      ]
+    },
+    {
+      "deploymentId": "dev-bandwidth",
+      "databaseName": "RMANCP1",
+      "assignedLicensePoolIds": [
+        "ee-processor-pool"
+      ],
+      "consumedQuantity": {
+        "Oracle Database Enterprise Edition": 4
+      },
+      "featureSignals": [
+        "CONTROL_MANAGEMENT_PACK_ACCESS=NONE"
+      ]
+    }
+  ]
+}

package/skills/opscompass-oracle-licensing/assets/mock-entitlements/overall-compliance.json

@@ -0,0 +1,36 @@
+{
+  "organization": "OpsCompass Demo",
+  "assessmentScope": "oracle-licensing",
+  "generatedAt": "2026-04-23T00:00:00Z",
+  "summary": {
+    "overallStatus": "non-compliant",
+    "deploymentsReviewed": 3,
+    "deploymentsCompliant": 1,
+    "deploymentsWithFindings": 2,
+    "licenseDeficiencyCount": 2,
+    "limitedUseIssues": 0
+  },
+  "findings": [
+    {
+      "deploymentId": "prod-microchip",
+      "databaseName": "REPP1",
+      "severity": "medium",
+      "findingType": "management-pack-overconsumption",
+      "message": "Diagnostics Pack + Tuning Pack usage is assigned, but the shared pool is oversubscribed.",
+      "recommendedAction": "Reconcile management pack entitlement assignments or reduce pack usage."
+    },
+    {
+      "deploymentId": "prod-sensor",
+      "databaseName": "REPP2",
+      "severity": "high",
+      "findingType": "processor-license-deficiency",
+      "message": "Current processor consumption exceeds the remaining available Enterprise Edition entitlement.",
+      "recommendedAction": "Add processor entitlements, reallocate underused licenses, or reduce deployment CPU footprint."
+    }
+  ],
+  "recommendations": [
+    "Prioritize REPP2 for remediation because it combines the largest CPU footprint with pack usage.",
+    "Review whether development environments require Enterprise Edition or can be right-sized.",
+    "Use the current deployment map when modeling the AWS target-state license plan."
+  ]
+}

package/skills/opscompass-oracle-licensing/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

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

@@ -0,0 +1,90 @@
+# Oracle Licensing Evidence Model
+
+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.
+
+## Workload Identity
+
+For each Oracle workload, try to establish:
+- database name
+- hostname
+- Oracle version
+- Oracle edition
+- environment or business context if available
+
+## Compliance And Usage Evidence
+
+Collect:
+- Oracle compliance findings
+- used features, options, packs, or other license-relevant settings
+- concerning configuration values tied to license exposure
+- RAC usage or cluster/RAC indicators that affect AWS edition recommendations
+- Partitioning usage indicators that require Enterprise Edition and affect AWS edition recommendations
+
+Treat Oracle compliance findings as Oracle license-relevant evidence unless the user clearly frames the request differently.
+
+For Oracle latest-configuration evidence, inspect:
+- `document.productUsageConcerns`
+- `document.parameters` entries where `isConcerning` is `true`
+
+Non-empty `productUsageConcerns` is per-database product/feature usage concern evidence. Concerning parameters are license-relevant evidence; for example, `CONTROL_MANAGEMENT_PACK_ACCESS=DIAGNOSTIC+TUNING` indicates Diagnostic Pack and Tuning Pack exposure.
+
+Do not conclude that per-database Oracle feature usage is unavailable until both `get-compliance --status open` and `get-latest-configuration` have been checked for that database.
+
+## Hosting And Compute Evidence
+
+Try to establish:
+- hosting platform
+- VM or managed-service context
+- host and cluster context where applicable
+- latest hardware configuration of hosts currently supporting Oracle workloads
+- current core or vCPU-related evidence
+- signals that compute exposure may affect licensing
+
+For VMware and Nutanix, latest-configuration is the primary infrastructure evidence source. For OLA work, use the OpsCompass resources workflow to fetch latest configuration for the VM and host resources supporting Oracle workloads, then use the host hardware configuration as current-state licensing evidence.
+
+Current Oracle environments are often licensed by CPU core. If host hardware configuration or core evidence cannot be established for workloads on infrastructure platforms, the assessment must treat the licensing conclusion as partial.
+
+## Entitlement Evidence
+
+Try to establish:
+- available licenses or entitlements
+- Limited Use restrictions
+- assigned versus unassigned entitlement position
+- known limitations or ambiguities in entitlement records
+
+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.
+
+## AWS Target-State Evidence
+
+When AWS Oracle planning is in scope, try to establish:
+- whether Amazon RDS for Oracle, Oracle on Amazon EC2, or both are in scope
+- whether the user explicitly excluded RDS or EC2
+- planned RDS deployment shape and sizing assumptions when RDS is in scope
+- planned EC2 deployment shape, tenancy, and sizing assumptions when EC2 is in scope
+- whether EC2 Dedicated Hosts are a licensing-relevant candidate
+- target-state vCPU/core assumptions where available
+- licensing-relevant RDS and/or EC2 architecture assumptions
+- which AWS choices appear most license-efficient from the available evidence
+- how current host/core exposure compares to the proposed AWS target assumptions
+- which RDS shapes, EC2 shapes, tenancy choices, and architecture choices best align to the current entitlement position, observed Oracle usage, and current host/core exposure
+- whether memory-optimized AWS families such as R Series, X1, or Z1 are appropriate candidates
+- whether RAC usage blocks a Standard Edition recommendation
+- whether RAC usage blocks an RDS recommendation unless RAC removal or HA redesign is part of the target-state assumption
+- whether RAC retention requires an EC2 target-state recommendation
+- whether Partitioning usage blocks a Standard Edition recommendation
+
+Evaluate RDS and EC2 by default unless the user explicitly scopes the assessment to one target or excludes one target. For EC2, treat Dedicated Hosts as a licensing-relevant option that can be favorable but must be validated against entitlement terms, current and target core exposure, consolidation, HA/DR, operations, and cost.
+Do not recommend Oracle Standard Edition when RAC usage is present unless the assessment explicitly assumes RAC removal.
+Do not recommend Amazon RDS for Oracle for workloads that must retain RAC. Oracle RAC is not supported on RDS; RAC workloads must either move off RAC for RDS or target EC2 to retain RAC.
+Do not recommend Oracle Standard Edition when Partitioning usage is present unless the assessment explicitly assumes Partitioning removal. Oracle Partitioning requires Enterprise Edition.
+
+## Confidence Rules
+
+For each conclusion, distinguish:
+- directly established evidence
+- strong inference
+- partial conclusion because key evidence is missing

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

@@ -0,0 +1,54 @@
+# Oracle Licensing Report Structure
+
+Use this file when the user wants a written OLA-style assessment focused on optimizing Oracle licensing for AWS.
+
+## Preferred Report Order
+
+1. Assessment summary
+2. Key findings
+3. Oracle workloads in scope
+4. Hosting and compute context
+5. Entitlement comparison
+6. Current-state deficiencies or risks
+7. AWS target-state findings, if applicable
+8. AWS optimization recommendations
+9. Evidence gaps and assumptions
+
+## Content Rules
+
+- Lead with licensing risk, not raw inventory.
+- Clearly separate observed facts from recommendations.
+- Clearly separate current-state findings from AWS target-state planning conclusions.
+- Surface Limited Use constraints explicitly.
+- Treat Oracle compliance findings and latest-configuration feature signals as license evidence. Include `document.productUsageConcerns` and concerning `document.parameters` when they support a finding.
+- Keep the recommendations focused on optimizing for AWS, not just explaining current-state licensing.
+- Evaluate both Amazon RDS for Oracle and Oracle on Amazon EC2 by default unless the user explicitly excludes one.
+- Include the recommended RDS shapes, EC2 shapes, tenancy choices, sizing posture, and architecture assumptions when the evidence supports them.
+- Tie AWS recommendations back to current entitlement position, observed Oracle usage, and current host/core exposure.
+- Prefer memory-optimized AWS shape candidates for Oracle when supported by the evidence. R Series, X1, and Z1 are common Oracle-friendly candidates.
+- Include EC2 Dedicated Hosts as a licensing-relevant option when EC2 is in scope, but state that Dedicated Hosts are not automatically optimal and must be validated.
+- Do not recommend Oracle Standard Edition when RAC usage is present; RAC is not included in Oracle SE.
+- Do not recommend Amazon RDS for Oracle for workloads that must retain RAC. Oracle RAC is not supported on RDS; RAC workloads must either move off RAC for RDS or target EC2 to retain RAC.
+- Do not recommend Oracle Standard Edition when Partitioning usage is present; Oracle Partitioning requires Enterprise Edition.
+- If the user scopes the assessment to RDS only, EC2 only, or excludes one option, state that scope explicitly and do not analyze the excluded option.
+- 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.
+
+## Recommended Finding Format
+
+For each major finding, try to state:
+- the risk or deficiency
+- the affected workload or scope
+- the Oracle feature, option, pack, product usage concern, or concerning parameter involved
+- the hosting platform and compute context
+- the host hardware/core evidence when available
+- the recommended RDS or EC2 shape, tenancy, or architecture implication
+- whether EC2 Dedicated Hosts are relevant to the recommendation
+- any RAC, RDS feasibility, EC2 requirement, Partitioning, or edition constraint affecting the recommendation
+- the evidence supporting the conclusion
+- the confidence level
+- the recommended next step

package/skills/opscompass-oracle-licensing/scripts/fake-entitlements-api.tool.js

@@ -0,0 +1,31 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const API_ROOT = path.resolve(fileURLToPath(new URL("../api", import.meta.url)));
+const PAYLOAD_FILES = {
+    "deployment-details": path.join(API_ROOT, "entitlement-deployment", "entitlement-deployment"),
+    "license-usage-map": path.join(API_ROOT, "entitlement-usage", "entitlement-usage.json"),
+    "overall-compliance": path.join(API_ROOT, "entitlement-compliance", "entitlement-compliance.json"),
+};
+export const fakeEntitlementsApiTool = {
+    name: "opscompass_oracle_licensing_fake_entitlements",
+    label: "read entitlement fixture",
+    description: "Read one of the checked-in Oracle entitlement API fixtures.",
+    parameters: {
+        type: "object",
+        properties: {
+            payload: { type: "string", enum: Object.keys(PAYLOAD_FILES) },
+            showPath: { type: "boolean" },
+        },
+        required: ["payload"],
+        additionalProperties: false,
+    },
+    async execute(input) {
+        const value = input;
+        if (!value?.payload || !Object.hasOwn(PAYLOAD_FILES, value.payload))
+            throw new Error("invalid entitlement payload");
+        const file = PAYLOAD_FILES[value.payload];
+        const text = await readFile(file, "utf8");
+        return { content: [{ type: "text", text: value.showPath ? `[entitlements] ${file}\n${text}` : text }] };
+    },
+};

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

@@ -0,0 +1,72 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isMainModule } from "../.opscompass-runtime/tools/cli-entrypoint.js";
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const API_ROOT = path.join(ROOT, "api");
+export const PAYLOAD_FILES = {
+    "deployment-details": path.join(API_ROOT, "entitlement-deployment", "entitlement-deployment"),
+    "license-usage-map": path.join(API_ROOT, "entitlement-usage", "entitlement-usage.json"),
+    "overall-compliance": path.join(API_ROOT, "entitlement-compliance", "entitlement-compliance.json"),
+};
+function isPayloadName(value) {
+    return typeof value === "string" && Object.hasOwn(PAYLOAD_FILES, value);
+}
+function parseArgs(argv) {
+    if (!argv.length) {
+        throw new Error("the following arguments are required: payload");
+    }
+    const payload = argv[0];
+    let showPath = false;
+    for (const flag of argv.slice(1)) {
+        if (flag === "--show-path") {
+            showPath = true;
+        }
+        else {
+            throw new Error(`unrecognized arguments: ${flag}`);
+        }
+    }
+    if (!isPayloadName(payload)) {
+        throw new Error(`invalid choice: '${payload}' (choose from deployment-details, license-usage-map, overall-compliance)`);
+    }
+    return { payload, showPath };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isMissingFileError(error) {
+    return error instanceof Error && error.code === "ENOENT";
+}
+export function main(argv = process.argv.slice(2)) {
+    try {
+        const args = parseArgs(argv);
+        const payloadPath = PAYLOAD_FILES[args.payload];
+        if (args.showPath) {
+            console.error(`[entitlements] ${args.payload} -> ${payloadPath}`);
+        }
+        let data;
+        try {
+            data = JSON.parse(readFileSync(payloadPath, "utf8"));
+        }
+        catch (error) {
+            if (isMissingFileError(error)) {
+                console.error(`Error: missing payload file: ${payloadPath}`);
+                return 2;
+            }
+            if (error instanceof SyntaxError) {
+                console.error(`Error: invalid JSON in ${payloadPath}: ${error.message}`);
+                return 2;
+            }
+            throw error;
+        }
+        console.log(JSON.stringify(data, null, 2));
+        return 0;
+    }
+    catch (error) {
+        console.error(`Error: ${errorMessage(error)}`);
+        return 2;
+    }
+}
+if (isMainModule(import.meta.url)) {
+    process.exitCode = main();
+}

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

@@ -0,0 +1,2 @@
+import { fakeEntitlementsApiTool } from "./fake-entitlements-api.tool.js";
+export const tools = [fakeEntitlementsApiTool];

package/skills/opscompass-resources/.opscompass-runtime/tools/cli-entrypoint.js

@@ -0,0 +1,15 @@
+import { realpathSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+export function isMainModule(moduleUrl) {
+    const entryPoint = process.argv[1];
+    if (!entryPoint)
+        return false;
+    try {
+        const entryPath = realpathSync.native(entryPoint);
+        return (entryPath === realpathSync.native(fileURLToPath(moduleUrl)) &&
+            statSync(entryPath).isFile());
+    }
+    catch {
+        return false;
+    }
+}

package/skills/opscompass-resources/.opscompass-runtime/tools/index.js

@@ -0,0 +1,2 @@
+export { resolveCliContext } from "./opsc-cli-context.js";
+export { buildSetDefaultsCommand, buildSetupCommand, commandText, DEFAULTS_PATH, getDefaultCompany, getDefaultsPath, KNOWN_DEFAULTS_PATHS, loadDefaults, resolveCompany, shellQuote, sortObject, } from "./opsc-cli-defaults.js";

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

@@ -0,0 +1,24 @@
+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}`),
+    };
+}