@itmetsam/samurai-framework 0.6.0 → 0.7.1

package/README.md

@@ -20,7 +20,7 @@ test("Visitor can sign in", async ({ page, env, secrets }) => {
 - **Semantic locators.** By role, label, text, test id, CSS or XPath, with ordered fallbacks.
 - **Environments and secrets.** One test file runs against `dev`, `staging` or `production`; secrets come from the environment or a `.env.<name>` file and are masked in logs and reports.
 - **Network control.** Mock, block or modify requests; wait for requests, responses and network idle; read response bodies.
-- **Recorder building blocks.** Specs are parsed into steps and edited back with minimal diffs, and an engine records what a person does in the browser. The UI that ties them together is not built yet (see the [roadmap](docs/roadmap.md)).
+- **Recorder building blocks.** Specs are parsed into steps and edited back with minimal diffs, and an engine records what a person does in the browser. A toolbar in the recorded page adds assertions, variables and secrets, waits, screenshots and pause (see [Steps and the recorder](docs/recorder.md)). The Electron app that ties them together lives in a separate repository (see the [roadmap](docs/roadmap.md)).
 
 > **Status:** early. Firefox only. See [what is still open](docs/roadmap.md).
 
@@ -119,7 +119,7 @@ Read it in a test as `secrets.TEST_PASSWORD`. Real environment variables win ove
 | [Command line](docs/cli.md)                                  | `samurai run`, `list`, `record` and `init`, options, output, exit codes, `--json`                     |
 | [Flows](docs/flows.md)                                       | `samurai flow list`, `check` and `run`: graphs of tests, groups and steps, reports, CI                |
 | [Running tests and reports](docs/running-and-reports.md)     | What a run does, `report.json`, page logs, timeouts                                                   |
-| [Steps and the recorder](docs/recorder.md)                   | The step codec and the recording engine                                                               |
+| [Steps and the recorder](docs/recorder.md)                   | The step codec, the recording engine and the recorder toolbar                                         |
 | [Embedding the framework](docs/embedding.md)                 | Using the package from another app (such as the Electron UI): build, entry points, `runTests`, events |
 | [Contributing](docs/contributing.md)                         | Project layout, running the framework's own tests, conventions                                        |
 | [Roadmap](docs/roadmap.md)                                   | What is built and what is still open                                                                  |

package/bin/samurai.mjs

@@ -1,4 +1,29 @@
 #!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// Specs import the framework from their project. A global (or linked) samurai must run that same copy, or the specs
+// register their tests in the project's copy and this one finds none
+const own = realpathSync(
+  path.join(path.dirname(fileURLToPath(import.meta.url)), ".."),
+);
+let local;
+try {
+  local = path.dirname(
+    createRequire(path.join(process.cwd(), "package.json")).resolve(
+      "@itmetsam/samurai-framework/package.json",
+    ),
+  );
+} catch {
+  local = undefined;
+}
+if (local !== undefined && realpathSync(local) !== own) {
+  // That copy's binary runs the command and exits
+  await import(pathToFileURL(path.join(local, "bin/samurai.mjs")).href);
+}
+
 // Quiet the framework's console logging unless the caller asked for more; the log files keep everything
 process.env.SAMURAI_LOG_LEVEL ??= "warn";
 

package/dist/browser/evidence.d.ts

@@ -0,0 +1,19 @@
+/** A screenshot name as a file name: letters, digits, - and _ (the rest becomes -) */
+export declare function cleanName(name: string): string;
+/** Where a run (or one test) saves named screenshots, and the ones it saved */
+export declare class Evidence {
+    private readonly resultDir;
+    private readonly testDir?;
+    readonly screenshots: {
+        name: string;
+        path: string;
+    }[];
+    private readonly used;
+    constructor(resultDir: string, testDir?: string | undefined);
+    /** The file for the next screenshot called `name` (`.jpg` for a jpeg, else `.png`); a repeat gets -2, -3, … */
+    fileFor(name: string, type?: "png" | "jpeg"): {
+        file: string;
+        name: string;
+        path: string;
+    };
+}

package/dist/browser/evidence.js

@@ -0,0 +1,35 @@
+import path from "node:path";
+/** A screenshot name as a file name: letters, digits, - and _ (the rest becomes -) */
+export function cleanName(name) {
+    const cleaned = name.replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+    return cleaned === "" ? "screenshot" : cleaned;
+}
+/** Where a run (or one test) saves named screenshots, and the ones it saved */
+export class Evidence {
+    constructor(resultDir, testDir) {
+        this.resultDir = resultDir;
+        this.testDir = testDir;
+        this.screenshots = [];
+        this.used = new Set();
+    }
+    /** The file for the next screenshot called `name` (`.jpg` for a jpeg, else `.png`); a repeat gets -2, -3, … */
+    fileFor(name, type = "png") {
+        const base = cleanName(name);
+        let unique = base;
+        for (let n = 2; this.used.has(unique); n++)
+            unique = `${base}-${n}`;
+        this.used.add(unique);
+        const relative = [
+            "screenshots",
+            ...(this.testDir ? this.testDir.split("/") : []),
+            `${unique}.${type === "jpeg" ? "jpg" : "png"}`,
+        ].join("/");
+        const entry = {
+            file: path.join(this.resultDir, ...relative.split("/")),
+            name: unique,
+            path: relative,
+        };
+        this.screenshots.push({ name: entry.name, path: entry.path });
+        return entry;
+    }
+}

package/dist/browser/page.d.ts

@@ -9,6 +9,7 @@ import { type EmulationOptions } from "./emulation.js";
 import { Download } from "./download.js";
 import { FileChooser } from "./file-chooser.js";
 import { type ScreenshotOptions } from "./screenshot.js";
+import { Evidence } from "./evidence.js";
 import { type ConsoleMessage, type LogRecord, type PageError } from "./page-logs.js";
 import { type RouteHandler } from "../network/router.js";
 import { Response } from "../network/response.js";
@@ -182,6 +183,11 @@ export default class Page {
      *  await page.screenshot({ path: "out/home.png", fullPage: true });
      */
     screenshot(options?: ScreenshotOptions): Promise<Buffer>;
+    private evidence;
+    /** @internal The runner gives each test its own evidence folder */
+    setEvidence(evidence: Evidence | undefined): void;
+    /** Waits `ms` milliseconds. Prefer waiting for something (an assertion, `waitForNetworkIdle`) when you can */
+    waitForTimeout(ms: number): Promise<void>;
     /** Renders the page as a PDF and returns it (also written to `options.path`) */
     pdf(options?: PdfOptions): Promise<Buffer>;
     /** The browser context (cookies, storage) this page belongs to */

package/dist/browser/page.js

@@ -1,7 +1,8 @@
 import Locator, {} from "../locator/locator.js";
 import { cssSelector, labelSelector, roleSelector, testIdSelector, textSelector, } from "../locator/selector.js";
 import EventEmitter from "node:events";
-import { readConfig } from "../config/config.js";
+import path from "node:path";
+import { projectDir, readConfig } from "../config/config.js";
 import { peekRunSettings } from "../config/run-settings.js";
 import logger from "../logger/index.js";
 import { NetworkTracker, } from "../network/network-tracker.js";
@@ -13,7 +14,8 @@ import { applyEmulation } from "./emulation.js";
 import { Download, DownloadTracker } from "./download.js";
 import { FileChooser, FileChooserTracker } from "./file-chooser.js";
 import { DownloadWaitTimeoutError, FileChooserTimeoutError, } from "./page-wait.js";
-import { takeScreenshot } from "./screenshot.js";
+import { takeScreenshot, writeOutput, } from "./screenshot.js";
+import { Evidence } from "./evidence.js";
 import { PageLogs, } from "./page-logs.js";
 import { Router } from "../network/router.js";
 import { DataCollector, ResponseBodyUnavailableError, } from "../network/data-collector.js";
@@ -405,7 +407,22 @@ export default class Page {
      */
     async screenshot(options = {}) {
         this.assertOpen();
-        return takeScreenshot(this.biDiConnector, this.id, options);
+        const image = await takeScreenshot(this.biDiConnector, this.id, options);
+        if (options.name !== undefined) {
+            const evidence = this.evidence ?? new Evidence(path.join(projectDir(), "result"));
+            await writeOutput(evidence.fileFor(options.name, options.type).file, image);
+        }
+        return image;
+    }
+    /** @internal The runner gives each test its own evidence folder */
+    setEvidence(evidence) {
+        this.evidence = evidence;
+    }
+    /** Waits `ms` milliseconds. Prefer waiting for something (an assertion, `waitForNetworkIdle`) when you can */
+    async waitForTimeout(ms) {
+        if (!Number.isFinite(ms) || ms < 0)
+            throw new RangeError(`waitForTimeout needs 0 or more milliseconds, got ${ms}`);
+        await new Promise((resolve) => setTimeout(resolve, ms));
     }
     /** Renders the page as a PDF and returns it (also written to `options.path`) */
     async pdf(options = {}) {

package/dist/browser/screenshot.d.ts

@@ -11,6 +11,8 @@ export interface ScreenshotOptions {
         width: number;
         height: number;
     };
+    /** Also save the image as run evidence under this name (see the Page API docs) */
+    name?: string;
     /** @default "png" */
     type?: "png" | "jpeg";
     /** 0 to 100, jpeg only */

package/dist/browser/screenshot.js

@@ -2,7 +2,7 @@ import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 const MIME = { png: "image/png", jpeg: "image/jpeg" };
 /** The `format` of a capture command; validates the type/quality combination */
-function imageFormat({ type, quality }) {
+function imageFormat({ type, quality, }) {
     if (quality !== undefined) {
         if (type !== "jpeg")
             throw new RangeError("screenshot(): quality only applies to jpeg");
@@ -12,7 +12,10 @@ function imageFormat({ type, quality }) {
     }
     if (type === undefined)
         return undefined;
-    return { type: MIME[type], ...(quality !== undefined && { quality: quality / 100 }) };
+    return {
+        type: MIME[type],
+        ...(quality !== undefined && { quality: quality / 100 }),
+    };
 }
 /**
  * Captures the page (or, with `element`, that element) and returns the image. Writes it to `options.path` too.

package/dist/cli/browsers.d.ts

@@ -2,5 +2,5 @@ import { type StoreOptions } from "../browsers/index.js";
 import type { Io } from "./main.js";
 export declare const BROWSERS_USAGE = "Usage:\n  samurai browsers [list]                        The pinned browsers and every build in the cache\n  samurai browsers install [firefox|chrome|all]  Download the pinned builds (default: all)\n  samurai browsers uninstall <name> [--build <id>]\n                                                 Remove a build (default: the pinned one)\n  samurai browsers uninstall --unused            Remove builds this framework version doesn't pin\n";
 export declare function formatBytes(n: number): string;
-/** `samurai browsers …`; `options` is for tests. The cache folder and download host follow `io.env` */
+/** `samurai browsers …`; `options` is for tests. The cache folder follows `io.env` */
 export declare function browsersCommand(argv: string[], io: Io, options?: StoreOptions): Promise<number>;

package/dist/cli/browsers.js

@@ -1,5 +1,4 @@
 import { browsersCacheDir, browserStatus, installBrowser, isManagedBrowser, listInstalled, MANAGED_BROWSERS, PINNED, uninstallBrowser, } from "../browsers/index.js";
-import { puppeteerDownloader } from "../browsers/downloader.js";
 import { parseCommandLine } from "./args.js";
 export const BROWSERS_USAGE = `Usage:
   samurai browsers [list]                        The pinned browsers and every build in the cache
@@ -70,12 +69,11 @@ async function install(io, targets, store) {
         io.out(`${label} installed at ${exe}\n`);
     }
 }
-/** `samurai browsers …`; `options` is for tests. The cache folder and download host follow `io.env` */
+/** `samurai browsers …`; `options` is for tests. The cache folder follows `io.env` */
 export async function browsersCommand(argv, io, options = {}) {
     const store = {
+        ...options,
         cacheDir: options.cacheDir ?? browsersCacheDir(io.env),
-        downloader: options.downloader ??
-            puppeteerDownloader(io.env.SAMURAI_BROWSERS_BASE_URL),
     };
     const { values, positionals } = parseCommandLine(argv);
     const [sub = "list", target] = positionals;

package/dist/cli/main.js

@@ -105,6 +105,8 @@ export async function main(argv, io) {
                     ? Number(values.test)
                     : values.test;
             let count = 0;
+            let state = "recording";
+            let toolbarWarned = false;
             const result = await recordSpec({
                 ...parseRunOverrides(rest, io.env),
                 file,
@@ -116,7 +118,19 @@ export async function main(argv, io) {
                 ...(io.signal && { signal: io.signal }),
                 onStarted: () => {
                     if (!values.json)
-                        io.out("Recording. Alt+click an element to assert on it. Press Ctrl+C or close the window to stop.\n");
+                        io.out("Recording. Alt+click an element to assert on it. Press Stop in the toolbar, Ctrl+C or close the window to stop.\n");
+                },
+                onStatus: (status) => {
+                    if (values.json)
+                        return;
+                    if (!status.toolbar && !toolbarWarned) {
+                        toolbarWarned = true;
+                        io.out("The toolbar couldn't load on this page. Alt+click still records assertions.\n");
+                    }
+                    if (status.state !== state) {
+                        state = status.state;
+                        io.out(state === "paused" ? "Paused\n" : "Recording\n");
+                    }
                 },
                 onEvent: (event) => {
                     if (values.json)
@@ -131,8 +145,8 @@ export async function main(argv, io) {
             });
             if (!values.json) {
                 io.out(`\nRecorded ${count} ${count === 1 ? "step" : "steps"} into "${result.test}" in ${result.file}\n`);
-                if (result.secrets.length > 0) {
-                    io.out(`Set ${result.secrets.map((name) => `SAMURAI_SECRET_${name}`).join(", ")} (environment variable or .env.<environment>) before running it.\n`);
+                if (result.unsetSecrets.length > 0) {
+                    io.out(`Set ${result.unsetSecrets.map((name) => `SAMURAI_SECRET_${name}`).join(", ")} (environment variable or .env.<environment>) before running it.\n`);
                 }
             }
             return 0;

package/dist/project/config-edit.d.ts

@@ -0,0 +1,16 @@
+export type ConfigValue = string | number | boolean | ConfigValue[] | {
+    [key: string]: ConfigValue;
+};
+/** The config can't be edited in place, e.g. it builds its object from variables or spreads */
+export declare class ConfigEditError extends Error {
+}
+/**
+ * Sets (or with `undefined`, removes) one value in samurai.config.ts, addressed by its path, e.g.
+ * ["environments", "staging", "baseURL"]. Only that property's text changes; missing objects on the way are
+ * created. Throws ConfigEditError when the file isn't shaped so that this is safe.
+ */
+export declare function editConfig(source: string, path: string[], value: ConfigValue | undefined): string;
+/** The text of one property (`staging: { … }`), indentation removed, for showing a part of the file; undefined when missing */
+export declare function propertyText(source: string, path: string[]): string | undefined;
+/** Whether the property at this path exists in the file's source, walking the same object literals `editConfig` does */
+export declare function hasConfigPath(source: string, path: string[]): boolean;

package/dist/project/config-edit.js

@@ -0,0 +1,218 @@
+import ts from "typescript";
+/** The config can't be edited in place, e.g. it builds its object from variables or spreads */
+export class ConfigEditError extends Error {
+}
+const KEY = /^[A-Za-z_$][\w$]*$/;
+const keyText = (key) => (KEY.test(key) ? key : JSON.stringify(key));
+function emit(value, indent, unit) {
+    if (typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return "[]";
+        const inner = indent + unit;
+        return `[\n${value.map((v) => `${inner}${emit(v, inner, unit)},`).join("\n")}\n${indent}]`;
+    }
+    const entries = Object.entries(value);
+    if (entries.length === 0)
+        return "{}";
+    const inner = indent + unit;
+    return `{\n${entries
+        .map(([k, v]) => `${inner}${keyText(k)}: ${emit(v, inner, unit)},`)
+        .join("\n")}\n${indent}}`;
+}
+function nameOf(prop) {
+    if (!ts.isPropertyAssignment(prop) &&
+        !ts.isShorthandPropertyAssignment(prop)) {
+        return undefined;
+    }
+    const n = prop.name;
+    return ts.isIdentifier(n) ||
+        ts.isStringLiteral(n) ||
+        ts.isNoSubstitutionTemplateLiteral(n)
+        ? n.text
+        : undefined;
+}
+/** The object `defineConfig({...})` or `export default {...}` is given */
+function rootObject(sf) {
+    for (const statement of sf.statements) {
+        if (!ts.isExportAssignment(statement))
+            continue;
+        let node = statement.expression;
+        for (;;) {
+            if (ts.isParenthesizedExpression(node) ||
+                ts.isSatisfiesExpression(node) ||
+                ts.isAsExpression(node)) {
+                node = node.expression;
+            }
+            else
+                break;
+        }
+        if (ts.isCallExpression(node) &&
+            node.arguments[0] &&
+            ts.isObjectLiteralExpression(node.arguments[0])) {
+            return node.arguments[0];
+        }
+        if (ts.isObjectLiteralExpression(node))
+            return node;
+    }
+    throw new ConfigEditError("samurai.config.ts doesn't export a plain object (defineConfig({ … })), so it can't be edited here.");
+}
+const lineIndent = (source, pos) => {
+    const start = source.lastIndexOf("\n", pos - 1) + 1;
+    return /^[ \t]*/.exec(source.slice(start))[0];
+};
+function unitOf(source, obj) {
+    const first = obj.properties[0];
+    if (first) {
+        const inner = lineIndent(source, first.getStart());
+        const outer = lineIndent(source, obj.getStart());
+        if (inner.length > outer.length)
+            return inner.slice(outer.length);
+    }
+    return "  ";
+}
+function insertProperty(source, obj, key, value) {
+    const unit = unitOf(source, obj);
+    const outer = lineIndent(source, obj.getStart());
+    const inner = outer + unit;
+    const multiline = obj.getText().includes("\n");
+    const prop = `${keyText(key)}: ${emit(value, inner, unit)}`;
+    const last = obj.properties[obj.properties.length - 1];
+    if (!last) {
+        return {
+            start: obj.getStart(),
+            end: obj.end,
+            text: `{\n${inner}${prop},\n${outer}}`,
+        };
+    }
+    const trailing = obj.properties.hasTrailingComma
+        ? /^\s*,/.exec(source.slice(last.end))
+        : null;
+    if (!multiline) {
+        return trailing
+            ? {
+                start: last.end + trailing[0].length,
+                end: last.end + trailing[0].length,
+                text: ` ${keyText(key)}: ${emit(value, outer, unit)},`,
+            }
+            : {
+                start: last.end,
+                end: last.end,
+                text: `, ${keyText(key)}: ${emit(value, outer, unit)}`,
+            };
+    }
+    return trailing
+        ? {
+            start: last.end + trailing[0].length,
+            end: last.end + trailing[0].length,
+            text: `\n${inner}${prop},`,
+        }
+        : { start: last.end, end: last.end, text: `,\n${inner}${prop}` };
+}
+function removeProperty(source, prop) {
+    const s = prop.getStart();
+    let e = prop.end;
+    const comma = /^[ \t]*,/.exec(source.slice(e));
+    if (comma)
+        e += comma[0].length;
+    const lineStart = source.lastIndexOf("\n", s - 1) + 1;
+    const aloneBefore = /^[ \t]*$/.test(source.slice(lineStart, s));
+    const rest = /^[ \t]*(\r?\n)/.exec(source.slice(e));
+    if (aloneBefore && rest)
+        return { start: lineStart, end: e + rest[0].length, text: "" };
+    const space = /^[ \t]*/.exec(source.slice(e))[0];
+    return { start: s, end: e + space.length, text: "" };
+}
+/**
+ * Sets (or with `undefined`, removes) one value in samurai.config.ts, addressed by its path, e.g.
+ * ["environments", "staging", "baseURL"]. Only that property's text changes; missing objects on the way are
+ * created. Throws ConfigEditError when the file isn't shaped so that this is safe.
+ */
+export function editConfig(source, path, value) {
+    if (path.length === 0)
+        throw new ConfigEditError("No setting given.");
+    const sf = ts.createSourceFile("samurai.config.ts", source, ts.ScriptTarget.Latest, true);
+    let obj = rootObject(sf);
+    for (let i = 0; i < path.length; i++) {
+        const key = path[i];
+        const prop = obj.properties.find((p) => nameOf(p) === key);
+        const isLast = i === path.length - 1;
+        if (prop && !ts.isPropertyAssignment(prop)) {
+            throw new ConfigEditError(`"${key}" in samurai.config.ts isn't a plain value (shorthand or spread), so it can't be edited here.`);
+        }
+        if (isLast) {
+            let splice;
+            if (value === undefined) {
+                if (!prop)
+                    return source;
+                splice = removeProperty(source, prop);
+            }
+            else if (prop && ts.isPropertyAssignment(prop)) {
+                const init = prop.initializer;
+                const unit = unitOf(source, obj);
+                splice = {
+                    start: init.getStart(),
+                    end: init.end,
+                    text: emit(value, lineIndent(source, prop.getStart()), unit),
+                };
+            }
+            else {
+                splice = insertProperty(source, obj, key, value);
+            }
+            return (source.slice(0, splice.start) + splice.text + source.slice(splice.end));
+        }
+        if (!prop) {
+            if (value === undefined)
+                return source;
+            // Build the rest of the path as one nested object and add it here
+            let nested = value;
+            for (let j = path.length - 1; j > i; j--)
+                nested = { [path[j]]: nested };
+            const splice = insertProperty(source, obj, key, nested);
+            return (source.slice(0, splice.start) + splice.text + source.slice(splice.end));
+        }
+        if (!ts.isObjectLiteralExpression(prop.initializer)) {
+            throw new ConfigEditError(`"${key}" in samurai.config.ts isn't a plain object, so it can't be edited here.`);
+        }
+        obj = prop.initializer;
+    }
+    return source;
+}
+/** The text of one property (`staging: { … }`), indentation removed, for showing a part of the file; undefined when missing */
+export function propertyText(source, path) {
+    const sf = ts.createSourceFile("samurai.config.ts", source, ts.ScriptTarget.Latest, true);
+    let obj;
+    try {
+        obj = rootObject(sf);
+    }
+    catch {
+        return undefined;
+    }
+    for (let i = 0; i < path.length; i++) {
+        const prop = obj.properties.find((p) => nameOf(p) === path[i]);
+        if (!prop)
+            return undefined;
+        if (i === path.length - 1) {
+            const indent = lineIndent(source, prop.getStart());
+            return prop
+                .getText()
+                .split("\n")
+                .map((line, n) => n === 0
+                ? line
+                : line.startsWith(indent)
+                    ? line.slice(indent.length)
+                    : line.trimStart())
+                .join("\n");
+        }
+        if (!ts.isPropertyAssignment(prop) ||
+            !ts.isObjectLiteralExpression(prop.initializer))
+            return undefined;
+        obj = prop.initializer;
+    }
+    return undefined;
+}
+/** Whether the property at this path exists in the file's source, walking the same object literals `editConfig` does */
+export function hasConfigPath(source, path) {
+    return propertyText(source, path) !== undefined;
+}

package/dist/project/index.d.ts

@@ -0,0 +1,3 @@
+export { ConfigEditError, editConfig, hasConfigPath, propertyText, type ConfigValue, } from "./config-edit.js";
+export { addVariable, ExistsError, VARIABLE_NAME } from "./variables.js";
+export { isGitIgnored, SECRET_NAME, setSecret } from "./secrets-file.js";

package/dist/project/index.js

@@ -0,0 +1,3 @@
+export { ConfigEditError, editConfig, hasConfigPath, propertyText, } from "./config-edit.js";
+export { addVariable, ExistsError, VARIABLE_NAME } from "./variables.js";
+export { isGitIgnored, SECRET_NAME, setSecret } from "./secrets-file.js";

package/dist/project/secrets-file.d.ts

@@ -0,0 +1,8 @@
+export declare const SECRET_NAME: RegExp;
+/** Whether .gitignore covers this file: its name, or `.env*` / `.env.*` */
+export declare function isGitIgnored(projectDir: string, file: string): Promise<boolean>;
+/**
+ * Sets SAMURAI_SECRET_<name> in .env.<environment>, replacing its line or adding one. The value is masked
+ * in this process's logs from then on, as a secret loaded from the file would be
+ */
+export declare function setSecret(projectDir: string, environment: string, name: string, value: string): Promise<void>;

package/dist/project/secrets-file.js

@@ -0,0 +1,69 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { registerSecret } from "../config/mask.js";
+const PREFIX = "SAMURAI_SECRET_";
+export const SECRET_NAME = /^[A-Z][A-Z0-9_]*$/;
+const ENVIRONMENT = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+function envFile(projectDir, environment) {
+    // The name ends up in a file name: keep it to plain characters
+    if (!ENVIRONMENT.test(environment))
+        throw new Error(`"${environment}" isn't a valid environment name.`);
+    return path.join(projectDir, `.env.${environment}`);
+}
+function checkName(name) {
+    if (!SECRET_NAME.test(name))
+        throw new Error("Use letters, digits and _; a secret is UPPER_SNAKE_CASE.");
+}
+/**
+ * dotenv value: bare when that is safe, else in the quotes that need no escaping. Node's parser, which the
+ * framework reads these files with, can't escape a quote inside a quote, so the quote kind is picked to not
+ * occur in the value.
+ */
+function formatValue(value) {
+    if (/^[A-Za-z0-9_./:@%+=-]*$/.test(value))
+        return value;
+    if (!value.includes("'") && !/[\r\n]/.test(value))
+        return `'${value}'`;
+    if (!value.includes("`"))
+        return `\`${value}\``;
+    if (!value.includes('"') && !value.includes("\\") && !/[\r\n]/.test(value))
+        return `"${value}"`;
+    throw new Error("This value has both ' and ` characters (and more), which a .env file can't hold. Set it as a SAMURAI_SECRET_* environment variable instead.");
+}
+const lineFor = (name) => new RegExp(`^[ \\t]*(?:export[ \\t]+)?${PREFIX}${name}[ \\t]*=`);
+/** Whether .gitignore covers this file: its name, or `.env*` / `.env.*` */
+export async function isGitIgnored(projectDir, file) {
+    try {
+        const text = await readFile(path.join(projectDir, ".gitignore"), "utf8");
+        return text.split(/\r?\n/).some((l) => {
+            const line = l.trim().replace(/^\//, "");
+            return line === file || line === ".env*" || line === ".env.*";
+        });
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Sets SAMURAI_SECRET_<name> in .env.<environment>, replacing its line or adding one. The value is masked
+ * in this process's logs from then on, as a secret loaded from the file would be
+ */
+export async function setSecret(projectDir, environment, name, value) {
+    checkName(name);
+    if (value === "")
+        throw new Error("A secret can't be empty. Remove it instead.");
+    if (/\r|\n/.test(value) && !value.trim())
+        throw new Error("A secret can't be only line breaks.");
+    const file = envFile(projectDir, environment);
+    const text = existsSync(file) ? await readFile(file, "utf8") : "";
+    const lines = text === "" ? [] : text.replace(/\n$/, "").split("\n");
+    const line = `${PREFIX}${name}=${formatValue(value)}`;
+    const at = lines.findIndex((l) => lineFor(name).test(l));
+    if (at >= 0)
+        lines[at] = line;
+    else
+        lines.push(line);
+    await writeFile(file, lines.join("\n") + "\n", { mode: 0o600 });
+    registerSecret(name, value);
+}

package/dist/project/variables.d.ts

@@ -0,0 +1,6 @@
+/** The name is already set in that environment */
+export declare class ExistsError extends Error {
+}
+export declare const VARIABLE_NAME: RegExp;
+/** Adds a variable to one environment in samurai.config.ts; only that property's text changes */
+export declare function addVariable(projectDir: string, environment: string, name: string, value: string): Promise<void>;

package/dist/project/variables.js

@@ -0,0 +1,17 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { editConfig, hasConfigPath } from "./config-edit.js";
+/** The name is already set in that environment */
+export class ExistsError extends Error {
+}
+export const VARIABLE_NAME = /^[A-Za-z_$][\w$]*$/;
+/** Adds a variable to one environment in samurai.config.ts; only that property's text changes */
+export async function addVariable(projectDir, environment, name, value) {
+    if (!VARIABLE_NAME.test(name))
+        throw new Error("Use letters, digits and _, starting with a letter.");
+    const file = path.join(projectDir, "samurai.config.ts");
+    const source = await readFile(file, "utf8");
+    if (hasConfigPath(source, ["environments", environment, "variables", name]))
+        throw new ExistsError(`"${name}" already exists`);
+    await writeFile(file, editConfig(source, ["environments", environment, "variables", name], value));
+}

package/dist/recorder/candidates.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Declarations that turn an element into locator candidates (test id, role and name, label, text, css and
+ * an absolute xpath), plus `inToolbar(event)`, which is true for events from the recorder toolbar. A string
+ * of plain declarations, interpolated into the capture script (page realm) and the toolbar script
+ * (sandbox realm), so no transpiler helper can end up in it.
+ */
+export declare const CANDIDATES_JS: string;