flowstride 1.0.1 → 1.0.3

package/README.md

@@ -49,6 +49,44 @@ _(This command executes your test while instantly booting up the local Flowstrid
 
 ---
 
+## Privacy & Data Security
+
+Flowstride is designed with a **zero-trust, local-first architecture**. Whether you are testing internal microservices, staging environments, or production APIs, your sensitive data, PHI, and credentials remain strictly on your infrastructure.
+
+### Open Source Core: 100% Local Isolation
+
+The Open Source version of Flowstride operates entirely as an ephemeral, local execution engine.
+
+- **Air-Gapped Execution:** Flowstride does not "phone home." The OS runner executes strictly on your local machine or within your private CI/CD pipeline. There is no external Flowstride database storing your test payloads or network logs.
+
+- **Ephemeral Memory:** Flowstride is inherently stateless. API request headers, response bodies, and DOM snapshots exist only in Node.js RAM during execution. The millisecond the execution process terminates, all memory is wiped.
+
+- **The DevTools Analogy:** Our network interception works natively within Playwright's browser context routing. It is fundamentally identical to opening the Chrome DevTools "Network" tab locally. We do not act as an external Man-In-The-Middle (MITM) proxy.
+
+- **Opt-In Local State:** Artifacts saved to disk—such as execution videos (`.flowstride/mock-cloud/`) or explicitly persisted browser states (`.flowstride/sessions/`)—are written strictly to your local file system to mirror the functionality of tools like Postman. _(Note: We strongly recommend adding `.flowstride/` to your `.gitignore` to prevent accidental credential commits)._
+
+### Flowstride Enterprise: Secure Cloud Telemetry
+
+For teams using Flowstride Enterprise to aggregate multi-flow metrics, we maintain a strict metadata-only boundary.
+
+- **Metadata, Not Payloads:** When cloud sync is active, Flowstride routes only execution metadata to your team's dashboard (e.g., Workspace ID, execution duration, total steps, and pass/fail tallies). **Zero bytes** of request headers, bearer tokens, or JSON bodies are ever transmitted to Flowstride Cloud.
+
+- **Deep Debugging Stays Local:** The rich, interactive visual dashboard, including the JSON explorer and API Replay tools, runs on a dynamic, locally bound port on your machine. You get the UI of a modern cloud app with the security of a local binary.
+
+### CI/CD Leak Protection & Terminal Hygiene
+
+Standard testing frameworks do dump failing API requests, and response bodies directly into the terminal so developers can debug them. In a CI/CD environment, this is a massive security liability, as those secrets are permanently burned into plaintext Jenkins, GitHub Actions, or GitLab CI logs.
+
+Flowstride completely neutralizes this threat by architecturally separating execution output from diagnostic telemetry:
+
+1. **Clean Standard Output (`stdout`):** Flowstride's terminal output only displays high-level, human-readable BDD execution steps (e.g., `✔ Given "User lands on home page"` or `✖ Action Failed`). No JSON request bodies, `cURL` strings, or bearer tokens are ever printed to the terminal console.
+
+2. **WebSocket Isolation:** All sensitive raw network data (payloads, headers, and responses) is emitted _exclusively_ over a secure, ephemeral WebSocket connection directly to the developer's local UI dashboard.
+
+3. **Total Evaporation:** Because CI/CD runners only capture `stdout` text and do not connect to local WebSockets, your highly sensitive diagnostic data simply evaporates the moment the pipeline execution ends. Your pipeline logs remain 100% free of plaintext secrets.
+
+---
+
 ## The `.flow` Syntax
 
 Flowstride utilizes a custom `.flow` file extension. It seamlessly pairs descriptive BDD steps (Given, When, And, Then) with direct, executable `flow.` commands.

package/dist/cli/commands/init.js

@@ -49,7 +49,9 @@ async function initAction() {
     const folders = ["flows", "reports", "plugins", "fixtures"];
     const sampleFlowPath = path.join(root, "flows", "example.flow");
     const fixturesReadmePath = path.join(root, "fixtures", "README.md");
+    const gitignorePath = path.join(root, ".gitignore");
     console.log("\n[Info] Initializing new workspace...");
+    // 1. Create Directories
     folders.forEach((folder) => {
         const dirPath = path.join(root, folder);
         if (!fs.existsSync(dirPath)) {
@@ -60,6 +62,7 @@ async function initAction() {
             console.log(`[Info] Directory already exists: ${folder}/`);
         }
     });
+    // 2. Create Sample Flow
     const exampleContent = `
 Feature: User login flow
 
@@ -91,6 +94,7 @@ Then "Logout of the Admin dashboard"
         fs.writeFileSync(sampleFlowPath, exampleContent);
         console.log("[OK] Created sample flow: flows/example.flow");
     }
+    // 3. Create Fixtures Readme
     const fixturesReadmeContent = `# Fixtures
 
 Store your audio, image, and data assets in this directory.
@@ -102,6 +106,19 @@ Store your audio, image, and data assets in this directory.
         fs.writeFileSync(fixturesReadmePath, fixturesReadmeContent);
         console.log("[OK] Created fixtures/README.md");
     }
+    // 4. Secure the Workspace (.gitignore)
+    const ignorePayload = `\n# Flowstride Execution Data\n.flowstride\nflowstride-artifacts\n`;
+    if (!fs.existsSync(gitignorePath)) {
+        fs.writeFileSync(gitignorePath, `node_modules\n${ignorePayload}`);
+        console.log("[OK] Created .gitignore to secure local session data");
+    }
+    else {
+        const existingIgnore = fs.readFileSync(gitignorePath, "utf8");
+        if (!existingIgnore.includes(".flowstride")) {
+            fs.appendFileSync(gitignorePath, ignorePayload);
+            console.log("[OK] Updated .gitignore to secure local session data");
+        }
+    }
     console.log();
     const browserSpinner = (0, ora_1.default)("Downloading Chromium execution engine...").start();
     try {

package/dist/cli/commands/run.d.ts

@@ -1 +1 @@
-export declare function runAction(targetPath: string | undefined, options: Record<string, any>): Promise<void>;
+export declare function runAction(targetPath: string, options: Record<string, any>): Promise<void>;

package/dist/cli/commands/run.js

@@ -38,6 +38,7 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const dotenv = __importStar(require("dotenv"));
 const os = __importStar(require("os"));
+const url_1 = require("url");
 const flow_worker_1 = require("../../runner/flow_worker");
 const flow_orchestrator_1 = require("../../runner/flow_orchestrator");
 const playwright_1 = require("../../adapters/web/playwright");
@@ -76,12 +77,10 @@ async function runAction(targetPath, options) {
     if (isCI) {
         console.log("\n[CI/CD]: Environment detected. Engaging Smart Automation Behaviors...");
     }
-    const resolvedPath = targetPath
-        ? path.resolve(root, targetPath)
-        : path.resolve(root, "flows");
+    // The CLI (index.ts) now strictly guarantees targetPath is the absolute path to ./flows
+    const resolvedPath = targetPath;
     if (!fs.existsSync(resolvedPath)) {
-        console.error(`\n[Error]: Cannot find target path "${resolvedPath}".`);
-        console.log(`[Info]: Try running 'flowstride init' to create a workspace first.\n`);
+        console.error(`\n[Error]: Cannot find strict target path "${resolvedPath}".`);
         process.exit(1);
     }
     console.log(`\n[Flowstride]: Starting execution suite at "${resolvedPath}"...`);
@@ -130,8 +129,33 @@ async function runAction(targetPath, options) {
     const pluginManager = new plugin_manager_1.PluginManager(config, web, store, apiProxy);
     const vault = new persistent_vault_1.PersistentVault(root);
     const sessions = new manager_1.SessionManager(web, api, vault);
-    const worker = new flow_worker_1.FlowWorker(config, web, api, store, sessions, pluginManager);
-    const orchestrator = new flow_orchestrator_1.FlowOrchestrator(worker, workerCount, config);
+    // ==========================================
+    // DYNAMIC ENGINE ROUTER (The Plugin Handoff)
+    // ==========================================
+    let ActiveFlowWorker = flow_worker_1.FlowWorker;
+    let ActiveFlowOrchestrator = flow_orchestrator_1.FlowOrchestrator;
+    let engineMode = "Open Source";
+    // Check the local node_modules for the Pro engine
+    const proWorkerPath = path.join(process.cwd(), "node_modules", "@flowstride", "pro", "dist", "runner", "flow_worker.js");
+    const proOrchPath = path.join(process.cwd(), "node_modules", "@flowstride", "pro", "dist", "runner", "flow_orchestrator.js");
+    if (fs.existsSync(proWorkerPath) && fs.existsSync(proOrchPath)) {
+        try {
+            // Dynamically load the Pro classes using native absolute URL resolution
+            const proWorkerModule = await import((0, url_1.pathToFileURL)(proWorkerPath).href);
+            const proOrchModule = await import((0, url_1.pathToFileURL)(proOrchPath).href);
+            ActiveFlowWorker = proWorkerModule.FlowWorker;
+            ActiveFlowOrchestrator = proOrchModule.FlowOrchestrator;
+            engineMode = "Enterprise (Pro)";
+        }
+        catch (err) {
+            console.warn(`\n[Warning]: Found @flowstride/pro but failed to boot it. Falling back to Open Source engine. (${err.message})`);
+        }
+    }
+    console.log(`\n[Engine]: Booting Flowstride in ${engineMode} mode...`);
+    // ==========================================
+    // Instantiate the chosen engine (OS or Pro)
+    const worker = new ActiveFlowWorker(config, web, api, store, sessions, pluginManager);
+    const orchestrator = new ActiveFlowOrchestrator(worker, workerCount, config);
     try {
         await orchestrator.start(resolvedPath);
         console.log("\n[Flowstride]: Execution suite completed successfully.");

package/dist/cli/index.js

@@ -1,34 +1,199 @@
 #!/usr/bin/env node
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const run_1 = require("./commands/run");
 const report_1 = require("./commands/report");
 const init_1 = require("./commands/init");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const child_process_1 = require("child_process");
+const prompts_1 = require("@inquirer/prompts");
+const chalk_1 = __importDefault(require("chalk"));
+const ora_1 = __importDefault(require("ora"));
 const program = new commander_1.Command();
 program
     .name("flowstride")
     .description("Flowstride: The Enterprise Flow-First Automation CLI")
-    .version("1.0.1");
+    .version("1.0.3");
 program
     .command("init")
     .description("Initialise a new Flowstride workspace in the current directory")
     .action(async () => {
     await (0, init_1.initAction)();
 });
+program
+    .command("login")
+    .description("Authenticate this machine with Flowstride Enterprise Cloud")
+    .action(async () => {
+    console.log(chalk_1.default.bold.blue("\n🌐 Flowstride Enterprise Cloud Sync\n"));
+    const userEmail = await (0, prompts_1.input)({ message: "Enter your Flowstride email:" });
+    const userPass = await (0, prompts_1.password)({ message: "Enter your password:" });
+    // Silently grab the computer's hostname without bothering the user
+    const deviceName = os.hostname();
+    const spinner = (0, ora_1.default)("Authenticating with Cloud...").start();
+    try {
+        // 1. Authenticate with Next.js Server
+        const authString = Buffer.from(`${userEmail}:${userPass}`).toString("base64");
+        const response = await fetch("https://cloud.flowstride.io/api/auth/cli-sync", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Basic ${authString}`,
+            },
+            body: JSON.stringify({ deviceName }),
+        });
+        const data = await response.json();
+        if (!response.ok) {
+            spinner.fail(chalk_1.default.red(`Authentication Failed: ${data.error || "Unknown error"}`));
+            process.exit(1);
+        }
+        spinner.succeed(chalk_1.default.green("Authentication Successful!"));
+        // 2. Save Machine Token Locally
+        const configDir = path.join(os.homedir(), ".flowstride");
+        if (!fs.existsSync(configDir)) {
+            fs.mkdirSync(configDir, { recursive: true });
+        }
+        const credentialsPath = path.join(configDir, "credentials.json");
+        fs.writeFileSync(credentialsPath, JSON.stringify({
+            machineToken: data.machineToken,
+            workspaceId: data.workspaceId,
+            deviceName: deviceName,
+            syncedAt: new Date().toISOString(),
+        }, null, 2));
+        console.log(chalk_1.default.gray(`\nCredentials saved to ${credentialsPath}`));
+        console.log(chalk_1.default.bold.green(`\n✅ Machine synchronized with Flowstride Enterprise.`));
+        // 3. The Auto-Installer Logic
+        if (data.githubToken) {
+            console.log(chalk_1.default.yellow(`\n⚙️ System Check: You have access to Enterprise features (AI Healing, Parallel Workers).`));
+            const localPackageJsonPath = path.join(process.cwd(), "package.json");
+            const nodeModulesPath = path.join(process.cwd(), "node_modules", "@heroamogs", "pro");
+            if (fs.existsSync(localPackageJsonPath) &&
+                !fs.existsSync(nodeModulesPath)) {
+                const installPro = await (0, prompts_1.confirm)({
+                    message: "The Pro Engine is not installed in this project. Would you like Flowstride to automatically install it now?",
+                    default: true,
+                });
+                if (installPro) {
+                    const installSpinner = (0, ora_1.default)("Configuring secure registry and installing @heroamogs/pro...").start();
+                    const npmrcPath = path.join(process.cwd(), ".npmrc");
+                    let originalNpmrc = "";
+                    try {
+                        // A. Backup existing .npmrc if it exists
+                        if (fs.existsSync(npmrcPath)) {
+                            originalNpmrc = fs.readFileSync(npmrcPath, "utf8");
+                        }
+                        // B. Write the temporary GitHub configuration
+                        const tempNpmrcContent = `
+@heroamogs:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${data.githubToken}
+`;
+                        fs.writeFileSync(npmrcPath, (originalNpmrc ? originalNpmrc + "\n" : "") + tempNpmrcContent);
+                        installSpinner.stop(); // Stop spinner so we can see the exact npm logs
+                        console.log(chalk_1.default.cyan("Starting npm install..."));
+                        // C. Run the install WITH INHERIT to expose the exact error
+                        (0, child_process_1.execSync)("npm install @heroamogs/pro --save-dev", {
+                            stdio: "inherit",
+                            cwd: process.cwd(),
+                        });
+                        console.log(chalk_1.default.green("\n✅ Enterprise Engine installed successfully!"));
+                    }
+                    catch (installError) {
+                        console.log(chalk_1.default.red("\n✖ Failed to install the Enterprise Engine automatically."));
+                        console.error(chalk_1.default.gray("You may need to install it manually."));
+                    }
+                    finally {
+                        // D. Secure Cleanup: Remove the token from .npmrc
+                        if (originalNpmrc) {
+                            fs.writeFileSync(npmrcPath, originalNpmrc); // Restore original
+                        }
+                        else {
+                            if (fs.existsSync(npmrcPath))
+                                fs.unlinkSync(npmrcPath); // Delete if we created it
+                        }
+                    }
+                }
+                else {
+                    console.log(chalk_1.default.gray(`\nSkipped installation. You can run 'npm install @heroamogs/pro --save-dev' manually later.`));
+                }
+            }
+        }
+    }
+    catch (error) {
+        spinner.fail(chalk_1.default.red(`Network Error: Could not connect to cloud.flowstride.io`));
+        process.exit(1);
+    }
+});
 program
     .command("run")
-    .description("Execute .flow automation journeys")
-    .argument("[path]", "Path to .flow files or directory (defaults to ./flows)")
+    .description("Execute all .flow automation journeys in the ./flows directory")
     .option("-b, --bail", "Stop execution on first failure", false)
     .option("--headed", "Run browser in headed mode", false)
     .option("--headless <boolean>", "Run browser in headless mode", (val) => val === "true", true)
     .option("--workers <number>", "Number of parallel workers to spawn (Pro feature)")
-    .action(async (path, options) => {
+    .action(async (options) => {
+    const credentialsPath = path.join(os.homedir(), ".flowstride", "credentials.json");
+    let isPro = false;
+    if (fs.existsSync(credentialsPath)) {
+        try {
+            const credentials = JSON.parse(fs.readFileSync(credentialsPath, "utf8"));
+            isPro = true;
+            console.log(`[PRO]: Machine Synced to Enterprise Cloud`);
+        }
+        catch (err) {
+            console.log(`[AUTH ERROR]: Invalid credentials file. Run 'flowstride login' to reconnect.`);
+        }
+    }
+    else {
+        console.log(`[OS]: Local Mode (Run 'flowstride login' to sync to Enterprise Cloud)`);
+    }
     if (options.headed) {
         options.headless = false;
     }
-    await (0, run_1.runAction)(path, options);
+    const strictUiFlowsDir = path.resolve(process.cwd(), "./flows");
+    if (!fs.existsSync(strictUiFlowsDir)) {
+        console.error(`\n[ERROR]: Could not find ${strictUiFlowsDir}.`);
+        console.error(`Flowstride requires all UI tests to be inside a './flows' directory.`);
+        process.exit(1);
+    }
+    await (0, run_1.runAction)(strictUiFlowsDir, options);
 });
 program
     .command("report")

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "flowstride",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "An opensource flowfirst test automation framework",
   "workspaces": [
-    "packages/*"
+    "packages/flowstride_report"
   ],
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -32,6 +32,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "@inquirer/prompts": "^7.10.1",
     "chalk": "^4.1.2",
     "commander": "^11.0.0",
     "dotenv": "^17.4.2",