@kansodata/kansodata-glue-plugin 0.1.0

package/AGENTS.md

@@ -0,0 +1,30 @@
+# AGENTS.md
+
+Repositorio: `@kansodata/kansodata-glue-plugin`
+
+## Objetivo operativo V1
+- Proveer plugin OpenClaw para AWS Glue con escritura controlada en workflows/triggers y diagnóstico ETL basado en Glue Catalog/particiones.
+- Operar con fail-closed, guardrails explícitos y documentación suficiente para continuidad.
+
+## Límites de alcance V1
+- Permitido: create/update workflow, create/update trigger, lecturas de catálogo y diagnóstico de particiones.
+- Prohibido: create/update/delete Job o Crawler, acciones destructivas por defecto, bypass de validaciones.
+
+## Reglas de seguridad
+- Rechazar payloads con patrones obvios de secretos.
+- Restringir writes por allowlist de prefijos cuando esté activa.
+- Exigir read-before-write para updates.
+- Sanitizar mensajes de error y no loggear datos sensibles.
+
+## Flujo recomendado
+1. Leer estado actual (`get/list`).
+2. Planificar cambio e impacto.
+3. Validar inputs, alcance y guardrails.
+4. Aplicar (preferir dry-run en cambios nuevos).
+5. Verificar estado posterior.
+
+## Validación mínima antes de merge
+- `npm run lint`
+- `npm run typecheck`
+- `npm run build`
+- `npm test`

package/README.md

@@ -0,0 +1,119 @@
+# @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
+
+```bash
+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)
+
+```ts
+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](./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
+
+```bash
+npm run lint
+npm run typecheck
+npm run build
+npm test
+```

package/dist/client/glueClientFactory.d.ts

@@ -0,0 +1,3 @@
+import { GlueClient } from "@aws-sdk/client-glue";
+import type { GluePluginConfig } from "../config/schema.js";
+export declare const createGlueClient: (config: GluePluginConfig) => GlueClient;

package/dist/client/glueClientFactory.js

@@ -0,0 +1,7 @@
+import { GlueClient } from "@aws-sdk/client-glue";
+export const createGlueClient = (config) => new GlueClient({
+    region: config.region,
+    ...(config.profile ? { profile: config.profile } : {}),
+    ...(config.endpointOverride ? { endpoint: config.endpointOverride } : {})
+});
+//# sourceMappingURL=glueClientFactory.js.map

package/dist/client/glueClientFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glueClientFactory.js","sourceRoot":"","sources":["../../src/client/glueClientFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGlD,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAwB,EAAc,EAAE,CACvE,IAAI,UAAU,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM;IACrB,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACtD,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;CAC1E,CAAC,CAAC"}

package/dist/config/loadConfig.d.ts

@@ -0,0 +1,7 @@
+import { type GluePluginConfig } from "./schema.js";
+export interface ResolveConfigOptions {
+    readonly openClawConfig?: unknown;
+    readonly env?: NodeJS.ProcessEnv;
+}
+export declare const resolveConfig: (options?: ResolveConfigOptions) => GluePluginConfig;
+export declare const loadConfigFromEnv: (env?: NodeJS.ProcessEnv) => GluePluginConfig;

package/dist/config/loadConfig.js

@@ -0,0 +1,82 @@
+import { GluePluginConfigSchema, GluePluginOpenClawConfigSchema } from "./schema.js";
+import { ConfigValidationError } from "../errors/glueErrors.js";
+const TRUE_VALUES = new Set(["1", "true", "yes", "on"]);
+const FALSE_VALUES = new Set(["0", "false", "no", "off"]);
+const parseBoolean = (value, fallback) => {
+    if (value === undefined) {
+        return fallback;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (TRUE_VALUES.has(normalized)) {
+        return true;
+    }
+    if (FALSE_VALUES.has(normalized)) {
+        return false;
+    }
+    throw new ConfigValidationError(`Invalid boolean value: ${value}`);
+};
+const parseOptionalBoolean = (value) => value === undefined ? undefined : parseBoolean(value, false);
+const parseAllowedPrefixes = (raw) => {
+    if (!raw) {
+        return [];
+    }
+    return raw
+        .split(",")
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+};
+const parseOptionalNumber = (value) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) {
+        throw new ConfigValidationError(`Invalid number value: ${value}`);
+    }
+    return parsed;
+};
+const toValidationDetails = (issues) => issues.map((issue) => ({
+    path: issue.path.join("."),
+    message: issue.message
+}));
+export const resolveConfig = (options = {}) => {
+    const env = options.env ?? process.env;
+    const parsedOpenClawConfig = GluePluginOpenClawConfigSchema.safeParse(options.openClawConfig ?? {});
+    if (!parsedOpenClawConfig.success) {
+        throw new ConfigValidationError("OpenClaw plugin configuration is invalid.", {
+            details: toValidationDetails(parsedOpenClawConfig.error.issues)
+        });
+    }
+    const envCandidate = {
+        region: env.AWS_REGION ?? env.AWS_DEFAULT_REGION,
+        profile: env.AWS_PROFILE,
+        endpointOverride: env.KANSODATA_GLUE_ENDPOINT_OVERRIDE,
+        allowedNamePrefixes: env.KANSODATA_GLUE_ALLOWED_PREFIXES === undefined
+            ? undefined
+            : parseAllowedPrefixes(env.KANSODATA_GLUE_ALLOWED_PREFIXES),
+        enforcePrefixAllowlist: parseOptionalBoolean(env.KANSODATA_GLUE_ENFORCE_PREFIX_ALLOWLIST),
+        dryRunByDefault: parseOptionalBoolean(env.KANSODATA_GLUE_DRY_RUN_BY_DEFAULT),
+        maxPartitionSampleSize: parseOptionalNumber(env.KANSODATA_GLUE_MAX_PARTITION_SAMPLE_SIZE)
+    };
+    const configCandidate = {
+        region: parsedOpenClawConfig.data.region ?? envCandidate.region,
+        profile: parsedOpenClawConfig.data.profile ?? envCandidate.profile,
+        endpointOverride: parsedOpenClawConfig.data.endpointOverride ?? envCandidate.endpointOverride,
+        allowedNamePrefixes: parsedOpenClawConfig.data.allowedNamePrefixes ?? envCandidate.allowedNamePrefixes,
+        enforcePrefixAllowlist: parsedOpenClawConfig.data.enforcePrefixAllowlist ?? envCandidate.enforcePrefixAllowlist,
+        dryRunByDefault: parsedOpenClawConfig.data.dryRunByDefault ?? envCandidate.dryRunByDefault,
+        maxPartitionSampleSize: parsedOpenClawConfig.data.maxPartitionSampleSize ?? envCandidate.maxPartitionSampleSize
+    };
+    const parsed = GluePluginConfigSchema.safeParse(configCandidate);
+    if (!parsed.success) {
+        throw new ConfigValidationError("Glue plugin configuration is invalid.", {
+            details: toValidationDetails(parsed.error.issues)
+        });
+    }
+    if (parsed.data.enforcePrefixAllowlist && parsed.data.allowedNamePrefixes.length === 0) {
+        throw new ConfigValidationError("Prefix allowlist is enforced but no allowed prefixes were configured.");
+    }
+    return parsed.data;
+};
+export const loadConfigFromEnv = (env = process.env) => resolveConfig({ env });
+//# sourceMappingURL=loadConfig.js.map

package/dist/config/loadConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadConfig.js","sourceRoot":"","sources":["../../src/config/loadConfig.ts"],"names":[],"mappings":"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"}

package/dist/config/schema.d.ts

@@ -0,0 +1,110 @@
+import { z } from "zod";
+export declare const GLUE_PLUGIN_CONFIG_LIMITS: {
+    readonly maxPartitionSampleSize: 25;
+};
+export declare const GLUE_PLUGIN_CONFIG_DEFAULTS: {
+    readonly allowedNamePrefixes: string[];
+    readonly enforcePrefixAllowlist: true;
+    readonly dryRunByDefault: true;
+    readonly maxPartitionSampleSize: 10;
+};
+export declare const GluePluginConfigSchema: z.ZodObject<{
+    region: z.ZodString;
+    profile: z.ZodOptional<z.ZodString>;
+    endpointOverride: z.ZodOptional<z.ZodString>;
+    allowedNamePrefixes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    enforcePrefixAllowlist: z.ZodDefault<z.ZodBoolean>;
+    dryRunByDefault: z.ZodDefault<z.ZodBoolean>;
+    maxPartitionSampleSize: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    region: string;
+    allowedNamePrefixes: string[];
+    enforcePrefixAllowlist: boolean;
+    dryRunByDefault: boolean;
+    maxPartitionSampleSize: number;
+    profile?: string | undefined;
+    endpointOverride?: string | undefined;
+}, {
+    region: string;
+    profile?: string | undefined;
+    endpointOverride?: string | undefined;
+    allowedNamePrefixes?: string[] | undefined;
+    enforcePrefixAllowlist?: boolean | undefined;
+    dryRunByDefault?: boolean | undefined;
+    maxPartitionSampleSize?: number | undefined;
+}>;
+export declare const GluePluginOpenClawConfigSchema: z.ZodObject<{
+    region: z.ZodOptional<z.ZodString>;
+    profile: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    endpointOverride: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    allowedNamePrefixes: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString, "many">>>;
+    enforcePrefixAllowlist: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    dryRunByDefault: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    maxPartitionSampleSize: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+}, "strict", z.ZodTypeAny, {
+    region?: string | undefined;
+    profile?: string | undefined;
+    endpointOverride?: string | undefined;
+    allowedNamePrefixes?: string[] | undefined;
+    enforcePrefixAllowlist?: boolean | undefined;
+    dryRunByDefault?: boolean | undefined;
+    maxPartitionSampleSize?: number | undefined;
+}, {
+    region?: string | undefined;
+    profile?: string | undefined;
+    endpointOverride?: string | undefined;
+    allowedNamePrefixes?: string[] | undefined;
+    enforcePrefixAllowlist?: boolean | undefined;
+    dryRunByDefault?: boolean | undefined;
+    maxPartitionSampleSize?: number | undefined;
+}>;
+export declare const GluePluginOpenClawConfigJsonSchema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly region: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly description: "AWS region for Glue operations. Fallback: AWS_REGION/AWS_DEFAULT_REGION.";
+        };
+        readonly profile: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly description: "Optional AWS profile. Fallback: AWS_PROFILE.";
+        };
+        readonly endpointOverride: {
+            readonly type: "string";
+            readonly format: "uri";
+            readonly minLength: 1;
+            readonly description: "Optional Glue endpoint override (strict URL validation).";
+        };
+        readonly allowedNamePrefixes: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+            readonly default: string[];
+            readonly description: "Allowed resource name prefixes for write operations.";
+        };
+        readonly enforcePrefixAllowlist: {
+            readonly type: "boolean";
+            readonly default: true;
+            readonly description: "When true, writes are rejected outside allowed prefixes.";
+        };
+        readonly dryRunByDefault: {
+            readonly type: "boolean";
+            readonly default: true;
+            readonly description: "Default write mode. True keeps writes in dry-run unless overridden.";
+        };
+        readonly maxPartitionSampleSize: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly maximum: 25;
+            readonly default: 10;
+            readonly description: "Upper bound for partition diagnostics sample size.";
+        };
+    };
+};
+export type GluePluginConfig = z.infer<typeof GluePluginConfigSchema>;
+export type GluePluginOpenClawConfigInput = z.infer<typeof GluePluginOpenClawConfigSchema>;

package/dist/config/schema.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+export const GLUE_PLUGIN_CONFIG_LIMITS = {
+    maxPartitionSampleSize: 25
+};
+export const GLUE_PLUGIN_CONFIG_DEFAULTS = {
+    allowedNamePrefixes: [],
+    enforcePrefixAllowlist: true,
+    dryRunByDefault: true,
+    maxPartitionSampleSize: 10
+};
+export const GluePluginConfigSchema = z
+    .object({
+    region: z.string().trim().min(1),
+    profile: z.string().trim().min(1).optional(),
+    endpointOverride: z.string().trim().url().optional(),
+    allowedNamePrefixes: z
+        .array(z.string().trim().min(1))
+        .default(GLUE_PLUGIN_CONFIG_DEFAULTS.allowedNamePrefixes),
+    enforcePrefixAllowlist: z.boolean().default(GLUE_PLUGIN_CONFIG_DEFAULTS.enforcePrefixAllowlist),
+    dryRunByDefault: z.boolean().default(GLUE_PLUGIN_CONFIG_DEFAULTS.dryRunByDefault),
+    maxPartitionSampleSize: z
+        .number()
+        .int()
+        .positive()
+        .max(GLUE_PLUGIN_CONFIG_LIMITS.maxPartitionSampleSize)
+        .default(GLUE_PLUGIN_CONFIG_DEFAULTS.maxPartitionSampleSize)
+})
+    .strict();
+export const GluePluginOpenClawConfigSchema = GluePluginConfigSchema.partial().strict();
+export const GluePluginOpenClawConfigJsonSchema = {
+    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: GLUE_PLUGIN_CONFIG_DEFAULTS.allowedNamePrefixes,
+            description: "Allowed resource name prefixes for write operations."
+        },
+        enforcePrefixAllowlist: {
+            type: "boolean",
+            default: GLUE_PLUGIN_CONFIG_DEFAULTS.enforcePrefixAllowlist,
+            description: "When true, writes are rejected outside allowed prefixes."
+        },
+        dryRunByDefault: {
+            type: "boolean",
+            default: GLUE_PLUGIN_CONFIG_DEFAULTS.dryRunByDefault,
+            description: "Default write mode. True keeps writes in dry-run unless overridden."
+        },
+        maxPartitionSampleSize: {
+            type: "integer",
+            minimum: 1,
+            maximum: GLUE_PLUGIN_CONFIG_LIMITS.maxPartitionSampleSize,
+            default: GLUE_PLUGIN_CONFIG_DEFAULTS.maxPartitionSampleSize,
+            description: "Upper bound for partition diagnostics sample size."
+        }
+    }
+};
+//# sourceMappingURL=schema.js.map

package/dist/config/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,sBAAsB,EAAE,EAAE;CAClB,CAAC;AAEX,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,mBAAmB,EAAE,EAAc;IACnC,sBAAsB,EAAE,IAAI;IAC5B,eAAe,EAAE,IAAI;IACrB,sBAAsB,EAAE,EAAE;CAClB,CAAC;AAEX,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC;KACpC,MAAM,CAAC;IACN,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAChC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC5C,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACpD,mBAAmB,EAAE,CAAC;SACnB,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;SAC/B,OAAO,CAAC,2BAA2B,CAAC,mBAAmB,CAAC;IAC3D,sBAAsB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,2BAA2B,CAAC,sBAAsB,CAAC;IAC/F,eAAe,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,2BAA2B,CAAC,eAAe,CAAC;IACjF,sBAAsB,EAAE,CAAC;SACtB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,GAAG,CAAC,yBAAyB,CAAC,sBAAsB,CAAC;SACrD,OAAO,CAAC,2BAA2B,CAAC,sBAAsB,CAAC;CAC/D,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,MAAM,CAAC,MAAM,8BAA8B,GAAG,sBAAsB,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC;AAExF,MAAM,CAAC,MAAM,kCAAkC,GAAG;IAChD,IAAI,EAAE,QAAQ;IACd,oBAAoB,EAAE,KAAK;IAC3B,UAAU,EAAE;QACV,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,SAAS,EAAE,CAAC;YACZ,WAAW,EAAE,0EAA0E;SACxF;QACD,OAAO,EAAE;YACP,IAAI,EAAE,QAAQ;YACd,SAAS,EAAE,CAAC;YACZ,WAAW,EAAE,8CAA8C;SAC5D;QACD,gBAAgB,EAAE;YAChB,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,KAAK;YACb,SAAS,EAAE,CAAC;YACZ,WAAW,EAAE,0DAA0D;SACxE;QACD,mBAAmB,EAAE;YACnB,IAAI,EAAE,OAAO;YACb,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,SAAS,EAAE,CAAC;aACb;YACD,OAAO,EAAE,2BAA2B,CAAC,mBAAmB;YACxD,WAAW,EAAE,sDAAsD;SACpE;QACD,sBAAsB,EAAE;YACtB,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,2BAA2B,CAAC,sBAAsB;YAC3D,WAAW,EAAE,0DAA0D;SACxE;QACD,eAAe,EAAE;YACf,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,2BAA2B,CAAC,eAAe;YACpD,WAAW,EAAE,qEAAqE;SACnF;QACD,sBAAsB,EAAE;YACtB,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,yBAAyB,CAAC,sBAAsB;YACzD,OAAO,EAAE,2BAA2B,CAAC,sBAAsB;YAC3D,WAAW,EAAE,oDAAoD;SAClE;KACF;CACO,CAAC"}

package/dist/domain/contracts.d.ts

@@ -0,0 +1,65 @@
+import type { GluePluginConfig } from "../config/schema.js";
+import type { GlueService } from "../services/glueService.js";
+export type ToolName = "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";
+export interface ToolExecutionContext {
+    readonly config: GluePluginConfig;
+    readonly glueService: GlueService;
+}
+export interface ToolExecutionResult {
+    readonly summary: string;
+    readonly data: Record<string, unknown>;
+    readonly warnings?: readonly string[];
+}
+export interface ToolDefinition<TInput> {
+    readonly name: ToolName;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+    execute(context: ToolExecutionContext, input: unknown): Promise<ToolExecutionResult>;
+    parseInput(input: unknown): TInput;
+}
+export interface GlueWorkflowView {
+    readonly name: string;
+    readonly description?: string;
+    readonly maxConcurrentRuns?: number;
+    readonly defaultRunProperties?: Readonly<Record<string, string>>;
+    readonly graphSummary?: {
+        readonly nodeCount: number;
+        readonly edgeCount: number;
+    };
+}
+export interface GlueTriggerView {
+    readonly name: string;
+    readonly type?: string;
+    readonly state?: string;
+    readonly workflowName?: string;
+    readonly schedule?: string;
+    readonly description?: string;
+    readonly actionJobNames: readonly string[];
+    readonly predicateSummary?: {
+        readonly logical?: string;
+        readonly conditions: number;
+    };
+}
+export interface CatalogTableView {
+    readonly databaseName: string;
+    readonly tableName: string;
+    readonly owner?: string;
+    readonly tableType?: string;
+    readonly location?: string;
+    readonly parameters: Readonly<Record<string, string>>;
+    readonly partitionKeys: readonly string[];
+    readonly storageDescriptorColumns: readonly string[];
+}
+export interface CatalogPartitionSample {
+    readonly values: readonly string[];
+    readonly location?: string;
+    readonly creationTime?: string;
+}
+export interface PartitioningExplainView {
+    readonly databaseName: string;
+    readonly tableName: string;
+    readonly partitionKeys: readonly string[];
+    readonly sampleCount: number;
+    readonly sampleValues: readonly string[];
+    readonly guidance: readonly string[];
+}

package/dist/domain/contracts.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contracts.js.map

package/dist/domain/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../src/domain/contracts.ts"],"names":[],"mappings":""}

package/dist/errors/glueErrors.d.ts

@@ -0,0 +1,30 @@
+export type ErrorMetadata = Readonly<Record<string, unknown>>;
+export declare class GluePluginError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly metadata?: ErrorMetadata;
+    constructor(message: string, options: {
+        code: string;
+        status: number;
+        metadata?: ErrorMetadata;
+        cause?: unknown;
+    });
+}
+export declare class ConfigValidationError extends GluePluginError {
+    constructor(message: string, metadata?: ErrorMetadata);
+}
+export declare class MissingAuthorizationError extends GluePluginError {
+    constructor(message?: string, metadata?: ErrorMetadata);
+}
+export declare class InvalidInputError extends GluePluginError {
+    constructor(message: string, metadata?: ErrorMetadata);
+}
+export declare class ResourceNotFoundError extends GluePluginError {
+    constructor(message: string, metadata?: ErrorMetadata);
+}
+export declare class UnsafeOperationError extends GluePluginError {
+    constructor(message: string, metadata?: ErrorMetadata);
+}
+export declare class RemoteServiceError extends GluePluginError {
+    constructor(message: string, metadata?: ErrorMetadata, cause?: unknown);
+}

package/dist/errors/glueErrors.js

@@ -0,0 +1,43 @@
+export class GluePluginError extends Error {
+    code;
+    status;
+    metadata;
+    constructor(message, options) {
+        super(message, { cause: options.cause });
+        this.name = this.constructor.name;
+        this.code = options.code;
+        this.status = options.status;
+        this.metadata = options.metadata;
+    }
+}
+export class ConfigValidationError extends GluePluginError {
+    constructor(message, metadata) {
+        super(message, { code: "CONFIG_INVALID", status: 400, metadata });
+    }
+}
+export class MissingAuthorizationError extends GluePluginError {
+    constructor(message = "AWS credentials are missing or invalid.", metadata) {
+        super(message, { code: "AUTH_MISSING", status: 401, metadata });
+    }
+}
+export class InvalidInputError extends GluePluginError {
+    constructor(message, metadata) {
+        super(message, { code: "INPUT_INVALID", status: 400, metadata });
+    }
+}
+export class ResourceNotFoundError extends GluePluginError {
+    constructor(message, metadata) {
+        super(message, { code: "RESOURCE_NOT_FOUND", status: 404, metadata });
+    }
+}
+export class UnsafeOperationError extends GluePluginError {
+    constructor(message, metadata) {
+        super(message, { code: "UNSAFE_OPERATION", status: 403, metadata });
+    }
+}
+export class RemoteServiceError extends GluePluginError {
+    constructor(message, metadata, cause) {
+        super(message, { code: "REMOTE_ERROR", status: 502, metadata, cause });
+    }
+}
+//# sourceMappingURL=glueErrors.js.map

package/dist/errors/glueErrors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glueErrors.js","sourceRoot":"","sources":["../../src/errors/glueErrors.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxB,IAAI,CAAS;IACb,MAAM,CAAS;IACf,QAAQ,CAAiB;IAEzC,YACE,OAAe,EACf,OAKC;QAED,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;QAClC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IACnC,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,eAAe;IACxD,YAAmB,OAAe,EAAE,QAAwB;QAC1D,KAAK,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;IACpE,CAAC;CACF;AAED,MAAM,OAAO,yBAA0B,SAAQ,eAAe;IAC5D,YAAmB,OAAO,GAAG,yCAAyC,EAAE,QAAwB;QAC9F,KAAK,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;IAClE,CAAC;CACF;AAED,MAAM,OAAO,iBAAkB,SAAQ,eAAe;IACpD,YAAmB,OAAe,EAAE,QAAwB;QAC1D,KAAK,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;IACnE,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,eAAe;IACxD,YAAmB,OAAe,EAAE,QAAwB;QAC1D,KAAK,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,oBAAoB,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;IACxE,CAAC;CACF;AAED,MAAM,OAAO,oBAAqB,SAAQ,eAAe;IACvD,YAAmB,OAAe,EAAE,QAAwB;QAC1D,KAAK,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;IACtE,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,eAAe;IACrD,YAAmB,OAAe,EAAE,QAAwB,EAAE,KAAe;QAC3E,KAAK,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;IACzE,CAAC;CACF"}

package/dist/guards/operationGuards.d.ts

@@ -0,0 +1,4 @@
+import type { GluePluginConfig } from "../config/schema.js";
+export declare const assertNoSecretsInPayload: (payload: unknown) => void;
+export declare const assertNameAllowedByPrefix: (config: GluePluginConfig, resourceName: string, resourceType: "workflow" | "trigger") => void;
+export declare const assertReadBeforeWrite: (existing: unknown, resourceType: "workflow" | "trigger", resourceName: string) => void;

package/dist/guards/operationGuards.js

@@ -0,0 +1,28 @@
+import { InvalidInputError, UnsafeOperationError } from "../errors/glueErrors.js";
+import { hasPotentialSecret } from "../utils/sanitize.js";
+const startsWithAny = (value, prefixes) => prefixes.some((prefix) => value.startsWith(prefix));
+export const assertNoSecretsInPayload = (payload) => {
+    if (hasPotentialSecret(payload)) {
+        throw new UnsafeOperationError("Payload rejected because it appears to contain secrets.");
+    }
+};
+export const assertNameAllowedByPrefix = (config, resourceName, resourceType) => {
+    if (!resourceName.trim()) {
+        throw new InvalidInputError(`${resourceType} name cannot be empty.`);
+    }
+    if (!config.enforcePrefixAllowlist) {
+        return;
+    }
+    if (!startsWithAny(resourceName, config.allowedNamePrefixes)) {
+        throw new UnsafeOperationError(`${resourceType} "${resourceName}" is outside allowed prefixes.`, {
+            resourceType,
+            resourceName
+        });
+    }
+};
+export const assertReadBeforeWrite = (existing, resourceType, resourceName) => {
+    if (!existing) {
+        throw new UnsafeOperationError(`Cannot update ${resourceType} "${resourceName}" because baseline state is unavailable.`);
+    }
+};
+//# sourceMappingURL=operationGuards.js.map

package/dist/guards/operationGuards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operationGuards.js","sourceRoot":"","sources":["../../src/guards/operationGuards.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAClF,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,MAAM,aAAa,GAAG,CAAC,KAAa,EAAE,QAA2B,EAAW,EAAE,CAC5E,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;AAEtD,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,OAAgB,EAAQ,EAAE;IACjE,IAAI,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,oBAAoB,CAAC,yDAAyD,CAAC,CAAC;IAC5F,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,yBAAyB,GAAG,CACvC,MAAwB,EACxB,YAAoB,EACpB,YAAoC,EAC9B,EAAE;IACR,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,EAAE,CAAC;QACzB,MAAM,IAAI,iBAAiB,CAAC,GAAG,YAAY,wBAAwB,CAAC,CAAC;IACvE,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,sBAAsB,EAAE,CAAC;QACnC,OAAO;IACT,CAAC;IAED,IAAI,CAAC,aAAa,CAAC,YAAY,EAAE,MAAM,CAAC,mBAAmB,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,oBAAoB,CAC5B,GAAG,YAAY,KAAK,YAAY,gCAAgC,EAChE;YACE,YAAY;YACZ,YAAY;SACb,CACF,CAAC;IACJ,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACnC,QAAiB,EACjB,YAAoC,EACpC,YAAoB,EACd,EAAE;IACR,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,oBAAoB,CAC5B,iBAAiB,YAAY,KAAK,YAAY,0CAA0C,CACzF,CAAC;IACJ,CAAC;AACH,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createManifest } from "./manifest.js";
+export { createPluginRuntime } from "./runtime/pluginRuntime.js";
+export { loadConfigFromEnv, resolveConfig } from "./config/loadConfig.js";
+export type { GluePluginConfig } from "./config/schema.js";
+export type { OpenClawPluginRuntime, RuntimeOptions, ToolErrorPayload } from "./runtime/pluginRuntime.js";