@asrunjs/asrun 0.0.0-stage → 0.5.2

package/dist/ui/server/profiles.js

@@ -0,0 +1,371 @@
+import fs from 'node:fs';
+import { chromium } from '@playwright/test';
+import { isMap, isSeq, parseDocument } from 'yaml';
+import { DEFAULT_SESSION_CHECK_PATH, DEFAULT_SESSION_CHECK, listEnvs, listProfiles, loadProfiles, PROFILES_FILE, validateSessionCheck } from '../../lib/profiles.js';
+import { authFile } from '../../lib/paths.js';
+import { checkSession } from '../../lib/session.js';
+import { withScheme } from '../shared/site-address.js';
+// Keyed by profile id.
+const verifications = new Map();
+const verifying = new Set();
+/** Only looks at file timestamps; the content of the session file is never read here. */
+function savedAt(profileId) {
+    const file = authFile(profileId);
+    return fs.existsSync(file) ? fs.statSync(file).mtime.toISOString() : null;
+}
+const toInfo = (profile) => {
+    const saved = savedAt(profile.id);
+    const verification = verifications.get(profile.id);
+    // A session file saved after the check (a new login from the CLI, another browser tab) makes the old
+    // result stale, so the row shows "unverified" until it is checked again.
+    const stale = Boolean(saved && verification && saved > verification.checkedAt);
+    let status;
+    if (!saved)
+        status = 'missing';
+    else if (!verification || stale)
+        status = 'unverified';
+    else
+        status = verification.status === 'missing' ? 'unverified' : verification.status;
+    return {
+        id: profile.id,
+        name: profile.name,
+        env: profile.env,
+        baseURL: profile.baseURL,
+        account: profile.account,
+        tags: profile.tags,
+        startPath: profile.startPath,
+        sessionCheckPath: profile.sessionCheckPath,
+        sessionCheck: profile.sessionCheck,
+        email: profile.email,
+        status,
+        verifying: verifying.has(profile.id),
+        savedAt: saved,
+        checkedAt: verification?.checkedAt ?? null,
+        error: verification?.error,
+    };
+};
+export function listProfileRows() {
+    return { profiles: listProfiles().map(toInfo), envs: listEnvs(), verifying: verifying.size > 0 };
+}
+/** Opens each saved session on the real site (read-only) and records whether it is still logged in. */
+export async function verifyProfiles(only) {
+    const profiles = listProfiles().filter((profile) => (!only?.ids || only.ids.includes(profile.id)) && (!only?.env || only.env === profile.env) && !verifying.has(profile.id));
+    const withSession = profiles.filter((profile) => savedAt(profile.id));
+    for (const profile of profiles) {
+        if (!savedAt(profile.id))
+            verifications.delete(profile.id);
+    }
+    if (withSession.length === 0)
+        return;
+    for (const profile of withSession)
+        verifying.add(profile.id);
+    let browser;
+    try {
+        browser = await chromium.launch();
+        await Promise.all(withSession.map(async (profile) => {
+            try {
+                const status = await checkSession(browser, profile);
+                verifications.set(profile.id, { status, checkedAt: new Date().toISOString() });
+            }
+            catch (error) {
+                verifications.set(profile.id, {
+                    status: 'error',
+                    checkedAt: new Date().toISOString(),
+                    error: error.message.split('\n')[0],
+                });
+            }
+            finally {
+                verifying.delete(profile.id);
+            }
+        }));
+    }
+    catch (error) {
+        for (const profile of withSession) {
+            verifications.set(profile.id, {
+                status: 'error',
+                checkedAt: new Date().toISOString(),
+                error: error.message.split('\n')[0],
+            });
+            verifying.delete(profile.id);
+        }
+    }
+    finally {
+        await browser?.close();
+    }
+}
+const PROFILE_ID = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const ENV_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+export class ProfileError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+function parseSiteAddress(text, label) {
+    let url;
+    try {
+        // A typed address without a scheme (`example.com`) is completed with https://.
+        url = new URL(withScheme(text));
+    }
+    catch {
+        throw new ProfileError(`${label} must be a full URL, e.g. https://www.example.com.`, 400);
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new ProfileError(`${label} must start with https:// (or http://).`, 400);
+    }
+    if (url.pathname !== '/' || url.search || url.hash || url.username || url.password) {
+        throw new ProfileError(`${label} must be only the site address, without a path, query or credentials.`, 400);
+    }
+    return url;
+}
+const normalTags = (tags) => [...new Set((tags ?? []).map((tag) => tag.trim()).filter(Boolean))];
+function readFields(request) {
+    const name = request.name.trim();
+    const env = request.env.trim();
+    const account = request.account?.trim() || undefined;
+    const startPath = request.startPath?.trim() || undefined;
+    const sessionCheckPath = request.sessionCheckPath?.trim() || undefined;
+    // Same rules as the loader, so the file the form writes is one `pnpm asrun` accepts.
+    const sessionCheck = validateSessionCheck('Session check', request.sessionCheck ?? null);
+    if (!name)
+        throw new ProfileError('Name is required.', 400);
+    if (!ENV_NAME.test(env)) {
+        throw new ProfileError('Environment must be lowercase letters and digits, separated by single dashes (e.g. "production", "staging").', 400);
+    }
+    if (env === 'production' && request.email === true) {
+        throw new ProfileError('email: true is not allowed. Tests never send email in production.', 400);
+    }
+    const baseURL = parseSiteAddress(request.baseURL, 'Base URL').origin;
+    if (startPath && (!startPath.startsWith('/') || startPath.startsWith('//') || /\s/.test(startPath))) {
+        throw new ProfileError('Start path must be empty (the site root) or a path on the site that starts with a single "/" and contains no spaces.', 400);
+    }
+    if (sessionCheckPath && (!sessionCheckPath.startsWith('/') || /\s/.test(sessionCheckPath))) {
+        throw new ProfileError('Session check path must start with "/" and contain no spaces.', 400);
+    }
+    return {
+        name,
+        env,
+        baseURL,
+        account,
+        tags: normalTags(request.tags),
+        startPath,
+        sessionCheckPath,
+        sessionCheck,
+        email: request.email === true,
+    };
+}
+/** The `sessionCheck` keys that differ from the defaults, or null when the profile can rely on them. */
+function sessionCheckEntry(check) {
+    const entry = {};
+    if (check.loggedOutUrl !== DEFAULT_SESSION_CHECK.loggedOutUrl)
+        entry.loggedOutUrl = check.loggedOutUrl;
+    if (check.loggedInSelector)
+        entry.loggedInSelector = check.loggedInSelector;
+    if (check.loggedOutSelector)
+        entry.loggedOutSelector = check.loggedOutSelector;
+    if (check.timeoutMs !== DEFAULT_SESSION_CHECK.timeoutMs)
+        entry.timeoutMs = check.timeoutMs;
+    return Object.keys(entry).length > 0 ? entry : null;
+}
+const sameSessionCheck = (a, b) => a.loggedOutUrl === b.loggedOutUrl &&
+    a.loggedInSelector === b.loggedInSelector &&
+    a.loggedOutSelector === b.loggedOutSelector &&
+    a.timeoutMs === b.timeoutMs;
+/**
+ * Writes the edited YAML document and restores the old file when the result cannot be loaded, so a
+ * failed save never leaves a profiles.yaml behind that the test runner cannot read.
+ */
+function saveDocument(file, doc, original, action) {
+    const temp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(temp, doc.toString());
+    fs.renameSync(temp, file);
+    try {
+        loadProfiles(file);
+    }
+    catch (error) {
+        fs.writeFileSync(file, original);
+        throw new ProfileError(`Could not ${action}: ${error.message}`, 400);
+    }
+}
+const sameList = (a, b) => a.length === b.length && a.every((value, index) => value === b[index]);
+/**
+ * Appends one profile to profiles.yaml. The file is edited as a YAML document, so comments and the
+ * existing entries stay as they are.
+ */
+export function addProfile(request, file = PROFILES_FILE) {
+    const id = request.id.trim();
+    const fields = readFields(request);
+    if (!PROFILE_ID.test(id)) {
+        throw new ProfileError('Profile id must be lowercase letters and digits, separated by single dashes (e.g. "example-staging").', 400);
+    }
+    if (loadProfiles(file).some((profile) => profile.id === id)) {
+        throw new ProfileError(`Profile "${id}" already exists.`, 409);
+    }
+    const original = fs.readFileSync(file, 'utf8');
+    const doc = parseDocument(original, { merge: true });
+    if (doc.errors.length > 0) {
+        throw new ProfileError('profiles.yaml has syntax errors; fix it by hand first.', 400);
+    }
+    const profiles = doc.get('profiles');
+    if (!isSeq(profiles))
+        throw new ProfileError('profiles.yaml has no "profiles" list.', 400);
+    // `profiles: []` is a flow sequence; adding a map entry to it would render `[ { ... } ]`. Keep the file block-style.
+    profiles.flow = false;
+    const hadEntries = profiles.items.length > 0;
+    const check = sessionCheckEntry(fields.sessionCheck);
+    const entry = doc.createNode({
+        id,
+        name: fields.name,
+        env: fields.env,
+        baseURL: fields.baseURL,
+        ...(fields.account && { account: fields.account }),
+        ...(fields.tags.length > 0 && { tags: fields.tags }),
+        ...(fields.startPath && { startPath: fields.startPath }),
+        ...(fields.sessionCheckPath && { sessionCheckPath: fields.sessionCheckPath }),
+        ...(check && { sessionCheck: check }),
+        // Never send email from a new profile until a human has checked that a mailbox is connected.
+        email: fields.email,
+    });
+    if (isMap(entry)) {
+        entry.spaceBefore = hadEntries;
+        entry.flow = false;
+    }
+    profiles.add(entry);
+    saveDocument(file, doc, original, 'add the profile');
+    return toInfo(loadProfiles(file).find((profile) => profile.id === id));
+}
+/**
+ * Deletes the saved login of one profile, so it has to log in again. The file holds the session cookies
+ * and is never read here, only removed.
+ */
+export function forgetSession(id, file = PROFILES_FILE) {
+    const profile = loadProfiles(file).find((candidate) => candidate.id === id);
+    if (!profile)
+        throw new ProfileError(`Profile "${id}" is not in profiles.yaml any more. Reload the page.`, 409);
+    fs.rmSync(authFile(id), { force: true });
+    verifications.delete(id);
+    return toInfo(profile);
+}
+/**
+ * Removes one profile from profiles.yaml and deletes its saved login. Only that entry is written, so the
+ * comments and the other entries stay in the file. Screenshot baselines named after the id stay on disk:
+ * they are files of the cases, not of the profile.
+ */
+export function deleteProfile(id, file = PROFILES_FILE) {
+    const profile = loadProfiles(file).find((candidate) => candidate.id === id);
+    if (!profile)
+        throw new ProfileError(`Profile "${id}" is not in profiles.yaml any more. Reload the page.`, 409);
+    const original = fs.readFileSync(file, 'utf8');
+    const doc = parseDocument(original, { merge: true });
+    if (doc.errors.length > 0) {
+        throw new ProfileError('profiles.yaml has syntax errors; fix it by hand first.', 400);
+    }
+    const profiles = doc.get('profiles');
+    if (!isSeq(profiles))
+        throw new ProfileError('profiles.yaml has no "profiles" list.', 400);
+    const index = profiles.items.findIndex((item) => isMap(item) && item.get('id') === id);
+    if (index < 0)
+        throw new ProfileError(`Profile "${id}" is not in profiles.yaml any more. Reload the page.`, 409);
+    profiles.delete(index);
+    // The entry that is first now keeps the blank line of the one before it; drop it so `profiles:` is followed
+    // directly by the entry, like a hand-written file.
+    const first = profiles.items[0];
+    if (isMap(first))
+        first.spaceBefore = false;
+    // A `profiles:` with nothing under it is null; the loader needs a list (it may be empty while the suite is
+    // set up), so an emptied list is written as `[]`.
+    if (profiles.items.length === 0)
+        profiles.flow = true;
+    saveDocument(file, doc, original, 'delete the profile');
+    // The saved login belonged to this profile. The file is never read here, only removed.
+    fs.rmSync(authFile(id), { force: true });
+    verifications.delete(id);
+}
+/**
+ * Changes the fields of one existing profile. Only the fields that actually changed are written, so
+ * comments on the others stay in the file. When the site address changes, the saved login belongs to
+ * the old site and is deleted: the profile has to log in again on the new one.
+ */
+export function editProfile(request, file = PROFILES_FILE) {
+    const id = request.id.trim();
+    if (!PROFILE_ID.test(id)) {
+        throw new ProfileError('Profile id must be lowercase letters and digits, separated by single dashes (e.g. "example-staging").', 400);
+    }
+    const fields = readFields(request);
+    const before = loadProfiles(file).find((profile) => profile.id === id);
+    if (!before)
+        throw new ProfileError(`Profile "${id}" is not in profiles.yaml any more. Reload the page.`, 409);
+    const original = fs.readFileSync(file, 'utf8');
+    const doc = parseDocument(original, { merge: true });
+    if (doc.errors.length > 0) {
+        throw new ProfileError('profiles.yaml has syntax errors; fix it by hand first.', 400);
+    }
+    const profiles = doc.get('profiles');
+    if (!isSeq(profiles))
+        throw new ProfileError('profiles.yaml has no "profiles" list.', 400);
+    const entry = profiles.items.find((item) => isMap(item) && item.get('id') === id);
+    if (!isMap(entry))
+        throw new ProfileError(`Profile "${id}" is not in profiles.yaml any more. Reload the page.`, 409);
+    if (fields.name !== before.name)
+        entry.set('name', fields.name);
+    if (fields.env !== before.env)
+        entry.set('env', fields.env);
+    if (fields.baseURL !== before.baseURL)
+        entry.set('baseURL', fields.baseURL);
+    if (fields.account) {
+        if (fields.account !== before.account)
+            entry.set('account', fields.account);
+    }
+    else if (entry.has('account')) {
+        entry.delete('account');
+    }
+    if (!sameList(fields.tags, before.tags)) {
+        if (fields.tags.length > 0)
+            entry.set('tags', fields.tags);
+        else
+            entry.delete('tags');
+    }
+    // An empty path means the site root; drop an explicit key instead of writing an empty one.
+    if (fields.startPath) {
+        if (fields.startPath !== before.startPath || !entry.has('startPath')) {
+            entry.set('startPath', fields.startPath);
+        }
+    }
+    else if (entry.has('startPath')) {
+        entry.delete('startPath');
+    }
+    // An omitted path means the default; drop an explicit key instead of writing the default out.
+    if (fields.sessionCheckPath && fields.sessionCheckPath !== DEFAULT_SESSION_CHECK_PATH) {
+        if (fields.sessionCheckPath !== before.sessionCheckPath || !entry.has('sessionCheckPath')) {
+            entry.set('sessionCheckPath', fields.sessionCheckPath);
+        }
+    }
+    else if (entry.has('sessionCheckPath')) {
+        entry.delete('sessionCheckPath');
+    }
+    // The same for the session check signals: write only what differs from the defaults, so the entry
+    // stays readable (and a comment above it stays in place when nothing about it changed).
+    if (!sameSessionCheck(fields.sessionCheck, before.sessionCheck)) {
+        const check = sessionCheckEntry(fields.sessionCheck);
+        if (check)
+            entry.set('sessionCheck', check);
+        else
+            entry.delete('sessionCheck');
+    }
+    if (fields.email !== before.email)
+        entry.set('email', fields.email);
+    saveDocument(file, doc, original, 'save the profile');
+    const siteChanged = fields.baseURL !== before.baseURL;
+    const hadSession = siteChanged && fs.existsSync(authFile(id));
+    if (siteChanged) {
+        // The saved login holds cookies of the old site. Deleting the file (never reading it) makes the
+        // profile log in again on the new address.
+        fs.rmSync(authFile(id), { force: true });
+        verifications.delete(id);
+    }
+    return {
+        profile: toInfo(loadProfiles(file).find((profile) => profile.id === id)),
+        sessionCleared: hadSession,
+    };
+}

package/dist/ui/server/watch-files.d.ts

@@ -0,0 +1,4 @@
+import { EventEmitter } from 'node:events';
+/** Emits `files` when a case file or a spec changes on disk, whoever changed it (the UI, an agent, an editor). */
+export declare const fileEvents: EventEmitter<[never]>;
+export declare function startFileWatcher(): void;

package/dist/ui/server/watch-files.js

@@ -0,0 +1,36 @@
+import { EventEmitter } from 'node:events';
+import fs from 'node:fs';
+import { CASES_DIR, TESTS_DIR } from '../../lib/paths.js';
+const DEBOUNCE_MS = 200;
+/** Emits `files` when a case file or a spec changes on disk, whoever changed it (the UI, an agent, an editor). */
+export const fileEvents = new EventEmitter();
+fileEvents.setMaxListeners(0);
+export function startFileWatcher() {
+    const pending = { cases: false, specs: false };
+    let timer = null;
+    const schedule = (kind) => {
+        pending[kind] = true;
+        timer ??= setTimeout(() => {
+            timer = null;
+            const change = { ...pending };
+            pending.cases = false;
+            pending.specs = false;
+            fileEvents.emit('files', change);
+        }, DEBOUNCE_MS);
+    };
+    const watch = (dir, kind, suffix) => {
+        try {
+            const watcher = fs.watch(dir, { recursive: true }, (_event, filename) => {
+                if (filename && filename.toString().endsWith(suffix))
+                    schedule(kind);
+            });
+            watcher.on('error', () => watcher.close());
+            watcher.unref();
+        }
+        catch {
+            // The folder does not exist (yet) or cannot be watched; the pages still refresh when the window gets focus.
+        }
+    };
+    watch(CASES_DIR, 'cases', '.md');
+    watch(TESTS_DIR, 'specs', '.spec.ts');
+}

package/dist/ui/shared/ai-commands.d.ts

@@ -0,0 +1,88 @@
+export declare const AI_TOOLS: readonly ['claude', 'opencode'];
+export type AiTool = (typeof AI_TOOLS)[number];
+export declare const DEFAULT_AI_TOOL: AiTool;
+export declare const AI_TOOL_LABEL: Record<AiTool, string>;
+export declare const AI_COMMANDS: readonly ['explore-case', 'gen-spec', 'heal-spec'];
+export type AiCommand = (typeof AI_COMMANDS)[number];
+export declare const AI_COMMAND_LABEL: Record<AiCommand, string>;
+/**
+ * What a one-shot run of a command may change, so the permissions can be as narrow as possible.
+ * `case`: only cases/*.md. `spec`: also the spec, but it never runs the tests.
+ * `files`: also snapshots, and it runs the tests.
+ */
+export type AiWrites = 'case' | 'spec' | 'files';
+export declare const AI_COMMAND_WRITES: Record<AiCommand, AiWrites>;
+/**
+ * Every command opens real pages, so every command needs an environment and there is no default.
+ * Agents never write data in any of them: a person does those steps.
+ */
+export declare const AI_ENV_HINT: Record<AiCommand, string>;
+/** What a run of a command on a case may be told besides the case id. */
+export interface AiRunOptions {
+    /** The environment to explore. There is no default. */
+    env: string;
+    /**
+     * The model to run the agent with, as `provider/model` (`#variant` for OpenCode) or a Claude alias/name.
+     * Omitted = whatever the CLI would pick by itself, which for OpenCode is its built-in free model.
+     */
+    model?: string;
+    /** `gen-spec` only: regenerate and overwrite an existing spec instead of leaving it alone. */
+    force?: boolean;
+    /** `explore-case` only: a person is at the machine, so steps that write data are handed to them in the browser. */
+    attended?: boolean;
+    /** Show the agent's reasoning in the log (`--thinking` for OpenCode). Off by default: it costs tokens and time. */
+    thinking?: boolean;
+    /** `heal-spec` only: the profiles to heal. Omitted = every profile that is logged in in `env`. */
+    profiles?: string[];
+    /** `heal-spec` only: file (relative to the project root) with the user's description and clues. */
+    hints?: string;
+    /** `heal-spec` only: the report (folder name under reports/) to read first instead of the newest one. */
+    report?: string;
+}
+export declare const slashCommand: (command: AiCommand, caseId: string, options: AiRunOptions) => string;
+/**
+ * The conversation of a one-shot run. The server picks the id, so a later turn can resume it: the first turn
+ * creates the session, every following one (`resume`) continues it with the same permissions.
+ */
+export interface AiSession {
+    id: string;
+    resume: boolean;
+}
+/** The prompt of a one-shot run. `heal-spec` has no questions of its own, so it keeps the plain slash command. */
+export declare function headlessPrompt(command: AiCommand, caseId: string, options: AiRunOptions): string;
+/** Executable and arguments of the one-shot (non-interactive) run. */
+export declare function headlessInvocation(tool: AiTool, command: AiCommand, caseId: string, options: AiRunOptions, session?: AiSession): {
+    file: string;
+    args: string[];
+};
+/** The one-shot command as it is typed in a shell. */
+export declare function headlessCommandLine(tool: AiTool, command: AiCommand, caseId: string, options: AiRunOptions, session?: AiSession): string;
+/** Folder (relative to the AsRun root, git-ignored) where the clues typed into the Heal dialog are stored. */
+export declare const HINTS_DIR = ".tmp/hints";
+export declare const HINTS_MAX_CHARS = 8000;
+/** Folder (relative to the AsRun root, git-ignored) where the answers typed into the Continue box are stored. */
+export declare const REPLY_DIR = ".tmp/replies";
+export declare const REPLY_MAX_CHARS = 4000;
+export declare const USE_DEFAULTS_REPLY = "Accept the suggestion of every open question: delete its TODO block and keep the sentence above it as confirmed text.";
+/**
+ * The next turn of a run that ended with `RESULT: needs-input`: the user's answers. They go into the case file, which
+ * stays the record of truth, and the task of the original command is finished. The answers come from a file
+ * (`.tmp/replies/…md`) rather than from the prompt, so a line break or a quote in them cannot break the command line.
+ */
+export declare function replyPrompt(command: AiCommand, replyFile: string): string;
+/** The next turn of an earlier run, in its session and with exactly the permissions of the first turn. */
+export declare function continueInvocation(tool: AiTool, command: AiCommand, replyFile: string, sessionId: string, model?: string, thinking?: boolean): {
+    file: string;
+    args: string[];
+};
+export declare const continueCommandLine: (tool: AiTool, command: AiCommand, replyFile: string, sessionId: string, model?: string, thinking?: boolean) => string;
+/** Folder (relative to the AsRun root, git-ignored) where memos from the Cases page are stored. */
+export declare const MEMO_DIR = ".tmp/memos";
+export declare const MEMO_MAX_CHARS = 100000;
+/** /make-case is interactive by design; a one-shot run cannot answer questions, so it must use the defaults. */
+export declare const makeCasePrompt: (memoPath: string) => string;
+export declare const makeCaseInvocation: (tool: AiTool, memoPath: string, model?: string, thinking?: boolean) => {
+    file: string;
+    args: string[];
+};
+export declare const makeCaseCommandLine: (tool: AiTool, memoPath: string, model?: string, thinking?: boolean) => string;