Tool Presets

Operator tool presets are pre-configured definitions for common DevOps and SRE tools. Each preset bundles the correct capability pair, scope ID, suggested commands, and typical use cases so you do not have to repeat that configuration across plugins.

Start from the operator fixtures in examples/fixtures/ rather than building preset usage from scratch. The operator-kubernetes-plugin.fixture.ts and operator-terraform-plugin.fixture.ts files show the full authoring pattern.

Available presets

Preset ID	Label	Suggested commands	Typical use cases
`docker-cli`	Docker CLI	`docker`, `docker compose`	Container dashboards, compose orchestration, image inspection
`kubectl`	kubectl	`kubectl`	Cluster dashboards, resource inspection, namespace operations
`helm`	Helm	`helm`	Release dashboards, chart upgrade flows, Helm diff workflows
`terraform`	Terraform	`terraform`	Plan review, apply orchestration, workspace management
`ansible`	Ansible	`ansible`, `ansible-playbook`	Playbook runners, inventory inspection, ops automation
`aws-cli`	AWS CLI	`aws`	Cloud inventory, operational runbooks, SSM/EKS workflows
`gcloud`	Google Cloud CLI	`gcloud`	GKE workflows, project inspection, operational tooling
`azure-cli`	Azure CLI	`az`	AKS workflows, resource group inspection, operational runbooks
`podman`	Podman	`podman`	Rootless container dashboards, image inspection, local runtime
`kustomize`	Kustomize	`kustomize`, `kubectl kustomize`	Manifest preview, overlay inspection, GitOps helpers
`gh`	GitHub CLI	`gh`	PR dashboards, workflow triage, repository automation
`git`	Git	`git`	Diff dashboards, status inspection, repository automation
`vault`	Vault	`vault`	Secret inspection, lease operations, auth troubleshooting
`nomad`	Nomad	`nomad`	Job dashboards, allocation inspection, cluster operations

OperatorToolPresetDefinition

Each preset is a fully typed OperatorToolPresetDefinition object:

type OperatorToolPresetDefinition = {
  id: OperatorToolPresetId;
  label: string;
  description: string;
  scopeId: string;
  capabilities: ["system.process.exec", ProcessScopeCapability];
  suggestedCommands: string[];
  typicalUseCases: string[];
};

The capabilities field always contains exactly two entries: the broad system.process.exec capability and the narrow system.process.scope.<scope-id> capability.

Getting a preset definition

getOperatorToolPreset(presetId) returns the full preset definition for a given ID:

import { getOperatorToolPreset } from "@anikitenko/fdo-sdk";

const preset = getOperatorToolPreset("kubectl");
// {
//   id: "kubectl",
//   label: "kubectl",
//   description: "Kubernetes cluster inspection and controlled mutation workflows...",
//   scopeId: "kubectl",
//   capabilities: ["system.process.exec", "system.process.scope.kubectl"],
//   suggestedCommands: ["kubectl"],
//   typicalUseCases: ["Cluster dashboards", "Resource inspection", "Namespace operations"],
// }

listOperatorToolPresets() returns all preset definitions sorted alphabetically by ID:

import { listOperatorToolPresets } from "@anikitenko/fdo-sdk";

const presets = listOperatorToolPresets();
// all 14 presets, sorted by id

Declaring capabilities

Use createOperatorToolCapabilityPreset(presetId) to get the capability array for use in declareCapabilities() or host configuration:

import {
  FDO_SDK,
  FDOInterface,
  PluginMetadata,
  createOperatorToolCapabilityPreset,
} from "@anikitenko/fdo-sdk";

export default class TerraformOperatorPlugin extends FDO_SDK implements FDOInterface {
  private readonly _metadata: PluginMetadata = {
    name: "Fixture: Terraform Operator",
    version: "1.0.0",
    author: "FDO SDK Team",
    description: "Reference fixture for Terraform-style operator plugins",
    icon: "predictive-analysis",
  };

  get metadata(): PluginMetadata {
    return this._metadata;
  }

  declareCapabilities() {
    return createOperatorToolCapabilityPreset("terraform");
    // ["system.process.exec", "system.process.scope.terraform"]
  }

  init(): void {
    this.info("Terraform operator initialized", {
      declaredCapabilities: this.declareCapabilities(),
    });
  }

  render(): string {
    return `<div>Terraform Operator</div>`;
  }
}

Running a command with a preset

requestOperatorTool(presetId, payload, options?) is the primary way to execute a command using a preset. It wires up the scope ID and correlation ID prefix automatically:

import { requestOperatorTool } from "@anikitenko/fdo-sdk";

const response = await requestOperatorTool("kubectl", {
  command: "/usr/local/bin/kubectl",
  args: ["get", "pods", "--all-namespaces", "-o", "json"],
  timeoutMs: 5000,
  dryRun: true,
  reason: "preview cluster workload inventory",
});

Payload fields

Field	Type	Required	Description
`command`	`string`	Yes	Absolute path to the executable
`args`	`string[]`	No	Command arguments
`cwd`	`string`	No	Absolute working directory path
`env`	`Record<string, string>`	No	Additional environment variables
`timeoutMs`	`number`	No	Execution timeout in milliseconds
`input`	`string`	No	Standard input for the process
`encoding`	`"utf8" \| "base64"`	No	Input/output encoding
`dryRun`	`boolean`	No	Validate without executing
`reason`	`string`	No	Human-readable reason for auditing

Building a request without sending it

createOperatorToolActionRequest(presetId, payload) builds a ProcessExecActionRequest without dispatching it. Use this when you need to inspect or log the request before sending, or to construct the request at plugin init time:

import {
  createOperatorToolActionRequest,
  requestPrivilegedAction,
  isPrivilegedActionSuccessResponse,
} from "@anikitenko/fdo-sdk";

const request = createOperatorToolActionRequest("terraform", {
  command: "/usr/local/bin/terraform",
  args: ["plan", "-input=false"],
  timeoutMs: 10000,
  dryRun: true,
  reason: "preview infrastructure plan",
});

// Inspect or log the request:
this.info("Built terraform plan request", { request });

// Then send it later:
const response = await requestPrivilegedAction(request, {
  correlationIdPrefix: "terraform",
});

if (isPrivilegedActionSuccessResponse(response)) {
  // handle success
}

Generic scoped execution for custom tools

For tools not in the curated preset list, use requestScopedProcessExec(scopeId, payload, options?):

import { requestScopedProcessExec } from "@anikitenko/fdo-sdk";

const response = await requestScopedProcessExec("internal-runner", {
  command: "/usr/local/bin/internal-runner",
  args: ["status"],
  timeoutMs: 3000,
  dryRun: true,
  reason: "preview internal runner status",
});

If you need to build the request without sending it, use createScopedProcessExecActionRequest(scopeId, payload):

import { createScopedProcessExecActionRequest } from "@anikitenko/fdo-sdk";

const request = createScopedProcessExecActionRequest("internal-runner", {
  command: "/usr/local/bin/internal-runner",
  args: ["status"],
  timeoutMs: 3000,
  dryRun: true,
});

For generic custom scopes, declare capabilities using createProcessCapabilityBundle(scopeId):

import { createProcessCapabilityBundle } from "@anikitenko/fdo-sdk";

const capabilities = createProcessCapabilityBundle("internal-runner");
// ["system.process.exec", "system.process.scope.internal-runner"]

Examples by tool

Docker
kubectl
Terraform
Custom tool

import {
  createOperatorToolCapabilityPreset,
  requestOperatorTool,
  isPrivilegedActionSuccessResponse,
  isPrivilegedActionErrorResponse,
} from "@anikitenko/fdo-sdk";

// Declare capabilities
declareCapabilities() {
  return createOperatorToolCapabilityPreset("docker-cli");
  // ["system.process.exec", "system.process.scope.docker-cli"]
}

// Run docker ps
async listContainers(): Promise<unknown> {
  return requestOperatorTool("docker-cli", {
    command: "/usr/local/bin/docker",
    args: ["ps", "--format", "json"],
    timeoutMs: 5000,
    dryRun: true,
    reason: "list running containers for dashboard",
  });
}

import {
  createOperatorToolCapabilityPreset,
  requestOperatorTool,
} from "@anikitenko/fdo-sdk";

// Declare capabilities
declareCapabilities() {
  return createOperatorToolCapabilityPreset("kubectl");
  // ["system.process.exec", "system.process.scope.kubectl"]
}

// List pods across all namespaces
async previewClusterObjects(): Promise<unknown> {
  return requestOperatorTool("kubectl", {
    command: "/usr/local/bin/kubectl",
    args: ["get", "pods", "--all-namespaces", "-o", "json"],
    timeoutMs: 5000,
    dryRun: true,
    reason: "preview cluster workload inventory",
  });
}

import {
  createOperatorToolCapabilityPreset,
  createOperatorToolActionRequest,
  requestOperatorTool,
} from "@anikitenko/fdo-sdk";

// Declare capabilities
declareCapabilities() {
  return createOperatorToolCapabilityPreset("terraform");
  // ["system.process.exec", "system.process.scope.terraform"]
}

// Build a plan request (without sending)
const request = createOperatorToolActionRequest("terraform", {
  command: "/usr/local/bin/terraform",
  args: ["plan", "-input=false"],
  timeoutMs: 10000,
  dryRun: true,
  reason: "preview infrastructure plan",
});

// Or send it directly
async previewPlan(): Promise<unknown> {
  return requestOperatorTool("terraform", {
    command: "/usr/local/bin/terraform",
    args: ["plan", "-input=false"],
    timeoutMs: 10000,
    dryRun: true,
    reason: "preview infrastructure plan",
  });
}

import {
  createProcessCapabilityBundle,
  createScopedProcessExecActionRequest,
  requestScopedProcessExec,
} from "@anikitenko/fdo-sdk";

private readonly scopeId = "internal-runner";

// Declare capabilities for a custom scope
declareCapabilities() {
  return createProcessCapabilityBundle(this.scopeId);
  // ["system.process.exec", "system.process.scope.internal-runner"]
}

// Execute a scoped command
async previewRunnerStatus(): Promise<unknown> {
  return requestScopedProcessExec(this.scopeId, {
    command: "/usr/local/bin/internal-runner",
    args: ["status"],
    timeoutMs: 3000,
    dryRun: true,
    reason: "preview internal runner status",
  });
}

Missing capability diagnostics

When a request fails because a capability is not granted, use parseMissingCapabilityError() to get a structured diagnostic instead of parsing the error message yourself:

import { parseMissingCapabilityError } from "@anikitenko/fdo-sdk";

try {
  await requestOperatorTool("kubectl", { /* ... */ });
} catch (error) {
  const diagnostic = parseMissingCapabilityError(error);
  if (diagnostic) {
    console.error("Missing capability:", diagnostic.capability);
    console.error("Category:", diagnostic.category);
    // "process" for system.process.exec
    // "process-scope" for system.process.scope.<id>
    console.error("Remediation:", diagnostic.remediation);
  }
}

This is especially useful for distinguishing a missing broad capability (system.process.exec) from a missing narrow scope capability (system.process.scope.kubectl), which require different remediation steps in the host configuration.

Get Started

Core Concepts

Building Plugins

UI Extensions

Operator Plugins

Available presets

OperatorToolPresetDefinition

Getting a preset definition

Declaring capabilities

Running a command with a preset

Payload fields

Building a request without sending it

Generic scoped execution for custom tools

Examples by tool

Missing capability diagnostics

Get Started

Core Concepts

Building Plugins

UI Extensions

Operator Plugins

​Available presets

​OperatorToolPresetDefinition

​Getting a preset definition

​Declaring capabilities

​Running a command with a preset

​Payload fields

​Building a request without sending it

​Generic scoped execution for custom tools

​Examples by tool

​Missing capability diagnostics

Available presets

OperatorToolPresetDefinition

Getting a preset definition

Declaring capabilities

Running a command with a preset

Payload fields

Building a request without sending it

Generic scoped execution for custom tools

Examples by tool

Missing capability diagnostics