tinybeeai 0.0.0-stage → 0.16.1

package/dist/repos.js

@@ -0,0 +1,891 @@
+// Workspace repos and per-dot repo sets (docs/MULTI-REPO.md section 1).
+//
+// Every reader of a dot's repos goes through watchRepos() and repoForEvent(). A dot saved before
+// multi-repo support has only `repo`; watchRepos() turns it into one app entry, so old rows and
+// new rows read the same way. `repo` is kept filled from the first app repo on every save so an
+// older build that ignores `repos` still works (section 1.3, Rollback).
+import { get, insert, list, remove, update } from './db.js';
+import { MAX_DEPLOY_URL_MATCH, cleanDeployUrlMatch } from './target-url.js';
+import { getMeta, setMeta } from './connect/store.js';
+import { publish } from './events.js';
+import { MAX_DEPLOY_ENVIRONMENT, MAX_DEPLOY_WAIT_SEC, cleanDeployEnvironment, cleanDeploySec, cleanTestBranches, isBaseUrlEnvName, isSafeBranchName, parseCommand, passEnvError, workingDirectoryError, } from './runner/command.js';
+export const REPO_ROLES = ['app', 'test', 'docs'];
+const OWNER = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
+const NAME = /^[A-Za-z0-9._-]{1,100}$/;
+const BRANCH = /^(?!\/)(?!.*\.\.)(?!.*\/\/)[A-Za-z0-9._/-]{1,250}(?<!\/)(?<!\.lock)$/;
+/** The workspace id of a repo: "owner/name", lower case. */
+export function repoId(owner, name) {
+    return `${owner}/${name}`.toLowerCase();
+}
+/** Reads "owner/name" (also a github.com URL or a trailing .git). null when it is not a repo. */
+export function parseRepoId(v) {
+    if (typeof v !== 'string')
+        return null;
+    const s = v
+        .trim()
+        .replace(/^https?:\/\/(www\.)?github\.com\//i, '')
+        .replace(/\.git$/i, '')
+        .replace(/\/+$/, '');
+    const parts = s.split('/');
+    if (parts.length !== 2)
+        return null;
+    const [owner, name] = parts;
+    if (!OWNER.test(owner) || !NAME.test(name) || name === '.' || name === '..')
+        return null;
+    return { owner, name };
+}
+export function isBranchName(v) {
+    return typeof v === 'string' && BRANCH.test(v);
+}
+const lc = (s) => (s ?? '').toLowerCase();
+/** Workspace repo by id, or undefined. Lookup errors (no table in a bare test db) count as missing. */
+export function getWorkspaceRepo(id) {
+    try {
+        return get('repos', id.toLowerCase());
+    }
+    catch {
+        return undefined;
+    }
+}
+export function listWorkspaceRepos() {
+    return list('repos', undefined, { orderBy: 'id ASC' });
+}
+/**
+ * The dot's repos with defaults filled in. `repos` when set, else one app entry built from `repo`.
+ * A branch left unset reads the workspace repo's default branch, then "main".
+ * Entries whose id is not "owner/name" are skipped.
+ */
+export function watchRepos(w, lookup = getWorkspaceRepo) {
+    if (Array.isArray(w.repos) && w.repos.length) {
+        const out = [];
+        const seen = new Set();
+        for (const e of w.repos) {
+            const ref = parseRepoId(e?.repo);
+            if (!ref)
+                continue;
+            const id = repoId(ref.owner, ref.name);
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            const ws = lookup(id);
+            // Keep the owner and name casing GitHub uses when the workspace row has it.
+            const owner = ws?.owner ?? ref.owner;
+            const name = ws?.name ?? ref.name;
+            const role = REPO_ROLES.includes(e.role) ? e.role : 'app';
+            out.push({
+                id,
+                owner,
+                name,
+                role,
+                defaultBranch: e.defaultBranch || ws?.defaultBranch || 'main',
+                ...(e.pathFilters?.length ? { pathFilters: e.pathFilters } : {}),
+                ...(e.test ? { test: e.test } : {}),
+                ...(e.targets?.length ? { targets: e.targets.map((t) => t.toLowerCase()) } : {}),
+                ...(e.prScope && Object.keys(e.prScope).length ? { prScope: e.prScope } : {}),
+                ...(e.runTests === false && role === 'app' ? { runTests: false } : {}),
+                ...(role === 'app' ? deployOf(e) : {}),
+            });
+        }
+        return out;
+    }
+    const r = w.repo;
+    if (!r?.owner || !r.name)
+        return [];
+    return [
+        {
+            id: repoId(r.owner, r.name),
+            owner: r.owner,
+            name: r.name,
+            role: 'app',
+            defaultBranch: r.defaultBranch || 'main',
+            ...(r.pathFilters?.length ? { pathFilters: r.pathFilters } : {}),
+            ...(r.prScope && Object.keys(r.prScope).length ? { prScope: r.prScope } : {}),
+            ...(r.runTests === false ? { runTests: false } : {}),
+            ...deployOf(r),
+        },
+    ];
+}
+/** The deploy wait fields of a repo entry as a read keeps them: a name with text, seconds from 0 up. Unset fields are left out. */
+function deployOf(e) {
+    const environment = cleanDeployEnvironment(e.deployEnvironment);
+    const sec = e.waitForDeploySec;
+    const match = cleanDeployUrlMatch(e.deployUrlMatch);
+    return {
+        ...(environment ? { deployEnvironment: environment } : {}),
+        ...(typeof sec === 'number' && Number.isInteger(sec) && sec >= 0 ? { waitForDeploySec: sec } : {}),
+        ...(match ? { deployUrlMatch: match } : {}),
+    };
+}
+/** The dot's first app repo: the one `repo` mirrors and the default for work that names no repo. */
+export function primaryRepo(w, lookup) {
+    const all = watchRepos(w, lookup);
+    return all.find((r) => r.role === 'app') ?? null;
+}
+/** True when the dot holds at least one app repo, the code that reviews and test runs read. */
+export function hasAppRepo(w) {
+    return !!primaryRepo(w);
+}
+/** The dot's entry for this repo, or null. */
+export function findRepo(w, ref, lookup) {
+    if (!ref?.owner || !ref.name)
+        return null;
+    const id = repoId(ref.owner, ref.name);
+    return watchRepos(w, lookup).find((r) => r.id === id) ?? null;
+}
+/** The dot's entry whose repo is the event's repo, or null (no repo on the event, or not in the set). */
+export function repoForEvent(w, ev, lookup) {
+    return findRepo(w, ev?.repo, lookup);
+}
+/**
+ * The repo a piece of work acts on: the event's repo when the dot holds it, else the first app repo
+ * (the repo a single-repo dot always used). null when the dot holds no app repo and no event repo matches.
+ */
+export function targetRepo(w, ev, lookup) {
+    return repoForEvent(w, ev, lookup) ?? primaryRepo(w, lookup);
+}
+/**
+ * The repo of an event when the dot runs no tests for it (KAT-361): an app repo with `runTests: false`. null when the tests run,
+ * including for an event with no repo, which belongs to the first app repo and is judged by that repo's entry.
+ */
+export function testsOffRepo(w, ev, lookup) {
+    const r = targetRepo(w, ev, lookup);
+    return r && r.role === 'app' && r.runTests === false ? r : null;
+}
+/**
+ * The repo that keeps a bug apart from the same bug in another repo: "owner/name", lower case, only for a dot with
+ * more than one repo. A single-repo dot gets none, so its older bug keys and signatures still match (KAT-324).
+ */
+export function bugRepoOf(w, repo) {
+    if (!repo || watchRepos(w).length < 2)
+        return undefined;
+    return `${repo.owner}/${repo.name}`.toLowerCase();
+}
+/**
+ * The other repo parts a bug key and signature may have been made with, for a dot that gained or lost a repo (KAT-326).
+ * A dot with several repos made them without a repo part (null) while it had one repo. A dot with one repo may have made
+ * them with its only repo while it had several.
+ */
+export function bugRepoAlts(w, repo) {
+    const repos = watchRepos(w);
+    if (repos.length >= 2)
+        return repo ? [null] : [];
+    const only = repo ?? repos[0];
+    return only ? [`${only.owner}/${only.name}`.toLowerCase()] : [];
+}
+/** `Watch.repo` as an older build reads it: the first app repo, or null. */
+export function legacyRepo(repos) {
+    const a = repos.find((r) => r.role === 'app');
+    if (!a)
+        return null;
+    return {
+        owner: a.owner,
+        name: a.name,
+        defaultBranch: a.defaultBranch,
+        ...(a.pathFilters?.length ? { pathFilters: a.pathFilters } : {}),
+        ...(a.prScope ? { prScope: a.prScope } : {}),
+        ...(a.runTests === false ? { runTests: false } : {}),
+        ...deployOf(a),
+    };
+}
+/** The repo of an outward action target such as `github:owner/name#12` or `github:owner/name@abc1234`. */
+export function repoFromTarget(target) {
+    const m = /^github:([^#@\s]+)/.exec(target ?? '');
+    return m ? parseRepoId(m[1]) : null;
+}
+/** "owner/name" for messages. */
+export const fullName = (r) => `${r.owner}/${r.name}`;
+export function sameRepo(a, b) {
+    return !!a && !!b && lc(a.owner) === lc(b.owner) && lc(a.name) === lc(b.name);
+}
+// ---------- validation (POST /api/dots, PATCH /api/dots/:id) ----------
+const TEST_FRAMEWORKS = ['playwright', 'cypress', 'webdriverio', 'pytest', 'junit', 'katalon'];
+function validTestConfig(v, at) {
+    if (v === undefined)
+        return null;
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return `${at}.test must be an object.`;
+    const t = v;
+    if (!TEST_FRAMEWORKS.includes(t.framework))
+        return `${at}.test.framework must be one of ${TEST_FRAMEWORKS.join(', ')}.`;
+    const passEnv = passEnvError(t.passEnv);
+    if (passEnv)
+        return `${at}.test.passEnv ${passEnv}`;
+    const text = (key, max) => {
+        const x = t[key];
+        if (x === undefined || x === null)
+            return null;
+        if (typeof x !== 'string')
+            return `${at}.test.${key} must be text.`;
+        return x.length > max ? `${at}.test.${key} must be under ${max} characters.` : null;
+    };
+    const bad = text('command', 1000) ?? text('setup', 4000) ?? text('label', 40) ?? text('smokeGrep', 100) ?? text('dir', 200);
+    if (bad)
+        return bad;
+    if (typeof t.command === 'string' && t.command.trim()) {
+        const p = parseCommand(t.command);
+        if (!p.ok)
+            return `${at}.test.command: ${p.error}`;
+    }
+    if (typeof t.dir === 'string') {
+        const dir = workingDirectoryError(t.dir);
+        if (dir)
+            return `${at}.test.dir ${dir}`;
+    }
+    if (typeof t.label === 'string' && /[\u0000-\u001f\u007f]/.test(t.label))
+        return `${at}.test.label must be one line.`;
+    if (t.ref !== undefined && t.ref !== null) {
+        const ref = t.ref;
+        const fixed = ref && typeof ref === 'object' && !Array.isArray(ref) ? ref.fixed : undefined;
+        if (ref !== 'default' && ref !== 'match_branch' && !(typeof fixed === 'string' && isSafeBranchName(fixed.trim())))
+            return `${at}.test.ref must be "default", "match_branch", or { "fixed": "<branch or tag>" }.`;
+    }
+    if (t.baseUrlEnv !== undefined && t.baseUrlEnv !== null) {
+        const names = t.baseUrlEnv;
+        if (!Array.isArray(names) || names.length > 5 || names.some((n) => !isBaseUrlEnvName(n)))
+            return `${at}.test.baseUrlEnv must be a list of up to 5 variable names in capital letters, digits and underscores that end in _URL (or are BASE_URL or BASEURL), for example BASE_URL.`;
+    }
+    if (t.on !== undefined && t.on !== null) {
+        if (!Array.isArray(t.on) || t.on.some((j) => j !== 'pr_check' && j !== 'post_merge'))
+            return `${at}.test.on must be a list of pr_check and post_merge.`;
+    }
+    if (t.areas !== undefined && t.areas !== null) {
+        const areas = t.areas;
+        if (!areas || typeof areas !== 'object' || Array.isArray(areas))
+            return `${at}.test.areas must map an area name to a grep text.`;
+        const rows = Object.entries(areas);
+        if (rows.length > 40)
+            return `${at}.test.areas holds at most 40 areas.`;
+        for (const [area, grep] of rows) {
+            if (!area.trim() || area.length > 60)
+                return `${at}.test.areas: an area name is 1 to 60 characters.`;
+            if (typeof grep !== 'string' || !grep.trim() || grep.length > 200)
+                return `${at}.test.areas["${area.slice(0, 40)}"] must be a grep text of up to 200 characters.`;
+            try {
+                new RegExp(grep);
+            }
+            catch {
+                return `${at}.test.areas["${area.slice(0, 40)}"] is not a valid grep text.`;
+            }
+        }
+    }
+    return null;
+}
+const SCOPE_RULES = ['authors', 'team', 'skipDrafts', 'skipBots', 'linkedIssueLabels'];
+const GITHUB_LOGIN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})(?:\[bot\])?$/;
+const TEAM_SLUG = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\/[A-Za-z0-9_.-]{1,100}$/;
+/**
+ * Checks a repo's PR scope (KAT-354) and returns it tidy: logins without a leading @, each once (case-insensitive),
+ * the team as "org/team", a flag only when true. null or an empty object means no scope.
+ */
+export function parsePrScope(v, at) {
+    if (v === undefined || v === null)
+        return { ok: true, scope: undefined };
+    if (typeof v !== 'object' || Array.isArray(v))
+        return { ok: false, error: `${at}.prScope must be an object.` };
+    const raw = v;
+    const stray = Object.keys(raw).find((k) => !SCOPE_RULES.includes(k));
+    if (stray)
+        return { ok: false, error: `${at}.prScope.${stray} is not a scope rule. Use ${SCOPE_RULES.join(', ')}.` };
+    const out = {};
+    const words = (key, clean, ok, max, what) => {
+        const list = raw[key];
+        if (list === undefined || list === null)
+            return null;
+        if (!Array.isArray(list) || list.some((x) => typeof x !== 'string'))
+            return `${at}.prScope.${key} must be a list of ${what}.`;
+        const seen = new Set();
+        const kept = [];
+        for (const x of list) {
+            const t = clean(x.trim());
+            if (!t)
+                continue;
+            if (!ok(t))
+                return `${at}.prScope.${key}: "${t.slice(0, 40)}" is not valid. Use ${what}.`;
+            if (seen.has(t.toLowerCase()))
+                continue;
+            seen.add(t.toLowerCase());
+            kept.push(t);
+        }
+        if (kept.length > max)
+            return `${at}.prScope.${key} holds at most ${max} entries.`;
+        if (kept.length)
+            out[key] = kept;
+        return null;
+    };
+    const bad = words('authors', (s) => s.replace(/^@/, ''), (s) => GITHUB_LOGIN.test(s), 200, 'GitHub logins') ??
+        words('linkedIssueLabels', (s) => s, (s) => s.length <= 100, 50, 'label names');
+    if (bad)
+        return { ok: false, error: bad };
+    if (raw.team !== undefined && raw.team !== null && raw.team !== '') {
+        const team = typeof raw.team === 'string' ? raw.team.trim().replace(/^@/, '') : '';
+        if (!TEAM_SLUG.test(team))
+            return { ok: false, error: `${at}.prScope.team must be a team slug like "acme/web-team".` };
+        out.team = team;
+    }
+    for (const flag of ['skipDrafts', 'skipBots']) {
+        if (raw[flag] === undefined || raw[flag] === null)
+            continue;
+        if (typeof raw[flag] !== 'boolean')
+            return { ok: false, error: `${at}.prScope.${flag} must be true or false.` };
+        if (raw[flag])
+            out[flag] = true;
+    }
+    return { ok: true, scope: Object.keys(out).length ? out : undefined };
+}
+/** Reads a runTests flag. `off` is true for `false`; true, null, and unset all mean the tests run and are not stored. */
+function parseRunTests(v, at) {
+    if (v === undefined || v === null || v === true)
+        return { ok: true, off: false };
+    if (v === false)
+        return { ok: true, off: true };
+    return { ok: false, error: `${at}.runTests must be true or false.` };
+}
+/**
+ * Reads the deploy wait of a repo (KAT-395): `deployEnvironment` is a name of up to 100 characters on one line, `waitForDeploySec` a whole
+ * number of seconds from 0 to 3600. null, an empty name and unset mean the dot's value. 0 is kept: it turns the wait off for this repo.
+ */
+function parseRepoDeploy(raw, at) {
+    const env = raw.deployEnvironment;
+    let deployEnvironment;
+    if (env !== undefined && env !== null) {
+        if (typeof env !== 'string')
+            return { ok: false, error: `${at}.deployEnvironment must be text, the name of a GitHub environment such as qa.` };
+        if (env.trim().length > MAX_DEPLOY_ENVIRONMENT || /[\u0000-\u001f\u007f]/.test(env))
+            return { ok: false, error: `${at}.deployEnvironment must be a name of up to ${MAX_DEPLOY_ENVIRONMENT} characters on one line.` };
+        deployEnvironment = cleanDeployEnvironment(env);
+    }
+    const sec = raw.waitForDeploySec;
+    let waitForDeploySec;
+    if (sec !== undefined && sec !== null) {
+        if (!(typeof sec === 'number' && Number.isInteger(sec) && sec >= 0 && sec <= MAX_DEPLOY_WAIT_SEC))
+            return {
+                ok: false,
+                error: `${at}.waitForDeploySec must be a whole number of seconds from 0 to ${MAX_DEPLOY_WAIT_SEC}. 0 turns the wait off for this repo.`,
+            };
+        waitForDeploySec = sec;
+    }
+    const rawMatch = raw.deployUrlMatch;
+    let deployUrlMatch;
+    if (rawMatch !== undefined && rawMatch !== null && !(typeof rawMatch === 'string' && !rawMatch.trim())) {
+        const match = cleanDeployUrlMatch(rawMatch);
+        if (!match)
+            return {
+                ok: false,
+                error: `${at}.deployUrlMatch must be a host such as web.qa.example.com or an origin such as https://web.qa.example.com, up to ${MAX_DEPLOY_URL_MATCH} characters, with no path.`,
+            };
+        deployUrlMatch = match;
+    }
+    return {
+        ok: true,
+        ...(deployEnvironment ? { deployEnvironment } : {}),
+        ...(waitForDeploySec !== undefined ? { waitForDeploySec } : {}),
+        ...(deployUrlMatch ? { deployUrlMatch } : {}),
+    };
+}
+/**
+ * Why the deploy waits of a dot's app repos cannot work together, or null (KAT-395): a repo that waits (its own seconds, else the dot's)
+ * needs an environment (its own, else the dot's). `dot` holds the dot's two fields as the save leaves them.
+ */
+export function repoDeployWaitError(dot, repos) {
+    for (const r of repos) {
+        if (r.role !== 'app')
+            continue;
+        const sec = r.waitForDeploySec !== undefined ? cleanDeploySec(r.waitForDeploySec) : cleanDeploySec(dot.waitForDeploySec);
+        const env = cleanDeployEnvironment(r.deployEnvironment) ?? cleanDeployEnvironment(dot.deployEnvironment);
+        if (sec && !env)
+            return `${r.id} waits for a deploy and needs a deploy environment, the GitHub environment its merge deploys to, for example qa.`;
+    }
+    return null;
+}
+/** The deploy wait fields of each app repo a save would change, as `repos[acme/shop].deployEnvironment`. These are the admin's like the dot's. */
+export function repoDeployChanges(current, body) {
+    const res = resolveRepoFields(body, current);
+    if (!res.ok || !res.fields)
+        return [];
+    const was = new Map(watchRepos(current).map((r) => [r.id, r]));
+    const out = [];
+    for (const r of watchRepos({ repos: res.fields.repos })) {
+        if (r.role !== 'app')
+            continue;
+        const old = was.get(r.id);
+        if (old?.deployEnvironment !== r.deployEnvironment)
+            out.push(`repos[${r.id}].deployEnvironment`);
+        if (old?.waitForDeploySec !== r.waitForDeploySec)
+            out.push(`repos[${r.id}].waitForDeploySec`);
+        if (old?.deployUrlMatch !== r.deployUrlMatch)
+            out.push(`repos[${r.id}].deployUrlMatch`);
+    }
+    return out;
+}
+/**
+ * Checks a `repos` body and returns it normalized (ids lower case, duplicates refused), or an error in words.
+ * Rules (section 1.2): ids are "owner/name", roles are app, test or docs, and a test repo needs an app repo.
+ */
+export function parseWatchRepos(v) {
+    if (v === null)
+        return { ok: true, repos: [] };
+    if (!Array.isArray(v))
+        return { ok: false, error: 'repos must be a list of { repo, role }.' };
+    if (v.length > 50)
+        return { ok: false, error: 'A dot holds at most 50 repos.' };
+    const out = [];
+    const seen = new Set();
+    for (const [i, raw] of v.entries()) {
+        const at = `repos[${i}]`;
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            return { ok: false, error: `${at} must be an object with repo and role.` };
+        const e = raw;
+        const ref = parseRepoId(e.repo);
+        if (!ref)
+            return { ok: false, error: `${at}.repo must be "owner/name".` };
+        const id = repoId(ref.owner, ref.name);
+        if (seen.has(id))
+            return { ok: false, error: `${id} is in the list twice.` };
+        seen.add(id);
+        const role = e.role === undefined ? 'app' : e.role;
+        if (!REPO_ROLES.includes(role))
+            return { ok: false, error: `${at}.role must be app, test or docs.` };
+        const entry = { repo: id, role: role };
+        if (e.defaultBranch !== undefined && e.defaultBranch !== null && e.defaultBranch !== '') {
+            if (!isBranchName(e.defaultBranch))
+                return { ok: false, error: `${at}.defaultBranch is not a branch name.` };
+            entry.defaultBranch = e.defaultBranch;
+        }
+        if (e.pathFilters !== undefined && e.pathFilters !== null) {
+            if (!Array.isArray(e.pathFilters) || e.pathFilters.some((p) => typeof p !== 'string'))
+                return { ok: false, error: `${at}.pathFilters must be a list of paths.` };
+            const paths = e.pathFilters.map((p) => p.trim()).filter(Boolean);
+            if (paths.length)
+                entry.pathFilters = paths;
+        }
+        const scope = parsePrScope(e.prScope, at);
+        if (!scope.ok)
+            return scope;
+        if (scope.scope) {
+            if (role !== 'app')
+                return { ok: false, error: `${at}: prScope applies to an app repo only.` };
+            entry.prScope = scope.scope;
+        }
+        const runTests = parseRunTests(e.runTests, at);
+        if (!runTests.ok)
+            return runTests;
+        if (runTests.off) {
+            if (role !== 'app')
+                return { ok: false, error: `${at}: runTests applies to an app repo only.` };
+            entry.runTests = false;
+        }
+        const deploy = parseRepoDeploy(e, at);
+        if (!deploy.ok)
+            return deploy;
+        if (deploy.deployEnvironment !== undefined || deploy.waitForDeploySec !== undefined || deploy.deployUrlMatch !== undefined) {
+            if (role !== 'app')
+                return { ok: false, error: `${at}: deployEnvironment, waitForDeploySec and deployUrlMatch apply to an app repo only.` };
+            if (deploy.deployEnvironment !== undefined)
+                entry.deployEnvironment = deploy.deployEnvironment;
+            if (deploy.waitForDeploySec !== undefined)
+                entry.waitForDeploySec = deploy.waitForDeploySec;
+            if (deploy.deployUrlMatch !== undefined)
+                entry.deployUrlMatch = deploy.deployUrlMatch;
+        }
+        if (role === 'test') {
+            const err = validTestConfig(e.test, at);
+            if (err)
+                return { ok: false, error: err };
+            if (e.test)
+                entry.test = e.test;
+            if (e.targets !== undefined && e.targets !== null) {
+                if (!Array.isArray(e.targets) || e.targets.some((t) => !parseRepoId(t)))
+                    return { ok: false, error: `${at}.targets must be a list of "owner/name".` };
+                const targets = e.targets.map((t) => {
+                    const r = parseRepoId(t);
+                    return repoId(r.owner, r.name);
+                });
+                if (targets.length)
+                    entry.targets = targets;
+            }
+        }
+        else if (e.test !== undefined || e.targets !== undefined) {
+            return { ok: false, error: `${at}: test and targets apply to a test repo only.` };
+        }
+        out.push(entry);
+    }
+    const apps = new Set(out.filter((r) => r.role === 'app').map((r) => r.repo));
+    if (out.some((r) => r.role === 'test') && !apps.size)
+        return { ok: false, error: 'A test repo runs against an app, so add an app repo too.' };
+    for (const r of out) {
+        const bad = r.targets?.find((t) => !apps.has(t));
+        if (bad)
+            return { ok: false, error: `${r.repo} targets ${bad}, which is not an app repo of this dot.` };
+    }
+    return { ok: true, repos: out };
+}
+/** Reads a legacy `repo` body: an object with owner and name, or null to clear. */
+export function parseLegacyRepo(v) {
+    if (v === null || v === undefined || v === '')
+        return { ok: true, repo: null };
+    if (typeof v !== 'object' || Array.isArray(v))
+        return { ok: false, error: 'repo must be an object with owner and name.' };
+    const r = v;
+    const ref = parseRepoId(`${String(r.owner ?? '')}/${String(r.name ?? '')}`);
+    if (!ref)
+        return { ok: false, error: 'repo needs a valid owner and name.' };
+    const branch = r.defaultBranch === undefined || r.defaultBranch === null || r.defaultBranch === '' ? 'main' : r.defaultBranch;
+    if (!isBranchName(branch))
+        return { ok: false, error: 'repo.defaultBranch is not a branch name.' };
+    const paths = Array.isArray(r.pathFilters) ? r.pathFilters.filter((p) => typeof p === 'string' && !!p.trim()).map((p) => p.trim()) : [];
+    const scope = parsePrScope(r.prScope, 'repo');
+    if (!scope.ok)
+        return scope;
+    const runTests = parseRunTests(r.runTests, 'repo');
+    if (!runTests.ok)
+        return runTests;
+    const deploy = parseRepoDeploy(r, 'repo');
+    if (!deploy.ok)
+        return deploy;
+    return {
+        ok: true,
+        repo: {
+            owner: ref.owner,
+            name: ref.name,
+            defaultBranch: branch,
+            ...(paths.length ? { pathFilters: paths } : {}),
+            ...(scope.scope ? { prScope: scope.scope } : {}),
+            ...(runTests.off ? { runTests: false } : {}),
+            ...(deploy.deployEnvironment ? { deployEnvironment: deploy.deployEnvironment } : {}),
+            ...(deploy.waitForDeploySec !== undefined ? { waitForDeploySec: deploy.waitForDeploySec } : {}),
+            ...(deploy.deployUrlMatch ? { deployUrlMatch: deploy.deployUrlMatch } : {}),
+        },
+    };
+}
+/**
+ * The `repo` and `repos` fields to store for a save. `repos` in the body wins and `repo` is derived
+ * from its first app entry. A body with only `repo` (the single-repo form) replaces the first app
+ * entry in its place and keeps the others in their order; `repo: null` drops it.
+ */
+export function resolveRepoFields(body, current) {
+    const hasRepos = 'repos' in body && body.repos !== undefined;
+    const hasRepo = 'repo' in body && body.repo !== undefined;
+    if (!hasRepos && !hasRepo)
+        return { ok: true, fields: null };
+    let repos;
+    if (hasRepos) {
+        const parsed = parseWatchRepos(body.repos);
+        if (!parsed.ok)
+            return parsed;
+        repos = parsed.repos;
+    }
+    else {
+        const parsed = parseLegacyRepo(body.repo);
+        if (!parsed.ok)
+            return parsed;
+        const held = (current ? watchRepos(current) : []).map(toWatchRepo);
+        const firstApp = held.findIndex((r) => r.role === 'app');
+        const next = parsed.repo
+            ? {
+                repo: repoId(parsed.repo.owner, parsed.repo.name),
+                role: 'app',
+                defaultBranch: parsed.repo.defaultBranch,
+                ...(parsed.repo.pathFilters ? { pathFilters: parsed.repo.pathFilters } : {}),
+                ...(parsed.repo.prScope ? { prScope: parsed.repo.prScope } : {}),
+                ...(parsed.repo.runTests === false ? { runTests: false } : {}),
+                ...legacyDeploy(body.repo, parsed.repo, held[firstApp]),
+            }
+            : null;
+        // The new first app entry takes the place of the old one, so a list that holds a docs or test repo first keeps its order.
+        // With no app entry yet it goes first. An entry that names the same repo is replaced by it.
+        const list = next
+            ? firstApp < 0
+                ? [next, ...held.filter((r) => r.repo !== next.repo)]
+                : held.flatMap((r, i) => (i === firstApp ? [next] : r.repo === next.repo ? [] : [r]))
+            : held.filter((_, i) => i !== firstApp);
+        const checked = parseWatchRepos(list);
+        if (!checked.ok)
+            return checked;
+        repos = checked.repos;
+    }
+    return { ok: true, fields: { repo: repoMirror(repos), repos } };
+}
+/**
+ * The deploy wait fields the single `repo` form saves for the first app repo (KAT-395). A body that names them sets them, null clears one.
+ * A body that leaves them out keeps the ones the repo has, so a client that does not know them does not wipe them.
+ */
+function legacyDeploy(body, parsed, held) {
+    const sent = body && typeof body === 'object' ? body : {};
+    const same = held && held.repo === repoId(parsed.owner, parsed.name);
+    return {
+        ...('deployEnvironment' in sent
+            ? parsed.deployEnvironment
+                ? { deployEnvironment: parsed.deployEnvironment }
+                : {}
+            : same && held.deployEnvironment
+                ? { deployEnvironment: held.deployEnvironment }
+                : {}),
+        ...('waitForDeploySec' in sent
+            ? parsed.waitForDeploySec !== undefined
+                ? { waitForDeploySec: parsed.waitForDeploySec }
+                : {}
+            : same && held.waitForDeploySec !== undefined
+                ? { waitForDeploySec: held.waitForDeploySec }
+                : {}),
+        ...('deployUrlMatch' in sent
+            ? parsed.deployUrlMatch
+                ? { deployUrlMatch: parsed.deployUrlMatch }
+                : {}
+            : same && held.deployUrlMatch
+                ? { deployUrlMatch: held.deployUrlMatch }
+                : {}),
+    };
+}
+/**
+ * `Watch.repo` for a list of `repos`: the first app repo, with the branch a run reads for it now. Call it again once a new repo
+ * has joined the workspace, since an entry with no branch reads the workspace default and a new row may hold another one than "main".
+ */
+export function repoMirror(repos) {
+    return legacyRepo(watchRepos({ repos }));
+}
+/**
+ * `Watch.repo` as the dot page shows it: the branch of the first app repo as a run reads it now. The stored mirror keeps the branch
+ * from the last save, and the workspace default may have moved since. The form sends this value back, so a save that leaves
+ * the branch alone reads as unchanged.
+ */
+export function repoAsRun(w) {
+    const first = primaryRepo(w);
+    if (!w.repo || !first || !sameRepo(w.repo, first) || w.repo.defaultBranch === first.defaultBranch)
+        return w.repo;
+    return { ...w.repo, defaultBranch: first.defaultBranch };
+}
+// ---------- repo changes only an admin may make (KAT-369) ----------
+/** A list as a save leaves it: trimmed, each entry once, order ignored. */
+const asSet = (v) => JSON.stringify([...new Set(cleanTestBranches(v))].sort());
+/** The ref of a test repo as a run reads it: an unset ref and `default` are the same. */
+const refOf = (t) => JSON.stringify(t?.ref === undefined || t.ref === 'default' ? 'default' : t.ref);
+/**
+ * The repo settings a save would change that an editor may not (KAT-369), as `repos[acme/shop].defaultBranch` or `testBranches`.
+ * Empty when none. These decide which code a run checks out: the repos of the dot and their roles, their order (the first app repo
+ * is the dot's repo), the branch of each, the app repos a test repo exercises, the framework and ref of a test repo, and the test
+ * branches. Path filters, PR scope, and the Run tests switch are not here. Both sides are read as a run reads them (`watchRepos`),
+ * so a save that sends `repo` alone, or the saved list as it is, changes nothing. A `repos` list the save routes refuse anyway
+ * changes nothing here: they answer it with the 400 and write nothing.
+ */
+export function repoAdminChanges(current, body) {
+    const out = [];
+    if (body.testBranches !== undefined && asSet(body.testBranches) !== asSet(current.testBranches))
+        out.push('testBranches');
+    const res = resolveRepoFields(body, current);
+    if (!res.ok) {
+        // A `repo` that cannot be stored next to the other repos (a test repo that targets the one it replaces) is still another repo.
+        const parsed = body.repos === undefined && body.repo !== undefined ? parseLegacyRepo(body.repo) : null;
+        if (parsed?.ok) {
+            const first = primaryRepo(current);
+            const asked = parsed.repo;
+            const same = asked ? !!first && first.id === repoId(asked.owner, asked.name) && first.defaultBranch === asked.defaultBranch : !first;
+            if (!same)
+                out.push('repo');
+        }
+        return out;
+    }
+    if (!res.fields)
+        return out;
+    const before = watchRepos(current);
+    const after = watchRepos({ repos: res.fields.repos });
+    const was = new Map(before.map((r) => [r.id, r]));
+    const now = new Set(after.map((r) => r.id));
+    for (const r of after) {
+        const old = was.get(r.id);
+        if (!old) {
+            out.push(`repos[${r.id}]`);
+            continue;
+        }
+        if (old.role !== r.role)
+            out.push(`repos[${r.id}].role`);
+        if (old.defaultBranch !== r.defaultBranch)
+            out.push(`repos[${r.id}].defaultBranch`);
+        if (asSet(old.targets) !== asSet(r.targets))
+            out.push(`repos[${r.id}].targets`);
+        if (old.test?.framework !== r.test?.framework)
+            out.push(`repos[${r.id}].test.framework`);
+        if (refOf(old.test) !== refOf(r.test))
+            out.push(`repos[${r.id}].test.ref`);
+    }
+    for (const r of before)
+        if (!now.has(r.id))
+            out.push(`repos[${r.id}]`);
+    // The same repos in another order: the first app repo is the one `repo` mirrors.
+    if (!out.length && before.map((r) => r.id).join() !== after.map((r) => r.id).join())
+        out.push('repos');
+    return out;
+}
+function toWatchRepo(r) {
+    return {
+        repo: r.id,
+        role: r.role,
+        defaultBranch: r.defaultBranch,
+        ...(r.pathFilters?.length ? { pathFilters: r.pathFilters } : {}),
+        ...(r.test ? { test: r.test } : {}),
+        ...(r.targets?.length ? { targets: r.targets } : {}),
+        ...(r.prScope ? { prScope: r.prScope } : {}),
+        ...(r.runTests === false ? { runTests: false } : {}),
+        ...deployOf(r),
+    };
+}
+// ---------- workspace repo store (section 1.3) ----------
+/** Dots (not archived) that hold this repo. */
+export function dotsUsingRepo(id, watches = list('watches')) {
+    const want = id.toLowerCase();
+    return watches.filter((w) => !w.archived && watchRepos(w).some((r) => r.id === want));
+}
+/**
+ * Adds a workspace repo when missing and returns the row. An existing row keeps its scan state;
+ * a known default branch or private flag is updated.
+ */
+export function ensureWorkspaceRepo(ref, info = {}) {
+    const id = repoId(ref.owner, ref.name);
+    const cur = getWorkspaceRepo(id);
+    if (cur) {
+        const patch = {};
+        if (info.defaultBranch && info.defaultBranch !== cur.defaultBranch)
+            patch.defaultBranch = info.defaultBranch;
+        if (info.private !== undefined && info.private !== cur.private)
+            patch.private = info.private;
+        if (Object.keys(patch).length) {
+            update('repos', id, patch);
+            return changed(getWorkspaceRepo(id));
+        }
+        return cur;
+    }
+    const now = new Date().toISOString();
+    const row = insert('repos', {
+        id,
+        owner: ref.owner,
+        name: ref.name,
+        defaultBranch: info.defaultBranch || 'main',
+        private: info.private ?? false,
+        addedAt: now,
+        // New repos wait in queued until a scan is requested.
+        scan: { state: 'queued' },
+    });
+    return changed(row);
+}
+/** Removes a workspace repo. Refused with the dot names while a dot still holds it. */
+export function removeWorkspaceRepo(id) {
+    const key = id.toLowerCase();
+    if (!getWorkspaceRepo(key))
+        return { ok: false, code: 404, error: `${key} is not a workspace repo.` };
+    const users = dotsUsingRepo(key);
+    if (users.length)
+        return {
+            ok: false,
+            code: 409,
+            error: `${key} is used by ${users.map((w) => w.name).join(', ')}. Remove it from those dots first.`,
+            dots: users.map((w) => w.name),
+        };
+    remove('repos', key);
+    mirrorSettings();
+    return { ok: true };
+}
+/**
+ * Writes a workspace repo's scan state and publishes the row so the pages update live. A patch
+ * keeps the fields it leaves out (the last profile's sha and time stay while a rescan runs).
+ * Returns the row, or undefined when the repo is not in the workspace.
+ */
+export function setRepoScan(id, patch) {
+    const cur = getWorkspaceRepo(id);
+    if (!cur)
+        return undefined;
+    const scan = { ...cur.scan, ...patch };
+    if (patch.state !== 'error')
+        delete scan.error;
+    update('repos', cur.id, { scan });
+    return changed(getWorkspaceRepo(cur.id));
+}
+function changed(row) {
+    try {
+        publish({ type: 'repo', repo: row });
+    }
+    catch {
+        /* live events are best effort */
+    }
+    return row;
+}
+/**
+ * Writes the GitHub provider's `settings.repos` from the repos table, so the Setup picker shows
+ * the workspace list (section 1.3 step 2). Skipped when the stored list already matches.
+ */
+export function mirrorSettings() {
+    try {
+        const ids = listWorkspaceRepos().map((r) => `${r.owner}/${r.name}`);
+        const meta = getMeta('github');
+        const cur = meta.settings?.repos;
+        const have = Array.isArray(cur) ? cur : typeof cur === 'string' && cur ? [cur] : [];
+        const same = have.length === ids.length && have.every((x, i) => x.toLowerCase() === ids[i].toLowerCase());
+        if (same)
+            return;
+        const settings = { ...(meta.settings ?? {}) };
+        if (ids.length)
+            settings.repos = ids;
+        else
+            delete settings.repos;
+        setMeta('github', { settings });
+    }
+    catch {
+        /* the connect store is not ready (no master key): the table stays the source of truth */
+    }
+}
+/** The GitHub provider's picked repos, as stored before the workspace table existed. */
+function settingsRepos() {
+    try {
+        const cur = getMeta('github').settings?.repos;
+        const vals = Array.isArray(cur) ? cur : typeof cur === 'string' && cur ? [cur] : [];
+        return vals.map(parseRepoId).filter((r) => !!r);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Boot migration (section 1.3), safe to repeat:
+ * 1. a dot with `repo` and no `repos` gets one app entry, and its repo joins the workspace;
+ * 2. every repo a dot holds and every repo in the GitHub provider's `settings.repos` joins the workspace;
+ * 3. `settings.repos` is rewritten to mirror the workspace.
+ * Scans are not queued here, so new rows stay in `queued` until one is requested.
+ */
+export function migrateWatchRepos() {
+    const out = { watches: [], added: [] };
+    const add = (ref, info) => {
+        const id = repoId(ref.owner, ref.name);
+        if (getWorkspaceRepo(id))
+            return;
+        ensureWorkspaceRepo(ref, info);
+        out.added.push(id);
+    };
+    for (const w of list('watches')) {
+        if (w.repo && !(Array.isArray(w.repos) && w.repos.length)) {
+            const ref = parseRepoId(`${w.repo.owner}/${w.repo.name}`);
+            if (!ref)
+                continue;
+            const entry = {
+                repo: repoId(ref.owner, ref.name),
+                role: 'app',
+                defaultBranch: w.repo.defaultBranch || 'main',
+                ...(w.repo.pathFilters?.length ? { pathFilters: w.repo.pathFilters } : {}),
+                ...(w.repo.prScope ? { prScope: w.repo.prScope } : {}),
+                ...(w.repo.runTests === false ? { runTests: false } : {}),
+                ...deployOf(w.repo),
+            };
+            update('watches', w.id, { repos: [entry] });
+            out.watches.push(w.id);
+        }
+        // `repo` first: it keeps the owner and name casing, which a `repos` id (lower case) has lost.
+        const legacy = w.repo ? parseRepoId(`${w.repo.owner}/${w.repo.name}`) : null;
+        if (legacy)
+            add(legacy, { defaultBranch: w.repo.defaultBranch || 'main' });
+        const now = get('watches', w.id) ?? w;
+        for (const r of watchRepos(now, () => undefined))
+            add(r, { defaultBranch: r.defaultBranch });
+    }
+    for (const ref of settingsRepos())
+        add(ref);
+    mirrorSettings();
+    return out;
+}
+//# sourceMappingURL=repos.js.map