adfinem 0.0.0 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to Adfinem are documented here.
+
+## [0.1.0] - 2026-06-06
+
+- Publish the initial open-source Adfinem snapshot.
+- Include catalog-gated API, database, Unix batch, and flow automation.
+- Include smoke scenarios, sample flows, a React workbench, and compiled CLI output.
+- Add npm package metadata and publication safeguards.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,21 @@
+# Code of Conduct
+
+Adfinem follows the Contributor Covenant Code of Conduct.
+
+## Our Pledge
+
+We pledge to make participation in this project a harassment-free experience for everyone, regardless of background, identity, experience level, or viewpoint.
+
+## Expected Behavior
+
+- Be respectful and constructive.
+- Prefer clear technical discussion over personal criticism.
+- Assume good intent, while taking reported harm seriously.
+
+## Unacceptable Behavior
+
+Harassment, threats, discriminatory language, sustained disruption, or publishing private information without permission are not acceptable.
+
+## Enforcement
+
+Project maintainers may remove, edit, or reject comments, commits, issues, and pull requests that do not align with this Code of Conduct.

package/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+Thanks for helping improve Adfinem.
+
+## Local Setup
+
+```bash
+npm install
+npm run check
+npm run validate
+npm run smoke:dry
+```
+
+Use dry runs while changing catalog or environment configuration.
+
+## Development Notes
+
+- Keep scenarios catalog-gated; do not add arbitrary SQL, shell, or request bodies directly to scenario files when a catalog entry is the safer fit.
+- Do not commit `.env`, evidence folders, uploaded batch input files, or local logs.
+- Add or update tests when changing compiler, runner, adapter, or validation behavior.
+- Run `npm run package:dry-run` before proposing publication-related changes.
+
+## Pull Requests
+
+Please include:
+
+- A short summary of the change.
+- The commands you ran.
+- Any migration notes for catalogs, scenarios, or flows.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adfinem contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,87 @@
-# Adfinem Open Source Project
+# Adfinem
 
-Adfinem Open Source Project.
+Open-source end-to-end QA test helper for deterministic API, database, Unix batch, and workflow automation.
+
+Adfinem is built for testers working on enterprise-grade business solutions where repeatable, catalog-gated checks matter.
+
+Adfinem executes catalog-gated workflows only. Scenario YAML can reference:
+
+- `catalogs/api-operations.yaml`
+- `catalogs/queries.yaml`
+- `catalogs/batches.yaml`
+
+## What It Does
+
+Adfinem lets QA teams define repeatable end-to-end checks that combine:
+
+- REST API calls from an allowlisted operation catalog
+- database queries, assertions, and execution steps
+- Unix commands over SSH, including batch operations and file-backed processing
+- SFTP file placement before Unix jobs and output retrieval after they finish
+- workflow files that chain API, DB, Unix, loop, parallel, and reusable flow blocks
+- dry-run validation before touching external systems
+- evidence output for executed runs
+
+## Install
+
+```bash
+npm install
+npm run check
+```
+
+When published to npm, the CLI can also be installed globally:
+
+```bash
+npm install -g adfinem
+adfinem validate scenarios/smoke/account-processing-smoke.yaml
+```
+
+## Commands
+
+```bash
+npm install
+npm test
+npm run build
+npm run validate
+npm run smoke:dry
+```
+
+## CLI-Only Usage
+
+Adfinem can be used fully from the terminal when a GUI is not wanted.
+
+```bash
+# Validate a scenario before running it
+npm run adfinem -- validate scenarios/smoke/account-processing-smoke.yaml
+
+# Run a scenario without external side effects
+npm run adfinem -- run scenarios/smoke/account-processing-smoke.yaml --env local --dry-run
+
+# Execute a cataloged API operation
+npm run adfinem -- api-call create_test_case --env local --param tenant=demo --param external_id=CASE-1001 --param case_type=account-processing
+
+# Execute a cataloged DB query
+npm run adfinem -- db-query test_activity_exists --env local --param case_id=CASE-1001 --param amount=json:111
+
+# Run a cataloged Unix batch
+npm run adfinem -- run-batch daily_processing --env local --param processing_date=2026-04-27
+```
+
+Use `--dry-run` while catalogs and environment credentials are still being completed.
+
+See `docs/FLOW_BUILDER.md` for flow files and `docs/DB_UNIX_OPERATIONS.md` for database and Unix scenario steps.
+
+## Package Safety
+
+The npm package is allowlisted through `package.json#files` so local state such as `.env`, evidence, logs, dependencies, and uploaded batch input files are not included in published artifacts.
+
+Before publishing or opening a release PR, run:
+
+```bash
+npm run check
+npm run package:dry-run
+```
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,13 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please report suspected vulnerabilities privately through GitHub security advisories when available, or by contacting the repository owner directly.
+
+Do not include secrets, credentials, private endpoints, raw production payloads, or proprietary SQL in public issues.
+
+## Sensitive Data
+
+Adfinem is designed around catalog-gated actions, but users are still responsible for keeping local environment files, evidence, logs, and batch input files out of published artifacts.
+
+The repository `.gitignore` excludes common local-state paths such as `.env`, `evidence/`, `web-dist/`, and uploaded batch input files.

package/catalogs/api-operations.yaml

@@ -0,0 +1,21 @@
+create_test_case:
+  description: Creates a generic test case through an allowlisted API operation.
+  type: rest
+  method: POST
+  path: "/api/test-cases"
+  requestTemplate: "templates/api/create-test-case.json"
+  idempotent: false
+  captures:
+    case_id: "$.case.id"
+    case_status: "$.case.status"
+
+record_test_activity:
+  description: Records a generic activity against an existing test case.
+  type: rest
+  method: POST
+  path: "/api/test-activities"
+  requestTemplate: "templates/api/record-test-activity.json"
+  idempotent: false
+  captures:
+    activity_id: "$.activity.id"
+    activity_status: "$.activity.status"

package/catalogs/batches.yaml

@@ -0,0 +1,74 @@
+daily_processing:
+  description: Runs a daily processing batch for a processing date.
+  hostRef: qa_worker
+  command: run_daily_processing.sh
+  args:
+    - name: processing_date
+      required: true
+      pattern: ^\d{4}-\d{2}-\d{2}$
+  timeoutSeconds: 3600
+  success:
+    exitCodes:
+      - 0
+    requiredOutput:
+      - SUCCESS
+  captures:
+    daily_processing_exit_code: $.exitCode
+
+nightly_reconciliation:
+  description: Runs a generic nightly reconciliation batch.
+  hostRef: qa_worker
+  command: sh
+  fixedArgs:
+    - -x
+    - reconcile_nightly.sh
+    - reconcile_nightly.log
+  workingDirectory: ${ADFINEM_BATCH_WORKDIR}
+  timeoutSeconds: 7200
+  success:
+    exitCodes:
+      - 0
+      - 1
+  captures:
+    nightly_reconciliation_exit_code: $.exitCode
+
+report_generation:
+  description: Generates a generic QA report.
+  hostRef: qa_worker
+  command: sh
+  fixedArgs:
+    - -x
+    - generate_report.sh
+    - generate_report.log
+  workingDirectory: ${ADFINEM_BATCH_WORKDIR}
+  timeoutSeconds: 3600
+  success:
+    exitCodes:
+      - 0
+  outputFiles:
+    - name: report
+      source: stderr
+      pathPattern: "Generated file:\\s*(\\S+)"
+      download: true
+  captures:
+    report_generation_exit_code: $.exitCode
+
+import_transactions:
+  description: Imports a generic transaction file for downstream checks.
+  hostRef: qa_worker
+  command: sh
+  fixedArgs:
+    - -x
+    - import_transactions.sh
+    - ${transactions_file}
+  inputFiles:
+    - name: transactions_file
+      required: true
+      remotePath: /tmp/adfinem/inbox/
+      paramName: transactions_file
+  timeoutSeconds: 3600
+  success:
+    exitCodes:
+      - 0
+  captures:
+    import_transactions_exit_code: $.exitCode

package/catalogs/queries.yaml

@@ -0,0 +1,75 @@
+set_processing_date:
+  description: Updates a generic processing date before running batch automation.
+  mode: execute
+  sql: |
+    update test_run_control
+       set processing_date = to_date(:processing_date, 'YYYY-MM-DD')
+     where control_name = 'default';
+    commit;
+  params:
+    processing_date:
+      required: true
+      type: string
+      pattern: ^\d{4}-\d{2}-\d{2}$
+
+test_activity_exists:
+  description: Verifies an activity was recorded for a test case and amount.
+  sql: |
+    select count(*) as CNT
+      from test_activity
+     where case_id = :case_id
+       and amount = :amount
+  params:
+    case_id:
+      required: true
+      pattern: ^[0-9A-Za-z_-]+$
+    amount:
+      required: true
+      type: number
+  expect:
+    type: number
+    column: CNT
+    operator: ">"
+    value: 0
+  captures:
+    activity_count: $.rows[0].CNT
+
+processing_balanced:
+  description: Verifies debit and credit totals are balanced for a test case and processing date.
+  sql: |
+    select abs(nvl(sum(debit_amount), 0) - nvl(sum(credit_amount), 0)) as DIFF
+      from test_ledger_entry
+     where case_id = :case_id
+       and processing_date = to_date(:processing_date, 'YYYY-MM-DD')
+  params:
+    case_id:
+      required: true
+      pattern: ^[0-9A-Za-z_-]+$
+    processing_date:
+      required: true
+      pattern: ^\d{4}-\d{2}-\d{2}$
+  expect:
+    type: number
+    column: DIFF
+    operator: =
+    value: 0
+  captures:
+    balance_diff: $.rows[0].DIFF
+
+case_by_external_id:
+  description: Retrieves a generic test case by external identifier.
+  sql: |
+    select case_id as CASE_ID, status as STATUS
+      from test_case
+     where external_id = :external_id
+  params:
+    external_id:
+      required: true
+      type: string
+  expect:
+    type: rowCount
+    operator: ">"
+    value: 0
+  captures:
+    case_id: $.rows[0].CASE_ID
+    case_status: $.rows[0].STATUS

package/config/environments.yaml

@@ -0,0 +1,13 @@
+local:
+  apiBaseUrl: "${ADFINEM_API_BASE_URL}"
+  apiTlsInsecure: "${ADFINEM_API_TLS_INSECURE}"
+  oracle:
+    user: "${ADFINEM_DB_USER}"
+    password: "${ADFINEM_DB_PASSWORD}"
+    connectString: "${ADFINEM_DB_CONNECT_STRING}"
+  sshHosts:
+    qa_worker:
+      host: "${ADFINEM_SSH_QA_WORKER_HOST}"
+      username: "${ADFINEM_SSH_USER}"
+      password: "${ADFINEM_SSH_PASSWORD}"
+      privateKeyPath: "${ADFINEM_SSH_PRIVATE_KEY_PATH}"

package/dist/actions/assert-db.js

@@ -0,0 +1,3 @@
+export async function assertDb(oracle, entry, params) {
+    return await oracle.assert(entry, params);
+}

package/dist/actions/run-eod.js

@@ -0,0 +1,3 @@
+export async function runBatch(batchRunner, entry, params, options) {
+    return await batchRunner.run(entry, params, options);
+}

package/dist/adapters/api/api-collections.js

@@ -0,0 +1,296 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { dirname, join } from "node:path";
+export function apiCollectionsPath(rootDir) {
+    return join(rootDir, "catalogs", "api-collections.json");
+}
+export async function loadApiCollections(rootDir) {
+    try {
+        const parsed = JSON.parse(await readFile(apiCollectionsPath(rootDir), "utf8"));
+        return normalizeCollectionFile(parsed);
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === "ENOENT")
+            return { version: 1, collections: [] };
+        throw error;
+    }
+}
+export async function writeApiCollections(rootDir, file) {
+    const outputPath = apiCollectionsPath(rootDir);
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, `${JSON.stringify(normalizeCollectionFile(file), null, 2)}\n`, "utf8");
+}
+export async function importPostmanCollection(rootDir, payload) {
+    const collection = parsePostmanCollection(payload);
+    const file = await loadApiCollections(rootDir);
+    const remaining = file.collections.filter((item) => item.id !== collection.id);
+    await writeApiCollections(rootDir, { version: 1, collections: [...remaining, collection] });
+    return collection;
+}
+export function parsePostmanCollection(payload) {
+    const source = asObject(payload);
+    const name = String(source.info?.name || "Imported API Collection").trim();
+    const collectionId = sanitizeId(source.info?._postman_id || `${name}_${shortHash(JSON.stringify(payload))}`);
+    const variables = postmanVariables(source.variable);
+    const requests = [];
+    const rootAuth = source.auth;
+    function visit(items, folderPath, inheritedAuth) {
+        for (const item of items ?? []) {
+            if (Array.isArray(item.item)) {
+                visit(item.item, [...folderPath, String(item.name || "Folder")], inheritedAuth);
+                continue;
+            }
+            const request = typeof item.request === "string" ? undefined : item.request;
+            if (!request)
+                continue;
+            const requestId = uniqueRequestId(collectionId, folderPath, item.name || request.method || "request", requests.length);
+            const spec = postmanRequestSpec(request, inheritedAuth);
+            const variableNames = [...new Set([
+                    ...findTemplateVariables(spec),
+                    ...Object.keys(variables)
+                ])].sort((a, b) => a.localeCompare(b));
+            requests.push({
+                id: requestId,
+                name: String(item.name || requestId),
+                folderPath,
+                operationKey: `pm_${collectionId}_${requestId}`,
+                description: descriptionText(request.description),
+                request: spec,
+                variables,
+                variableNames
+            });
+        }
+    }
+    visit(source.item, [], rootAuth);
+    return {
+        id: collectionId,
+        name,
+        importedAt: new Date().toISOString(),
+        variables,
+        requestCount: requests.length,
+        requests
+    };
+}
+export function previewPostmanCollection(payload) {
+    const collection = parsePostmanCollection(payload);
+    return {
+        name: collection.name,
+        id: collection.id,
+        requestCount: collection.requestCount,
+        variables: collection.variables ?? {},
+        folders: [...new Set(collection.requests.map((request) => request.folderPath.join(" / ")).filter(Boolean))].sort(),
+        requests: collection.requests.map((request) => ({
+            id: request.id,
+            name: request.name,
+            folderPath: request.folderPath,
+            operationKey: request.operationKey,
+            variableNames: request.variableNames,
+            ...request.request
+        }))
+    };
+}
+export function importedOperationsFromCollections(file) {
+    const operations = {};
+    for (const collection of file.collections) {
+        for (const request of collection.requests) {
+            operations[request.operationKey] = {
+                type: "rest",
+                description: request.description || `${collection.name}${request.folderPath.length ? ` / ${request.folderPath.join(" / ")}` : ""} / ${request.name}`,
+                ...request.request,
+                params: paramsFromVariables(request.variableNames),
+                source: {
+                    collectionId: collection.id,
+                    collectionName: collection.name,
+                    requestId: request.id,
+                    folderPath: request.folderPath
+                }
+            };
+        }
+    }
+    return operations;
+}
+export function operationToRequestSpec(operation) {
+    if (!operation)
+        return {};
+    return {
+        method: operation.method,
+        path: operation.path,
+        headers: operation.headers,
+        query: operation.query,
+        body: operation.body,
+        rawBody: operation.rawBody,
+        bodyMode: operation.bodyMode,
+        auth: operation.auth,
+        acceptStatuses: operation.acceptStatuses
+    };
+}
+export function mergeApiRequest(base, override) {
+    const source = operationToRequestSpec(base);
+    return cleanRequest({
+        ...source,
+        ...(override ?? {}),
+        headers: mergeRecord(source.headers, override?.headers),
+        query: mergeRecord(source.query, override?.query),
+        acceptStatuses: override?.acceptStatuses ?? source.acceptStatuses
+    });
+}
+function postmanRequestSpec(request, inheritedAuth) {
+    const url = parsePostmanUrl(request.url);
+    const body = parsePostmanBody(request.body);
+    return cleanRequest({
+        method: normalizeMethod(request.method),
+        path: url.path,
+        query: url.query,
+        headers: mergeRecord(generatedPostmanHeaders(body), keyValueRecord(request.header)),
+        auth: request.auth ?? inheritedAuth,
+        ...body
+    });
+}
+function parsePostmanUrl(value) {
+    if (typeof value === "string")
+        return pathAndQueryFromRaw(value);
+    const url = asObject(value);
+    const raw = optionalString(url.raw);
+    const query = keyValueRecord(url.query);
+    if (raw) {
+        const parsed = pathAndQueryFromRaw(raw);
+        return { path: parsed.path, query: mergeRecord(parsed.query, query) };
+    }
+    const pathParts = Array.isArray(url.path) ? url.path.map(String) : [];
+    return {
+        path: pathParts.length ? `/${pathParts.join("/")}` : undefined,
+        query
+    };
+}
+function pathAndQueryFromRaw(raw) {
+    const trimmed = raw.trim();
+    const withoutBase = trimmed.replace(/^\{\{[^}]+\}\}/, "");
+    try {
+        const url = new URL(trimmed.replace(/^\{\{[^}]+\}\}/, "http://postman.local"));
+        return { path: url.pathname, query: Object.fromEntries(url.searchParams.entries()) };
+    }
+    catch {
+        const [path, qs] = withoutBase.split("?");
+        return {
+            path: path.startsWith("/") ? path : `/${path}`,
+            query: qs ? Object.fromEntries(new URLSearchParams(qs).entries()) : undefined
+        };
+    }
+}
+function parsePostmanBody(body) {
+    if (!body?.mode)
+        return { bodyMode: "none" };
+    if (body.mode === "raw") {
+        const rawBody = body.raw ?? "";
+        const trimmed = rawBody.trim();
+        if (trimmed && looksLikeJson(trimmed)) {
+            return { bodyMode: "json", rawBody };
+        }
+        return { bodyMode: "raw", rawBody };
+    }
+    if (body.mode === "urlencoded") {
+        return { bodyMode: "urlencoded", body: keyValueRecord(body.urlencoded) ?? {} };
+    }
+    if (body.mode === "formdata") {
+        return { bodyMode: "formdata", body: keyValueRecord(body.formdata) ?? {} };
+    }
+    return { bodyMode: "raw", rawBody: body.raw ?? "" };
+}
+function normalizeMethod(value) {
+    const method = String(value || "GET").toUpperCase();
+    if (["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"].includes(method)) {
+        return method;
+    }
+    return "GET";
+}
+function keyValueRecord(items) {
+    const entries = (items ?? [])
+        .filter((item) => !item.disabled && item.key)
+        .map((item) => [String(item.key), String(item.value ?? "")]);
+    return entries.length ? Object.fromEntries(entries) : undefined;
+}
+function generatedPostmanHeaders(body) {
+    const headers = {
+        Accept: "*/*",
+        "Cache-Control": "no-cache"
+    };
+    if (body.bodyMode === "json")
+        headers["Content-Type"] = "application/json";
+    if (body.bodyMode === "urlencoded")
+        headers["Content-Type"] = "application/x-www-form-urlencoded";
+    return Object.keys(headers).length ? headers : undefined;
+}
+function postmanVariables(items) {
+    return Object.fromEntries((items ?? [])
+        .filter((item) => !item.disabled && item.key)
+        .map((item) => [String(item.key), item.value ?? ""]));
+}
+function findTemplateVariables(value) {
+    const names = [];
+    const visit = (current) => {
+        if (typeof current === "string") {
+            for (const match of current.matchAll(/\{\{([A-Za-z0-9_.-]+)\}\}/g))
+                names.push(match[1]);
+            for (const match of current.matchAll(/\$\{([A-Za-z0-9_.-]+)\}/g))
+                names.push(match[1]);
+            return;
+        }
+        if (Array.isArray(current))
+            current.forEach(visit);
+        if (current && typeof current === "object")
+            Object.values(current).forEach(visit);
+    };
+    visit(value);
+    return names;
+}
+function paramsFromVariables(variableNames) {
+    if (!variableNames.length)
+        return undefined;
+    return Object.fromEntries(variableNames.map((name) => [name, { required: false, type: "string" }]));
+}
+function normalizeCollectionFile(file) {
+    return {
+        version: 1,
+        collections: Array.isArray(file.collections) ? file.collections.map((collection) => ({
+            ...collection,
+            requestCount: collection.requests?.length ?? collection.requestCount ?? 0,
+            requests: collection.requests ?? []
+        })) : []
+    };
+}
+function cleanRequest(request) {
+    return Object.fromEntries(Object.entries(request).filter(([, value]) => value !== undefined && value !== null && !(typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === 0)));
+}
+function mergeRecord(base, override) {
+    const merged = { ...(base ?? {}), ...(override ?? {}) };
+    return Object.keys(merged).length ? merged : undefined;
+}
+function asObject(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function optionalString(value) {
+    return value === undefined || value === null ? undefined : String(value);
+}
+function looksLikeJson(value) {
+    return value.startsWith("{") || value.startsWith("[");
+}
+function descriptionText(value) {
+    if (typeof value === "string")
+        return value;
+    const description = asObject(value);
+    return optionalString(description.content);
+}
+function uniqueRequestId(collectionId, folderPath, name, index) {
+    return sanitizeId(`${folderPath.join("_")}_${name}_${index || ""}`) || `${collectionId}_request_${index + 1}`;
+}
+function sanitizeId(value) {
+    return String(value ?? "")
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .slice(0, 80) || "collection";
+}
+function shortHash(value) {
+    return createHash("sha1").update(value).digest("hex").slice(0, 8);
+}