@sifurai/cli 0.0.0-stage → 0.1.1

package/dist/login.js

@@ -0,0 +1,123 @@
+import { spawn } from 'node:child_process';
+import { hostname, userInfo } from 'node:os';
+import { Api, ApiError, CliError, DEFAULT_API } from './api.js';
+import { deleteCredentials, loadCredentials, saveCredentials } from './config.js';
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export function openInBrowser(url) {
+    const [command, args] = process.platform === 'darwin'
+        ? ['open', [url]]
+        : process.platform === 'win32'
+            ? ['cmd', ['/c', 'start', '""', url]]
+            : ['xdg-open', [url]];
+    try {
+        const child = spawn(command, args, { stdio: 'ignore', detached: true });
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch {
+        // The URL is printed too; a machine without a browser just doesn't open one.
+    }
+}
+export function defaultClientName() {
+    let user = '';
+    try {
+        user = userInfo().username;
+    }
+    catch {
+        user = '';
+    }
+    return user ? `${user}@${hostname()}` : hostname();
+}
+export function withCode(verificationUrl, userCode) {
+    try {
+        const url = new URL(verificationUrl);
+        if (!url.searchParams.has('code'))
+            url.searchParams.set('code', userCode);
+        return url.toString();
+    }
+    catch {
+        return verificationUrl;
+    }
+}
+export async function login(api, deps) {
+    const { io } = deps;
+    const sleep = deps.sleep ?? wait;
+    const now = deps.now ?? Date.now;
+    const notSifur = new CliError(`${api.base} isn't Sifur's API. --api is Sifur's address (for example ${DEFAULT_API}); your test server goes in \`accept --url\`.`);
+    let start;
+    try {
+        start = await api.request('auth/device', {
+            method: 'POST',
+            body: { clientName: (deps.clientName ?? defaultClientName()).slice(0, 100) },
+        });
+    }
+    catch (error) {
+        if (error instanceof ApiError && (!error.json || [404, 405, 419].includes(error.status)))
+            throw notSifur;
+        throw error;
+    }
+    if (!start?.deviceCode || !start.userCode || !start.verificationUrl)
+        throw notSifur;
+    const url = withCode(start.verificationUrl, start.userCode);
+    io.out(`Your code: ${start.userCode}`);
+    io.out(`Approve it at ${url}`);
+    io.out('Waiting for approval…');
+    (deps.openBrowser ?? openInBrowser)(url);
+    let interval = Math.max(1, start.interval ?? 5) * 1000;
+    const deadline = now() + (start.expiresIn ?? 600) * 1000;
+    for (;;) {
+        await sleep(interval);
+        try {
+            const granted = await api.request('auth/device/token', {
+                method: 'POST',
+                body: { deviceCode: start.deviceCode },
+            });
+            let consoleOrigin = null;
+            try {
+                consoleOrigin = new URL(start.verificationUrl).origin;
+            }
+            catch {
+                consoleOrigin = null;
+            }
+            const credentials = { api: api.base, token: granted.token, console: consoleOrigin };
+            const path = await saveCredentials(credentials, deps.env);
+            const who = granted.user?.email ?? granted.user?.name;
+            io.out(`Signed in${who ? ` as ${who}` : ''}. Saved to ${path}.`);
+            return credentials;
+        }
+        catch (error) {
+            if (!(error instanceof ApiError))
+                throw error;
+            if (error.code === 'authorization_pending' || error.status === 428) {
+                if (now() >= deadline)
+                    throw new CliError('The code expired before it was approved. Run `sifur login` again.');
+                continue;
+            }
+            if (error.status === 429 || error.code === 'slow_down') {
+                interval = Math.max(interval + 5000, (error.retryAfterSeconds ?? 0) * 1000);
+                continue;
+            }
+            if (error.code === 'access_denied' || error.status === 403)
+                throw new CliError('The sign-in was denied.');
+            if (error.code === 'expired_token' || error.status === 410) {
+                throw new CliError('The code expired before it was approved. Run `sifur login` again.');
+            }
+            throw error;
+        }
+    }
+}
+export async function logout(io, env = process.env) {
+    const credentials = await loadCredentials(env);
+    if (!credentials) {
+        io.out('Not signed in.');
+        return;
+    }
+    try {
+        await new Api(credentials.api, credentials.token).request('account/logout', { method: 'POST' });
+    }
+    catch {
+        // The session may already be revoked or Sifur unreachable; the local token goes either way.
+    }
+    await deleteCredentials(env);
+    io.out('Signed out.');
+}

package/dist/resolve.js

@@ -0,0 +1,36 @@
+import { ApiError, CliError } from './api.js';
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const KEY = /^([A-Za-z][A-Za-z0-9]*)-(\d+)$/;
+export function parseTicketRef(ref) {
+    if (UUID.test(ref))
+        return { uuid: ref.toLowerCase() };
+    const match = KEY.exec(ref);
+    if (!match)
+        throw new CliError(`"${ref}" is neither a ticket key (like AZA-12) nor a ticket uuid.`);
+    return { projectKey: match[1].toUpperCase(), number: Number(match[2]) };
+}
+/** Asks each of the person's organizations in turn; the first that has the ticket scopes every later call. */
+export async function resolveTicket(api, ref) {
+    const parsed = parseTicketRef(ref);
+    const organizations = (await api.request('account/organizations')) ?? [];
+    if (organizations.length === 0)
+        throw new CliError('Your account is not in any organization.');
+    const path = 'uuid' in parsed
+        ? `tickets/${parsed.uuid}`
+        : `ticket-links/${encodeURIComponent(parsed.projectKey)}/${parsed.number}`;
+    for (const organization of organizations) {
+        try {
+            const ticket = await api.request(path, { organization: organization.uuid });
+            if (!ticket?.uuid)
+                throw new CliError(`Sifur found ${ref} but didn't say which ticket it is.`);
+            const key = ticket.key ?? ('projectKey' in parsed ? `${parsed.projectKey}-${parsed.number}` : null);
+            return { ticketUuid: ticket.uuid, key, organization };
+        }
+        catch (error) {
+            if (error instanceof ApiError && [403, 404].includes(error.status))
+                continue;
+            throw error;
+        }
+    }
+    throw new CliError(`No ticket ${ref} in your organizations (${organizations.map((o) => o.name).join(', ')}).`);
+}

package/dist/results.js

@@ -0,0 +1,32 @@
+/** `screenshots` maps a local screenshot path to the uuid its upload returned. */
+export function buildResultsPayload(stateVersion, baseUrl, results, screenshots) {
+    return {
+        stateVersion,
+        via: 'cli',
+        baseUrl,
+        results: results.map((result) => ({
+            caseUuid: result.caseUuid,
+            status: result.status,
+            notes: result.notes,
+            steps: result.steps.map((step) => ({
+                n: step.n,
+                caption: step.caption,
+                ok: step.ok,
+                error: step.error,
+                screenshotUuid: step.screenshot ? (screenshots.get(step.screenshot) ?? null) : null,
+            })),
+            ...(result.output !== undefined ? { output: result.output } : {}),
+        })),
+    };
+}
+/** Failed outranks blocked: a case that both failed a check and couldn't finish another still failed. */
+export function combine(statuses) {
+    if (statuses.includes('failed'))
+        return 'failed';
+    if (statuses.includes('blocked'))
+        return 'blocked';
+    return 'passed';
+}
+export function outcome(results) {
+    return combine(results.map((result) => result.status));
+}

package/dist/runner.js

@@ -0,0 +1,195 @@
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { newRunToken, redact, resolveStep } from './secrets.js';
+const ASSERTIONS = new Set(['expectText', 'expectVisible', 'expectUrl']);
+const TIMEOUT = 60_000;
+// An assertion after an action waits for the page to settle, as Playwright's own do: a
+// response that lands half a second later still counts.
+export async function eventually(check, timeoutMs = 10_000) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            return await check();
+        }
+        catch (error) {
+            if (Date.now() >= deadline)
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, 250));
+        }
+    }
+}
+/**
+ * The first visible match in the page or any of its frames: older apps put whole screens in
+ * iframes, where the top page's locator never looks.
+ */
+async function find(page, selector, timeoutMs) {
+    if (!selector)
+        throw new Error('the step has no selector');
+    return eventually(async () => {
+        for (const frame of page.frames()) {
+            const match = frame.locator(selector).first();
+            if ((await match.count()) > 0 && (await match.isVisible().catch(() => false)))
+                return match;
+        }
+        throw new Error(`nothing visible matches ${selector}, in the page or its frames`);
+    }, timeoutMs);
+}
+/** The text of every frame's body: what a person reading the screen sees. */
+async function screenText(page) {
+    const texts = await Promise.all(page.frames().map((frame) => frame.locator('body').innerText().catch(() => '')));
+    return texts.join('\n');
+}
+/**
+ * A case's path under `--url`, which may be the app's folder rather than the site's root
+ * (`https://test.example/team/app/`): `/login.php`, `login.php` and `#list` all open under it.
+ * A full URL is used as is.
+ */
+export function caseUrl(path, baseUrl) {
+    if (/^[a-z][a-z0-9+.-]*:/i.test(path))
+        return path;
+    const base = new URL(baseUrl);
+    base.search = '';
+    base.hash = '';
+    // `…/app/login.php` is a page in the app's folder; `…/app` is the folder itself.
+    if (!base.pathname.endsWith('/')) {
+        base.pathname = /\.[a-z0-9]+$/i.test(base.pathname)
+            ? base.pathname.replace(/[^/]*$/, '')
+            : `${base.pathname}/`;
+    }
+    return new URL(path.replace(/^\/+/, ''), base).toString();
+}
+async function perform(page, step, baseUrl, settleMs) {
+    const url = step.url ? caseUrl(step.url, baseUrl) : null;
+    switch (step.action) {
+        case 'goto':
+            if (!url)
+                throw new Error('the step has no url');
+            // `load`, not `networkidle`: an app that polls never goes quiet, least of all over a VPN.
+            await page.goto(url, { waitUntil: 'load' });
+            break;
+        case 'click':
+            await (await find(page, step.selector, settleMs)).click();
+            break;
+        case 'fill':
+            await (await find(page, step.selector, settleMs)).fill(String(step.value ?? ''));
+            break;
+        case 'press':
+            await (await find(page, step.selector, settleMs)).press(String(step.value));
+            break;
+        case 'select':
+            await (await find(page, step.selector, settleMs)).selectOption(String(step.value));
+            break;
+        case 'wait':
+            await page.waitForTimeout(Math.min(Number(step.value ?? 500), 10_000));
+            break;
+        case 'expectText': {
+            const selector = step.selector;
+            await eventually(async () => {
+                const text = selector ? await (await find(page, selector, 0)).innerText() : await screenText(page);
+                if (!text.includes(String(step.text)))
+                    throw new Error(`expected "${step.text}" in ${selector ?? 'the page'}`);
+            }, settleMs);
+            break;
+        }
+        case 'expectVisible':
+            await find(page, step.selector, settleMs);
+            break;
+        case 'expectUrl':
+            await eventually(async () => {
+                if (!page.url().includes(String(step.text))) {
+                    throw new Error(`expected the URL to contain "${step.text}", got ${page.url()}`);
+                }
+            }, settleMs);
+            break;
+        case 'judge':
+            break;
+        default:
+            throw new Error(`unknown action ${step.action}`);
+    }
+}
+/** What a step does, for one with no caption: a screenshot labeled "expectText" says nothing. */
+export function describe(step) {
+    const target = step.selector ?? '';
+    switch (step.action) {
+        case 'goto':
+            return `Open ${step.url ?? ''}`.trim();
+        case 'click':
+            return `Click ${target}`.trim();
+        case 'fill':
+            return `Type into ${target}`.trim();
+        case 'press':
+            return `Press ${step.value ?? ''} in ${target}`.trim();
+        case 'select':
+            return `Choose ${step.value ?? ''} in ${target}`.trim();
+        case 'wait':
+            return `Wait ${Number(step.value ?? 500) / 1000}s`;
+        case 'expectText':
+            return `Expect "${step.text ?? ''}"${target ? ` in ${target}` : ''}`;
+        case 'expectVisible':
+            return `Expect ${target} to show`;
+        case 'expectUrl':
+            return `Expect the address to contain "${step.text ?? ''}"`;
+        case 'judge':
+            return 'Check the screen';
+        default:
+            return step.action;
+    }
+}
+/** One case's UI script, as the sandbox's runner plays it: a screenshot after every step, stopping at the first failure. */
+export async function runUiCase(browser, testCase, options) {
+    const secrets = options.secrets ?? {};
+    const runToken = options.runToken ?? newRunToken();
+    const dir = join(options.outDir, testCase.id);
+    await mkdir(dir, { recursive: true });
+    // Light, always: an app that follows the system theme is judged in one, the same every run.
+    const context = await browser.newContext({ viewport: { width: 1440, height: 900 }, colorScheme: 'light' });
+    const page = await context.newPage();
+    page.setDefaultTimeout(options.timeoutMs ?? TIMEOUT);
+    const steps = [];
+    const notes = [];
+    let status = 'passed';
+    try {
+        for (const [index, step] of (testCase.uiScript ?? []).entries()) {
+            const n = index + 1;
+            const caption = redact(step.caption ?? describe(step), secrets);
+            let ok = true;
+            let error = null;
+            options.onStep?.(n, caption);
+            try {
+                await perform(page, resolveStep(step, secrets, runToken), options.baseUrl, options.timeoutMs ?? TIMEOUT);
+            }
+            catch (caught) {
+                ok = false;
+                error = redact(String(caught?.message ?? caught).split('\n')[0] ?? '', secrets);
+            }
+            let screenshot = join(dir, `${String(n).padStart(2, '0')}.png`);
+            await page.screenshot({ path: screenshot, fullPage: true }).catch(() => {
+                screenshot = null;
+            });
+            let judged = false;
+            if (ok && step.action === 'judge') {
+                const answer = await options.judge(step, screenshot, testCase);
+                judged = true;
+                if (answer.note)
+                    notes.push(`Step ${n} (${caption}): ${answer.note}`);
+                if (!answer.ok) {
+                    ok = false;
+                    error = answer.note ? `The engineer judged it wrong: ${answer.note}` : 'The engineer judged it wrong.';
+                }
+            }
+            steps.push({ n, action: step.action, caption, ok, error, screenshot });
+            if (!ok) {
+                // A failed assertion (or a judged screenshot that's wrong) is a failed case; anything
+                // failing before it means the case couldn't be run as written, so it's blocked.
+                status = ASSERTIONS.has(step.action) || judged ? 'failed' : 'blocked';
+                if (!judged)
+                    notes.push(`Step ${n} (${caption}): ${error}`);
+                break;
+            }
+        }
+    }
+    finally {
+        await context.close().catch(() => { });
+    }
+    return { status, steps, notes };
+}

package/dist/secrets.js

@@ -0,0 +1,83 @@
+import { randomBytes } from 'node:crypto';
+const PLACEHOLDER = /\{\{([A-Z][A-Z0-9_]*)\}\}/g;
+/** Not a secret: each run's own token, for data a case creates and can create again next run. */
+export const RUN = 'RUN';
+const ECHOED = /USER|EMAIL|LOGIN/;
+const HIDDEN = /PASSWORD|TOKEN|SECRET/;
+/** Where a step's secrets go: what it types, the page it opens, and the text it checks for. */
+function secretFields(step) {
+    switch (step.action) {
+        case 'fill':
+            return ['value'];
+        case 'goto':
+            return ['url'];
+        case 'expectText':
+        case 'expectUrl':
+            return ['text'];
+        default:
+            return [];
+    }
+}
+/** Each secret the scripts use, with the first step that needs it. */
+export function secretUses(cases) {
+    const uses = new Map();
+    for (const testCase of cases) {
+        for (const [index, step] of (testCase.uiScript ?? []).entries()) {
+            for (const field of secretFields(step)) {
+                for (const match of String(step[field] ?? '').matchAll(PLACEHOLDER)) {
+                    const name = match[1];
+                    if (name !== RUN && !uses.has(name))
+                        uses.set(name, { name, caseId: testCase.id, step: index + 1, caption: step.caption });
+                }
+            }
+        }
+    }
+    return [...uses.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+export function secretNames(cases) {
+    return secretUses(cases).map((use) => use.name);
+}
+/** From `SIFUR_SECRET_<NAME>`, or typed. Kept in memory only: never written or sent to Sifur. */
+export async function collectSecrets(uses, io, env = process.env) {
+    const secrets = {};
+    for (const { name, caseId, step, caption } of uses) {
+        const fromEnv = env[`SIFUR_SECRET_${name}`];
+        if (fromEnv !== undefined) {
+            secrets[name] = fromEnv;
+            continue;
+        }
+        io.out(`${caseId} uses {{${name}}} in step ${step}${caption ? ` (${caption})` : ''}.`);
+        const prompt = `${name} (or set SIFUR_SECRET_${name}): `;
+        secrets[name] = ECHOED.test(name) && !HIDDEN.test(name) ? await io.ask(prompt) : await io.askHidden(prompt);
+    }
+    return secrets;
+}
+export function withSecrets(value, secrets) {
+    return value.replace(PLACEHOLDER, (match, name) => secrets[name] ?? match);
+}
+export function newRunToken() {
+    const alphabet = 'abcdefghijklmnopqrstuvwxyz0123456789';
+    return [...randomBytes(8)].map((byte) => alphabet[byte % alphabet.length]).join('');
+}
+/** The step as it's played: this run's token in every field, secrets where they belong. */
+export function resolveStep(step, secrets, runToken) {
+    const resolved = { ...step };
+    for (const field of ['url', 'selector', 'value', 'text']) {
+        const value = resolved[field];
+        if (typeof value === 'string')
+            resolved[field] = value.replaceAll(`{{${RUN}}}`, runToken);
+    }
+    for (const field of secretFields(step)) {
+        const value = resolved[field];
+        if (value !== undefined)
+            resolved[field] = withSecrets(String(value), secrets);
+    }
+    return resolved;
+}
+export function redact(text, secrets) {
+    let redacted = text;
+    for (const value of Object.values(secrets))
+        if (value)
+            redacted = redacted.replaceAll(value, '[secret]');
+    return redacted;
+}

package/dist/store.js

@@ -0,0 +1,89 @@
+import { mkdir, readdir, readFile, rm, rmdir, writeFile } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { CliError } from './api.js';
+/** Where 0.1.0 kept a ticket's files, in the directory it ran from. Never read or written now. */
+export const LEGACY_STORE = '.sifur';
+/** Folder of a patch `sifur apply` put in a checkout, kept until `--revert` needs it. */
+export const APPLIED = 'applied';
+export function ticketDir(root, key) {
+    return join(root, key.replace(/[^A-Za-z0-9_-]/g, '_'));
+}
+export async function saveCases(root, saved) {
+    const dir = ticketDir(root, saved.acceptance.ticket.key);
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, 'cases.json'), `${JSON.stringify(saved, null, 2)}\n`);
+    return dir;
+}
+function mapScreenshots(results, map) {
+    return {
+        ...results,
+        results: results.results.map((result) => ({
+            ...result,
+            steps: result.steps.map((step) => ({ ...step, screenshot: step.screenshot ? map(step.screenshot) : null })),
+        })),
+    };
+}
+/** Screenshot paths are kept relative to the ticket's folder, so the folder can move between --run and --upload. */
+export async function saveResults(dir, results) {
+    const path = join(dir, 'results.json');
+    const portable = mapScreenshots(results, (screenshot) => (isAbsolute(screenshot) ? relative(dir, screenshot) : screenshot));
+    await writeFile(path, `${JSON.stringify(portable, null, 2)}\n`);
+    return path;
+}
+async function readJson(path) {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw new CliError(`${path} isn't readable JSON: ${error.message}`);
+    }
+}
+/** A key names its folder; a uuid is looked for among the downloaded tickets. */
+export async function findTicketDir(root, ref) {
+    const direct = ticketDir(root, ref.toUpperCase());
+    if (await readJson(join(direct, 'cases.json')))
+        return direct;
+    let entries;
+    try {
+        entries = await readdir(root);
+    }
+    catch {
+        return null;
+    }
+    for (const entry of entries) {
+        const saved = await readJson(join(root, entry, 'cases.json'));
+        if (saved?.acceptance.ticket.uuid === ref.toLowerCase())
+            return join(root, entry);
+    }
+    return null;
+}
+export async function loadCases(dir) {
+    const saved = await readJson(join(dir, 'cases.json'));
+    if (!saved)
+        throw new CliError(`No downloaded cases in ${dir}. Run with --download first.`);
+    return saved;
+}
+export async function loadResults(dir) {
+    const saved = await readJson(join(dir, 'results.json'));
+    if (!saved)
+        throw new CliError(`No results in ${dir}. Run with --run first.`);
+    return mapScreenshots(saved, (screenshot) => resolve(dir, screenshot));
+}
+async function removeIfEmpty(dir) {
+    await rmdir(dir).catch(() => { });
+}
+/** Removes a ticket's folder, and the store's own folder when nothing else is left in it. */
+export async function pruneTicketDir(store, dir) {
+    await removeIfEmpty(dir);
+    await removeIfEmpty(store);
+}
+/** Everything kept for a ticket once its results are in, except a patch that's still applied. */
+export async function removeTicketFiles(store, dir) {
+    const entries = await readdir(dir).catch(() => []);
+    for (const entry of entries)
+        if (entry !== APPLIED)
+            await rm(join(dir, entry), { recursive: true, force: true });
+    await pruneTicketDir(store, dir);
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};