@sdods/core 0.7.2 → 0.8.0

package/dist/mail/extract.d.ts

@@ -0,0 +1,38 @@
+import type { MailMessage } from './types.js';
+/** Decode the HTML entities that show up in hrefs and body text: named basics and numeric. */
+export declare function decodeEntities(s: string): string;
+/** The HTML part as plain text: scripts and styles dropped, tags removed, whitespace collapsed. */
+export declare function htmlToText(html: string): string;
+/** Everything a reader could see: the text part, then the HTML part rendered to text. */
+export declare function readableText(m: Pick<MailMessage, 'text' | 'html'>): string;
+export interface MailLink {
+    href: string;
+    /** Visible text of the anchor; empty for a URL found in the text part. */
+    text: string;
+}
+/**
+ * Links in the message. Anchors in the HTML part come first, with `&amp;` and friends decoded
+ * (an href is HTML-escaped, and a verify link with `?token=…&amp;email=…` is the common case).
+ * URLs in the text part follow, so a text-only message still has links; duplicates are dropped.
+ */
+export declare function extractLinks(m: Pick<MailMessage, 'text' | 'html'>): MailLink[];
+/** Compile a scenario's pattern; one that is not a valid regular expression is matched literally. */
+export declare function toPattern(pattern: string): RegExp;
+/**
+ * The first link whose href contains `pattern` literally or matches it as a regular expression.
+ * Both, because a URL is the natural thing to write and its `?` and `.` are regex syntax:
+ * `https://app.test/verify?token=` is a valid regex that does NOT match its own text.
+ */
+export declare function findLinkMatching(m: Pick<MailMessage, 'text' | 'html'>, pattern: string): MailLink | undefined;
+/**
+ * The link a person would click by name: an anchor whose visible text equals `name`
+ * (case-insensitive, whitespace-normalised), else one whose text contains it, else one whose href
+ * contains it.
+ */
+export declare function findLinkNamed(m: Pick<MailMessage, 'text' | 'html'>, name: string): MailLink | undefined;
+/**
+ * The first match of `pattern` in the readable text: capture group 1 when the pattern has one,
+ * the whole match otherwise. `code: (\d{6})` saves the six digits, `\d{6}` saves the same.
+ */
+export declare function findCode(m: Pick<MailMessage, 'text' | 'html'>, pattern: string): string | undefined;
+//# sourceMappingURL=extract.d.ts.map

package/dist/mail/extract.js

@@ -0,0 +1,106 @@
+/**
+ * Pure helpers over a fetched message: its readable text, its links and a code in it. Kept apart
+ * from the steps so the parsing, which fails quietly when wrong, is testable on its own.
+ */
+const ENTITIES = {
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+    nbsp: ' ',
+};
+/** Decode the HTML entities that show up in hrefs and body text: named basics and numeric. */
+export function decodeEntities(s) {
+    return s.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (m, ref) => {
+        if (ref[0] === '#') {
+            const code = ref[1]?.toLowerCase() === 'x' ? parseInt(ref.slice(2), 16) : parseInt(ref.slice(1), 10);
+            return Number.isFinite(code) ? String.fromCodePoint(code) : m;
+        }
+        return ENTITIES[ref.toLowerCase()] ?? m;
+    });
+}
+/** The HTML part as plain text: scripts and styles dropped, tags removed, whitespace collapsed. */
+export function htmlToText(html) {
+    return decodeEntities(html
+        .replace(/<(script|style|head)\b[\s\S]*?<\/\1>/gi, ' ')
+        .replace(/<br\s*\/?>|<\/(p|div|tr|li|h[1-6])>/gi, '\n')
+        .replace(/<[^>]+>/g, ' '))
+        .replace(/[ \t\f\v\r]+/g, ' ')
+        .replace(/ *\n */g, '\n')
+        .trim();
+}
+/** Everything a reader could see: the text part, then the HTML part rendered to text. */
+export function readableText(m) {
+    return [m.text, m.html ? htmlToText(m.html) : ''].filter(Boolean).join('\n');
+}
+/** Trailing punctuation that ends a sentence rather than a URL. */
+const TRAILING = /[.,;:!?)\]}>'"]+$/;
+/**
+ * Links in the message. Anchors in the HTML part come first, with `&amp;` and friends decoded
+ * (an href is HTML-escaped, and a verify link with `?token=…&amp;email=…` is the common case).
+ * URLs in the text part follow, so a text-only message still has links; duplicates are dropped.
+ */
+export function extractLinks(m) {
+    const out = [];
+    const seen = new Set();
+    const add = (href, text) => {
+        if (!href || seen.has(href))
+            return;
+        seen.add(href);
+        out.push({ href, text });
+    };
+    const anchor = /<a\b[^>]*?\bhref\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))[^>]*>([\s\S]*?)<\/a>/gi;
+    for (const match of m.html.matchAll(anchor)) {
+        const href = decodeEntities((match[1] ?? match[2] ?? match[3] ?? '').trim());
+        if (/^(mailto:|tel:|#|javascript:)/i.test(href))
+            continue;
+        add(href, htmlToText(match[4] ?? ''));
+    }
+    for (const match of m.text.matchAll(/https?:\/\/[^\s<>"]+/gi)) {
+        add(match[0].replace(TRAILING, ''), '');
+    }
+    return out;
+}
+/** Compile a scenario's pattern; one that is not a valid regular expression is matched literally. */
+export function toPattern(pattern) {
+    try {
+        return new RegExp(pattern);
+    }
+    catch {
+        return new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    }
+}
+/**
+ * The first link whose href contains `pattern` literally or matches it as a regular expression.
+ * Both, because a URL is the natural thing to write and its `?` and `.` are regex syntax:
+ * `https://app.test/verify?token=` is a valid regex that does NOT match its own text.
+ */
+export function findLinkMatching(m, pattern) {
+    const re = toPattern(pattern);
+    return extractLinks(m).find((l) => l.href.includes(pattern) || re.test(l.href));
+}
+/**
+ * The link a person would click by name: an anchor whose visible text equals `name`
+ * (case-insensitive, whitespace-normalised), else one whose text contains it, else one whose href
+ * contains it.
+ */
+export function findLinkNamed(m, name) {
+    const norm = (s) => s.replace(/\s+/g, ' ').trim().toLowerCase();
+    const wanted = norm(name);
+    const links = extractLinks(m);
+    return (links.find((l) => norm(l.text) === wanted) ??
+        links.find((l) => wanted !== '' && norm(l.text).includes(wanted)) ??
+        links.find((l) => l.href.includes(name)));
+}
+/**
+ * The first match of `pattern` in the readable text: capture group 1 when the pattern has one,
+ * the whole match otherwise. `code: (\d{6})` saves the six digits, `\d{6}` saves the same.
+ */
+export function findCode(m, pattern) {
+    const match = toPattern(pattern).exec(readableText(m));
+    if (!match)
+        return undefined;
+    return match[1] ?? match[0];
+}
+//# sourceMappingURL=extract.js.map

package/dist/mail/index.d.ts

@@ -0,0 +1,8 @@
+import type { MailConfig } from '@sdods/contracts';
+import type { MailInbox } from './types.js';
+export type { MailAddress, MailInbox, MailMessage, MailSearch, MailSummary } from './types.js';
+export { MailpitInbox, type MailpitOptions } from './mailpit.js';
+export { decodeEntities, extractLinks, findCode, findLinkMatching, findLinkNamed, htmlToText, readableText, type MailLink, } from './extract.js';
+/** The inbox adapter for an environment's `mail` block. */
+export declare function createMailInbox(config: Pick<MailConfig, 'provider' | 'url' | 'auth'>): MailInbox;
+//# sourceMappingURL=index.d.ts.map

package/dist/mail/index.js

@@ -0,0 +1,11 @@
+import { MailpitInbox } from './mailpit.js';
+export { MailpitInbox } from './mailpit.js';
+export { decodeEntities, extractLinks, findCode, findLinkMatching, findLinkNamed, htmlToText, readableText, } from './extract.js';
+/** The inbox adapter for an environment's `mail` block. */
+export function createMailInbox(config) {
+    switch (config.provider ?? 'mailpit') {
+        case 'mailpit':
+            return new MailpitInbox({ url: config.url, auth: config.auth });
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/mail/mailpit.d.ts

@@ -0,0 +1,26 @@
+import type { MailInbox, MailMessage, MailSearch, MailSummary } from './types.js';
+export interface MailpitOptions {
+    url: string;
+    auth?: {
+        type: 'basic';
+        username: string;
+        password: string;
+    };
+}
+/**
+ * Mailpit over its REST API (`/api/v1`).
+ *
+ * The server-side query is only `to:"<address>"`. Mailpit's `to:` is a substring match and its
+ * `subject:` is word-tokenised rather than a substring, so both are narrowed here, where the
+ * semantics are the ones the step text promises.
+ */
+export declare class MailpitInbox implements MailInbox {
+    private readonly base;
+    private readonly headers;
+    constructor(opts: MailpitOptions);
+    clear(address: string): Promise<void>;
+    search(query: MailSearch): Promise<MailSummary[]>;
+    get(id: string): Promise<MailMessage>;
+    private call;
+}
+//# sourceMappingURL=mailpit.d.ts.map

package/dist/mail/mailpit.js

@@ -0,0 +1,124 @@
+import { SdodsError } from '../errors.js';
+/** Page size for search. Mailpit's own default is 50; a per-address inbox rarely comes close. */
+const PAGE = 100;
+/** A hard stop on pagination, so a runaway inbox fails loudly instead of paging forever. */
+const MAX_PAGES = 50;
+/**
+ * Mailpit over its REST API (`/api/v1`).
+ *
+ * The server-side query is only `to:"<address>"`. Mailpit's `to:` is a substring match and its
+ * `subject:` is word-tokenised rather than a substring, so both are narrowed here, where the
+ * semantics are the ones the step text promises.
+ */
+export class MailpitInbox {
+    base;
+    headers;
+    constructor(opts) {
+        this.base = opts.url.replace(/\/+$/, '');
+        this.headers = { accept: 'application/json' };
+        if (opts.auth) {
+            const token = Buffer.from(`${opts.auth.username}:${opts.auth.password}`).toString('base64');
+            this.headers.authorization = `Basic ${token}`;
+        }
+    }
+    async clear(address) {
+        const ids = (await this.search({ to: address })).map((m) => m.id);
+        if (ids.length === 0)
+            return;
+        // By ID rather than `DELETE /api/v1/search?query=to:"…"`: that query is a substring match
+        // and would also delete another scenario's mail to `b${address}`.
+        await this.call('DELETE', '/api/v1/messages', { IDs: ids });
+    }
+    async search(query) {
+        const wanted = query.to.trim().toLowerCase();
+        const q = `to:"${wanted.replace(/"/g, '')}"`;
+        const out = [];
+        for (let page = 0; page < MAX_PAGES; page++) {
+            const params = new URLSearchParams({
+                query: q,
+                start: String(page * PAGE),
+                limit: String(PAGE),
+            });
+            const body = (await this.call('GET', `/api/v1/search?${params}`));
+            const messages = body.messages ?? [];
+            for (const m of messages) {
+                const summary = toSummary(m);
+                if (!summary.to.some((t) => t.address.toLowerCase() === wanted))
+                    continue;
+                if (query.since && summary.receivedAt.getTime() < query.since.getTime())
+                    continue;
+                if (query.subjectContains !== undefined &&
+                    !summary.subject.includes(query.subjectContains)) {
+                    continue;
+                }
+                out.push(summary);
+            }
+            // Newest first: once a page ends before `since`, every later page is older still.
+            const oldest = messages.at(-1);
+            if (messages.length < PAGE)
+                break;
+            if (query.since && oldest && toDate(oldest.Created).getTime() < query.since.getTime())
+                break;
+        }
+        return out.sort((a, b) => b.receivedAt.getTime() - a.receivedAt.getTime());
+    }
+    async get(id) {
+        const m = (await this.call('GET', `/api/v1/message/${encodeURIComponent(id)}`));
+        return { ...toSummary(m), text: m.Text ?? '', html: m.HTML ?? '' };
+    }
+    async call(method, path, json) {
+        const url = `${this.base}${path}`;
+        let res;
+        try {
+            res = await fetch(url, {
+                method,
+                headers: json === undefined
+                    ? this.headers
+                    : { ...this.headers, 'content-type': 'application/json' },
+                body: json === undefined ? undefined : JSON.stringify(json),
+            });
+        }
+        catch (e) {
+            throw new SdodsError('MAIL_REQUIRED', `Could not reach Mailpit at ${this.base}.`, {
+                hint: 'Start Mailpit (for example `docker run -p 8025:8025 -p 1025:1025 axllent/mailpit`) and check `mail.url` in the environment yaml. The application under test must send its SMTP mail to the same Mailpit.',
+                cause: e,
+                details: { url, method },
+            });
+        }
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new SdodsError('MAIL_REQUIRED', `Mailpit answered ${res.status} to ${method} ${path}.`, {
+                hint: res.status === 401 || res.status === 403
+                    ? 'Mailpit is protected: set `mail.auth: { type: basic, username, password: ${VAR} }` in the environment yaml.'
+                    : 'Check that `mail.url` points at the Mailpit web/API port (8025 by default), not the SMTP port.',
+                details: { url, method, status: res.status, body: text.slice(0, 500) },
+            });
+        }
+        const text = await res.text();
+        if (!text)
+            return {};
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return {};
+        }
+    }
+}
+function toAddress(a) {
+    return { name: a?.Name ?? '', address: a?.Address ?? '' };
+}
+function toDate(s) {
+    const d = s ? new Date(s) : new Date(0);
+    return Number.isNaN(d.getTime()) ? new Date(0) : d;
+}
+function toSummary(m) {
+    return {
+        id: m.ID,
+        from: toAddress(m.From),
+        to: (m.To ?? []).map(toAddress),
+        subject: m.Subject ?? '',
+        receivedAt: toDate(m.Created ?? m.Date),
+    };
+}
+//# sourceMappingURL=mailpit.js.map

package/dist/mail/types.d.ts

@@ -0,0 +1,38 @@
+export interface MailAddress {
+    name: string;
+    address: string;
+}
+/** One message as a search returns it: enough to pick which message to open, no body. */
+export interface MailSummary {
+    id: string;
+    from: MailAddress;
+    to: MailAddress[];
+    subject: string;
+    /** When the mail catcher received it, on the catcher's clock. */
+    receivedAt: Date;
+}
+/** A whole message. `text` and `html` are empty strings when that part is absent. */
+export interface MailMessage extends MailSummary {
+    text: string;
+    html: string;
+}
+export interface MailSearch {
+    /** Exact recipient address, compared case-insensitively. */
+    to: string;
+    /** Case-sensitive substring of the subject. */
+    subjectContains?: string;
+    /** Only messages received at or after this instant. */
+    since?: Date;
+}
+/**
+ * A mail catcher the email steps read. Implementations return search results newest first and
+ * match `to` EXACTLY: a catcher whose own `to:` filter is a substring search (Mailpit's is) must
+ * narrow it client-side, or `a@x.test` would also match `ba@x.test`.
+ */
+export interface MailInbox {
+    /** Delete every message addressed to `address`. */
+    clear(address: string): Promise<void>;
+    search(query: MailSearch): Promise<MailSummary[]>;
+    get(id: string): Promise<MailMessage>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/mail/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/matrix/index.d.ts

@@ -0,0 +1,104 @@
+import { ROLES_MATRIX_FILE, type ProjectConfig } from '@sdods/contracts';
+/**
+ * Role matrix (#118): `roles.matrix.yaml` declares, per surface, the outcome each role should see;
+ * a `@matrix:<name>` Scenario Outline is the template; `sdods matrix expand` writes one `Examples:`
+ * block per role, tagged `@user:<role>`, between marker comments.
+ *
+ * playwright-bdd has no hook for external Examples, so the rows are generated INTO the feature file
+ * rather than injected at bddgen time. That keeps the generated tests visible in review, in
+ * `sdods features list`, and to every tool that reads Gherkin, at the cost of a generator that has
+ * to be idempotent and must never touch rows a person wrote.
+ */
+export { ROLES_MATRIX_FILE };
+export declare const MATRIX_BEGIN = "sdods:matrix:begin";
+export declare const MATRIX_END = "sdods:matrix:end";
+export interface RolesMatrix {
+    name: string;
+    description?: string;
+    roles: string[];
+    /** Row columns in declaration order, excluding `role` and `expect`. */
+    columns: string[];
+    /** `# title-format:` written above every generated block. */
+    title: string;
+    rows: Array<{
+        values: Record<string, string>;
+        expect: Record<string, string>;
+    }>;
+    /** 1-based line of `<name>:` in the yaml, for findings. */
+    line?: number;
+}
+export interface MatrixProblem {
+    rule: string;
+    severity: 'error' | 'warning';
+    message: string;
+    /** Relative to the project root. */
+    file: string;
+    line?: number;
+}
+export interface LoadedMatrices {
+    file: string;
+    /** Every name under `matrices:`, valid or not, so an invalid matrix is not also reported as unknown. */
+    declared: string[];
+    matrices: Map<string, RolesMatrix>;
+    problems: MatrixProblem[];
+}
+/** Read and validate `roles.matrix.yaml`. Undefined when the project has none. */
+export declare function loadRolesMatrices(projectRoot: string): LoadedMatrices | undefined;
+/** Validate matrix yaml text. Problems never throw: lint reports them as findings. */
+export declare function parseRolesMatrices(text: string, file?: string): LoadedMatrices;
+export interface ExpandResult {
+    text: string;
+    changed: boolean;
+    /** Generated example rows in the file after expansion. */
+    examples: number;
+    problems: MatrixProblem[];
+}
+/**
+ * Rewrite the generated Examples of every `@matrix:<name>` outline in one feature file.
+ * Pure: text in, text out. Hand-written Examples and everything outside the markers are kept.
+ */
+export declare function expandFeatureText(text: string, matrices: ReadonlyMap<string, RolesMatrix>, opts?: {
+    file?: string;
+}): ExpandResult;
+/** The generated region for one outline: a title-format, a role tag and a table per role. */
+export declare function renderBlock(matrix: RolesMatrix, indent: string): string[];
+export interface MatrixFilePlan {
+    /** Absolute path. */
+    file: string;
+    /** Relative to the project root. */
+    path: string;
+    changed: boolean;
+    examples: number;
+    before: string;
+    after: string;
+    problems: MatrixProblem[];
+}
+export interface MatrixPlan {
+    loaded?: LoadedMatrices;
+    files: MatrixFilePlan[];
+    /** Config, role and pool findings (not tied to one feature). */
+    problems: MatrixProblem[];
+}
+/**
+ * Everything `sdods matrix expand`, `--check`, lint and the MCP tool need, computed once:
+ * the matrices, their project-level findings, and the before/after text of every feature that
+ * uses (or used to use) a matrix.
+ */
+export declare function planMatrixExpansion(project: ProjectConfig & {
+    root: string;
+}, featureFiles: string[]): MatrixPlan;
+/**
+ * Roles the matrix names must be roles the project declares, and each needs an account to lease.
+ *
+ * The matrix does not create identities. A role with no pool row turns every generated scenario for
+ * that role red with a lease error that says nothing about the product, so this is surfaced before
+ * anything runs — per environment, because a role seeded on staging may not exist locally.
+ */
+export declare function checkMatrixRoles(project: ProjectConfig & {
+    root: string;
+}, matrices: ReadonlyMap<string, RolesMatrix>): MatrixProblem[];
+/** Roles present in the user-pool dataset, per available environment. Undefined if not file-backed. */
+export declare function poolRolesByEnv(project: ProjectConfig & {
+    root: string;
+}): Map<string, Set<string>> | undefined;
+//# sourceMappingURL=index.d.ts.map