flowstride 1.0.14 → 1.0.16

package/README.md

@@ -4,6 +4,8 @@
 
 Flowstride OS combines the human-readable structure of Behavior-Driven Development (BDD) with the raw execution power of Playwright. It allows QA engineers and developers to write robust, maintainable UI and API tests using an intuitive domain-specific language (DSL), while providing a rich, interactive React dashboard to monitor, debug, and replay test runs in real time.
 
+[Documentation](https://docs.flowstride.io/)
+
 ---
 
 ## Why Flowstride?

package/dist/cli/commands/run.js

@@ -97,7 +97,11 @@ async function runAction(targetPath, options) {
         }
     }
     const config = {
-        headless: isCI ? true : (options.headless ?? localConfig.headless ?? true),
+        headless: isCI
+            ? true
+            : options.headed
+                ? false
+                : (localConfig.headless ?? true),
         timeout: localConfig.timeout ?? 30000,
         bail: options.bail ?? localConfig.bail ?? false,
         baseUrl: process.env.BASE_URL ?? localConfig.baseUrl,
@@ -129,15 +133,11 @@ 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);
-    // ==========================================
-    // DYNAMIC ENGINE ROUTER (The Plugin Handoff)
-    // ==========================================
     let ActiveFlowWorker = flow_worker_1.FlowWorker;
     let ActiveFlowOrchestrator = flow_orchestrator_1.FlowOrchestrator;
     let engineMode = "Open Source";
     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");
-    // We only attempt to load the Pro Engine if the DRM Bouncer (index.ts) did NOT force OS Mode
     if (!options.forceOS &&
         fs.existsSync(proWorkerPath) &&
         fs.existsSync(proOrchPath)) {
@@ -153,7 +153,6 @@ async function runAction(targetPath, options) {
         }
     }
     console.log(`\n[Engine]: Booting Flowstride in ${engineMode} mode...`);
-    // ==========================================
     const worker = new ActiveFlowWorker(config, web, api, store, sessions, pluginManager);
     const orchestrator = new ActiveFlowOrchestrator(worker, workerCount, config);
     try {

package/dist/cli/index.js

@@ -54,7 +54,7 @@ const API_BASE = process.env.FLOWSTRIDE_API_URL || "https://cloud.flowstride.io"
 program
     .name("flowstride")
     .description("Flowstride: The Enterprise Flow-First Automation CLI")
-    .version("1.0.14");
+    .version("1.0.16");
 program
     .command("init")
     .description("Initialise a new Flowstride workspace in the current directory")
@@ -64,33 +64,40 @@ program
 program
     .command("login")
     .description("Authenticate this machine with Flowstride Enterprise Cloud")
-    .action(async () => {
+    .option("-t, --token <token>", "Enterprise Developer Token")
+    .option("-g, --global", "Save the token globally for all projects on this machine", false)
+    .action(async (options) => {
     const localPackageJsonPath = path.join(process.cwd(), "package.json");
-    if (!fs.existsSync(localPackageJsonPath)) {
-        console.error(chalk_1.default.red("✖ Error: Please navigate to a valid Flowstride project directory before logging in."));
-        process.exit(1);
-    }
-    const pkg = JSON.parse(fs.readFileSync(localPackageJsonPath, "utf8"));
-    const deps = {
-        ...(pkg.dependencies || {}),
-        ...(pkg.devDependencies || {}),
-    };
-    if (!deps["flowstride"] && !deps["flowstride-os"]) {
-        console.error(chalk_1.default.red("✖ Error: Please navigate to a valid Flowstride project directory before logging in."));
-        process.exit(1);
+    // Enforce valid project directory ONLY if doing a local login
+    if (!options.global) {
+        if (!fs.existsSync(localPackageJsonPath)) {
+            console.error(chalk_1.default.red("✖ Error: Please navigate to a valid Flowstride project directory before logging in locally, or use --global."));
+            process.exit(1);
+        }
+        const pkg = JSON.parse(fs.readFileSync(localPackageJsonPath, "utf8"));
+        const deps = {
+            ...(pkg.dependencies || {}),
+            ...(pkg.devDependencies || {}),
+        };
+        if (!deps["flowstride"] && !deps["flowstride-os"]) {
+            console.error(chalk_1.default.red("✖ Error: Please navigate to a valid Flowstride project directory before logging in locally, or use --global."));
+            process.exit(1);
+        }
     }
     console.log(chalk_1.default.bold.blue("\n🌐 Flowstride Enterprise Cloud Sync\n"));
-    let authHeader = "";
-    if (process.env.FLOWSTRIDE_API_KEY) {
-        console.log(chalk_1.default.yellow("🤖 CI/CD Environment Detected. Authenticating via API Key..."));
-        authHeader = `Bearer ${process.env.FLOWSTRIDE_API_KEY}`;
+    let token = process.env.FLOWSTRIDE_TOKEN || options.token;
+    if (process.env.FLOWSTRIDE_TOKEN) {
+        console.log(chalk_1.default.yellow("🤖 CI/CD Environment Detected. Authenticating via FLOWSTRIDE_TOKEN..."));
     }
-    else {
-        const userEmail = await (0, prompts_1.input)({
-            message: "Enter your Flowstride email:",
+    else if (!token) {
+        token = await (0, prompts_1.password)({
+            message: "Paste your Enterprise Developer Token:",
+            mask: "*",
         });
-        const userPass = await (0, prompts_1.password)({ message: "Enter your password:" });
-        authHeader = `Basic ${Buffer.from(`${userEmail}:${userPass}`).toString("base64")}`;
+    }
+    if (!token || token.trim().length === 0) {
+        console.error(chalk_1.default.red("✖ Error: A valid Developer Token is required."));
+        process.exit(1);
     }
     const deviceName = os.hostname();
     const spinner = (0, ora_1.default)("Authenticating with Cloud...").start();
@@ -99,34 +106,37 @@ program
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
-                Authorization: authHeader,
+                Authorization: `Bearer ${token.trim()}`,
             },
             body: JSON.stringify({ deviceName }),
         });
         const data = await response.json();
         if (!response.ok) {
-            spinner.fail(chalk_1.default.red(`Authentication Failed: ${data.error || "Unknown error"}`));
+            spinner.fail(chalk_1.default.red(`Authentication Failed: ${data.error || "Invalid token or network error"}`));
             process.exit(1);
         }
         spinner.succeed(chalk_1.default.green("Authentication Successful!"));
-        const configDir = path.join(process.cwd(), ".flowstride", "login");
+        const configDir = options.global
+            ? path.join(os.homedir(), ".flowstride")
+            : path.join(process.cwd(), ".flowstride");
         if (!fs.existsSync(configDir)) {
             fs.mkdirSync(configDir, { recursive: true });
         }
-        const credentialsPath = path.join(configDir, "login.json");
+        const credentialsPath = path.join(configDir, "credentials.json");
         fs.writeFileSync(credentialsPath, JSON.stringify({
-            machineToken: data.machineToken,
+            machineToken: data.machineToken || token.trim(),
             workspaceId: data.workspaceId,
             deviceName: deviceName,
             syncedAt: new Date().toISOString(),
         }, null, 2));
-        console.log(chalk_1.default.gray(`\nCredentials securely scoped to ${credentialsPath}`));
+        const scopeText = options.global ? "GLOBALLY" : "LOCALLY to this project";
+        console.log(chalk_1.default.gray(`\nCredentials securely scoped ${scopeText} at: ${credentialsPath}`));
         if (data.isProEligible) {
             console.log(chalk_1.default.yellow(`\n⚙️ System Check: You have access to Enterprise features (AI Healing, Parallel Workers).`));
             const nodeModulesPath = path.join(process.cwd(), "node_modules", "@flowstride", "pro");
             if (!fs.existsSync(nodeModulesPath)) {
                 let installPro = true;
-                if (!process.env.FLOWSTRIDE_API_KEY && !process.env.CI) {
+                if (!process.env.FLOWSTRIDE_TOKEN && !process.env.CI) {
                     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,
@@ -138,7 +148,7 @@ program
                     try {
                         const tarballResponse = await fetch(`${API_BASE}/api/workspace/download-pro`, {
                             method: "GET",
-                            headers: { Authorization: `Bearer ${data.machineToken}` },
+                            headers: { Authorization: `Bearer ${token.trim()}` },
                         });
                         if (!tarballResponse.ok) {
                             throw new Error(`Secure proxy rejected request: ${tarballResponse.statusText}`);
@@ -200,21 +210,34 @@ program
     .command("status")
     .description("Display the current Flowstride CLI authentication and engine tier")
     .action(async () => {
-    let token = process.env.FLOWSTRIDE_API_KEY || null;
-    const credentialsPath = path.join(process.cwd(), ".flowstride", "login", "login.json");
-    const nodeModulesPath = path.join(process.cwd(), "node_modules", "@flowstride", "pro");
-    if (!token && fs.existsSync(credentialsPath)) {
-        try {
-            const credentials = JSON.parse(fs.readFileSync(credentialsPath, "utf8"));
-            token = credentials.machineToken;
+    let token = process.env.FLOWSTRIDE_TOKEN || null;
+    const localCredentialsPath = path.join(process.cwd(), ".flowstride", "credentials.json");
+    const globalCredentialsPath = path.join(os.homedir(), ".flowstride", "credentials.json");
+    let activeCredentialsPath = localCredentialsPath; // Default for cleanup
+    if (!token) {
+        if (fs.existsSync(localCredentialsPath)) {
+            activeCredentialsPath = localCredentialsPath;
+            try {
+                const credentials = JSON.parse(fs.readFileSync(localCredentialsPath, "utf8"));
+                token = credentials.machineToken;
+            }
+            catch (err) { }
+        }
+        else if (fs.existsSync(globalCredentialsPath)) {
+            activeCredentialsPath = globalCredentialsPath;
+            try {
+                const credentials = JSON.parse(fs.readFileSync(globalCredentialsPath, "utf8"));
+                token = credentials.machineToken;
+            }
+            catch (err) { }
         }
-        catch (err) { }
     }
-    if (!process.env.FLOWSTRIDE_API_KEY &&
+    const nodeModulesPath = path.join(process.cwd(), "node_modules", "@flowstride", "pro");
+    if (!process.env.FLOWSTRIDE_TOKEN &&
         token &&
         !fs.existsSync(nodeModulesPath)) {
-        if (fs.existsSync(credentialsPath))
-            fs.unlinkSync(credentialsPath);
+        if (fs.existsSync(activeCredentialsPath))
+            fs.unlinkSync(activeCredentialsPath);
         token = null;
     }
     if (!token) {
@@ -228,8 +251,8 @@ program
         });
         if (response.status === 401) {
             console.log(chalk_1.default.red("🔴 AUTH EXPIRED: Your device session was revoked or expired."));
-            if (fs.existsSync(credentialsPath))
-                fs.unlinkSync(credentialsPath);
+            if (fs.existsSync(activeCredentialsPath))
+                fs.unlinkSync(activeCredentialsPath);
         }
         else if (response.ok) {
             const data = await response.json();
@@ -253,30 +276,43 @@ program
     .command("run [targetPath]")
     .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("--headed", "Run browser in headed mode")
+    .option("--headless", "Run browser in headless mode")
     .option("--workers <number>", "Number of parallel workers to spawn (Pro feature)")
     .action(async (targetPath, options) => {
     if (typeof targetPath === "object") {
         options = targetPath;
         targetPath = undefined;
     }
-    let token = process.env.FLOWSTRIDE_API_KEY || null;
+    let token = process.env.FLOWSTRIDE_TOKEN || null;
     let forceOS = false;
-    const credentialsPath = path.join(process.cwd(), ".flowstride", "login", "login.json");
-    const nodeModulesPath = path.join(process.cwd(), "node_modules", "@flowstride", "pro");
-    if (!token && fs.existsSync(credentialsPath)) {
-        try {
-            const credentials = JSON.parse(fs.readFileSync(credentialsPath, "utf8"));
-            token = credentials.machineToken;
+    const localCredentialsPath = path.join(process.cwd(), ".flowstride", "credentials.json");
+    const globalCredentialsPath = path.join(os.homedir(), ".flowstride", "credentials.json");
+    let activeCredentialsPath = localCredentialsPath;
+    if (!token) {
+        if (fs.existsSync(localCredentialsPath)) {
+            activeCredentialsPath = localCredentialsPath;
+            try {
+                const credentials = JSON.parse(fs.readFileSync(localCredentialsPath, "utf8"));
+                token = credentials.machineToken;
+            }
+            catch (err) { }
+        }
+        else if (fs.existsSync(globalCredentialsPath)) {
+            activeCredentialsPath = globalCredentialsPath;
+            try {
+                const credentials = JSON.parse(fs.readFileSync(globalCredentialsPath, "utf8"));
+                token = credentials.machineToken;
+            }
+            catch (err) { }
         }
-        catch (err) { }
     }
-    if (!process.env.FLOWSTRIDE_API_KEY &&
+    const nodeModulesPath = path.join(process.cwd(), "node_modules", "@flowstride", "pro");
+    if (!process.env.FLOWSTRIDE_TOKEN &&
         token &&
         !fs.existsSync(nodeModulesPath)) {
-        if (fs.existsSync(credentialsPath))
-            fs.unlinkSync(credentialsPath);
+        if (fs.existsSync(activeCredentialsPath))
+            fs.unlinkSync(activeCredentialsPath);
         token = null;
     }
     if (!token) {
@@ -291,8 +327,8 @@ program
             });
             if (response.status === 401) {
                 console.log(chalk_1.default.red("🔴 AUTH EXPIRED: Your device session was revoked or expired."));
-                if (fs.existsSync(credentialsPath))
-                    fs.unlinkSync(credentialsPath);
+                if (fs.existsSync(activeCredentialsPath))
+                    fs.unlinkSync(activeCredentialsPath);
                 forceOS = true;
             }
             else if (response.ok) {
@@ -328,7 +364,7 @@ program
 });
 async function handleOfflinePrompt() {
     console.log(chalk_1.default.yellow("🛜 OFFLINE: Unable to reach Flowstride Cloud. Enterprise Sync paused."));
-    if (process.env.CI || process.env.FLOWSTRIDE_API_KEY) {
+    if (process.env.CI || process.env.FLOWSTRIDE_TOKEN) {
         console.log(chalk_1.default.yellow("⚠️ CI/CD Environment: Automatically falling back to OS Engine."));
         return true;
     }

package/dist/parser/parser.js

@@ -615,9 +615,28 @@ class Parser {
                     throw new Error(`Syntax Error on line ${targetToken.line}: Invalid keyword '${target}'. Flowstride uses strict camelCase. Did you mean 'reqHeader'?`);
                 }
                 if (target === "reqHeader") {
-                    const hKey = this.consume(lexer_1.TokenType.STRING, "Header key expected").value;
-                    const hVal = this.consume(lexer_1.TokenType.STRING, "Header value expected").value;
-                    payload.headers.push({ key: hKey, value: hVal });
+                    const firstToken = this.consume(lexer_1.TokenType.STRING, "Header key or JSON block expected");
+                    if (!this.isAtEnd() && this.peek().type === lexer_1.TokenType.STRING) {
+                        const hKey = firstToken.value;
+                        const hVal = this.advance().value;
+                        payload.headers.push({ key: hKey, value: hVal });
+                    }
+                    else {
+                        try {
+                            const headerObj = JSON.parse(firstToken.value);
+                            if (typeof headerObj !== "object" ||
+                                headerObj === null ||
+                                Array.isArray(headerObj)) {
+                                throw new Error("Parsed JSON is not a Key-Value object.");
+                            }
+                            for (const [k, v] of Object.entries(headerObj)) {
+                                payload.headers.push({ key: k, value: String(v) });
+                            }
+                        }
+                        catch (e) {
+                            throw new Error(`Line ${firstToken.line}: Invalid JSON format for reqHeader block. Ensure it is a valid JSON object, or use the legacy format with two strings (Key and Value).`);
+                        }
+                    }
                 }
                 else if (target === "reqBody") {
                     payload.body = this.consume(lexer_1.TokenType.STRING, "Body content expected").value;

package/dist/runner/flow_orchestrator.js

@@ -276,22 +276,41 @@ class FlowOrchestrator {
                     }
                 });
             });
-            this.httpServer.listen(0, async () => {
-                const address = this.httpServer?.address();
-                const port = typeof address === "object" && address !== null ? address.port : null;
-                if (!port) {
-                    console.error(chalk_1.default.red("\n[Error]: Could not bind to an available port."));
-                    process.exit(1);
-                }
-                const localUrl = `http://localhost:${port}`;
-                const { default: open } = await import("open");
-                await open(localUrl);
-                console.log(chalk_1.default.yellow(`\n[Dashboard]: Local server running at ${localUrl}`));
-                console.log(chalk_1.default.yellow("[Dashboard]: Waiting for UI connection..."));
-                while (this.wss.clients.size === 0)
-                    await new Promise((r) => setTimeout(r, 250));
-                console.log(chalk_1.default.green("[Dashboard]: Connected to UI!"));
-                await this.executeTestRun(targetPath);
+            return new Promise((resolve, reject) => {
+                this.httpServer.listen(0, async () => {
+                    try {
+                        const address = this.httpServer?.address();
+                        const port = typeof address === "object" && address !== null
+                            ? address.port
+                            : null;
+                        if (!port) {
+                            console.error(chalk_1.default.red("\n[Error]: Could not bind to an available port."));
+                            return reject(new Error("No port available"));
+                        }
+                        const localUrl = `http://localhost:${port}`;
+                        console.log(chalk_1.default.yellow(`\n[Dashboard]: Local server running at ${localUrl}`));
+                        const isStrictHeadless = process.argv.includes("--headless") ||
+                            !!process.env.CI ||
+                            !!process.env.GITHUB_ACTIONS ||
+                            !!process.env.FLOWSTRIDE_API_KEY;
+                        if (!isStrictHeadless) {
+                            const { default: open } = await import("open");
+                            await open(localUrl);
+                            console.log(chalk_1.default.yellow("[Dashboard]: Waiting for UI connection..."));
+                            while (this.wss.clients.size === 0)
+                                await new Promise((r) => setTimeout(r, 250));
+                            console.log(chalk_1.default.green("[Dashboard]: Connected to UI!"));
+                        }
+                        else {
+                            console.log(chalk_1.default.gray("[Dashboard]: Headless mode active. Bypassing UI auto-launch..."));
+                        }
+                        await this.executeTestRun(targetPath);
+                        resolve(undefined);
+                    }
+                    catch (err) {
+                        reject(err);
+                    }
+                });
             });
         }
         catch (e) {

package/dist/runner/flow_worker.js

@@ -131,6 +131,9 @@ class FlowWorker extends events_1.EventEmitter {
         return context;
     }
     resolveTextVariables(text) {
+        if (typeof text !== "string") {
+            return text;
+        }
         let resolved = text;
         resolved = resolved.replace(/\{\{env\.([a-zA-Z0-9_]+)\}\}/g, (_, varName) => {
             const val = process.env[varName];
@@ -259,11 +262,21 @@ class FlowWorker extends events_1.EventEmitter {
         catch {
             rawBodyString = typeof body === "string" ? body : null;
         }
-        const curlString = this.web.synthesizeCurl(method, cleanUrl, headers || {}, rawBodyString);
+        let formattedHeaders = {};
+        if (Array.isArray(headers)) {
+            headers.forEach((h) => {
+                if (h && h.key)
+                    formattedHeaders[h.key] = h.value;
+            });
+        }
+        else if (headers && typeof headers === "object") {
+            formattedHeaders = headers;
+        }
+        const curlString = this.web.synthesizeCurl(method, cleanUrl, formattedHeaders, rawBodyString);
         this.emitLog("REST", (state.status || 500) < 400 ? "success" : "error", `${method.toUpperCase()} ${endpointName}`, {
             method: method.toUpperCase(),
             url: cleanUrl,
-            requestHeaders: headers,
+            requestHeaders: formattedHeaders,
             requestBody: parsedReqBody,
             responseStatus: state.status,
             responseHeaders: state.headers,
@@ -340,7 +353,14 @@ class FlowWorker extends events_1.EventEmitter {
         this.isAborted = true;
     }
     async runBatch(filesToProcess) {
-        this.config.headless = true;
+        // this.config.headless = true;
+        const isCliHeadless = process.argv.includes("--headless");
+        if (isCliHeadless) {
+            this.config.headless = true;
+        }
+        else if (this.config.headless === undefined) {
+            this.config.headless = false;
+        }
         this.activeAudioPath = undefined;
         this.isAborted = false;
         this.isDebugHalted = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowstride",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "description": "An opensource flowfirst test automation framework",
   "workspaces": [
     "packages/flowstride_report"