adfinem 0.0.0 → 0.1.1

package/src/adapters/db/oracle-client.ts

@@ -0,0 +1,133 @@
+import type { EnvironmentConfig } from "../../config/environments.js";
+import type { DbExecuteResult, QueryCatalogEntry } from "../../dsl/types.js";
+import { assertQueryResult } from "./assertions.js";
+import { normalizeBindParamRecord, validateQueryParams } from "./query-catalog.js";
+
+type OracleDbModule = {
+  OUT_FORMAT_OBJECT: unknown;
+  getConnection(config: { user?: string; password?: string; connectString?: string }): Promise<{
+    execute(sql: string, binds: Record<string, unknown>, options: Record<string, unknown>): Promise<{ rows?: Record<string, unknown>[] }>;
+    close(): Promise<void>;
+  }>;
+};
+
+export class OracleClient {
+  constructor(private readonly env: EnvironmentConfig) {}
+
+  async query(entry: QueryCatalogEntry, params: Record<string, unknown>): Promise<Record<string, unknown>[]> {
+    const bindParams = normalizeBindParamRecord(params);
+    validateQueryParams(entry, bindParams);
+    if (!this.env.oracle.user || !this.env.oracle.password || !this.env.oracle.connectString) {
+      throw new Error("ADFINEM_DB_USER, ADFINEM_DB_PASSWORD, and ADFINEM_DB_CONNECT_STRING are required for DB execution.");
+    }
+
+    const oracledb = await loadOracleDbModule();
+    const connection = await oracledb.getConnection(this.env.oracle);
+    try {
+      const prepared = expandArrayBinds(entry.sql, bindParams);
+      const result = await connection.execute(prepared.sql, prepared.binds, { outFormat: oracledb.OUT_FORMAT_OBJECT });
+      return limitRows(result.rows ?? [], entry.maxRows);
+    } finally {
+      await closeQuietly(connection);
+    }
+  }
+
+  async assert(entry: QueryCatalogEntry, params: Record<string, unknown>): Promise<Record<string, unknown>[]> {
+    const rows = await this.query(entry, params);
+    assertQueryResult(entry, rows);
+    return rows;
+  }
+
+  async execute(entry: QueryCatalogEntry, params: Record<string, unknown>): Promise<DbExecuteResult> {
+    const bindParams = normalizeBindParamRecord(params);
+    validateQueryParams(entry, bindParams);
+    if (!this.env.oracle.user || !this.env.oracle.password || !this.env.oracle.connectString) {
+      throw new Error("ADFINEM_DB_USER, ADFINEM_DB_PASSWORD, and ADFINEM_DB_CONNECT_STRING are required for DB execution.");
+    }
+
+    const oracledb = await loadOracleDbModule();
+    const connection = await oracledb.getConnection(this.env.oracle);
+    try {
+      const prepared = expandArrayBinds(entry.sql, bindParams);
+      const result = await connection.execute(prepared.sql, prepared.binds, {
+        outFormat: oracledb.OUT_FORMAT_OBJECT,
+        autoCommit: true
+      });
+      const execution = result as { rowsAffected?: number; outBinds?: Record<string, unknown> };
+      return {
+        status: "passed",
+        rowsAffected: execution.rowsAffected,
+        outBinds: execution.outBinds
+      };
+    } finally {
+      await closeQuietly(connection);
+    }
+  }
+}
+
+async function closeQuietly(connection: { close(): Promise<void> }): Promise<void> {
+  try {
+    await connection.close();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    // Connection close failures must not mask the operation error from the surrounding try.
+    console.warn(`Oracle connection close failed: ${message}`);
+  }
+}
+
+let oracleDbModule: OracleDbModule | undefined;
+
+async function loadOracleDbModule(): Promise<OracleDbModule> {
+  if (oracleDbModule) return oracleDbModule;
+  try {
+    const imported = await import("oracledb") as unknown;
+    oracleDbModule = normalizeOracleDbModule(imported);
+    return oracleDbModule;
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    throw new Error(`Could not load optional dependency 'oracledb'. Run 'npm install' and ensure Oracle client libraries are available. Original error: ${err.message}`);
+  }
+}
+
+function normalizeOracleDbModule(imported: unknown): OracleDbModule {
+  const moduleValue = imported as OracleDbModule & { default?: OracleDbModule };
+  const candidate = typeof moduleValue.getConnection === "function" ? moduleValue : moduleValue.default;
+  if (!candidate || typeof candidate.getConnection !== "function") {
+    throw new Error("Loaded 'oracledb', but it did not expose getConnection().");
+  }
+  return candidate;
+}
+
+function limitRows(rows: Record<string, unknown>[], maxRows: number | undefined): Record<string, unknown>[] {
+  if (maxRows === undefined) return rows;
+  return rows.slice(0, maxRows);
+}
+
+function expandArrayBinds(sql: string, params: Record<string, unknown>): { sql: string; binds: Record<string, unknown> } {
+  const binds: Record<string, unknown> = {};
+  let expandedSql = sql;
+
+  for (const [name, value] of Object.entries(params)) {
+    if (!Array.isArray(value)) {
+      binds[name] = value;
+      continue;
+    }
+
+    if (value.length === 0) {
+      throw new Error(`Query param '${name}' must contain at least one value.`);
+    }
+
+    const placeholders = value.map((entry, index) => {
+      const bindName = `${name}_${index}`;
+      binds[bindName] = entry;
+      return `:${bindName}`;
+    });
+    expandedSql = expandedSql.replace(new RegExp(`:${escapeRegExp(name)}\\b`, "g"), placeholders.join(", "));
+  }
+
+  return { sql: expandedSql, binds };
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/adapters/db/query-catalog.ts

@@ -0,0 +1,80 @@
+import { isLuhnValid } from "../../config/secrets.js";
+import type { CatalogParam, QueryCatalogEntry } from "../../dsl/types.js";
+
+export function validateQueryParams(entry: QueryCatalogEntry, params: Record<string, unknown>): void {
+  const specs = normalizeBindParamRecord(entry.params ?? {});
+  const normalizedParams = normalizeBindParamRecord(params);
+  for (const [name, spec] of Object.entries(specs)) {
+    const value = normalizedParams[name];
+    if (spec.required && (value === undefined || value === null || value === "")) {
+      throw new Error(`Missing required query param '${name}'.`);
+    }
+    validateParamValue(name, value, spec);
+  }
+}
+
+export function normalizeQueryCatalog(queries: Record<string, QueryCatalogEntry>): Record<string, QueryCatalogEntry> {
+  return Object.fromEntries(Object.entries(queries).map(([id, entry]) => [id, normalizeQueryCatalogEntry(entry)]));
+}
+
+export function normalizeQueryCatalogEntry(entry: QueryCatalogEntry): QueryCatalogEntry {
+  return {
+    ...entry,
+    params: entry.params ? normalizeBindParamRecord(entry.params) : undefined
+  };
+}
+
+export function normalizeBindParamRecord<T>(value: Record<string, T>): Record<string, T> {
+  const normalized: Record<string, T> = {};
+  for (const [name, entry] of Object.entries(value)) {
+    const bindName = normalizeBindParamName(name);
+    if (bindName) normalized[bindName] = entry;
+  }
+  return normalized;
+}
+
+export function normalizeBindParamName(name: string): string {
+  return String(name ?? "").trim().replace(/^:+/, "");
+}
+
+function validateParamValue(name: string, value: unknown, spec: CatalogParam): void {
+  if (value === undefined || value === null) return;
+  if (spec.type?.endsWith("[]")) {
+    const expectedItemType = spec.type.slice(0, -"[]".length);
+    const values = Array.isArray(value) ? value : [value];
+    if (values.length === 0) throw new Error(`Query param '${name}' must contain at least one value.`);
+    for (const item of values) {
+      if (typeof item !== expectedItemType) {
+        throw new Error(`Query param '${name}' must be ${spec.type}; got ${typeof item} item.`);
+      }
+      validatePattern(name, item, spec);
+      validateLuhn(name, item, spec);
+    }
+    return;
+  }
+  if (spec.type && typeof value !== spec.type) {
+    throw new Error(`Query param '${name}' must be ${spec.type}; got ${typeof value}.`);
+  }
+  validatePattern(name, value, spec);
+  validateLuhn(name, value, spec);
+}
+
+function validatePattern(name: string, value: unknown, spec: CatalogParam): void {
+  if (spec.pattern && typeof value === "string" && !new RegExp(spec.pattern).test(value)) {
+    throw new Error(`Query param '${name}' does not match ${spec.pattern}.`);
+  }
+}
+
+function validateLuhn(name: string, value: unknown, spec: CatalogParam): void {
+  if (!spec.luhn) return;
+  if (typeof value !== "string" && typeof value !== "number") {
+    throw new Error(`Query param '${name}' must be a string or number for Luhn validation.`);
+  }
+  const digits = String(value).replace(/\D+/g, "");
+  if (digits.length < 12 || digits.length > 19) {
+    throw new Error(`Query param '${name}' must be 12-19 digits for Luhn validation.`);
+  }
+  if (!isLuhnValid(digits)) {
+    throw new Error(`Query param '${name}' fails Luhn check.`);
+  }
+}

package/src/adapters/unix/batch-catalog.ts

@@ -0,0 +1,81 @@
+import type { BatchCatalogEntry } from "../../dsl/types.js";
+
+export function buildBatchCommand(entry: BatchCatalogEntry, params: Record<string, unknown>): string {
+  return buildBatchCommandDetails(entry, params).command;
+}
+
+export function buildBatchDisplayCommand(entry: BatchCatalogEntry, params: Record<string, unknown>): string {
+  return buildBatchCommandDetails(entry, params).displayCommand;
+}
+
+export interface BuiltBatchCommand {
+  command: string;
+  displayCommand: string;
+}
+
+export function buildBatchCommandDetails(entry: BatchCatalogEntry, params: Record<string, unknown>, extraArgs: Array<string | number | boolean> = []): BuiltBatchCommand {
+  const fixedArgs = (entry.fixedArgs ?? []).map((value) => resolvePlaceholders(String(value), params));
+  const args = (entry.args ?? []).map((arg) => {
+    const hasValue = Object.prototype.hasOwnProperty.call(params, arg.name);
+    const value = params[arg.name];
+    if (!hasValue || value === undefined || value === null) {
+      return undefined;
+    }
+    if (value === "") {
+      if (arg.required === false) return undefined;
+      throw new Error(`Missing required batch arg '${arg.name}'.`);
+    }
+    if (arg.pattern && !new RegExp(arg.pattern).test(String(value))) {
+      throw new Error(`Batch arg '${arg.name}' does not match ${arg.pattern}.`);
+    }
+    return resolvePlaceholders(String(value), params);
+  }).filter((value): value is string => Boolean(value));
+  const appendedArgs = extraArgs.map((value) => resolvePlaceholders(String(value), params));
+
+  const commandTokens = [resolvePlaceholders(entry.command, params), ...fixedArgs, ...args, ...appendedArgs];
+  const command = commandTokens.map(shellQuote).join(" ");
+  const displayCommand = commandTokens.map(displayToken).join(" ");
+  const envEntries = Object.entries(entry.environment ?? {})
+    .map(([name, value]) => [name, resolvePlaceholders(String(value), params)] as const);
+  const envPrefix = envEntries
+    .map(([name, value]) => `${name}=${shellQuote(value)}`)
+    .join(" ");
+  const displayEnvPrefix = envEntries
+    .map(([name, value]) => `${name}=${displayToken(value)}`)
+    .join(" ");
+  const commandWithEnv = envPrefix ? `${envPrefix} ${command}` : command;
+  const displayCommandWithEnv = displayEnvPrefix ? `${displayEnvPrefix} ${displayCommand}` : displayCommand;
+  const workingDirectory = entry.useWorkingDirectory === true
+    ? blankToUndefined(entry.workingDirectory ? resolvePlaceholders(entry.workingDirectory, params) : undefined)
+    : undefined;
+  return {
+    command: workingDirectory
+      ? `cd ${shellQuote(workingDirectory)} && ${commandWithEnv}`
+      : commandWithEnv,
+    displayCommand: workingDirectory
+      ? `cd ${displayToken(workingDirectory)} && ${displayCommandWithEnv}`
+      : displayCommandWithEnv
+  };
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+function resolvePlaceholders(value: string, params: Record<string, unknown>): string {
+  return value.replace(/\$\{([A-Za-z0-9_.-]+)\}/g, (_match, name: string) => {
+    const paramValue = params[name];
+    if (paramValue !== undefined && paramValue !== null) return String(paramValue);
+    return process.env[name] ?? "";
+  });
+}
+
+function displayToken(value: string): string {
+  if (value === "") return "\"\"";
+  if (/^[A-Za-z0-9_./:=@%+-]+$/.test(value)) return value;
+  return `"${value.replace(/(["\\$`])/g, "\\$1")}"`;
+}
+
+function blankToUndefined(value: string | undefined): string | undefined {
+  return value && value.trim() ? value : undefined;
+}

package/src/adapters/unix/batch-input-files.ts

@@ -0,0 +1,39 @@
+import type { BatchCatalogEntry, BatchInputFileSpec, BatchInputFileValue } from "../../dsl/types.js";
+
+export function batchInputFiles(entry: BatchCatalogEntry | undefined): BatchInputFileSpec[] {
+  return entry?.inputFiles ?? [];
+}
+
+export function batchInputFileParamNames(entry: BatchCatalogEntry | undefined): string[] {
+  return batchInputFiles(entry).flatMap((file) => {
+    const names = [file.name];
+    if (file.paramName && file.paramName !== file.name) names.push(file.paramName);
+    return names;
+  });
+}
+
+export function batchFileBackedArgNames(entry: BatchCatalogEntry | undefined): Set<string> {
+  return new Set(batchInputFiles(entry).map((file) => file.paramName || file.name));
+}
+
+export function isBatchInputFileValue(value: unknown): value is BatchInputFileValue {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+export function hasBatchInputFilePayload(value: unknown): boolean {
+  if (typeof value === "string") return value.trim().length > 0;
+  if (!isBatchInputFileValue(value)) return false;
+  return Boolean(value.localPath || value.contentBase64);
+}
+
+export function batchArgParamsForValidation(params: Record<string, unknown>, entry: BatchCatalogEntry | undefined): Record<string, unknown> {
+  const next = { ...params };
+  for (const file of batchInputFiles(entry)) {
+    const value = params[file.name];
+    if (!hasBatchInputFilePayload(value)) continue;
+    next[file.paramName || file.name] = isBatchInputFileValue(value)
+      ? value.remotePath || file.remotePath || "__uploaded_input_file__"
+      : file.remotePath || "__uploaded_input_file__";
+  }
+  return next;
+}