adfinem 0.1.0 → 0.1.1

package/.env.example

@@ -0,0 +1,13 @@
+ADFINEM_ENV=local
+ADFINEM_API_BASE_URL=https://example-api
+ADFINEM_API_TLS_INSECURE=false
+# raw is useful while developing; set redacted before sharing evidence.
+ADFINEM_EVIDENCE_VISIBILITY=raw
+ADFINEM_DB_USER=
+ADFINEM_DB_PASSWORD=
+ADFINEM_DB_CONNECT_STRING=
+ADFINEM_SSH_USER=
+ADFINEM_SSH_PASSWORD=
+ADFINEM_SSH_PRIVATE_KEY_PATH=
+ADFINEM_SSH_QA_WORKER_HOST=
+ADFINEM_BATCH_WORKDIR=

package/CHANGELOG.md

@@ -1,10 +1,17 @@
-# 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.
+# Changelog
+
+All notable changes to Adfinem are documented here.
+
+## [0.1.1] - 2026-06-06
+
+- Add `adfinem init` to create a starter project from the global package.
+- Add `adfinem app` to launch the web workbench from a global install.
+- Make CLI commands resolve catalogs, config, evidence, flows, and scenarios from the current project directory.
+- Include built web assets and `.env.example` in the npm package.
+
+## [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

@@ -1,21 +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.
+# 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

@@ -1,29 +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.
+# 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/README.md

@@ -1,87 +1,97 @@
-# Adfinem
-
-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
+# Adfinem
+
+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
+```
+
+The published CLI can also be installed globally:
+
+```bash
+npm install -g adfinem
+adfinem init my-adfinem-tests
+cd my-adfinem-tests
+adfinem validate scenarios/smoke/account-processing-smoke.yaml
+adfinem app
+```
+
+## 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
+# Create a starter project when using the global package
+adfinem init my-adfinem-tests
+cd my-adfinem-tests
+
+# Open the web workbench for the current project
+adfinem app
+
+# Validate a scenario before running it
+adfinem validate scenarios/smoke/account-processing-smoke.yaml
+
+# Run a scenario without external side effects
+adfinem run scenarios/smoke/account-processing-smoke.yaml --env local --dry-run
+
+# Execute a cataloged API operation
+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
+adfinem db-query test_activity_exists --env local --param case_id=CASE-1001 --param amount=json:111
+
+# Run a cataloged Unix batch
+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

@@ -1,13 +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.
+# 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/dist/app/server.js

@@ -17,11 +17,12 @@ import { loadFlow, writeFlow } from "../flows/parser.js";
 import { validateFlow } from "../flows/validator.js";
 import { importPostmanCollection, loadApiCollections, previewPostmanCollection } from "../adapters/api/api-collections.js";
 import { normalizeBindParamRecord, normalizeQueryCatalog } from "../adapters/db/query-catalog.js";
-const rootDir = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const rootDir = resolve(process.env.ADFINEM_PROJECT_ROOT ?? packageRoot);
 const flowsDir = join(rootDir, "flows");
 const evidenceDir = join(rootDir, "evidence");
 const batchInputFilesDir = join(rootDir, "data", "batch-input-files");
-const webDistDir = join(rootDir, "web-dist");
+const webDistDir = resolve(process.env.ADFINEM_WEB_DIST ?? join(packageRoot, "web-dist"));
 const queriesFile = join(rootDir, "catalogs", "queries.yaml");
 const batchesFile = join(rootDir, "catalogs", "batches.yaml");
 const catalogYamlOptions = { defaultStringType: "PLAIN", defaultKeyType: "PLAIN", lineWidth: 0 };

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import { writeFile } from "node:fs/promises";
+import { access, cp, mkdir, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ZodError } from "zod";
@@ -21,12 +21,60 @@ import { compileFlow } from "./flows/compiler.js";
 import { loadFlow, readFlowSource, writeFlow } from "./flows/parser.js";
 import { validateFlow } from "./flows/validator.js";
 import { concatFlows } from "./flows/concat.js";
-const rootDir = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const rootDir = resolve(process.env.ADFINEM_PROJECT_ROOT ?? process.cwd());
 const program = new Command();
 program
     .name("adfinem")
     .description("Adfinem deterministic API, database, and Unix scenario runner")
-    .version("0.1.0");
+    .version("0.1.1");
+program
+    .command("init")
+    .argument("[directory]", "Project directory to create or update", ".")
+    .description("Create a starter Adfinem project with catalogs, config, scenarios, flows, docs, and templates")
+    .option("--force", "Overwrite starter files that already exist")
+    .action(async (directory, options) => {
+    await handleErrors(async () => {
+        const targetRoot = resolve(process.cwd(), directory);
+        await mkdir(targetRoot, { recursive: true });
+        const entries = ["catalogs", "config", "flows", "scenarios", "templates", "docs", ".env.example"];
+        const copied = [];
+        const skipped = [];
+        for (const entry of entries) {
+            const source = join(packageRoot, entry);
+            const target = join(targetRoot, entry);
+            if (!options.force && await pathExists(target)) {
+                skipped.push(entry);
+                continue;
+            }
+            await cp(source, target, { recursive: true, force: Boolean(options.force) });
+            copied.push(entry);
+        }
+        console.log(`Adfinem project ready: ${targetRoot}`);
+        if (copied.length > 0)
+            console.log(`Created: ${copied.join(", ")}`);
+        if (skipped.length > 0)
+            console.log(`Skipped existing: ${skipped.join(", ")} (use --force to overwrite)`);
+        console.log("Next:");
+        console.log(`  cd ${targetRoot}`);
+        console.log("  adfinem validate scenarios/smoke/account-processing-smoke.yaml");
+        console.log("  adfinem app");
+    });
+});
+program
+    .command("app")
+    .description("Start the Adfinem web workbench for the current project")
+    .option("--project <dir>", "Project root containing catalogs, config, scenarios, and flows", ".")
+    .option("--port <port>", "Port to bind; defaults to 4177 with fallback ports", parseInteger)
+    .action(async (options) => {
+    await handleErrors(async () => {
+        process.env.ADFINEM_PROJECT_ROOT = resolve(process.cwd(), options.project);
+        process.env.ADFINEM_WEB_DIST = join(packageRoot, "web-dist");
+        if (options.port !== undefined)
+            process.env.ADFINEM_RUNNER_PORT = String(options.port);
+        await import("./app/server.js");
+    });
+});
 program
     .command("validate")
     .argument("<scenario>", "Scenario YAML path")
@@ -390,6 +438,9 @@ function parseInteger(value) {
         throw new Error(`Invalid integer: ${value}`);
     return parsed;
 }
+async function pathExists(path) {
+    return access(path).then(() => true).catch(() => false);
+}
 function collectOption(value, previous) {
     return [...previous, value];
 }

package/package.json

@@ -1,71 +1,73 @@
-{
-  "name": "adfinem",
-  "version": "0.1.0",
-  "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",
-    "catalogs",
-    "config",
-    "flows",
-    "scenarios",
-    "templates",
-    "docs",
-    "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"
-  },
+{
+  "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",

package/src/app/server.ts

@@ -26,11 +26,12 @@ import type { BatchCatalogEntry, QueryCatalogEntry, StepResult } from "../dsl/ty
 import { importPostmanCollection, loadApiCollections, previewPostmanCollection } from "../adapters/api/api-collections.js";
 import { normalizeBindParamRecord, normalizeQueryCatalog } from "../adapters/db/query-catalog.js";
 
-const rootDir = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const rootDir = resolve(process.env.ADFINEM_PROJECT_ROOT ?? packageRoot);
 const flowsDir = join(rootDir, "flows");
 const evidenceDir = join(rootDir, "evidence");
 const batchInputFilesDir = join(rootDir, "data", "batch-input-files");
-const webDistDir = join(rootDir, "web-dist");
+const webDistDir = resolve(process.env.ADFINEM_WEB_DIST ?? join(packageRoot, "web-dist"));
 const queriesFile = join(rootDir, "catalogs", "queries.yaml");
 const batchesFile = join(rootDir, "catalogs", "batches.yaml");
 const catalogYamlOptions = { defaultStringType: "PLAIN", defaultKeyType: "PLAIN", lineWidth: 0 } as const;