@kansodata/kansodata-glue-plugin

OpenClaw plugin runtime + companion skill for AWS Glue operations with controlled V1 write scope and ETL diagnostics focused on Glue Catalog partition behavior.

V1 Scope

Included

• Controlled writes:
  • glue_create_workflow
  • glue_update_workflow
  • glue_create_trigger
  • glue_update_trigger
• Operational reads:
  • glue_list_workflows
  • glue_get_workflow
  • glue_list_triggers
  • glue_get_trigger
  • glue_get_catalog_table
  • glue_list_catalog_tables
  • glue_get_catalog_partitions_sample
  • glue_explain_partitioning

Explicitly excluded in V1

• Create/update/delete for Glue Jobs.
• Create/update/delete for Glue Crawlers.
• Destructive default actions.
• Unsafe auto-apply flows.

Architecture

• Native OpenClaw plugin entrypoint: src/openclawEntry.ts (definePluginEntry + api.registerTool).
• src/runtime: plugin runtime orchestration and tool dispatch.
• src/config: strict configuration loading and validation.
• src/client: AWS Glue client creation.
• src/services: Glue service adapter with output shaping and safe updates.
• src/tools: V1 tool implementations by domain (workflows, triggers, catalog).
• src/guards: write guards (allowlist, secret detection, read-before-write).
• src/errors: typed error hierarchy.
• skills/kansodata-glue-operator: companion operator skill.
• docs: architecture, threat model, rollback, roadmap, usage.

Installation

npm install
npm run build

Configuration

Effective config keys (OpenClaw pluginConfig + env fallback):

• region
• profile
• endpointOverride
• allowedNamePrefixes
• enforcePrefixAllowlist
• dryRunByDefault
• maxPartitionSampleSize

Precedence order:

1. OpenClaw plugin config (api.pluginConfig)
2. Environment variables
3. Safe defaults already defined in schema (allowedNamePrefixes, enforcePrefixAllowlist, dryRunByDefault, maxPartitionSampleSize)

Optional:

• AWS_PROFILE
• KANSODATA_GLUE_ENDPOINT_OVERRIDE
• KANSODATA_GLUE_ALLOWED_PREFIXES (comma separated)
• KANSODATA_GLUE_ENFORCE_PREFIX_ALLOWLIST (default true)
• KANSODATA_GLUE_DRY_RUN_BY_DEFAULT (default true)
• KANSODATA_GLUE_MAX_PARTITION_SAMPLE_SIZE (default 10, max 25)

Fail-closed behavior:

• Missing region across OpenClaw config + env fails.
• Allowlist enforcement with empty prefix list fails.
• Write operations outside allowed prefixes fail when enforcement is active.
• Potential secret-like payloads are rejected.

Security and Hardening

• Strict TypeScript + strong input validation (zod).
• Error sanitization and explicit error taxonomy.
• No raw AWS payloads exposed by tools.
• glue_update_trigger accepts only fields that AWS UpdateTrigger can really apply (schedule, description, actions, predicate).
• Update tools use controlled fields only, with read-before-write discipline.
• Dry-run defaults to true.

Usage (runtime helpers)

import { createPluginRuntime } from "@kansodata/kansodata-glue-plugin";

const runtime = createPluginRuntime();
const result = await runtime.executeTool("glue_list_workflows", { limit: 10 });
console.log(result.summary, result.data);

See docs/usage.md for more examples.

OpenClaw Wiring

• openclaw.plugin.json declares plugin id, contracts, config schema, and companion skills ("./skills").
• package.json declares OpenClaw runtime extension entrypoint ("./dist/openclawEntry.js").
• src/openclawEntry.ts is the canonical plugin entry and registers tool contracts via the official OpenClaw SDK.

Plugin/Skill Relationship

• Plugin executes controlled AWS Glue operations.
• Skill governs operational sequence: read -> plan -> validate -> apply -> verify.
• Skill does not replace plugin guardrails; it enforces higher-level operator discipline.

Validation Commands

npm run lint
npm run typecheck
npm run build
npm test