@llm4ts/shell 2.11.0 → 2.13.0

package/kits/soap-ace/flows/lib/soap/DesignProposal.js

@@ -0,0 +1,204 @@
+import * as Schema from "effect/Schema";
+import { ComplexTypeDef, localName } from "./Catalog.js";
+import { effectiveClass } from "./Classification.js";
+import { ApiDesign } from "./Design.js";
+// The reasoning seat drafts the REST design; it never has the last word.
+// The prompt carries the style guide as hard rules, the confirmed classes,
+// the 1:1 mapping (the only paths a source may cite), the named XSD types a
+// model may bind to, and the analysis evidence. The reply is decoded into
+// `ApiDesign` and then goes through `checkDesign` like a hand-written one;
+// `revise` feeds the check's findings back for another draft.
+const property = { type: "object", required: ["name", "type", "required"] };
+const designJsonSchema = {
+    type: "object",
+    required: ["version", "title", "basePath", "endpoints", "models", "excluded"],
+    properties: {
+        version: { const: 1 },
+        title: { type: "string" },
+        basePath: { type: "string", description: "/v1" },
+        endpoints: {
+            type: "array",
+            items: {
+                type: "object",
+                required: [
+                    "method",
+                    "path",
+                    "operationId",
+                    "summary",
+                    "sources",
+                    "parameters",
+                    "responses",
+                    "errors",
+                    "evidence"
+                ],
+                properties: {
+                    method: { enum: ["GET", "POST", "PUT", "PATCH", "DELETE"] },
+                    path: { type: "string" },
+                    operationId: { type: "string" },
+                    summary: { type: "string" },
+                    sources: { type: "array", items: { type: "string" } },
+                    parameters: { type: "array", items: property },
+                    requestBody: { type: "object", required: ["model", "required"] },
+                    responses: {
+                        type: "array",
+                        items: { type: "object", required: ["status", "description"] }
+                    },
+                    errors: {
+                        type: "array",
+                        items: { type: "object", required: ["status", "code", "title", "from"] }
+                    },
+                    evidence: { type: "array", items: { type: "string" } }
+                }
+            }
+        },
+        models: {
+            type: "array",
+            items: {
+                type: "object",
+                required: ["name", "properties"],
+                properties: { properties: { type: "array", items: property } }
+            }
+        },
+        excluded: { type: "array", items: { type: "object", required: ["operation", "reason"] } },
+        notes: { type: "array", items: { type: "string" } }
+    }
+};
+const fieldLine = (field) => `    ${field.xsd}: ${field.jsonType}${field.format === undefined ? "" : `(${field.format})`} ${field.xsdType}${field.required ? "" : " optional"}${field.enumeration === undefined ? "" : ` enum ${field.enumeration.join("|")}`}`;
+const analysisLines = (analysis) => [
+    `  ${analysis.operation}: ${analysis.exchanges} samples`,
+    ...analysis.observations.map((line) => `    - ${line}`),
+    ...analysis.outcomes.map((outcome) => `    - outcome ${outcome.code}${outcome.description === undefined ? "" : ` "${outcome.description}"`} ×${outcome.count}`),
+    ...analysis.faults.map((fault) => `    - fault ${fault.detailElement ?? fault.code}: ${fault.reason} ×${fault.count}`),
+    ...(analysis.pagination === undefined
+        ? []
+        : [
+            `    - pagination ${analysis.pagination.style}: request ${analysis.pagination.requestFields.join(", ")}; response ${analysis.pagination.responseFields.join(", ")}; ${analysis.pagination.observed}`
+        ]),
+    ...analysis.fields
+        .filter((field) => field.distinct > 0 &&
+        field.distinct <= 8 &&
+        field.values.every((entry) => entry.value.length <= 20))
+        .map((field) => `    - values of ${field.path}: ${field.values.map((entry) => entry.value).join(", ")}`)
+];
+const exampleDesign = {
+    version: 1,
+    title: "Example",
+    basePath: "/v1",
+    endpoints: [
+        {
+            method: "GET",
+            path: "/orders/{orderId}",
+            operationId: "getOrder",
+            summary: "One order",
+            sources: ["leggiOrdine"],
+            parameters: [
+                { name: "orderId", in: "path", required: true, type: "string", source: "idOrdine" }
+            ],
+            responses: [{ status: 200, description: "The order", model: "Order", source: "" }],
+            errors: [{ status: 404, code: "order-not-found", title: "No such order", from: ["KO04"] }],
+            evidence: ["analysis/leggiOrdine: KO04 inside a 200 when the order does not exist"]
+        }
+    ],
+    models: [
+        {
+            name: "Order",
+            sourceType: "leggiOrdineResponse",
+            properties: [
+                { name: "id", type: "string", required: true, source: "ordine.id" },
+                {
+                    name: "status",
+                    type: "string",
+                    required: true,
+                    source: "ordine.stato",
+                    enum: ["OPEN", "SHIPPED"],
+                    enumMap: { APERTO: "OPEN", SPEDITO: "SHIPPED" }
+                },
+                { name: "total", type: "object", ref: "Amount", required: true, source: "ordine.totale" }
+            ]
+        },
+        {
+            name: "Amount",
+            sourceType: "ImportoType",
+            properties: [
+                { name: "amount", type: "string", format: "decimal", required: true, source: "valore" },
+                { name: "currency", type: "string", required: true, source: "divisa" }
+            ]
+        }
+    ],
+    excluded: []
+};
+export const designPrompt = (options) => {
+    const { catalog } = options;
+    const namedTypes = catalog.types
+        .filter((type) => !type.anonymous && type instanceof ComplexTypeDef)
+        .map((type) => localName(type.name));
+    return [
+        "You design the REST API that an IBM ACE integration will expose in front of a bank's SOAP service.",
+        "Design resources, not a SOAP facade: group operations into resources, map SOAP faults and business",
+        "outcome codes to HTTP statuses and problem codes, flatten SOAP wrappers, drop the esito envelope, and",
+        "translate Italian field names to English camelCase. Every design element must be traceable to the SOAP",
+        "service, and every decision the samples inform must cite them in `evidence`.",
+        "",
+        "## Style guide (hard rules)",
+        "",
+        options.style.trim(),
+        "",
+        "## Operations (confirmed class: read ones may be GET; mutating ones never are)",
+        "",
+        ...catalog.operations.map((operation) => `- ${operation.name} [${effectiveClass(options.operations, operation.name)}]${operation.documentation === undefined ? "" : `: ${operation.documentation}`}`),
+        "",
+        "## 1:1 mapping: the only XSD paths a source may cite",
+        "",
+        ...options.mapping.operations.flatMap((operation) => [
+            `${operation.operation}`,
+            `  request ${operation.request}:`,
+            ...operation.requestFields.map(fieldLine),
+            ...(operation.response === undefined
+                ? []
+                : [`  response ${operation.response}:`, ...operation.responseFields.map(fieldLine)])
+        ]),
+        "",
+        `Named XSD types a model may bind to (besides the request/response elements above): ${namedTypes.join(", ")}`,
+        "",
+        "## Evidence from masked samples",
+        "",
+        ...(options.analyses.length === 0
+            ? ["(no samples analysed)"]
+            : options.analyses.flatMap(analysisLines)),
+        "",
+        "## Format",
+        "",
+        "- Each model binds to one XSD element or named type (`sourceType`); each property's `source` is an XSD",
+        "  path relative to it (`saldo.valore`), or `derivation` explains how it is computed.",
+        "- Each parameter's `source` is a path in the request of the endpoint's first SOAP operation.",
+        '- Each response names its `model` and the `source` path in the SOAP response it comes from (`""` for the',
+        "  whole response); collections set `list: true` (and `paged: true` when the service pages).",
+        "- An `enumMap` must cover every declared SOAP value and every value the samples showed.",
+        "- `errors[].from` lists the outcome codes (KO17) and fault detail elements (ServizioFault) it maps; map",
+        "  every one the evidence shows.",
+        "- Every SOAP operation appears in some endpoint's `sources` or in `excluded` with a reason.",
+        "",
+        "Example of the shape (not of this service):",
+        "```json",
+        JSON.stringify(exampleDesign, null, 2),
+        "```",
+        "",
+        "Reply with the ApiDesign JSON only."
+    ].join("\n");
+};
+export const proposeDesign = (reasoning, options) => reasoning.executeStructured(designPrompt(options), ApiDesign, designJsonSchema);
+export const reviseDesign = (reasoning, options) => reasoning.executeStructured([
+    designPrompt(options),
+    "",
+    "## Current draft",
+    "",
+    "```json",
+    JSON.stringify(Schema.encodeSync(ApiDesign)(options.current), null, 2),
+    "```",
+    "",
+    "## The design check found",
+    "",
+    ...options.issues.map((issue) => `- ${issue.severity} ${issue.where}: ${issue.detail}`),
+    "",
+    "Fix every error and every warning you can; keep everything else as it is. Reply with the full ApiDesign JSON."
+].join("\n"), ApiDesign, designJsonSchema);

package/kits/soap-ace/flows/lib/soap/Discover.js

@@ -0,0 +1,139 @@
+import { basename } from "node:path";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { ComplexTypeDef, elementByName, localName, splitClark, typeByName, WsdlCatalog } from "./Catalog.js";
+import { decodeAuthProfile } from "./Auth.js";
+import { classifyOperations, operationsDrift, parseOperationsFile, renderOperationsFile } from "./Classification.js";
+import { readCatalog } from "./Wsdl.js";
+// `soap-discover` as a library call: read the catalog, persist it with a
+// human summary, and propose operation classes unless a classification file
+// already exists (the existing file wins, as every approval file does).
+export class CatalogFileError extends Schema.TaggedError()("CatalogFileError", {
+    path: Schema.String,
+    detail: Schema.String
+}) {
+    get message() {
+        return `${this.path}: ${this.detail}`;
+    }
+}
+/** `.llm4ts/soap/<service>` */
+export const serviceDirectory = (service) => `.llm4ts/soap/${service}`;
+export const servicePaths = (service) => {
+    const directory = serviceDirectory(service);
+    return {
+        directory,
+        catalog: `${directory}/catalog.json`,
+        summary: `${directory}/catalog.md`,
+        operations: `${directory}/operations.md`,
+        auth: `${directory}/auth.json`,
+        masking: `${directory}/masking.json`,
+        gitignore: `${directory}/.gitignore`
+    };
+};
+/** A directory-safe service name: explicit, else the WSDL's service, else the file name. */
+export const serviceName = (catalog, location, explicit) => {
+    const raw = explicit ??
+        catalog.endpoints[0]?.service ??
+        basename(location.replace(/[?#].*$/, "")).replace(/\.[^.]*$/, "");
+    const safe = raw.replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+    return safe === "" ? "service" : safe;
+};
+/** What never leaves the machine: credentials references, raw captures, the masking key. */
+export const serviceGitignore = ["auth.json", "raw/", ".masking-key", ""].join("\n");
+export const loadAuthProfile = (workspace, service) => Effect.flatMap(readIfPresent(workspace, servicePaths(service).auth), (text) => text === undefined ? Effect.succeed(undefined) : decodeAuthProfile(text));
+export const readIfPresent = (workspace, path) => Effect.flatMap(workspace.discover(path), (found) => found.includes(path) ? workspace.read(path) : Effect.succeed(undefined));
+export const encodeCatalog = (catalog) => `${JSON.stringify(Schema.encodeSync(WsdlCatalog)(catalog), null, 2)}\n`;
+export const loadCatalog = (workspace, service) => {
+    const path = servicePaths(service).catalog;
+    return Effect.flatMap(workspace.read(path), (text) => Schema.decodeUnknownEffect(Schema.fromJsonString(WsdlCatalog))(text).pipe(Effect.mapError((error) => new CatalogFileError({ path, detail: `not a catalog: ${error.message}` }))));
+};
+export const loadOperationsFile = (workspace, service) => Effect.flatMap(readIfPresent(workspace, servicePaths(service).operations), (text) => text === undefined ? Effect.succeed(undefined) : parseOperationsFile(text));
+const occurs = (min, max) => max === "unbounded" ? `${min}..*` : min === max ? `${min}` : `${min}..${max}`;
+const fieldLines = (catalog, element) => {
+    if (element === undefined)
+        return ["  (none)"];
+    const declared = elementByName(catalog, element);
+    const type = typeByName(catalog, declared?.type ?? "");
+    if (!(type instanceof ComplexTypeDef)) {
+        return [`  - value: ${localName(declared?.type ?? element)}`];
+    }
+    return type.fields.map((field) => `  - ${field.name}: ${localName(field.type)} [${occurs(field.minOccurs, field.maxOccurs)}]${field.nillable ? " nillable" : ""}`);
+};
+const operationSection = (catalog, operation) => [
+    `### ${operation.name}`,
+    "",
+    ...(operation.documentation === undefined ? [] : [operation.documentation, ""]),
+    `- SOAPAction: \`${operation.soapAction}\``,
+    `- SOAP ${operation.soapVersion}, binding ${operation.binding}, ${operation.wrapped ? "wrapped" : "bare"}`,
+    `- request \`${localName(operation.input)}\`:`,
+    ...fieldLines(catalog, operation.input),
+    `- response \`${operation.output === undefined ? "(one-way)" : localName(operation.output)}\`:`,
+    ...fieldLines(catalog, operation.output),
+    `- faults: ${operation.faults.length === 0 ? "none" : operation.faults.map((fault) => `${fault.name} (${localName(fault.element)})`).join(", ")}`,
+    ""
+];
+export const renderCatalogSummary = (service, catalog) => {
+    const namedTypes = catalog.types.filter((type) => !type.anonymous);
+    const namespaces = [...new Set(catalog.types.map((type) => splitClark(type.name).namespace))];
+    return [
+        `# SOAP catalog: ${service}`,
+        "",
+        `WSDL ${catalog.wsdlVersion}, target namespace \`${catalog.targetNamespace}\`. Generated by`,
+        "`soap-discover` from the documents below; regenerate rather than edit.",
+        "",
+        "## Summary",
+        "",
+        `- ${catalog.operations.length} operations, ${catalog.endpoints.length} endpoints`,
+        `- ${namedTypes.length} named types, ${catalog.elements.length} global elements across ${namespaces.length} namespaces`,
+        `- ${catalog.openQuestions.length} open questions`,
+        "",
+        "## Documents",
+        "",
+        ...catalog.documents.map((document) => `- ${document}`),
+        "",
+        "## Endpoints",
+        "",
+        ...(catalog.endpoints.length === 0
+            ? ["(none declared)"]
+            : catalog.endpoints.map((endpoint) => `- ${endpoint.service}/${endpoint.port} — SOAP ${endpoint.soapVersion} — ${endpoint.address}`)),
+        "",
+        "## Open questions",
+        "",
+        ...(catalog.openQuestions.length === 0
+            ? ["None: every construct in the WSDL and its schemas is modelled."]
+            : catalog.openQuestions.map((question) => `- **${question.code}** ${question.subject} (${question.location}): ${question.detail}`)),
+        "",
+        "## Operations",
+        "",
+        ...catalog.operations.flatMap((operation) => operationSection(catalog, operation))
+    ].join("\n");
+};
+export const discoverService = (options) => Effect.gen(function* () {
+    const catalog = yield* readCatalog(options.location);
+    const service = serviceName(catalog, options.location, options.service);
+    const paths = servicePaths(service);
+    yield* options.workspace.write(paths.gitignore, serviceGitignore);
+    yield* options.workspace.write(paths.catalog, encodeCatalog(catalog));
+    yield* options.workspace.write(paths.summary, renderCatalogSummary(service, catalog));
+    const existing = yield* loadOperationsFile(options.workspace, service);
+    if (existing !== undefined) {
+        return {
+            service,
+            paths,
+            catalog,
+            proposals: undefined,
+            existing,
+            drift: operationsDrift(existing, catalog)
+        };
+    }
+    const proposals = yield* classifyOperations(catalog, options.judgment);
+    yield* options.workspace.write(paths.operations, renderOperationsFile(service, catalog, proposals));
+    return {
+        service,
+        paths,
+        catalog,
+        proposals,
+        existing: undefined,
+        drift: { missing: [], unknown: [] }
+    };
+});

package/kits/soap-ace/flows/lib/soap/Envelope.js

@@ -0,0 +1,132 @@
+import { createHash } from "node:crypto";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import * as Schema from "effect/Schema";
+import { elements, escapeAttribute, escapeText, firstChild, is, textOf } from "./Xml.js";
+// SOAP envelopes: building a request around a body, the WS-Security
+// UsernameToken header, reading a response (body or fault), and removing
+// every security header before an exchange is persisted.
+export const Soap11Namespace = "http://schemas.xmlsoap.org/soap/envelope/";
+export const Soap12Namespace = "http://www.w3.org/2003/05/soap-envelope";
+export const WsseNamespace = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd";
+export const WsuNamespace = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd";
+const TokenProfile = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0";
+const Base64Binary = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary";
+export const envelopeNamespace = (version) => version === "1.1" ? Soap11Namespace : Soap12Namespace;
+/** HTTP headers a SOAP request carries for its version. */
+export const soapHeaders = (version, soapAction) => version === "1.1"
+    ? { "content-type": "text/xml; charset=utf-8", soapaction: `"${soapAction}"` }
+    : {
+        "content-type": `application/soap+xml; charset=utf-8${soapAction === "" ? "" : `; action="${escapeAttribute(soapAction)}"`}`
+    };
+/** `Base64(SHA-1(nonce + created + password))`, per the UsernameToken profile. */
+export const passwordDigest = (material, password) => createHash("sha1")
+    .update(Buffer.from(material.nonce))
+    .update(material.created, "utf8")
+    .update(password, "utf8")
+    .digest("base64");
+export const usernameTokenHeader = (token, material) => {
+    const password = Redacted.value(token.password);
+    const passwordValue = token.passwordType === "digest" ? passwordDigest(material, password) : password;
+    const type = token.passwordType === "digest" ? "PasswordDigest" : "PasswordText";
+    return Redacted.make([
+        `<wsse:Security xmlns:wsse="${WsseNamespace}" xmlns:wsu="${WsuNamespace}" soapenv:mustUnderstand="1">`,
+        '<wsse:UsernameToken wsu:Id="UsernameToken-1">',
+        `<wsse:Username>${escapeText(token.user)}</wsse:Username>`,
+        `<wsse:Password Type="${TokenProfile}#${type}">${escapeText(passwordValue)}</wsse:Password>`,
+        `<wsse:Nonce EncodingType="${Base64Binary}">${Buffer.from(material.nonce).toString("base64")}</wsse:Nonce>`,
+        `<wsu:Created>${material.created}</wsu:Created>`,
+        "</wsse:UsernameToken>",
+        "</wsse:Security>"
+    ].join(""));
+};
+/**
+ * Wrap a body element (serialized XML, carrying its own namespace
+ * declarations) in an envelope. The header, when present, is secret
+ * material and so is the whole envelope that includes it.
+ */
+export const buildEnvelope = (version, body, header) => Redacted.make([
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    `<soapenv:Envelope xmlns:soapenv="${envelopeNamespace(version)}">`,
+    header === undefined ? "" : `<soapenv:Header>${Redacted.value(header)}</soapenv:Header>`,
+    `<soapenv:Body>${body}</soapenv:Body>`,
+    "</soapenv:Envelope>"
+].join(""));
+export class EnvelopeError extends Schema.TaggedError()("EnvelopeError", {
+    detail: Schema.String
+}) {
+    get message() {
+        return `SOAP envelope: ${this.detail}`;
+    }
+}
+export class SoapFault extends Schema.Class("SoapFault")({
+    code: Schema.String,
+    reason: Schema.String,
+    /** Local name of the detail's first element, e.g. `ServizioFault`. */
+    detailElement: Schema.optionalKey(Schema.String)
+}) {
+}
+export const readEnvelope = (root) => Effect.suspend(() => {
+    const read = readEnvelopeSync(root);
+    return read instanceof EnvelopeError ? Effect.fail(read) : Effect.succeed(read);
+});
+const readEnvelopeSync = (root) => {
+    const version = is(root, Soap11Namespace, "Envelope")
+        ? "1.1"
+        : is(root, Soap12Namespace, "Envelope")
+            ? "1.2"
+            : undefined;
+    if (version === undefined) {
+        return new EnvelopeError({
+            detail: `root is {${root.name.namespace}}${root.name.local}, not a SOAP Envelope`
+        });
+    }
+    const namespace = envelopeNamespace(version);
+    const body = firstChild(root, namespace, "Body");
+    if (body === undefined)
+        return new EnvelopeError({ detail: "envelope has no Body" });
+    const payload = elements(body)[0];
+    if (payload === undefined || !is(payload, namespace, "Fault")) {
+        return { version, payload, fault: undefined };
+    }
+    const unqualified = (local) => elements(payload).find((child) => child.name.local === local);
+    const deep = (element, ...path) => path.reduce((current, local) => current === undefined
+        ? undefined
+        : elements(current).find((child) => child.name.local === local), element);
+    const fault = version === "1.1"
+        ? new SoapFault({
+            code: optionalText(unqualified("faultcode")),
+            reason: optionalText(unqualified("faultstring")),
+            ...detailOf(unqualified("detail"))
+        })
+        : new SoapFault({
+            code: optionalText(deep(payload, "Code", "Value")),
+            reason: optionalText(deep(payload, "Reason", "Text")),
+            ...detailOf(unqualified("Detail"))
+        });
+    return { version, payload, fault };
+};
+/** A fault part's text; absent parts are empty, never the whole fault's text. */
+const optionalText = (element) => element === undefined ? "" : textOf(element).trim();
+const detailOf = (detail) => {
+    const first = detail === undefined ? undefined : elements(detail)[0];
+    return first === undefined ? {} : { detailElement: first.name.local };
+};
+/** Remove every WS-Security header block (any version of the wsse namespace). */
+export const stripSecurity = (root) => {
+    const isSecurity = (node) => node._tag === "element" &&
+        node.name.local === "Security" &&
+        /wss|secext/i.test(node.name.namespace);
+    const walk = (element) => ({
+        ...element,
+        children: element.children
+            .filter((child) => !isSecurity(child))
+            .map((child) => (child._tag === "element" ? walk(child) : child))
+    });
+    return walk(root);
+};
+const sensitiveHeader = /^(authorization|proxy-authorization|cookie|set-cookie|x-api-key)$|token|secret|password|session|auth/i;
+/** Response and request headers safe to persist. */
+export const safeHeaders = (headers) => Object.fromEntries(Object.entries(headers)
+    .filter(([name]) => !sensitiveHeader.test(name))
+    .map(([name, value]) => [name.toLowerCase(), value]));