tinybeeai 0.0.0-stage → 0.16.1

package/dist/routes/dot-suggest.js

@@ -0,0 +1,1002 @@
+// New dot in two steps (KAT-97). GET /api/dots/repos lists the repos the connected GitHub account
+// can see, recent first. GET /api/dots/suggest?repo=owner/name returns every default a new dot
+// inherits, each with its source: the tracker from Setup, a base URL from deployments, the homepage,
+// or the Playwright config, setup steps and the test command from package.json, the lockfile, the
+// Playwright config, and CI workflows, the model and AI-Vision from Setup, and the brief from the
+// Product area role preset (its brief and its six stages) with the repo filled in. The client posts `input` to POST /api/dots.
+//
+// TODO(KAT-85): when Watch.repos lands, accept several repos here and return a role per repo.
+import path from 'node:path';
+import { baseUrlFromConfig } from '../cli/init.js';
+import { config, setting } from '../config.js';
+import { list } from '../db.js';
+import { fetchT } from '../connect/deps.js';
+import { apiBase, appAuth, ghHeaders } from '../connect/github-app.js';
+import { getMeta } from '../connect/store.js';
+import { parseCommand, PLAYWRIGHT_TEST, playwrightTail, scriptRun, shQuote, splitSetupSteps, validateRunner, workingDirectoryError, } from '../runner/command.js';
+import { ROLE_PRESETS } from './roles.js';
+import { DEMO_REPO } from '../onboarding.js';
+const PW_CONFIGS = ['playwright.config.ts', 'playwright.config.mts', 'playwright.config.js', 'playwright.config.mjs', 'playwright.config.cjs'];
+const SEGMENT_RE = /^[A-Za-z0-9_.-]{1,100}$/;
+/**
+ * "owner/name" as a GitHub API path, or undefined. Each part is checked and encoded on its own, and
+ * dot-only parts are refused: `repo=../user` would otherwise resolve `/repos/../user` to `/user`.
+ */
+export function repoPath(full) {
+    const parts = full.split('/');
+    if (parts.length !== 2 || !parts.every((x) => SEGMENT_RE.test(x) && !/^\.+$/.test(x)))
+        return undefined;
+    return parts.map(encodeURIComponent).join('/');
+}
+// A new dot starts as a product area, with all six stages on (docs/STAGES.md section 6.3).
+const DEFAULT_ROLE = 'product-area';
+export class SuggestError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+// GitHub access
+function githubConnected() {
+    return !!((setting('GITHUB_APP_ID') && setting('GITHUB_PRIVATE_KEY')) || setting('GITHUB_TOKEN'));
+}
+/** A token that can read `full`: the PAT or gh token, or an App installation token for the repo. */
+async function tokenFor(full) {
+    const id = setting('GITHUB_APP_ID');
+    const key = setting('GITHUB_PRIVATE_KEY');
+    if (id && key) {
+        const auth = await appAuth(id, key);
+        if (!full || !repoPath(full))
+            return undefined;
+        const jwt = (await auth({ type: 'app' })).token;
+        const res = await fetchT(`${apiBase()}/repos/${repoPath(full)}/installation`, { headers: ghHeaders(jwt) });
+        if (!res.ok)
+            throw new SuggestError(404, `The GitHub App is not installed on ${full}. Install it on the repo, then try again.`);
+        const inst = (await res.json());
+        return (await auth({ type: 'installation', installationId: inst.id })).token;
+    }
+    return setting('GITHUB_TOKEN') || undefined;
+}
+function client(token) {
+    const headers = token ? ghHeaders(token) : { Accept: 'application/vnd.github+json', 'User-Agent': 'localdost' };
+    return {
+        async get(p) {
+            const res = await fetchT(`${apiBase()}${p}`, { headers });
+            if (!res.ok)
+                return { status: res.status };
+            try {
+                return { status: res.status, body: (await res.json()) };
+            }
+            catch {
+                return { status: res.status };
+            }
+        },
+        async raw(p) {
+            const res = await fetchT(`${apiBase()}${p}`, { headers: { ...headers, Accept: 'application/vnd.github.raw+json' } });
+            return res.ok ? await res.text() : undefined;
+        },
+    };
+}
+function repoChoice(r) {
+    const full = typeof r.full_name === 'string' ? r.full_name : '';
+    const [owner, name] = full.split('/');
+    if (!owner || !name)
+        return undefined;
+    const out = { fullName: full, owner, name, private: !!r.private };
+    if (typeof r.default_branch === 'string')
+        out.defaultBranch = r.default_branch;
+    if (typeof r.language === 'string' && r.language)
+        out.language = r.language;
+    if (typeof r.pushed_at === 'string')
+        out.pushedAt = r.pushed_at;
+    if (typeof r.description === 'string' && r.description)
+        out.description = r.description.slice(0, 200);
+    return out;
+}
+/** Repos the connection can see, most recently pushed first. `q` filters by owner/name. */
+export async function listRepos(q = '') {
+    if (!githubConnected())
+        return { connected: false, repos: [] };
+    const needle = q.trim().toLowerCase();
+    const seen = new Map();
+    const add = (r) => {
+        const c = repoChoice(r);
+        if (c && !seen.has(c.fullName.toLowerCase()))
+            seen.set(c.fullName.toLowerCase(), c);
+    };
+    try {
+        const id = setting('GITHUB_APP_ID');
+        const key = setting('GITHUB_PRIVATE_KEY');
+        if (id && key) {
+            const auth = await appAuth(id, key);
+            const jwt = (await auth({ type: 'app' })).token;
+            const inst = await client(jwt).get('/app/installations?per_page=100');
+            for (const i of inst.body ?? []) {
+                const tok = (await auth({ type: 'installation', installationId: i.id })).token;
+                const res = await client(tok).get('/installation/repositories?per_page=100');
+                for (const r of res.body?.repositories ?? [])
+                    add(r);
+            }
+        }
+        else {
+            const gh = client(setting('GITHUB_TOKEN'));
+            for (let page = 1; page <= 3; page++) {
+                const res = await gh.get(`/user/repos?per_page=100&sort=pushed&page=${page}`);
+                if (!res.body) {
+                    if (page === 1)
+                        return { connected: true, repos: [], error: `GitHub answered HTTP ${res.status} for the repo list.` };
+                    break;
+                }
+                for (const r of res.body)
+                    add(r);
+                if (res.body.length < 100)
+                    break;
+            }
+        }
+        // A repo the list does not hold, typed in full: look it up directly (public repos, other orgs).
+        if (repoPath(needle) && ![...seen.keys()].includes(needle)) {
+            const tok = await tokenFor(needle).catch(() => setting('GITHUB_TOKEN'));
+            const one = await client(tok).get(`/repos/${repoPath(needle)}`);
+            if (one.body)
+                add(one.body);
+        }
+    }
+    catch (err) {
+        return { connected: true, repos: [], error: err instanceof Error ? err.message : String(err) };
+    }
+    const repos = [...seen.values()]
+        .filter((r) => !needle || r.fullName.toLowerCase().includes(needle))
+        .sort((a, b) => (b.pushedAt ?? '').localeCompare(a.pushedAt ?? ''))
+        .slice(0, 50);
+    return { connected: true, repos };
+}
+/** The package manager of the project in `dir` (a folder of the repo, or the root): its lockfile, else the root's. */
+function packageManager(paths, dir) {
+    for (const base of dir ? [dir, ''] : ['']) {
+        const has = (f) => paths.has(base ? `${base}/${f}` : f);
+        if (has('pnpm-lock.yaml'))
+            return { pm: 'pnpm', lockfile: 'pnpm-lock.yaml' };
+        if (has('yarn.lock'))
+            return { pm: 'yarn', lockfile: 'yarn.lock' };
+        if (has('bun.lock'))
+            return { pm: 'bun', lockfile: 'bun.lock' };
+        if (has('bun.lockb'))
+            return { pm: 'bun', lockfile: 'bun.lockb' };
+        if (has('package-lock.json'))
+            return { pm: 'npm', lockfile: 'package-lock.json' };
+        if (has('npm-shrinkwrap.json'))
+            return { pm: 'npm', lockfile: 'npm-shrinkwrap.json' };
+    }
+    return { pm: 'npm' };
+}
+const INSTALL = {
+    npm: (l) => (l ? 'npm ci' : 'npm install'),
+    pnpm: (l) => `corepack enable && pnpm install${l ? ' --frozen-lockfile' : ''}`,
+    yarn: (l) => `corepack enable && yarn install${l ? ' --frozen-lockfile' : ''}`,
+    bun: (l) => `bun install${l ? ' --frozen-lockfile' : ''}`,
+};
+const EXEC = { npm: 'npx', pnpm: 'pnpm exec', yarn: 'yarn', bun: 'bunx' };
+const RUN = { npm: 'npm run', pnpm: 'pnpm run', yarn: 'yarn', bun: 'bun run' };
+const unquote = (v) => v
+    .replace(/\s+#.*$/, '')
+    .trim()
+    .replace(/^(['"])(.*)\1$/, '$2');
+const CD_LINE = /^cd\s+(?:"([^"]*)"|'([^']*)'|([^\s;&|<>()"']+))\s*(?:&&\s*([\s\S]*))?$/;
+/**
+ * A `cd` inside a run block sets the folder of the lines after it (KAT-134), as in the shell the
+ * block runs in. `cd web` alone is dropped; `cd web && npm ci` keeps `npm ci`. `cd` with no folder,
+ * `cd -`, and a cd inside a subshell are left as plain lines.
+ */
+function addRuns(step, lines) {
+    for (let line of lines) {
+        for (;;) {
+            const m = CD_LINE.exec(line);
+            if (!m || (m[3] ?? m[1] ?? m[2]) === '-')
+                break;
+            step.cd = foldCd(step.cd, m[1] ?? m[2] ?? m[3] ?? '');
+            line = (m[4] ?? '').trim();
+            if (!line)
+                break;
+        }
+        if (line)
+            step.runs.push({ run: line, ...(step.cd ? { cd: step.cd } : {}) });
+    }
+}
+/** `dir` with a cd target applied. An absolute target replaces it; `..` and variables stay visible so checkoutDir can refuse them. */
+function foldCd(dir, target) {
+    if (target.startsWith('/') || /^[$~`]/.test(target) || target.includes('${{'))
+        return target;
+    return path.posix.join(dir ?? '', target) || '.';
+}
+/**
+ * `run:` steps per job, in order, each with the working-directory it runs in. A small reader for the
+ * shapes GitHub workflows use; no YAML dependency. A step's own `working-directory` wins over the
+ * job's `defaults.run.working-directory`, which wins over the workflow's.
+ */
+export function workflowJobs(src) {
+    const lines = src.replace(/\r/g, '').split('\n');
+    const jobs = [];
+    let workflowDir;
+    let section = 'other';
+    let jobIndent = -1;
+    let cur;
+    // Steps of the current job.
+    let inSteps = false;
+    let stepsIndent = -1;
+    let dashIndent = -1;
+    let keyIndent = -1;
+    let step;
+    let jobDefaults = false;
+    const endStep = () => {
+        if (step && cur)
+            for (const r of step.runs)
+                cur.steps.push({ run: r.run, ...(step.dir ? { dir: step.dir } : {}), ...(r.cd ? { cd: r.cd } : {}) });
+        step = undefined;
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const text = line.trim();
+        if (!text || text.startsWith('#'))
+            continue;
+        const indent = line.length - line.trimStart().length;
+        if (indent === 0) {
+            endStep();
+            inSteps = false;
+            section = /^jobs:\s*$/.test(line) ? 'jobs' : /^defaults:\s*$/.test(line) ? 'defaults' : 'other';
+            continue;
+        }
+        if (section === 'defaults') {
+            const wd = /^working-directory:\s*(.+)$/.exec(text);
+            if (wd)
+                workflowDir = unquote(wd[1]);
+            continue;
+        }
+        if (section !== 'jobs')
+            continue;
+        if (inSteps && indent <= stepsIndent && !text.startsWith('-')) {
+            endStep();
+            inSteps = false;
+        }
+        const jobHead = /^([A-Za-z0-9_-]+):\s*$/.exec(text);
+        if (!inSteps && jobHead && (jobIndent < 0 || indent === jobIndent)) {
+            endStep();
+            jobIndent = indent;
+            cur = { job: jobHead[1], steps: [] };
+            jobs.push(cur);
+            jobDefaults = false;
+            continue;
+        }
+        if (!cur)
+            continue;
+        if (!inSteps) {
+            if (/^steps:\s*$/.test(text)) {
+                inSteps = true;
+                stepsIndent = indent;
+                dashIndent = -1;
+            }
+            else if (/^defaults:\s*$/.test(text))
+                jobDefaults = true;
+            else if (jobDefaults) {
+                const wd = /^working-directory:\s*(.+)$/.exec(text);
+                if (wd)
+                    cur.defaultDir = unquote(wd[1]);
+            }
+            continue;
+        }
+        // Inside steps: find the key this line sets, at the step's own key indent.
+        let key = text;
+        let at = indent;
+        const dash = /^-\s+/.exec(text);
+        if (dash && (dashIndent < 0 || indent === dashIndent)) {
+            endStep();
+            dashIndent = indent;
+            step = { runs: [] };
+            key = text.slice(dash[0].length);
+            at = indent + dash[0].length;
+            keyIndent = at;
+        }
+        else if (!step)
+            continue;
+        if (at !== keyIndent)
+            continue;
+        const wd = /^working-directory:\s*(.+)$/.exec(key);
+        if (wd) {
+            step.dir = unquote(wd[1]);
+            continue;
+        }
+        const run = /^run:\s*(.*)$/.exec(key);
+        if (!run)
+            continue;
+        const rest = run[1].trim();
+        if (rest === '|' || rest === '>' || rest === '|-' || rest === '>-') {
+            const block = [];
+            let j = i + 1;
+            let blockIndent = -1;
+            for (; j < lines.length; j++) {
+                const l = lines[j];
+                if (!l.trim())
+                    continue;
+                const ind = l.length - l.trimStart().length;
+                if (blockIndent < 0)
+                    blockIndent = ind;
+                if (ind < blockIndent || ind <= keyIndent)
+                    break;
+                block.push(l.trim());
+            }
+            i = j - 1;
+            const joined = rest.startsWith('>') ? [block.join(' ')] : block;
+            addRuns(step, joined.filter((x) => x && !x.startsWith('#')));
+        }
+        else if (rest) {
+            addRuns(step, [rest.replace(/^(['"])(.*)\1$/, '$2')]);
+        }
+    }
+    endStep();
+    return jobs.map((j) => ({
+        job: j.job,
+        steps: j.steps.map((st) => {
+            const base = st.dir ?? j.defaultDir ?? workflowDir;
+            const dir = st.cd ? foldCd(base, st.cd) : base;
+            return { run: st.run, ...(dir ? { workingDirectory: dir } : {}) };
+        }),
+    }));
+}
+/** `run:` steps per job, in order, without their working directories. */
+export function workflowRunSteps(src) {
+    return workflowJobs(src).map((j) => ({ job: j.job, steps: j.steps.map((st) => st.run) }));
+}
+/**
+ * A working-directory from a workflow as a clean path inside the checkout: `./web/` becomes `web`.
+ * Undefined for the root, or when the value cannot be used (an expression, an absolute path, `..`).
+ */
+export function checkoutDir(dir, notes) {
+    if (!dir)
+        return undefined;
+    const d = path.posix.normalize(dir.trim()).replace(/\/+$/, '');
+    if (!d || d === '.')
+        return undefined;
+    if (/[$`~]/.test(d) || workingDirectoryError(d)) {
+        notes?.push(`Ignored the CI working-directory "${dir}": it is not a plain folder inside the repo. Set Working directory if the tests live in a subfolder.`);
+        return undefined;
+    }
+    return d;
+}
+const ENV_PREFIX = /^((?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S*)\s+)*)([\s\S]*)$/;
+/**
+ * A package.json script that runs Playwright as a test command: leading `VAR=value` words stay in
+ * front, and the package manager's exec prefix goes between them and the program, so
+ * `CI=1 playwright test` becomes `CI=1 npx playwright test`, never `npx CI=1 playwright test`.
+ */
+export function scriptAsCommand(value, pm) {
+    const [, env = '', rest = ''] = ENV_PREFIX.exec(value.trim()) ?? [];
+    const exec = EXEC[pm];
+    const prog = rest.startsWith('npx ') || rest.startsWith(`${exec} `) ? rest : `${exec} ${rest}`;
+    return `${env}${prog}`;
+}
+/**
+ * A test command for a package.json script whose body runs Playwright. The runner appends its
+ * options (--reporter=json, --output, --config) to the end of the command (src/runner/command.ts
+ * `forwardingArgv` adds the `--` npm needs), so they must reach Playwright from there:
+ * - the script is one Playwright command: that command, run through the package manager's exec;
+ * - Playwright is the last step of `a && playwright test`: `npm run <script>`, which keeps the
+ *   earlier steps and passes the options on to the last one;
+ * - Playwright is an earlier step (`playwright test && node report.js`): that step alone, since
+ *   appended options would reach the last one. The other steps are named in `notes`.
+ * Null when no step of the script runs Playwright.
+ */
+export function scriptTestCommand(name, body, pm, notes, scripts = {}) {
+    const tail = playwrightTail(body);
+    const hooks = scriptHooks(scripts, name);
+    if (hooks.length) {
+        // npm runs pre<name> and post<name> only for `<pm> run <name>`, so unwrapping the script would skip
+        // them (fixtures created in a pretest hook). Keep the call, which the runner forwards its options
+        // through when the script's last command is Playwright.
+        if (tail)
+            return `${RUN[pm]} ${name}`;
+        addNote(notes, `The package.json script "${name}" has ${hooks.join(' and ')}, so it must run through ${pm}. Its last command is not Playwright, so the runner's options cannot reach the tests. Type the test command.`);
+        return null;
+    }
+    if (tail) {
+        if (!tail.pre.length) {
+            const direct = scriptAsCommand(tail.last, pm);
+            if (parseCommand(direct).ok)
+                return direct;
+        }
+        return `${RUN[pm]} ${name}`;
+    }
+    const steps = splitSetupSteps(body);
+    const at = steps.findIndex((x) => /\bplaywright\s+test\b/.test(x));
+    if (at < 0)
+        return null;
+    const direct = scriptAsCommand(steps[at], pm);
+    if (!parseCommand(direct).ok)
+        return null;
+    const others = steps.filter((_, i) => i !== at).join(' && ');
+    addNote(notes, `The package.json script "${name}" runs "${others}" next to Playwright. Options can only reach the last step of a script, so the test command runs just the Playwright step. Add the other steps to Setup steps if the tests need them.`);
+    return direct;
+}
+/** The lifecycle hooks (`pre<name>`, `post<name>`) a script has in `scripts`. */
+export function scriptHooks(scripts, name) {
+    return [`pre${name}`, `post${name}`].filter((h) => Object.hasOwn(scripts, h));
+}
+const addNote = (notes, note) => {
+    if (notes && !notes.includes(note))
+        notes.push(note);
+};
+/**
+ * True when a CI step runs tests: the step is `playwright test`, or it calls a package.json script whose
+ * body does. This is the one classifier for what may become the test command. Matching a script name
+ * as text inside the step ("e2e" in `npm run e2e:install`, "playwright" in `npx playwright install`)
+ * would pick an install step, which produces no test results (KAT-156).
+ */
+export function stepRunsTests(step, scripts) {
+    const parsed = parseCommand(step);
+    if (!parsed.ok)
+        return PLAYWRIGHT_TEST.test(step);
+    const call = scriptRun(parsed.argv, scripts);
+    return call ? PLAYWRIGHT_TEST.test(scripts[call.name] ?? '') : PLAYWRIGHT_TEST.test(parsed.argv.join(' '));
+}
+/**
+ * The test command for a CI step that runs Playwright. A step that calls a package.json script
+ * (`npm run test:e2e`) is resolved through scriptTestCommand, so the runner's options reach
+ * Playwright; the step's variables and extra arguments (`-- --project=chromium`) are kept. Any
+ * other step is the command itself. Null when the step cannot be a test command.
+ */
+function ciTestCommand(step, scripts, notes) {
+    const parsed = parseCommand(step);
+    if (!parsed.ok || !stepRunsTests(step, scripts))
+        return null;
+    const call = scriptRun(parsed.argv, scripts);
+    if (!call)
+        return step;
+    const resolved = scriptTestCommand(call.name, scripts[call.name], call.pm, notes, scripts);
+    if (!resolved)
+        return null;
+    const env = Object.entries(parsed.env)
+        .map(([k, v]) => `${k}=${shQuote(v)} `)
+        .join('');
+    if (!call.extra.length)
+        return `${env}${resolved}`;
+    const viaRun = resolved.endsWith(` ${RUN[call.pm]} ${call.name}`) || resolved === `${RUN[call.pm]} ${call.name}`;
+    return `${env}${resolved}${viaRun && call.pm === 'npm' ? ' --' : ''} ${call.extra.map(shQuote).join(' ')}`;
+}
+function browsersFromConfig(src) {
+    if (!src)
+        return ['chromium'];
+    const out = new Set();
+    if (/Desktop Chrome|chromium|Pixel|Galaxy/i.test(src))
+        out.add('chromium');
+    if (/firefox/i.test(src))
+        out.add('firefox');
+    if (/webkit|Safari|iPhone|iPad/i.test(src))
+        out.add('webkit');
+    return out.size ? [...out] : ['chromium'];
+}
+/** Setup steps, test command, and smoke grep from the files of the default branch. */
+export function guessRunner(files) {
+    const paths = new Set(files.paths);
+    const notes = [];
+    // The one place a package.json, its scripts, and its Playwright config are read: relative to the
+    // folder the tests run in (the CI job's working-directory, KAT-146), else the repo root.
+    const projects = new Map();
+    const projectAt = (dir) => {
+        const known = projects.get(dir ?? '');
+        if (known)
+            return known;
+        const rel = (f) => (dir ? `${dir}/${f}` : f);
+        const pkgPath = rel('package.json');
+        const pkgText = files.text[pkgPath];
+        let pkg = {};
+        let pkgInvalid = false;
+        if (pkgText) {
+            try {
+                const parsed = JSON.parse(pkgText);
+                if (parsed && typeof parsed === 'object')
+                    pkg = parsed;
+            }
+            catch {
+                pkgInvalid = true;
+            }
+        }
+        const configPath = dir
+            ? PW_CONFIGS.map(rel).find((f) => paths.has(f))
+            : (PW_CONFIGS.find((f) => paths.has(f)) ??
+                files.paths.find((p) => PW_CONFIGS.some((f) => p.endsWith(`/${f}`)) && p.split('/').length <= 3 && !p.includes('node_modules')));
+        const project = {
+            ...(dir ? { dir } : {}),
+            pkgPath,
+            ...(pkgText ? { pkgText } : {}),
+            pkgInvalid,
+            scripts: pkg.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {},
+            deps: { ...pkg.dependencies, ...pkg.devDependencies },
+            ...(configPath ? { configPath, config: files.text[configPath] } : {}),
+        };
+        projects.set(dir ?? '', project);
+        return project;
+    };
+    // Test command: a CI step that runs Playwright, else a package.json script, else the default.
+    let command = null;
+    let commandSource = '';
+    let setup = null;
+    let setupSource = '';
+    let workingDirectory;
+    const workflows = files.paths.filter((p) => /^\.github\/workflows\/[^/]+\.ya?ml$/.test(p)).sort();
+    for (const wf of workflows) {
+        const src = files.text[wf];
+        if (!src)
+            continue;
+        for (const job of workflowJobs(src)) {
+            const idx = job.steps.findIndex((s) => stepRunsTests(s.run, projectAt(checkoutDir(s.workingDirectory)).scripts));
+            if (idx < 0)
+                continue;
+            const step = job.steps[idx].run;
+            // The tests run in the folder the CI step ran in. Earlier steps from another folder keep their own via a subshell.
+            const testDir = checkoutDir(job.steps[idx].workingDirectory, notes);
+            if (testDir)
+                workingDirectory = testDir;
+            const name = wf.split('/').pop();
+            const ci = step.includes('${{') ? null : ciTestCommand(step, projectAt(testDir).scripts, notes);
+            if (ci) {
+                command = ci;
+                commandSource = `CI workflow ${name}, job ${job.job}`;
+            }
+            const ciPm = packageManager(paths, testDir).pm;
+            const before = job.steps
+                .slice(0, idx)
+                .filter((s) => !s.run.includes('${{'))
+                .map((s) => {
+                const text = s.run.replace(/\s+--with-deps\b/, '');
+                const dir = checkoutDir(s.workingDirectory, notes);
+                if (dir === testDir)
+                    return text;
+                const rel = path.posix.relative(testDir ?? '.', dir ?? '.') || '.';
+                return `(cd ${shQuote(rel)} && ${text})`;
+            });
+            if (before.length) {
+                // `actions/setup-*` and Corepack steps do not run here, so pnpm and yarn need the bootstrap the
+                // lockfile path adds, unless a run step already does it.
+                const needsCorepack = (ciPm === 'pnpm' || ciPm === 'yarn') &&
+                    before.some((s) => new RegExp(`\\b${ciPm}\\b`).test(s)) &&
+                    !before.some((s) => /\bcorepack\s+(enable|prepare)\b|\b(npm|npx)\b.*\s(-g|--global)\b.*\b(pnpm|yarn)\b/.test(s));
+                setup = (needsCorepack ? ['corepack enable', ...before] : before).join('\n');
+                setupSource = `CI workflow ${name}, job ${job.job}`;
+                if (job.steps.slice(0, idx).some((s) => /--with-deps/.test(s.run)))
+                    notes.push('Dropped --with-deps from the browser install: it needs root on this machine.');
+            }
+            break;
+        }
+        if (command || setup)
+            break;
+    }
+    // Everything below reads the project the tests run in.
+    const proj = projectAt(workingDirectory);
+    const { pm, lockfile } = packageManager(paths, workingDirectory);
+    if (proj.pkgInvalid)
+        notes.push(`${proj.pkgPath} is not valid JSON.`);
+    const { scripts, pkgText, configPath, config } = proj;
+    const hasPlaywright = !!proj.deps['@playwright/test'] || !!proj.deps.playwright || !!configPath || (!!workingDirectory && !!projectAt().deps['@playwright/test']);
+    const webServer = !!config && /webServer\s*:/.test(config);
+    const configUrl = config ? baseUrlFromConfig(config).url : undefined;
+    // A config below the root is found from the root; inside the working directory it is found by name.
+    const configArg = configPath && !workingDirectory && !PW_CONFIGS.includes(configPath) ? ` --config ${configPath}` : '';
+    if (!command) {
+        const order = ['test:e2e', 'e2e', 'test:playwright', 'playwright', 'test'];
+        const names = [...order.filter((n) => scripts[n]), ...Object.keys(scripts).filter((n) => !order.includes(n))];
+        const script = names.find((n) => /playwright\s+test/.test(scripts[n]));
+        if (script) {
+            command = scriptTestCommand(script, scripts[script], pm, notes, scripts);
+            // A script with hooks that cannot take the options stays empty (the note says why); any other
+            // script that cannot be unwrapped runs through the package manager.
+            if (!command && !scriptHooks(scripts, script).length)
+                command = `${RUN[pm]} ${script}`;
+            if (command)
+                commandSource = `package.json script "${script}"${command === `${RUN[pm]} ${script}` ? `, run through ${pm}` : ''}`;
+        }
+        else if (hasPlaywright) {
+            command = `${EXEC[pm]} playwright test${configArg}`;
+            commandSource = configPath ? `Playwright config ${configPath}` : 'the @playwright/test dependency';
+        }
+        else {
+            commandSource = 'No Playwright config or dependency found. Add one, or type the test command.';
+        }
+    }
+    if (!setup && pkgText) {
+        const steps = [INSTALL[pm](!!lockfile)];
+        const why = [lockfile ?? `${proj.pkgPath} without a lockfile`];
+        if (hasPlaywright) {
+            steps.push(`${EXEC[pm]} playwright install ${browsersFromConfig(config).join(' ')}`);
+            why.push('Playwright browsers');
+        }
+        if (scripts.build) {
+            steps.push(`${RUN[pm]} build`);
+            why.push('build script');
+        }
+        setup = steps.join('\n');
+        setupSource = why.join(', ');
+    }
+    if (!setup)
+        setupSource = `No ${proj.pkgPath === 'package.json' ? 'package.json at the repo root' : proj.pkgPath}. Add install steps if the tests need them.`;
+    let smokeGrep = null;
+    let smokeSource = 'No @smoke tag found. Every run tests the whole suite.';
+    for (const p of files.paths.filter((x) => /smoke/i.test(x) && /\.(spec|test)\.[cm]?[jt]sx?$/.test(x))) {
+        if (files.text[p]?.includes('@smoke')) {
+            smokeGrep = '@smoke';
+            smokeSource = `@smoke tag in ${p}`;
+            break;
+        }
+    }
+    const out = { setup, setupSource, command, commandSource, smokeGrep, smokeSource, webServer, notes };
+    if (workingDirectory)
+        out.workingDirectory = workingDirectory;
+    if (configPath)
+        out.configPath = configPath;
+    if (configUrl)
+        out.configUrl = configUrl;
+    return out;
+}
+/** Fills a role preset's brief with the repo: "a release" becomes "a release of acme/shop". */
+export function fillPreset(preset, repo) {
+    const full = `${repo.owner}/${repo.name}`;
+    const fill = (s) => s
+        ?.replace(/\bthe default branch\b/g, repo.defaultBranch)
+        .replace(/\ba release\b/g, `a release of ${full}`)
+        .replace(/^A merge\b/, `A merge to ${full}`)
+        .replace(/\bMain stays releasable\b/, `${full} ${repo.defaultBranch} stays releasable`);
+    const d = preset.defaults;
+    const out = { ...d };
+    for (const k of ['mission', 'notifyWhen', 'mustNot'])
+        if (d[k] !== undefined)
+            out[k] = fill(d[k]);
+    return out;
+}
+const isLocal = (u) => /^https?:\/\/(localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])(:|\/|$)/i.test(u);
+/** The base URL: the app the checkout starts, a staging or production deployment, the homepage, or the config URL. */
+export function guessBaseUrl(input) {
+    const notes = [];
+    const withUrl = input.deployments.filter((d) => d.url && /^https?:\/\//.test(d.url));
+    const previews = input.deployments.filter((d) => /preview|pr[-_ ]?\d+|review/i.test(d.environment));
+    if (previews.length)
+        notes.push('This repo deploys previews. Pull request runs use the preview URL of each PR.');
+    const pick = withUrl.find((d) => /stag|qa|test|uat/i.test(d.environment)) ??
+        withUrl.find((d) => /prod|live/i.test(d.environment)) ??
+        withUrl.find((d) => !/preview|pr[-_ ]?\d+|review/i.test(d.environment));
+    const cfg = input.runner.configPath;
+    if (input.runner.webServer && (!input.runner.configUrl || isLocal(input.runner.configUrl))) {
+        const other = pick?.url ?? input.homepage;
+        if (other)
+            notes.push(`Found ${other}. Set it as the base URL to test the deployed app instead.`);
+        return { value: null, source: `Not needed: ${cfg} starts the app from the checkout`, notes };
+    }
+    if (pick)
+        return { value: pick.url, source: `GitHub deployment to ${pick.environment}`, notes };
+    if (input.homepage && /^https?:\/\//.test(input.homepage))
+        return { value: input.homepage, source: 'Repo homepage on GitHub', notes };
+    if (input.runner.configUrl && !isLocal(input.runner.configUrl))
+        return { value: input.runner.configUrl, source: `baseURL in ${cfg}`, notes };
+    if (input.runner.configUrl)
+        return { value: input.runner.configUrl, source: `baseURL in ${cfg}. Start the app before the tests, or set a deployed URL.`, notes };
+    return { value: null, source: 'No deployment, homepage, or Playwright baseURL found', notes };
+}
+// Tracker choices from Setup
+async function trackerChoices(repoName, notes, issues) {
+    const { providerOptions, readiness } = await import('../connect/registry.js');
+    const choices = [];
+    let pick;
+    let source = 'No tracker is connected in Setup';
+    const near = (a, b) => {
+        const x = a.toLowerCase().replace(/[^a-z0-9]/g, '');
+        const y = b.toLowerCase().replace(/[^a-z0-9]/g, '');
+        return !!x && !!y && (x.includes(y) || y.includes(x));
+    };
+    const repo = repoName.toLowerCase();
+    if ((await readiness('linear')).state === 'ready') {
+        try {
+            const teams = await providerOptions('linear', 'teams', {});
+            const saved = getMeta('linear').settings?.teamId;
+            const mine = teams
+                .filter((t) => t.hint)
+                .map((t) => ({ kind: 'linear', label: `Linear team ${t.label} (${t.hint})`, tracker: { kind: 'linear', teamKeys: [t.hint] } }));
+            choices.push(...mine);
+            const savedIdx = teams.findIndex((t) => t.value === saved);
+            const nearIdx = teams.findIndex((t) => near(t.label, repo) || near(t.hint ?? '', repo));
+            if (savedIdx >= 0) {
+                pick = mine[savedIdx];
+                source = 'Linear team chosen in Setup';
+            }
+            else if (nearIdx >= 0) {
+                pick = mine[nearIdx];
+                source = 'Linear team whose name matches the repo';
+            }
+            else if (mine.length) {
+                pick = mine[0];
+                source = mine.length === 1 ? 'The only Linear team' : `First of ${mine.length} Linear teams. Pick another if it is wrong.`;
+            }
+        }
+        catch (err) {
+            notes.push(`Could not list Linear teams: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if ((await readiness('jira')).state === 'ready') {
+        try {
+            const base = setting('JIRA_BASE_URL').replace(/\/$/, '');
+            const projects = await providerOptions('jira', 'projects', {});
+            const saved = getMeta('jira').settings?.projectKey;
+            const mine = projects.map((p) => ({
+                kind: 'jira',
+                label: `Jira project ${p.label} (${p.value})`,
+                tracker: { kind: 'jira', baseUrl: base, projectKeys: [p.value] },
+            }));
+            choices.push(...mine);
+            const savedIdx = projects.findIndex((p) => p.value === saved);
+            const nearIdx = projects.findIndex((p) => near(p.label, repo) || near(p.value, repo));
+            if (!pick || savedIdx >= 0) {
+                if (savedIdx >= 0) {
+                    pick = mine[savedIdx];
+                    source = 'Jira project chosen in Setup';
+                }
+                else if (nearIdx >= 0) {
+                    pick = mine[nearIdx];
+                    source = 'Jira project whose name matches the repo';
+                }
+                else if (mine.length) {
+                    pick = mine[0];
+                    source = mine.length === 1 ? 'The only Jira project' : `First of ${mine.length} Jira projects. Pick another if it is wrong.`;
+                }
+            }
+        }
+        catch (err) {
+            notes.push(`Could not list Jira projects: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // GitHub Issues of the repo (KAT-87): always a choice when the repo has issues, the default when no other tracker is connected.
+    if (issues) {
+        const gi = { kind: 'github', label: `GitHub Issues in ${issues.full}`, tracker: { kind: 'github', repos: [issues.full] } };
+        choices.push(gi);
+        if (!pick) {
+            pick = gi;
+            source = 'GitHub Issues of the repo. No other tracker is connected in Setup';
+        }
+    }
+    return { choices, ...(pick ? { pick } : {}), source };
+}
+// The suggestion
+const MAX_OPTIONAL_READS = 20;
+const isPwConfig = (p) => PW_CONFIGS.some((f) => p === f || p.endsWith(`/${f}`)) && p.split('/').length <= 3 && !p.includes('node_modules');
+const isWorkflow = (p) => /^\.github\/workflows\/[^/]+\.ya?ml$/.test(p);
+const isSmokeSpec = (p) => /smoke/i.test(p) && /\.(spec|test)\.[cm]?[jt]sx?$/.test(p) && !p.includes('node_modules');
+/**
+ * The files to read from the repo. `package.json` and the Playwright configs come first and are never
+ * dropped by the cap: setup steps and the test command depend on them. Workflows (in the order
+ * `guessRunner` reads them) and smoke specs share what is left of the cap, which keeps the number of
+ * GitHub calls bounded on repos with many of either.
+ */
+export function filesToRead(paths) {
+    const required = [...paths.filter((p) => p === 'package.json'), ...paths.filter(isPwConfig)];
+    const optional = [...paths.filter(isWorkflow).sort(), ...paths.filter(isSmokeSpec)];
+    return [...required, ...optional.slice(0, Math.max(0, MAX_OPTIONAL_READS - required.length))];
+}
+const MAX_NESTED_PACKAGES = 5;
+/**
+ * The package.json files of the folders the CI workflows run in (`working-directory`, `defaults.run`,
+ * `cd`), for a monorepo whose root package.json holds no scripts (KAT-146). They can only be named
+ * once the workflows are read, so suggestDot reads them in a second round.
+ */
+export function nestedPackageFiles(paths, text) {
+    const have = new Set(paths);
+    const out = new Set();
+    for (const wf of paths.filter(isWorkflow).sort()) {
+        const src = text[wf];
+        if (!src)
+            continue;
+        for (const job of workflowJobs(src))
+            for (const st of job.steps) {
+                const dir = checkoutDir(st.workingDirectory);
+                if (dir && have.has(`${dir}/package.json`) && text[`${dir}/package.json`] === undefined)
+                    out.add(`${dir}/package.json`);
+            }
+    }
+    return [...out].slice(0, MAX_NESTED_PACKAGES);
+}
+/**
+ * The runner of a new dot with every field checked on its own against validateRunner, so one bad
+ * field is left out with a note instead of making POST /api/dots refuse the whole suggestion.
+ */
+export function acceptedRunner(candidate, notes) {
+    const out = { mode: candidate.mode };
+    for (const [key, value] of Object.entries(candidate)) {
+        if (key === 'mode')
+            continue;
+        const bad = validateRunner({ mode: candidate.mode, [key]: value });
+        if (bad)
+            notes.push(`The detected ${RUNNER_FIELD_LABEL[key] ?? key} was left out: ${bad}`);
+        else
+            out[key] = value;
+    }
+    return out;
+}
+const RUNNER_FIELD_LABEL = { setup: 'setup steps', command: 'test command', workingDirectory: 'working directory' };
+function uniqueName(base, owner) {
+    const taken = new Set(list('watches')
+        .filter((w) => !w.archived)
+        .map((w) => w.name.toLowerCase()));
+    if (!taken.has(base.toLowerCase()))
+        return base;
+    const withOwner = `${base} (${owner})`;
+    if (!taken.has(withOwner.toLowerCase()))
+        return withOwner;
+    for (let i = 2; i < 100; i++)
+        if (!taken.has(`${base} ${i}`.toLowerCase()))
+            return `${base} ${i}`;
+    return `${base} ${Date.now().toString(36)}`;
+}
+/**
+ * Demo mode with no GitHub: the sample shop as the repo, so the first-run flow can make a dot that
+ * runs the sample specs (KAT-257). Same shape as a real suggestion; the runner is the demo runner.
+ */
+export async function demoSuggestion() {
+    const [owner, name] = DEMO_REPO.split('/');
+    const repo = { fullName: DEMO_REPO, owner, name, private: false, defaultBranch: 'main', description: 'The sample shop that demo mode starts.' };
+    const base = `http://localhost:${config.sampleAppPort}`;
+    const jira = {
+        kind: 'jira',
+        label: 'Jira project SHOP (demo)',
+        tracker: { kind: 'jira', baseUrl: 'https://example.atlassian.net', projectKeys: ['SHOP'] },
+    };
+    const { readiness } = await import('../connect/registry.js');
+    const model = await readiness('model');
+    const preset = ROLE_PRESETS.find((p) => p.key === DEFAULT_ROLE);
+    const brief = fillPreset(preset, repo);
+    const presetSource = `${preset.label} role preset`;
+    const dotName = uniqueName(name, owner);
+    const input = {
+        ...brief,
+        name: dotName,
+        repo: { owner, name, defaultBranch: 'main' },
+        runner: { mode: 'demo' },
+        tracker: jira.tracker,
+        baseUrl: base,
+        probes: [{ url: `${base}/health` }],
+    };
+    return {
+        repo,
+        name: { value: dotName, source: dotName === name ? 'Repo name' : 'Repo name, made unique among your dots' },
+        tracker: { value: jira.tracker, source: 'The demo Jira project', choices: [jira] },
+        baseUrl: { value: base, source: 'The sample shop demo mode starts' },
+        setup: { value: null, source: 'Not needed: demo mode runs the sample shop specs' },
+        command: { value: null, source: 'Demo mode runs the sample shop specs' },
+        smokeGrep: { value: null, source: 'Not set' },
+        model: { value: model.detail, source: 'Setup. One model serves every dot.' },
+        aivision: { value: null, source: 'Off in demo mode' },
+        role: { value: preset.key, label: preset.label, source: 'Default role for a new dot' },
+        mission: { value: brief.mission ?? null, source: presetSource },
+        notifyWhen: { value: brief.notifyWhen ?? null, source: presetSource },
+        mustNot: { value: brief.mustNot ?? null, source: presetSource },
+        input,
+        notes: ['Demo mode: the sample shop stands in for a GitHub repo, and comments go to the outbox.'],
+    };
+}
+export async function suggestDot(full) {
+    const rp = repoPath(full);
+    if (!rp)
+        throw new SuggestError(400, 'repo must look like owner/name.');
+    if (config.demo && !githubConnected() && full.toLowerCase() === DEMO_REPO)
+        return demoSuggestion();
+    if (!githubConnected())
+        throw new SuggestError(409, 'Connect GitHub in Setup first, so localdost can read the repo.');
+    const gh = client(await tokenFor(full));
+    const meta = await gh.get(`/repos/${rp}`);
+    if (!meta.body)
+        throw new SuggestError(meta.status === 404 ? 404 : 502, meta.status === 404 ? `GitHub has no repo ${full}, or this connection cannot see it.` : `GitHub answered HTTP ${meta.status} for ${full}.`);
+    const r = meta.body;
+    const choice = repoChoice(r);
+    const branch = choice.defaultBranch ?? 'main';
+    const repo = { ...choice, defaultBranch: branch };
+    const notes = [];
+    // Files: one tree read, then only the files the detectors use.
+    const tree = await gh.get(`/repos/${rp}/git/trees/${encodeURIComponent(branch)}?recursive=1`);
+    const paths = (tree.body?.tree ?? []).filter((t) => t.type === 'blob').map((t) => t.path);
+    if (!tree.body)
+        notes.push(`Could not read the file list (HTTP ${tree.status}). Setup steps and the test command use defaults.`);
+    const text = {};
+    await Promise.all(filesToRead(paths).map(async (p) => {
+        text[p] = await gh
+            .raw(`/repos/${rp}/contents/${p.split('/').map(encodeURIComponent).join('/')}?ref=${encodeURIComponent(branch)}`)
+            .catch(() => undefined);
+    }));
+    await Promise.all(nestedPackageFiles(paths, text).map(async (p) => {
+        text[p] = await gh
+            .raw(`/repos/${rp}/contents/${p.split('/').map(encodeURIComponent).join('/')}?ref=${encodeURIComponent(branch)}`)
+            .catch(() => undefined);
+    }));
+    const runner = guessRunner({ paths, text });
+    notes.push(...runner.notes);
+    // Deployments: the latest per environment, with the URL of its newest status.
+    const deployments = [];
+    const deps = await gh.get(`/repos/${rp}/deployments?per_page=30`);
+    const latest = new Map();
+    for (const d of deps.body ?? [])
+        if (!latest.has(d.environment))
+            latest.set(d.environment, d.id);
+    await Promise.all([...latest].slice(0, 6).map(async ([environment, id]) => {
+        const st = await gh.get(`/repos/${rp}/deployments/${Number(id)}/statuses?per_page=5`);
+        const url = (st.body ?? []).find((s) => s.state === 'success' && s.environment_url)?.environment_url;
+        deployments.push(url ? { environment, url } : { environment });
+    }));
+    if (!deps.body?.length) {
+        const envs = await gh.get(`/repos/${rp}/environments`);
+        for (const e of envs.body?.environments ?? [])
+            deployments.push({ environment: e.name });
+    }
+    const base = guessBaseUrl({ deployments, homepage: typeof r.homepage === 'string' && r.homepage ? r.homepage : undefined, runner });
+    notes.push(...base.notes);
+    const tracker = await trackerChoices(repo.name, notes, r.has_issues === false ? undefined : { full: choice.fullName });
+    const { readiness } = await import('../connect/registry.js');
+    const [model, aivision] = await Promise.all([readiness('model'), readiness('aivision')]);
+    const aiOn = aivision.state === 'ready';
+    const preset = ROLE_PRESETS.find((p) => p.key === DEFAULT_ROLE);
+    const brief = fillPreset(preset, repo);
+    const presetSource = `${preset.label} role preset`;
+    const name = uniqueName(repo.name, repo.owner);
+    const candidate = { mode: 'local' };
+    if (runner.setup)
+        candidate.setup = runner.setup;
+    if (runner.command)
+        candidate.command = runner.command;
+    if (runner.smokeGrep)
+        candidate.smokeGrep = runner.smokeGrep;
+    if (runner.workingDirectory)
+        candidate.workingDirectory = runner.workingDirectory;
+    if (aiOn)
+        candidate.aivision = { backend: 'server' };
+    const runnerInput = acceptedRunner(candidate, notes);
+    const input = {
+        ...brief,
+        name,
+        repo: { owner: repo.owner, name: repo.name, defaultBranch: branch },
+        runner: runnerInput,
+        ...(tracker.pick ? { tracker: tracker.pick.tracker } : {}),
+        ...(base.value ? { baseUrl: base.value } : {}),
+    };
+    return {
+        repo,
+        name: { value: name, source: name === repo.name ? 'Repo name' : 'Repo name, made unique among your dots' },
+        tracker: { value: tracker.pick?.tracker ?? null, source: tracker.source, choices: tracker.choices },
+        baseUrl: { value: base.value, source: base.source },
+        setup: runnerInput.setup
+            ? { value: runnerInput.setup, source: runner.setupSource }
+            : { value: null, source: runner.setup ? 'Left out: the detected steps are not valid for a dot' : runner.setupSource },
+        command: { value: runnerInput.command ?? null, source: runnerInput.command ? runner.commandSource : 'Default: npx playwright test' },
+        smokeGrep: { value: runner.smokeGrep, source: runner.smokeSource },
+        model: { value: model.detail, source: 'Setup. One model serves every dot.' },
+        aivision: {
+            value: aiOn ? { backend: 'server' } : null,
+            source: aiOn ? 'AI-Vision server connected in Setup' : 'Off. Connect AI-Vision in Setup to add natural-language cases.',
+        },
+        role: { value: preset.key, label: preset.label, source: 'Default role for a new dot' },
+        mission: { value: brief.mission ?? null, source: presetSource },
+        notifyWhen: { value: brief.notifyWhen ?? null, source: presetSource },
+        mustNot: { value: brief.mustNot ?? null, source: presetSource },
+        input,
+        notes,
+    };
+}
+export async function register(app) {
+    app.get('/api/dots/repos', async (req, reply) => {
+        reply.header('Cache-Control', 'no-store');
+        return listRepos(typeof req.query.q === 'string' ? req.query.q.slice(0, 200) : '');
+    });
+    app.get('/api/dots/suggest', async (req, reply) => {
+        reply.header('Cache-Control', 'no-store');
+        try {
+            return await suggestDot(String(req.query.repo ?? '').trim());
+        }
+        catch (err) {
+            if (err instanceof SuggestError)
+                return reply.code(err.status).send({ error: err.message });
+            const msg = err instanceof Error && err.name === 'TimeoutError' ? 'GitHub did not answer in time.' : err instanceof Error ? err.message : String(err);
+            return reply.code(502).send({ error: msg });
+        }
+    });
+}
+//# sourceMappingURL=dot-suggest.js.map