@kansodata/kansodata-glue-plugin 0.1.0

package/docs/usage.md

@@ -0,0 +1,70 @@
+# Usage
+
+## Runtime Initialization
+
+```ts
+import { createPluginRuntime } from "@kansodata/kansodata-glue-plugin";
+
+const runtime = createPluginRuntime();
+```
+
+## OpenClaw Plugin Loading
+
+- Manifest: `openclaw.plugin.json`
+- Runtime extension entry: `package.json -> openclaw.extensions -> ./dist/openclawEntry.js`
+- Companion skill discovery: `openclaw.plugin.json -> skills -> ["./skills"]`
+- Runtime config precedence: `OpenClaw pluginConfig -> env vars -> schema defaults`
+
+## Runtime Config Mapping
+
+- `region` -> fallback `AWS_REGION` / `AWS_DEFAULT_REGION`
+- `profile` -> fallback `AWS_PROFILE`
+- `endpointOverride` -> fallback `KANSODATA_GLUE_ENDPOINT_OVERRIDE`
+- `allowedNamePrefixes` -> fallback `KANSODATA_GLUE_ALLOWED_PREFIXES`
+- `enforcePrefixAllowlist` -> fallback `KANSODATA_GLUE_ENFORCE_PREFIX_ALLOWLIST`
+- `dryRunByDefault` -> fallback `KANSODATA_GLUE_DRY_RUN_BY_DEFAULT`
+- `maxPartitionSampleSize` -> fallback `KANSODATA_GLUE_MAX_PARTITION_SAMPLE_SIZE`
+
+## Read Examples
+
+```ts
+await runtime.executeTool("glue_get_workflow", { name: "kdo-sales-wf" });
+await runtime.executeTool("glue_list_catalog_tables", {
+  databaseName: "analytics",
+  maxResults: 20
+});
+await runtime.executeTool("glue_explain_partitioning", {
+  databaseName: "analytics",
+  tableName: "fact_orders",
+  sampleSize: 10
+});
+```
+
+## Controlled Write Examples
+
+```ts
+await runtime.executeTool("glue_create_workflow", {
+  name: "kdo-sales-wf",
+  description: "Sales workflow",
+  dryRun: true
+});
+
+await runtime.executeTool("glue_update_trigger", {
+  name: "kdo-sales-schedule",
+  schedule: "cron(0 2 * * ? *)",
+  dryRun: true
+});
+```
+
+`glue_update_trigger` mutable fields are intentionally limited to:
+- `schedule`
+- `description`
+- `actions`
+- `predicate`
+
+## Recommended Operator Sequence
+1. Read current state (`get/list`).
+2. Build expected impact summary.
+3. Validate names, scope, and dry-run result.
+4. Apply with explicit `dryRun: false` only when safe.
+5. Verify resulting state with `get`.

package/openclaw.plugin.json

@@ -0,0 +1,73 @@
+{
+  "id": "kansodata-glue",
+  "name": "@kansodata/kansodata-glue-plugin",
+  "version": "0.1.0",
+  "description": "Controlled AWS Glue workflow/trigger writes and catalog diagnostics for ETL operator agents.",
+  "skills": [
+    "./skills"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "region": {
+        "type": "string",
+        "minLength": 1,
+        "description": "AWS region for Glue operations. Fallback: AWS_REGION/AWS_DEFAULT_REGION."
+      },
+      "profile": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Optional AWS profile. Fallback: AWS_PROFILE."
+      },
+      "endpointOverride": {
+        "type": "string",
+        "format": "uri",
+        "minLength": 1,
+        "description": "Optional Glue endpoint override (strict URL validation)."
+      },
+      "allowedNamePrefixes": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "minLength": 1
+        },
+        "default": [],
+        "description": "Allowed resource name prefixes for write operations."
+      },
+      "enforcePrefixAllowlist": {
+        "type": "boolean",
+        "default": true,
+        "description": "When true, writes are rejected outside allowed prefixes."
+      },
+      "dryRunByDefault": {
+        "type": "boolean",
+        "default": true,
+        "description": "Default write mode. True keeps writes in dry-run unless overridden."
+      },
+      "maxPartitionSampleSize": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 25,
+        "default": 10,
+        "description": "Upper bound for partition diagnostics sample size."
+      }
+    }
+  },
+  "contracts": {
+    "tools": [
+      "glue_list_workflows",
+      "glue_get_workflow",
+      "glue_create_workflow",
+      "glue_update_workflow",
+      "glue_list_triggers",
+      "glue_get_trigger",
+      "glue_create_trigger",
+      "glue_update_trigger",
+      "glue_get_catalog_table",
+      "glue_list_catalog_tables",
+      "glue_get_catalog_partitions_sample",
+      "glue_explain_partitioning"
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@kansodata/kansodata-glue-plugin",
+  "version": "0.1.0",
+  "description": "OpenClaw plugin and companion skill for controlled AWS Glue orchestration writes and ETL catalog diagnostics.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "skills",
+    "docs",
+    "README.md",
+    "AGENTS.md"
+  ],
+  "scripts": {
+    "clean": "node -e \"const { rmSync } = require('node:fs'); rmSync('dist', { recursive: true, force: true });\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "validate": "npm run lint && npm run typecheck && npm run build && npm run test"
+  },
+  "keywords": [
+    "openclaw",
+    "aws-glue",
+    "plugin",
+    "etl"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/openclawEntry.js"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.4.14",
+      "minGatewayVersion": "2026.4.14"
+    }
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.41",
+    "@aws-sdk/client-glue": "^3.917.0",
+    "openclaw": "^2026.4.14",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.1",
+    "@typescript-eslint/eslint-plugin": "^8.31.0",
+    "@typescript-eslint/parser": "^8.31.0",
+    "eslint": "^9.24.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.1"
+  }
+}

package/skills/kansodata-glue-operator/SKILL.md

@@ -0,0 +1,47 @@
+# Skill: kansodata-glue-operator
+
+## Purpose
+Operational companion for the `@kansodata/kansodata-glue-plugin` OpenClaw plugin. It governs safe sequencing and rejection criteria for AWS Glue orchestration changes and ETL catalog diagnostics.
+
+## Operational Modes
+- `diagnose`: read-only ETL/catalog diagnosis.
+- `plan-change`: impact and guardrail validation before write.
+- `apply-change`: controlled write after explicit validation.
+- `verify-change`: post-apply verification.
+
+## Expected Inputs
+- Environment context (`region`, profile if relevant).
+- Target resource names.
+- Desired workflow/trigger fields.
+- ETL diagnostic context (database/table, partition expectations).
+
+## Mandatory Sequence
+1. `read`: fetch current state with `get/list` tools.
+2. `plan`: summarize intended impact and allowed fields.
+3. `validate`: confirm allowlist match, no secrets, and scope fit.
+4. `apply`: run create/update with explicit `dryRun` intent.
+5. `verify`: read again and compare expected vs observed state.
+
+## Degradation Rules
+- If permissions fail, switch to read-only diagnostics and emit actionable IAM/config hints.
+- If resource missing in update flow, reject write and propose create flow.
+- If catalog metadata is incomplete, return bounded diagnosis and next checks.
+
+## Rejection Rules
+- Reject ambiguous write requests with missing target name or mutable field intent.
+- Reject any request containing plain-text secrets.
+- Reject writes outside allowed name prefixes when enforcement is enabled.
+- Reject out-of-scope requests (jobs/crawlers write in V1).
+
+## Safe Change Guidelines
+- Prefer `dryRun: true` on first pass.
+- Keep updates minimal and explicit (no blind patching).
+- Always verify with follow-up `get` call.
+
+## Out-of-Scope Guidelines
+- Job/Crawler write changes: reject in V1 and route to roadmap.
+- Destructive flows: reject unless future explicit capability exists.
+
+See:
+- `skills/kansodata-glue-operator/docs/examples.md`
+- `skills/kansodata-glue-operator/docs/scope.md`

package/skills/kansodata-glue-operator/docs/examples.md

@@ -0,0 +1,44 @@
+# Examples
+
+## Safe Diagnostic Request
+Input:
+- "Explain why `push_down_predicate` is not reducing scan for `analytics.fact_orders`."
+
+Expected flow:
+1. `glue_get_catalog_table`
+2. `glue_get_catalog_partitions_sample`
+3. `glue_explain_partitioning`
+4. Summarize partition-key alignment and predicate guidance.
+
+## Safe Write Request
+Input:
+- "Update trigger `kdo-sales-schedule` cron to 02:00 UTC."
+
+Expected flow:
+1. `glue_get_trigger`
+2. impact summary
+3. `glue_update_trigger` with explicit schedule field
+4. `glue_get_trigger` verification
+
+## Ambiguous Request
+Input:
+- "Fix my workflow please."
+
+Expected response:
+- Reject as ambiguous.
+- Ask for exact workflow name, intended field changes, and expected outcome.
+
+## Must Reject
+Input:
+- "Create trigger with token=abc123 in parameters."
+
+Expected response:
+- Reject due to secret-like payload.
+
+## Out of Scope (V1)
+Input:
+- "Update Glue job script location and worker settings."
+
+Expected response:
+- Reject write request as out-of-scope in V1.
+- Suggest read-only diagnostics or roadmap path.

package/skills/kansodata-glue-operator/docs/scope.md

@@ -0,0 +1,37 @@
+# Scope Contract
+
+## In Scope (V1)
+- Workflow writes:
+  - create
+  - update
+- Trigger writes:
+  - create
+  - update
+- Read/diagnostics:
+  - workflows
+  - triggers
+  - catalog tables
+  - partition samples
+  - partition explanation guidance
+
+## Out of Scope (V1)
+- Any Job write operation.
+- Any Crawler write operation.
+- Destructive default operations.
+- Unvalidated free-form patches against Glue resources.
+
+## Safety Contract
+- Enforce read-before-write for updates.
+- Block secret-like payloads.
+- Respect prefix allowlist when enabled.
+- Prefer dry-run defaults and explicit opt-out for apply.
+
+## Diagnostic Coverage
+- Supported:
+  - partition key visibility
+  - sampled partition values
+  - guidance for `from_catalog` + `push_down_predicate`
+- Not supported:
+  - notebook parsing
+  - runtime Spark plan analysis
+  - proprietary ETL framework introspection