@simplysf/simply-utam-core 0.0.0 → 0.1.0

package/lib/steps/snippet-generator.d.ts

@@ -0,0 +1,34 @@
+import { ParameterTypeRegistry } from '@cucumber/cucumber-expressions';
+import { ParsedGherkinStep, StepSemanticKeyword } from './gherkin-parser.js';
+export interface GeneratedStepSnippet {
+    keyword: StepSemanticKeyword;
+    expression: string;
+    parameters: string[];
+    fullText: string;
+    featureFile: string;
+    stepText: string;
+}
+/**
+ * Formats parameter names into clean, non-conflicting JavaScript identifier names.
+ *
+ * @param names - Raw parameter names from Cucumber expression generator.
+ * @param hasDataTable - Whether the step includes a Gherkin data table.
+ * @param hasDocString - Whether the step includes a Gherkin doc string.
+ * @returns Array of sanitized unique identifier names.
+ */
+export declare function formatParameterNames(names: readonly string[], hasDataTable?: boolean, hasDocString?: boolean): string[];
+/**
+ * Generates an idiomatic Cucumber step definition snippet using CucumberExpressionGenerator.
+ *
+ * @param step - Parsed Gherkin step.
+ * @param registry - Optional Cucumber parameter type registry.
+ * @returns Generated snippet object with expression and implementation template.
+ */
+export declare function generateStepSnippet(step: ParsedGherkinStep, registry?: ParameterTypeRegistry): GeneratedStepSnippet;
+/**
+ * Formats generated JavaScript/TypeScript code using Prettier.
+ *
+ * @param code - Raw code string to format.
+ * @returns Formatted code string.
+ */
+export declare function formatCode(code: string): Promise<string>;

package/lib/steps/snippet-generator.js

@@ -0,0 +1,101 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { ParameterTypeRegistry, CucumberExpressionGenerator } from '@cucumber/cucumber-expressions';
+import prettier from 'prettier';
+/**
+ * Formats parameter names into clean, non-conflicting JavaScript identifier names.
+ *
+ * @param names - Raw parameter names from Cucumber expression generator.
+ * @param hasDataTable - Whether the step includes a Gherkin data table.
+ * @param hasDocString - Whether the step includes a Gherkin doc string.
+ * @returns Array of sanitized unique identifier names.
+ */
+export function formatParameterNames(names, hasDataTable = false, hasDocString = false) {
+    const result = [];
+    const counts = {};
+    for (const name of names) {
+        const sanitized = name.replace(/[^a-zA-Z0-9_$]/g, '') || 'arg';
+        counts[sanitized] = (counts[sanitized] || 0) + 1;
+    }
+    const seen = {};
+    for (const name of names) {
+        const sanitized = name.replace(/[^a-zA-Z0-9_$]/g, '') || 'arg';
+        if (counts[sanitized] > 1) {
+            seen[sanitized] = (seen[sanitized] || 0) + 1;
+            result.push(`${sanitized}${seen[sanitized]}`);
+        }
+        else {
+            result.push(sanitized);
+        }
+    }
+    if (hasDataTable) {
+        result.push('dataTable');
+    }
+    if (hasDocString) {
+        result.push('docString');
+    }
+    return result;
+}
+/**
+ * Generates an idiomatic Cucumber step definition snippet using CucumberExpressionGenerator.
+ *
+ * @param step - Parsed Gherkin step.
+ * @param registry - Optional Cucumber parameter type registry.
+ * @returns Generated snippet object with expression and implementation template.
+ */
+export function generateStepSnippet(step, registry = new ParameterTypeRegistry()) {
+    const generator = new CucumberExpressionGenerator(() => registry.parameterTypes);
+    const generatedList = generator.generateExpressions(step.text);
+    let expressionSource = step.text;
+    let rawParamNames = [];
+    if (generatedList.length > 0) {
+        const bestMatch = generatedList[0];
+        expressionSource = bestMatch.source;
+        rawParamNames = bestMatch.parameterNames;
+    }
+    const parameters = formatParameterNames(rawParamNames, step.hasDataTable, step.hasDocString);
+    const escapedExpression = expressionSource.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+    const fullText = `${step.keyword}('${escapedExpression}', async (${parameters.join(', ')}) => {\n  // TODO: Implement step logic\n  console.warn('[STEP NOT IMPLEMENTED]: ${escapedExpression}');\n});`;
+    return {
+        keyword: step.keyword,
+        expression: expressionSource,
+        parameters,
+        fullText,
+        featureFile: step.filePath,
+        stepText: step.text,
+    };
+}
+/**
+ * Formats generated JavaScript/TypeScript code using Prettier.
+ *
+ * @param code - Raw code string to format.
+ * @returns Formatted code string.
+ */
+export async function formatCode(code) {
+    try {
+        return await prettier.format(code, {
+            parser: 'typescript',
+            singleQuote: true,
+            semi: true,
+            trailingComma: 'all',
+            printWidth: 100,
+        });
+    }
+    catch {
+        return code;
+    }
+}
+//# sourceMappingURL=snippet-generator.js.map

package/lib/steps/snippet-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snippet-generator.js","sourceRoot":"","sources":["../../src/steps/snippet-generator.ts"],"names":[],"mappings":"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"}

package/lib/steps/step-scaffolder.d.ts

@@ -0,0 +1,49 @@
+import { GeneratedStepSnippet } from './snippet-generator.js';
+export interface GenerateStepsOptions {
+    rootDir?: string;
+    features?: string | string[];
+    steps?: string | string[];
+    outputFile?: string;
+    dryRun?: boolean;
+    verbose?: boolean;
+}
+export interface GenerateStepsResult {
+    featureFilesScanned: number;
+    stepFilesScanned: number;
+    totalFeatureSteps: number;
+    matchedStepsCount: number;
+    undefinedStepsCount: number;
+    uniqueSnippetsGenerated: number;
+    dryRun: boolean;
+    outputFile: string;
+    snippets: GeneratedStepSnippet[];
+    generatedCode?: string;
+}
+/**
+ * Resolves one or more glob patterns or file paths into absolute file paths.
+ *
+ * @param patterns - Pattern or list of glob patterns to resolve.
+ * @param rootDir - Root directory to resolve relative paths against.
+ * @returns Array of unique resolved absolute file paths.
+ */
+export declare function resolveGlobs(patterns: string | string[], rootDir: string): string[];
+/**
+ * Determines the default output target file path for scaffolded step definitions.
+ *
+ * If existing step definition files are found, places generated.steps.mjs in the same directory.
+ * Otherwise, inspects project discovery for package directories (e.g. sfdx-source, force-app)
+ * and checks candidate test/utam directory locations.
+ *
+ * @param rootDir - Root directory of the project.
+ * @param stepFiles - List of resolved existing step definition file paths.
+ * @returns Absolute path to target generated.steps.mjs file.
+ */
+export declare function resolveDefaultTargetOutput(rootDir: string, stepFiles?: readonly string[]): string;
+/**
+ * Scans feature files, discovers undefined Gherkin steps against existing step definition files,
+ * deduplicates snippets by expression, and non-destructively scaffolds new step definitions.
+ *
+ * @param options - Step generation configuration options.
+ * @returns Summary of scanned features, matched steps, and generated snippet definitions.
+ */
+export declare function generateCucumberSteps(options?: GenerateStepsOptions): Promise<GenerateStepsResult>;

package/lib/steps/step-scaffolder.js

@@ -0,0 +1,225 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { ParameterTypeRegistry } from '@cucumber/cucumber-expressions';
+import { discoverProject } from '../discovery/index.js';
+import { extractStepsFromGherkin } from './gherkin-parser.js';
+import { extractStepExpressionsFromContent, compileStepExpressions, matchStepAgainstExpressions, normalizeExpression, } from './expression-matcher.js';
+import { generateStepSnippet, formatCode } from './snippet-generator.js';
+/**
+ * Resolves one or more glob patterns or file paths into absolute file paths.
+ *
+ * @param patterns - Pattern or list of glob patterns to resolve.
+ * @param rootDir - Root directory to resolve relative paths against.
+ * @returns Array of unique resolved absolute file paths.
+ */
+export function resolveGlobs(patterns, rootDir) {
+    const files = [];
+    const list = Array.isArray(patterns) ? patterns : [patterns];
+    for (const pattern of list) {
+        if (!pattern)
+            continue;
+        const normalized = pattern.replace(/\\/g, '/');
+        try {
+            const matched = fs.globSync(normalized, { cwd: rootDir });
+            for (const m of matched) {
+                files.push(path.resolve(rootDir, m));
+            }
+        }
+        catch {
+            // If globSync fails, check if pattern is a direct file path
+            const direct = path.resolve(rootDir, pattern);
+            if (fs.existsSync(direct)) {
+                files.push(direct);
+            }
+        }
+    }
+    return Array.from(new Set(files));
+}
+function collectExistingExpressions(stepFiles, targetOutput) {
+    const rawExpressions = [];
+    for (const stepFile of stepFiles) {
+        try {
+            if (fs.existsSync(stepFile)) {
+                const content = fs.readFileSync(stepFile, 'utf-8');
+                rawExpressions.push(...extractStepExpressionsFromContent(content));
+            }
+        }
+        catch {
+            // Ignore unreadable step files
+        }
+    }
+    if (fs.existsSync(targetOutput)) {
+        try {
+            const content = fs.readFileSync(targetOutput, 'utf-8');
+            rawExpressions.push(...extractStepExpressionsFromContent(content));
+        }
+        catch {
+            // Ignore read errors
+        }
+    }
+    const registry = new ParameterTypeRegistry();
+    const compiledExpressions = compileStepExpressions(rawExpressions, registry);
+    const existingNormalizedExpressions = new Set();
+    for (const raw of rawExpressions) {
+        existingNormalizedExpressions.add(normalizeExpression(raw.pattern));
+    }
+    return { compiledExpressions, existingNormalizedExpressions, registry };
+}
+function collectStepsFromFeatures(featureFiles, rootDir) {
+    const allParsedSteps = [];
+    for (const featureFile of featureFiles) {
+        try {
+            const content = fs.readFileSync(featureFile, 'utf-8');
+            const relativePath = path.relative(rootDir, featureFile);
+            const steps = extractStepsFromGherkin(content, relativePath);
+            allParsedSteps.push(...steps);
+        }
+        catch {
+            // Ignore unreadable feature files
+        }
+    }
+    return allParsedSteps;
+}
+async function writeScaffoldedSnippets(uniqueSnippets, targetOutput, dryRun) {
+    if (uniqueSnippets.length === 0) {
+        return undefined;
+    }
+    let fileContent = fs.existsSync(targetOutput)
+        ? fs.readFileSync(targetOutput, 'utf-8').trim() + '\n\n'
+        : "import { Given, When, Then } from '@wdio/cucumber-framework';\n\n";
+    for (const snippet of uniqueSnippets) {
+        fileContent += snippet.fullText + '\n\n';
+    }
+    const generatedCode = await formatCode(fileContent);
+    if (!dryRun) {
+        const parentDir = path.dirname(targetOutput);
+        if (!fs.existsSync(parentDir)) {
+            fs.mkdirSync(parentDir, { recursive: true });
+        }
+        fs.writeFileSync(targetOutput, generatedCode, 'utf-8');
+    }
+    return generatedCode;
+}
+/**
+ * Determines the default output target file path for scaffolded step definitions.
+ *
+ * If existing step definition files are found, places generated.steps.mjs in the same directory.
+ * Otherwise, inspects project discovery for package directories (e.g. sfdx-source, force-app)
+ * and checks candidate test/utam directory locations.
+ *
+ * @param rootDir - Root directory of the project.
+ * @param stepFiles - List of resolved existing step definition file paths.
+ * @returns Absolute path to target generated.steps.mjs file.
+ */
+export function resolveDefaultTargetOutput(rootDir, stepFiles = []) {
+    if (stepFiles.length > 0) {
+        const primaryDir = path.dirname(stepFiles[0]);
+        return path.join(primaryDir, 'generated.steps.mjs');
+    }
+    const discovery = discoverProject(rootDir);
+    const sourceDir = discovery.defaultPackageDirectory ?? discovery.packageDirectories[0] ?? 'force-app';
+    const candidateDirs = [
+        path.join(rootDir, sourceDir, 'test', 'utam', 'step_definitions'),
+        path.join(rootDir, sourceDir, 'tests', 'utam', 'step_definitions'),
+        path.join(rootDir, sourceDir, 'test', 'utam'),
+        path.join(rootDir, sourceDir, 'tests', 'utam'),
+        path.join(rootDir, 'test', 'utam', 'step_definitions'),
+        path.join(rootDir, 'tests', 'utam', 'step_definitions'),
+        path.join(rootDir, 'test', 'utam'),
+        path.join(rootDir, 'tests', 'utam'),
+    ];
+    for (const dir of candidateDirs) {
+        if (fs.existsSync(dir)) {
+            if (dir.endsWith('step_definitions')) {
+                return path.join(dir, 'generated.steps.mjs');
+            }
+            return path.join(dir, 'step_definitions', 'generated.steps.mjs');
+        }
+    }
+    return path.resolve(rootDir, sourceDir, 'test/utam/step_definitions/generated.steps.mjs');
+}
+/**
+ * Scans feature files, discovers undefined Gherkin steps against existing step definition files,
+ * deduplicates snippets by expression, and non-destructively scaffolds new step definitions.
+ *
+ * @param options - Step generation configuration options.
+ * @returns Summary of scanned features, matched steps, and generated snippet definitions.
+ */
+export async function generateCucumberSteps(options = {}) {
+    const rootDir = path.resolve(options.rootDir ?? process.cwd());
+    const dryRun = Boolean(options.dryRun);
+    const featurePatterns = options.features ?? [
+        'sfdx-source/**/*.feature',
+        'force-app/**/*.feature',
+        'test/**/*.feature',
+        '**/*.feature',
+    ];
+    const stepPatterns = options.steps ?? [
+        'sfdx-source/**/*.steps.{js,mjs,ts}',
+        'force-app/**/*.steps.{js,mjs,ts}',
+        'test/**/*.steps.{js,mjs,ts}',
+    ];
+    const featureFiles = resolveGlobs(featurePatterns, rootDir).filter((f) => f.endsWith('.feature'));
+    const stepFiles = resolveGlobs(stepPatterns, rootDir);
+    const targetOutput = options.outputFile
+        ? path.isAbsolute(options.outputFile)
+            ? options.outputFile
+            : path.resolve(rootDir, options.outputFile)
+        : resolveDefaultTargetOutput(rootDir, stepFiles);
+    const { compiledExpressions, existingNormalizedExpressions, registry } = collectExistingExpressions(stepFiles, targetOutput);
+    const allParsedSteps = collectStepsFromFeatures(featureFiles, rootDir);
+    let matchedStepsCount = 0;
+    const undefinedSteps = [];
+    for (const step of allParsedSteps) {
+        if (matchStepAgainstExpressions(step.text, compiledExpressions)) {
+            matchedStepsCount++;
+        }
+        else {
+            undefinedSteps.push(step);
+        }
+    }
+    const uniqueSnippets = [];
+    const seenExpressionsInRun = new Set();
+    for (const step of undefinedSteps) {
+        const snippet = generateStepSnippet(step, registry);
+        const normalized = normalizeExpression(snippet.expression);
+        if (existingNormalizedExpressions.has(normalized)) {
+            matchedStepsCount++;
+            continue;
+        }
+        if (seenExpressionsInRun.has(normalized)) {
+            continue;
+        }
+        seenExpressionsInRun.add(normalized);
+        uniqueSnippets.push(snippet);
+    }
+    const generatedCode = await writeScaffoldedSnippets(uniqueSnippets, targetOutput, dryRun);
+    return {
+        featureFilesScanned: featureFiles.length,
+        stepFilesScanned: stepFiles.length,
+        totalFeatureSteps: allParsedSteps.length,
+        matchedStepsCount,
+        undefinedStepsCount: undefinedSteps.length,
+        uniqueSnippetsGenerated: uniqueSnippets.length,
+        dryRun,
+        outputFile: targetOutput,
+        snippets: uniqueSnippets,
+        generatedCode,
+    };
+}
+//# sourceMappingURL=step-scaffolder.js.map

package/lib/steps/step-scaffolder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-scaffolder.js","sourceRoot":"","sources":["../../src/steps/step-scaffolder.ts"],"names":[],"mappings":"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"}

package/lib/test-environment.d.ts

@@ -1,13 +1,37 @@
-import { Org } from '@salesforce/core';
+import { Connection, Org } from '@salesforce/core';
 /** The environment variable naming the org a UTAM run authenticates to. */
 export declare const USERNAME_ENV = "UTAM_USERNAME";
 /** An environment-shaped map; `process.env` by default. */
 export type EnvLike = Record<string, string | undefined>;
+/**
+ * Default trusted Salesforce host regular expression patterns for Experience Cloud and Salesforce domains.
+ */
+export declare const DEFAULT_ALLOWED_HOST_PATTERNS: RegExp[];
+/**
+ * Checks whether a given hostname is an authorized Salesforce or custom domain.
+ *
+ * @param hostname - The hostname to validate.
+ * @param instanceUrl - Optional base instance URL of the target org.
+ * @param envAllowedDomains - Comma-delimited custom allowed domains or wildcards.
+ * @returns True if the hostname is authorized, false otherwise.
+ */
+export declare function isHostAllowed(hostname: string, instanceUrl?: string, envAllowedDomains?: string | undefined): boolean;
+/**
+ * Validates and parses a raw secure URL retrieved from SiteDetail.
+ *
+ * @param secureUrl - The raw secure URL string.
+ * @param siteId - Identifier of the site for error reporting.
+ * @param hostValidator - Optional callback function validating the hostname.
+ * @returns The parsed and validated WHATWG URL object.
+ */
+export declare function validateAndParseSecureUrl(secureUrl: string, siteId: string, hostValidator?: (host: string) => boolean): URL;
 export type TestEnvironmentOptions = {
     /** Username or alias of an org already authorized with the Salesforce CLI. Wins over `UTAM_USERNAME`. */
     username?: string;
     /** Where `UTAM_USERNAME` is read from. Defaults to `process.env`. */
     env?: EnvLike;
+    /** Optional custom allowed domains or wildcards overriding UTAM_ALLOWED_DOMAINS. */
+    allowedDomains?: string;
 };
 /**
  * The org a UTAM run tests against, resolved from the Salesforce CLI's local auth store.
@@ -21,6 +45,10 @@ export declare class TestEnvironment {
      * @param options Explicit username and environment overrides.
      */
     constructor(options?: TestEnvironmentOptions);
+    /**
+     * Indicates whether authentication has been initialized.
+     */
+    get isInitialized(): boolean;
     /**
      * Resolve the authenticated org. The first call authenticates and every later call shares its
      * result, so callers need not coordinate who goes first; a failed attempt is not cached.
@@ -31,13 +59,80 @@ export declare class TestEnvironment {
      * starts. Optional: every other method authenticates on first use.
      */
     init(): Promise<void>;
+    /**
+     * Returns the underlying `@salesforce/core` Connection instance.
+     */
+    getConnection(): Promise<Connection>;
+    /**
+     * Returns the cleaned instance URL (My Domain) of the target org.
+     */
+    getInstanceUrl(): Promise<string>;
     /**
      * Build a single-use frontdoor URL that logs the browser in and lands on `returnUrl`.
      *
-     * The URL comes from Salesforce's single-access endpoint rather than a `sid=` query parameter,
-     * so the session's access token never appears in the browser's address bar or history.
-     *
      * @param returnUrl Path to open after login, e.g. `/lightning/page/home`. Omit for the org's default landing page.
      */
     buildFrontdoorUrl(returnUrl?: string): Promise<string>;
+    /**
+     * Checks whether a hostname is authorized using the current target org context.
+     *
+     * @param hostname - The hostname to validate.
+     */
+    isHostAllowedInternal(hostname: string): Promise<boolean>;
+    /**
+     * Queries the Experience Cloud site and validates its SecureUrl.
+     */
+    getValidatedExperienceSiteUrl(sitePrefix?: string): Promise<URL>;
+    /**
+     * Generates a Frontdoor URL for an Experience Cloud Site using the singleaccess API.
+     *
+     * @param sitePrefix - Optional URL path prefix of the site.
+     * @param returnUrl - Optional landing page path after login.
+     * @returns One-time Experience Cloud frontdoor login URL.
+     */
+    buildExperienceFrontdoorUrl(sitePrefix?: string, returnUrl?: string): Promise<string>;
+    /**
+     * Retrieves the Salesforce Organization ID dynamically via SOQL query.
+     */
+    getOrgId(): Promise<string>;
+    /**
+     * Resolves a given Salesforce username to its corresponding User ID via SOQL query.
+     *
+     * @param username - Target Salesforce username to resolve.
+     */
+    getUserIdByUsername(username: string): Promise<string>;
+    /**
+     * Resolves an Experience Cloud Site's prefix to its corresponding 15-character Network ID.
+     *
+     * @param sitePrefix - The URL path prefix of the Experience site.
+     */
+    getNetworkIdByPrefix(sitePrefix?: string): Promise<string>;
+    /**
+     * Generates a fully qualified secure URL for a given Experience Cloud Site (Community).
+     *
+     * @param sitePrefix - The URL path prefix of the Experience site.
+     * @param path - Optional relative subpath to append.
+     */
+    buildExperienceUrl(sitePrefix?: string, path?: string): Promise<string>;
+    /**
+     * Resets active connection state, requiring re-authentication on subsequent calls.
+     */
+    reset(): void;
 }
+/**
+ * Returns the global singleton TestEnvironment instance, lazily creating it if necessary.
+ *
+ * @param options - Optional configuration options to initialize or overwrite the singleton.
+ * @returns The active TestEnvironment instance.
+ */
+export declare function getTestEnvironment(options?: TestEnvironmentOptions): TestEnvironment;
+/**
+ * Overrides the active global singleton TestEnvironment instance.
+ *
+ * @param instance - The TestEnvironment instance to set, or null to clear.
+ */
+export declare function setTestEnvironment(instance: TestEnvironment | null): void;
+/**
+ * Clears and resets the global singleton TestEnvironment instance.
+ */
+export declare function resetTestEnvironment(): void;