adfinem 0.0.0 → 0.1.1

package/docs/DB_UNIX_OPERATIONS.md

@@ -0,0 +1,118 @@
+# Database and Unix Operations
+
+## Purpose
+
+Adfinem supports Action Library-driven database and Unix batch steps inside the same scenario engine as API operations.
+
+Scenarios do not carry arbitrary SQL or shell commands. They reference allowlisted Action Library templates:
+
+- `catalogs/queries.yaml`
+- `catalogs/batches.yaml`
+
+This keeps generated or hand-authored scenarios executable but bounded.
+
+## Database Queries
+
+Use `db_assert` when the query has an `expect` block and must pass or fail the scenario.
+
+```yaml
+- id: assert_activity
+  action: db_assert
+  via: db
+  query: test_activity_exists
+  params:
+    case_id: "${case_id}"
+    amount: 100.00
+```
+
+Use `db_query` when the query is meant to retrieve values for later steps.
+
+```yaml
+- id: load_case
+  action: db_query
+  via: db
+  query: case_by_external_id
+  params:
+    external_id: "CASE-1001"
+```
+
+Direct CLI checks:
+
+```powershell
+npm run adfinem -- db-query test_activity_exists --env local --params "{\"case_id\":\"CASE-1001\",\"amount\":111}"
+npm run adfinem -- db-assert test_activity_exists --env local --params "{\"case_id\":\"CASE-1001\",\"amount\":111}"
+```
+
+## Unix Batches
+
+Batch templates define the SSH host, command, arguments, timeout, success criteria, and optional captures.
+
+```yaml
+daily_processing:
+  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"
+```
+
+Scenario step:
+
+```yaml
+- id: run_processing
+  action: unix_batch
+  via: unix
+  batch: daily_processing
+  params:
+    processing_date: "${processing_date}"
+  retry:
+    attempts: 2
+    delaySeconds: 30
+```
+
+Direct CLI check:
+
+```powershell
+npm run adfinem -- run-batch daily_processing --env local --params "{\"processing_date\":\"2026-04-27\"}" --attempts 2 --delay-seconds 30
+```
+
+## Captures
+
+Database and Unix steps can capture values into scenario context. Later steps can use them as `${name}`.
+
+Supported capture expressions:
+
+- JSONPath: `$.rows[0].CNT`, `$.stdout`, `$.exitCode`
+- Simple property path: `rowCount`, `stdout`, `exitCode`
+- Literal: `literal:some-value`
+- Regex: `regex:$.stdout:Case=(\\d+)`
+
+If a capture expression does not match, the step fails. This is intentional so data passing bugs are visible.
+
+## Environment
+
+`config/environments.yaml` maps environment names to database and SSH connection settings. Values usually come from `.env`:
+
+```text
+ADFINEM_DB_USER=
+ADFINEM_DB_PASSWORD=
+ADFINEM_DB_CONNECT_STRING=
+ADFINEM_SSH_QA_WORKER_HOST=
+ADFINEM_SSH_USER=
+ADFINEM_SSH_PASSWORD=
+ADFINEM_SSH_PRIVATE_KEY_PATH=
+```
+
+## Evidence
+
+Each database step writes `<step>.db.json`.
+
+Each Unix step writes `<step>.unix.json`, and when captures exist, `<step>.unix-captures.json`.

package/docs/FLOW_BUILDER.md

@@ -0,0 +1,87 @@
+# Flow Builder
+
+## Purpose
+
+Flows are the durable source of truth for chained API, database, and Unix automation. They let you combine cataloged API operations with database queries, assertions, Unix batches, and captured output mappings without typing long CLI command chains.
+
+Flow files live under `flows/` and use the suffix `.flow.yaml`.
+
+## Concepts
+
+- **API operation**: an allowlisted operation from `catalogs/api-operations.yaml`.
+- **Action**: a technical step such as `db_query`, `db_assert`, `db_execute`, or `unix_batch`.
+- **Post action**: an action attached to an API operation and executed immediately after it.
+- **Output mapping**: later steps reference previous outputs with `${node_id.capture_name}`.
+
+The compatibility folder is still named `catalogs/`; those files are the Action Library.
+
+## CLI
+
+Validate a flow:
+
+```powershell
+npm run adfinem -- validate-flow flows\account_processing_cycle.flow.yaml
+```
+
+Compile a flow to the scenario structure:
+
+```powershell
+npm run adfinem -- compile-flow flows\account_processing_cycle.flow.yaml --output evidence\compiled-flow.json
+```
+
+Dry run a flow:
+
+```powershell
+npm run adfinem -- run-flow flows\account_processing_cycle.flow.yaml --env local --dry-run
+```
+
+Execute a flow:
+
+```powershell
+npm run adfinem -- run-flow flows\account_processing_cycle.flow.yaml --env local
+```
+
+Create a new flow by concatenating existing flows:
+
+```powershell
+npm run adfinem -- concat-flows flows\combined.flow.yaml flows\first.flow.yaml flows\second.flow.yaml --id combined --name "Combined flow"
+```
+
+The concat command preserves the internal order of each input flow, connects the last top-level node of one flow to the first top-level node of the next flow, merges variables, and rewrites node references if ids collide.
+
+## Local App
+
+Start the app:
+
+```powershell
+npm run app
+```
+
+Open:
+
+```text
+http://localhost:4177
+```
+
+The app saves the same flow files used by the CLI. It can load API operations, database templates, Unix batches, validate flows, and start runs through the local backend.
+
+### Workbench Features
+
+- Delete saved workflows from the Flows explorer. The app removes the matching `flows/*.flow.yaml` file after confirmation.
+- Import Postman collection JSON files from **API Collections**. Imported collections are stored locally in `catalogs/api-collections.json` and exposed as grouped request templates instead of flooding the sidebar.
+- Click an imported collection to search requests by folder, method, name, or path, then add one or multiple requests to the workflow.
+- API request steps are editable per workflow. Method, path, headers, query params, body, auth, inputs, captures, assertions, and accepted statuses can diverge from the imported template without changing the source collection.
+- Import Postman environment JSON files from the top bar. Variables are copied into the selected workflow/environment input set.
+- Use insert controls, drag/drop, move, duplicate, disable, and section labels to organize the workflow timeline.
+- Recent run history is read from `evidence/*/run-result.json` and shown per workflow.
+
+## Evidence
+
+Each `run-flow` execution writes:
+
+- `run-result.json`
+- the original `flow.yaml`
+- `compiled-flow.json`
+- per-step input/evidence files
+- `report.html`
+- `junit.xml`

package/flows/account_processing_cycle.flow.yaml

@@ -0,0 +1,88 @@
+version: 1
+id: account_processing_cycle
+name: Account processing cycle
+environment: local
+variables:
+  processing_date: "2026-04-27"
+nodes:
+  - id: create_case
+    label: Create test case
+    type: api_operation
+    operation: create_test_case
+    input:
+      tenant: demo
+      external_id: CASE-3001
+      case_type: account-processing
+    capture:
+      case_id: $.case.id
+      case_status: $.case.status
+  - id: record_activity
+    label: Record test activity
+    type: api_operation
+    operation: record_test_activity
+    input:
+      case_id: ${create_case.case_id}
+      amount: 100
+      currency: USD
+      activity_type: adjustment
+    capture:
+      activity_id: $.activity.id
+      activity_status: $.activity.status
+  - id: assert_activity
+    label: Assert activity exists
+    type: db_assert
+    query: test_activity_exists
+    params:
+      case_id: ${create_case.case_id}
+      amount: 100
+  - id: processing_loop
+    label: Processing loop
+    type: loop
+    loop:
+      mode: count
+      count: 2
+      itemName: run
+      maxIterations: 10
+      dateCursor:
+        outputName: processing_date
+        start: ${processing_date}
+        inputFormat: YYYY-MM-DD
+        outputFormat: YYYY-MM-DD
+        advance:
+          mode: days
+          amount: 1
+    nodes:
+      - id: run_processing
+        label: Run daily processing
+        type: unix_batch
+        batch: daily_processing
+        params:
+          processing_date: ${processing_loop.processing_date}
+      - id: assert_processing
+        label: Assert processing balanced
+        type: db_assert
+        query: processing_balanced
+        params:
+          case_id: ${create_case.case_id}
+          processing_date: ${processing_loop.processing_date}
+edges:
+  - from: create_case
+    to: record_activity
+  - from: record_activity
+    to: assert_activity
+  - from: assert_activity
+    to: processing_loop
+ui:
+  positions:
+    create_case:
+      x: -360
+      y: 0
+    record_activity:
+      x: -160
+      y: 180
+    assert_activity:
+      x: 60
+      y: 360
+    processing_loop:
+      x: 340
+      y: 520

package/flows/new_flow.flow.yaml

@@ -0,0 +1,22 @@
+version: 1
+id: new_flow
+name: New flow
+environment: local
+variables: {}
+nodes:
+  - id: import_transactions
+    label: Import transactions
+    params:
+      transactions_file:
+        fileName: transactions.csv
+        localPath: data/batch-input-files/new_flow/import_transactions/transactions_file/transactions.csv
+        sizeBytes: 128
+        remotePath: /tmp/adfinem/inbox/
+    type: unix_batch
+    batch: import_transactions
+edges: []
+ui:
+  positions:
+    import_transactions:
+      x: 18
+      y: -150

package/package.json

@@ -1,11 +1,98 @@
-{
-  "name": "adfinem",
-  "version": "0.0.0",
-  "description": "Adfinem Open Source Project.",
-  "main": "index.js",
-  "files": [
-    "index.js",
-    "README.md"
-  ],
-  "license": "MIT"
-}
+{
+  "name": "adfinem",
+  "version": "0.1.1",
+  "description": "Open-source QA test helper for deterministic API, database, Unix, and workflow automation",
+  "keywords": [
+    "qa",
+    "testing",
+    "api",
+    "database",
+    "unix",
+    "workflow",
+    "automation",
+    "cli"
+  ],
+  "author": "Adfinem contributors",
+  "license": "MIT",
+  "private": false,
+  "homepage": "https://github.com/amnotabot/adfinem#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amnotabot/adfinem.git"
+  },
+  "bugs": {
+    "url": "https://github.com/amnotabot/adfinem/issues"
+  },
+  "type": "module",
+  "bin": {
+    "adfinem": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "web",
+    "web-dist",
+    "catalogs",
+    "config",
+    "flows",
+    "scenarios",
+    "templates",
+    "docs",
+    ".env.example",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md",
+    "SECURITY.md",
+    "tsconfig.json",
+    "vite.config.ts"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "adfinem": "tsx src/cli.ts",
+    "cli": "tsx src/cli.ts",
+    "test": "tsx --test tests/api-only.test.ts",
+    "check": "npm run build && npm test",
+    "validate": "tsx src/cli.ts validate scenarios/smoke/account-processing-smoke.yaml",
+    "smoke:dry": "tsx src/cli.ts run scenarios/smoke/account-processing-smoke.yaml --env local --dry-run",
+    "web:build": "vite build",
+    "app": "npm run web:build && tsx src/app/server.ts",
+    "package:dry-run": "npm pack --dry-run --json",
+    "release:validate": "npm run check && npm run web:build && npm run validate && npm run smoke:dry && npm run package:dry-run",
+    "prepublishOnly": "npm run release:validate"
+  },
+  "dependencies": {
+    "@xyflow/react": "^12.10.2",
+    "axios": "^1.9.0",
+    "commander": "^12.1.0",
+    "dotenv": "^16.4.7",
+    "elkjs": "^0.11.1",
+    "jsonpath-plus": "^10.3.0",
+    "lucide-react": "^1.14.0",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "ssh2": "^1.16.0",
+    "yaml": "^2.7.1",
+    "zod": "^3.24.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.31",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@types/ssh2": "^1.15.5",
+    "@vitejs/plugin-react": "^6.0.1",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3",
+    "vite": "^8.0.10"
+  },
+  "optionalDependencies": {
+    "oracledb": "^6.8.0"
+  }
+}

package/scenarios/smoke/account-processing-smoke.yaml

@@ -0,0 +1,44 @@
+id: account_processing_smoke
+environment: local
+variables:
+  processing_date: "2026-04-27"
+steps:
+  - id: create_case
+    action: create_test_case
+    via: api
+    input:
+      tenant: "demo"
+      external_id: "CASE-1001"
+      case_type: "account-processing"
+
+  - id: record_activity
+    action: record_test_activity
+    via: api
+    input:
+      case_id: "${case_id}"
+      amount: 100.00
+      currency: "USD"
+      activity_type: "adjustment"
+
+  - id: assert_activity
+    action: db_assert
+    via: db
+    query: test_activity_exists
+    params:
+      case_id: "${case_id}"
+      amount: 100.00
+
+  - id: run_processing
+    action: unix_batch
+    via: unix
+    batch: daily_processing
+    params:
+      processing_date: "${processing_date}"
+
+  - id: assert_processing
+    action: db_assert
+    via: db
+    query: processing_balanced
+    params:
+      case_id: "${case_id}"
+      processing_date: "${processing_date}"

package/scenarios/smoke/api-db-batch-check.yaml

@@ -0,0 +1,40 @@
+id: api_db_batch_check
+environment: local
+variables:
+  processing_date: "2026-04-27"
+
+steps:
+  - id: create_case
+    action: create_test_case
+    via: api
+    input:
+      tenant: "demo"
+      external_id: "CASE-2001"
+      case_type: "api-db-batch"
+
+  - id: record_activity
+    action: record_test_activity
+    via: api
+    input:
+      case_id: "${case_id}"
+      amount: 111
+      currency: "USD"
+      activity_type: "posting"
+
+  - id: run_processing
+    action: unix_batch
+    via: unix
+    batch: daily_processing
+    params:
+      processing_date: "${processing_date}"
+    retry:
+      attempts: 2
+      delaySeconds: 30
+
+  - id: assert_processing
+    action: db_assert
+    via: db
+    query: processing_balanced
+    params:
+      case_id: "${case_id}"
+      processing_date: "${processing_date}"

package/src/actions/assert-db.ts

@@ -0,0 +1,6 @@
+import type { QueryCatalogEntry } from "../dsl/types.js";
+import { OracleClient } from "../adapters/db/oracle-client.js";
+
+export async function assertDb(oracle: OracleClient, entry: QueryCatalogEntry, params: Record<string, unknown>) {
+  return await oracle.assert(entry, params);
+}

package/src/actions/run-eod.ts

@@ -0,0 +1,6 @@
+import type { BatchCatalogEntry } from "../dsl/types.js";
+import { BatchRunner, type BatchRunOptions } from "../adapters/unix/batch-runner.js";
+
+export async function runBatch(batchRunner: BatchRunner, entry: BatchCatalogEntry, params: Record<string, unknown>, options?: BatchRunOptions) {
+  return await batchRunner.run(entry, params, options);
+}