adfinem 0.0.0 → 0.1.0

package/src/engine/captures.ts

@@ -0,0 +1,66 @@
+import { JSONPath } from "jsonpath-plus";
+
+export function extractCaptures(payload: unknown, specs: Record<string, string> | undefined): Record<string, unknown> {
+  const captures: Record<string, unknown> = {};
+  for (const [name, expression] of Object.entries(specs ?? {})) {
+    const value = extractCaptureValue(payload, expression);
+    if (value !== undefined) captures[name] = value;
+  }
+  return captures;
+}
+
+export function mergeCaptureSpecs(...specs: Array<Record<string, string> | undefined>): Record<string, string> {
+  return Object.assign({}, ...specs.filter(Boolean));
+}
+
+function extractCaptureValue(payload: unknown, expression: string): unknown {
+  const { expression: trimmed, required } = parseCaptureExpression(expression);
+  if (!trimmed) throw new Error("Capture expression must not be empty.");
+  try {
+    if (trimmed.startsWith("literal:")) return trimmed.slice("literal:".length);
+    if (trimmed.startsWith("regex:")) return extractRegexCapture(payload, trimmed);
+    return extractJsonPathCapture(payload, normalizeJsonPath(trimmed), trimmed);
+  } catch (error) {
+    if (!required && isCaptureNoMatch(error)) return undefined;
+    throw error;
+  }
+}
+
+function parseCaptureExpression(expression: string): { expression: string; required: boolean } {
+  const trimmed = expression.trim();
+  if (trimmed.startsWith("optional:")) {
+    return { expression: trimmed.slice("optional:".length).trim(), required: false };
+  }
+  return { expression: trimmed, required: true };
+}
+
+function extractJsonPathCapture(payload: unknown, jsonPath: string, original: string): unknown {
+  const json = payload as string | number | boolean | object | unknown[] | null;
+  const values = JSONPath({ path: jsonPath, json, wrap: true }) as unknown as unknown[];
+  if (values.length === 0) throw new Error(`Capture expression '${original}' did not match any value.`);
+  return values.length === 1 ? values[0] : values;
+}
+
+function extractRegexCapture(payload: unknown, expression: string): string {
+  const parts = expression.split(":");
+  if (parts.length < 3) {
+    throw new Error(`Invalid regex capture '${expression}'. Use regex:<jsonpath>:<pattern>.`);
+  }
+  const sourcePath = parts[1]?.trim() || "$";
+  const pattern = parts.slice(2).join(":");
+  const source = extractJsonPathCapture(payload, normalizeJsonPath(sourcePath), sourcePath);
+  const match = String(source ?? "").match(new RegExp(pattern, "m"));
+  if (!match) throw new Error(`Regex capture '${expression}' did not match.`);
+  return match[1] ?? match[0];
+}
+
+function normalizeJsonPath(expression: string): string {
+  if (expression.startsWith("$")) return expression;
+  if (/^[A-Za-z_][A-Za-z0-9_]*(?:[.[].*)?$/.test(expression)) return `$.${expression}`;
+  throw new Error(`Unsupported capture expression '${expression}'. Use JSONPath, simple property path, literal:, or regex:.`);
+}
+
+function isCaptureNoMatch(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return /did not match any value|did not match\./i.test(message);
+}

package/src/engine/context.ts

@@ -0,0 +1,76 @@
+import type { Scenario } from "../dsl/types.js";
+
+export class RunContext {
+  private readonly values = new Map<string, unknown>();
+
+  constructor(scenario: Scenario) {
+    for (const [key, value] of Object.entries(scenario.variables ?? {})) {
+      this.values.set(key, value);
+    }
+    for (const [key, value] of Object.entries(scenario.tenant ?? {})) {
+      this.values.set(`tenant.${key}`, value);
+    }
+  }
+
+  set(name: string, value: unknown): void {
+    this.values.set(name, value);
+  }
+
+  get(name: string): unknown {
+    return this.values.get(name);
+  }
+
+  snapshot(): Record<string, unknown> {
+    return Object.fromEntries(this.values);
+  }
+
+  restore(snapshot: Record<string, unknown>): void {
+    this.values.clear();
+    for (const [key, value] of Object.entries(snapshot)) this.values.set(key, value);
+  }
+
+  resolve<T>(value: T): T {
+    return this.resolveValue(value) as T;
+  }
+
+  private resolveValue(value: unknown): unknown {
+    if (typeof value === "string") {
+        const exact = /^\$\{([^}]+)\}$/.exec(value);
+      if (exact) {
+        const resolved = this.values.get(exact[1]);
+        if (resolved === undefined || resolved === null) {
+          throw new Error(`Variable '${exact[1]}' is not available in run context.`);
+        }
+        return resolved;
+      }
+      const postmanExact = /^\{\{([A-Za-z0-9_.-]+)\}\}$/.exec(value);
+      if (postmanExact) {
+        const resolved = this.values.get(postmanExact[1]);
+        if (resolved === undefined || resolved === null) {
+          throw new Error(`Variable '${postmanExact[1]}' is not available in run context.`);
+        }
+        return resolved;
+      }
+      return value
+        .replace(/\$\{([^}]+)\}/g, (_match, name: string) => {
+          const resolved = this.values.get(name);
+          if (resolved === undefined || resolved === null) {
+            throw new Error(`Variable '${name}' is not available in run context.`);
+          }
+          return String(resolved);
+        })
+        .replace(/\{\{([A-Za-z0-9_.-]+)\}\}/g, (_match, name: string) => {
+        const resolved = this.values.get(name);
+        if (resolved === undefined || resolved === null) {
+          throw new Error(`Variable '${name}' is not available in run context.`);
+        }
+        return String(resolved);
+      });
+    }
+    if (Array.isArray(value)) return value.map((item) => this.resolveValue(item));
+    if (value && typeof value === "object") {
+      return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, this.resolveValue(entry)]));
+    }
+    return value;
+  }
+}

package/src/engine/evidence.ts

@@ -0,0 +1,35 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { applyEvidenceVisibility, evidenceVisibilityMode } from "../config/secrets.js";
+import type { EvidenceVisibilityMode } from "../dsl/types.js";
+
+export class EvidenceWriter {
+  constructor(public readonly runDir: string, private readonly visibility: EvidenceVisibilityMode = evidenceVisibilityMode()) {}
+
+  async init(): Promise<void> {
+    await mkdir(this.runDir, { recursive: true });
+  }
+
+  async writeJson(name: string, value: unknown): Promise<string> {
+    const path = join(this.runDir, sanitizeName(name));
+    await writeFile(path, JSON.stringify(applyEvidenceVisibility(value, this.visibility), null, 2), "utf8");
+    return path;
+  }
+
+  async writeJsonPath(relativePath: string, value: unknown): Promise<string> {
+    const path = join(this.runDir, ...relativePath.split(/[\\/]+/).map(sanitizeName));
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(applyEvidenceVisibility(value, this.visibility), null, 2), "utf8");
+    return path;
+  }
+
+  async writeText(name: string, value: string): Promise<string> {
+    const path = join(this.runDir, sanitizeName(name));
+    await writeFile(path, value, "utf8");
+    return path;
+  }
+}
+
+function sanitizeName(name: string): string {
+  return name.replace(/[^A-Za-z0-9_.-]/g, "_");
+}

package/src/engine/known-errors.ts

@@ -0,0 +1,145 @@
+export interface KnownErrorMessage {
+  message: string;
+  hints: string[];
+}
+
+export function explainKnownError(error: unknown): KnownErrorMessage {
+  const err = error instanceof Error ? error : new Error(String(error));
+  const text = `${err.name}: ${err.message}`;
+  const hints: string[] = [];
+  let message = err.message;
+
+  if (/Invalid JSON for --params|Invalid JSON value for --param/i.test(text)) {
+    hints.push("In PowerShell, prefer repeated --param name=value options instead of --params JSON.");
+    hints.push("Example: --param case_id=CASE-1001 --param case_id=CASE-1002");
+  }
+  if (/Invalid JSON for --input/i.test(text)) {
+    hints.push("In PowerShell, wrap JSON input in single quotes or escape double quotes.");
+    hints.push("Example: --input '{\"application_id\":\"000000000000000000001452\"}'");
+  }
+
+  if (err instanceof SyntaxError && (/json/i.test(err.message) || /Expected property name|Unexpected token|Unexpected end/.test(err.message))) {
+    message = `Invalid JSON argument: ${err.message}`;
+    hints.push("In PowerShell, prefer repeated --param name=value options instead of --params JSON.");
+    hints.push("Example: --param case_id=CASE-1001 --param case_id=CASE-1002");
+  }
+
+  if (/ADFINEM_DB_USER|ADFINEM_DB_PASSWORD|ADFINEM_DB_CONNECT_STRING/.test(text)) {
+    hints.push("Set ADFINEM_DB_USER, ADFINEM_DB_PASSWORD, and ADFINEM_DB_CONNECT_STRING in .env or your shell.");
+    hints.push("Example connect string: <host>:1521/<service>");
+  }
+
+  if (/DPI-1047|Cannot locate an Oracle Client library/i.test(text)) {
+    message = "Oracle client libraries are not available to node-oracledb.";
+    hints.push("Install/configure Oracle Instant Client and make sure its directory is on PATH.");
+  }
+
+  if (/oracledb\.getConnection is not a function|did not expose getConnection/i.test(text)) {
+    message = "The oracledb module loaded in an unexpected shape.";
+    hints.push("Run npm install again, then npm run build. This runner supports both ESM default and direct oracledb exports.");
+  }
+
+  addOracleHint(text, hints);
+  addSshHint(text, hints);
+  addCatalogHint(text, hints);
+
+  return { message, hints: unique(hints) };
+}
+
+export function formatKnownError(error: unknown): string {
+  const explained = explainKnownError(error);
+  if (!explained.hints.length) return explained.message;
+  return [
+    explained.message,
+    "",
+    "Hints:",
+    ...explained.hints.map((hint) => `- ${hint}`)
+  ].join("\n");
+}
+
+function addOracleHint(text: string, hints: string[]): void {
+  if (/ORA-01017/.test(text)) {
+    hints.push("Oracle rejected the username/password. Check ADFINEM_DB_USER and ADFINEM_DB_PASSWORD.");
+  }
+  if (/ORA-28000/.test(text)) {
+    hints.push("Oracle account is locked. Unlock/reset the DB user before rerunning.");
+  }
+  if (/ORA-12154/.test(text)) {
+    hints.push("Oracle could not resolve the connect identifier. Check ADFINEM_DB_CONNECT_STRING.");
+  }
+  if (/ORA-12514/.test(text)) {
+    hints.push("Oracle listener does not know the requested service. Check the service name in ADFINEM_DB_CONNECT_STRING.");
+  }
+  if (/ORA-12541|ECONNREFUSED/.test(text)) {
+    hints.push("Oracle listener connection was refused. Check host, port, VPN, and listener status.");
+  }
+  if (/ORA-12170|ETIMEDOUT|NJS-510|NJS-511/.test(text)) {
+    hints.push("Oracle connection timed out. Check network/VPN/firewall and DB host reachability.");
+  }
+  if (/ORA-00942/.test(text)) {
+    hints.push("Table or view does not exist for this schema, or the DB user lacks privileges.");
+  }
+  if (/ORA-00904/.test(text)) {
+    hints.push("Invalid column name. Check the Action Library SQL against the target environment schema.");
+  }
+  if (/ORA-01036|NJS-098/.test(text)) {
+    hints.push("SQL bind mismatch. Check Action Library parameter names and supplied --param values.");
+  }
+  if (/ORA-01722/.test(text)) {
+    hints.push("Invalid number. Use json: for numeric --param values, for example --param amount=json:111.");
+  }
+}
+
+function addSshHint(text: string, hints: string[]): void {
+  if (/Unknown SSH hostRef/.test(text)) {
+    hints.push("Add the hostRef under sshHosts in config/environments.yaml.");
+  }
+  if (/requires host and username/.test(text)) {
+    hints.push("Set the SSH host and username in config/environments.yaml/.env.");
+  }
+  if (/All configured authentication methods failed|Permission denied/i.test(text)) {
+    hints.push("SSH authentication failed. Check ADFINEM_SSH_USER, ADFINEM_SSH_PASSWORD, or ADFINEM_SSH_PRIVATE_KEY_PATH.");
+  }
+  if (/ENOTFOUND|getaddrinfo/.test(text)) {
+    hints.push("SSH host name could not be resolved. Check the host value and VPN/DNS.");
+  }
+  if (/ECONNREFUSED/.test(text)) {
+    hints.push("SSH connection was refused. Check host, port, firewall, and sshd status.");
+  }
+  if (/timed out|ETIMEDOUT/i.test(text)) {
+    hints.push("SSH command or connection timed out. Check server load, VPN, and the Action Library timeoutSeconds.");
+  }
+  if (/exit code 127|No such file or directory|command not found|not found/i.test(text)) {
+    hints.push("The Unix command did not find the batch script. Set ADFINEM_BATCH_WORKDIR in .env, or put an absolute script path in the Action Library batch template.");
+    hints.push("If the script lives on the remote server, ADFINEM_BATCH_WORKDIR must be the remote directory that contains reconcile_nightly.sh, generate_report.sh, and the other batch scripts.");
+    hints.push("If the command works only after an interactive SSH login, enable 'Run commands in login shell' for the SSH host in Environments.");
+  }
+  if (/ENOENT.*private|no such file/i.test(text)) {
+    hints.push("SSH private key path does not exist. Check ADFINEM_SSH_PRIVATE_KEY_PATH.");
+  }
+}
+
+function addCatalogHint(text: string, hints: string[]): void {
+  if (/Unknown API operation/.test(text)) {
+    hints.push("Run against an API operation present in the Action Library file catalogs/api-operations.yaml.");
+  }
+  if (/Unknown query/.test(text)) {
+    hints.push("Run against a query template present in the Action Library file catalogs/queries.yaml.");
+  }
+  if (/Unknown batch/.test(text)) {
+    hints.push("Run against a batch template present in the Action Library file catalogs/batches.yaml.");
+  }
+  if (/Missing required query param|Missing required batch arg/.test(text)) {
+    hints.push("Supply missing values with --param name=value or scenario params/input.");
+  }
+  if (/Capture expression .* did not match/i.test(text)) {
+    hints.push("A required capture did not exist in the action output. If this value is legitimately optional for the flow, prefix the capture expression with optional: in the Action Library template.");
+  }
+  if (/must be string\[\]|must contain at least one value/.test(text)) {
+    hints.push("For list params, pass one value or repeat --param. Example: --param case_id=CASE-1001 --param case_id=CASE-1002");
+  }
+}
+
+function unique(values: string[]): string[] {
+  return [...new Set(values)];
+}

package/src/engine/retry.ts

@@ -0,0 +1,11 @@
+export async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T> {
+  let timeout: NodeJS.Timeout | undefined;
+  const timeoutPromise = new Promise<never>((_resolve, reject) => {
+    timeout = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms.`)), timeoutMs);
+  });
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}