@agent-native/core 0.98.1 → 0.98.2

package/dist/cli/recap.js

@@ -86,6 +86,8 @@ export const PR_VISUAL_RECAP_SETUP = [
     "  VISUAL_RECAP_API_KEY (secret) + VISUAL_RECAP_AGENT=openai-compatible + VISUAL_RECAP_BASE_URL (variable) — use DeepSeek, Kimi, or any OpenAI-compatible API",
     "  VISUAL_RECAP_MODEL (variable, required for openai-compatible) — provider model id; optional override for Claude/Codex",
     "  VISUAL_RECAP_REASONING (variable) — reasoning depth (none|minimal|low|medium|high|xhigh; Codex only)",
+    '  VISUAL_RECAP_RUNS_ON (variable) — JSON hosted label or self-hosted label array; defaults to "ubuntu-latest"',
+    "  VISUAL_RECAP_GATE_RUNS_ON (variable) — trusted same-repo authors only; plain single gate label; defaults to ubuntu-latest",
     "  VISUAL_RECAP_SKILL_SOURCE=repo (variable) — pin CI to the repo-local visual-recap skill instead of latest bundled guidance",
     "  VISUAL_RECAP_SECRET_SCAN=off|high-confidence|strict (variable) — default high-confidence; strict restores generic TOKEN/SECRET assignment suppression",
     "  PLAN_RECAP_APP_URL (secret) — only when self-hosting the plan app (defaults to https://plan.agent-native.com)",
@@ -133,6 +135,12 @@ export function buildReusableCallerWorkflow(options = {}) {
     const ref = (options.ref ?? "main").replace(/^@/, "");
     const agentValue = options.agent ?? "${{ vars.VISUAL_RECAP_AGENT || 'claude' }}";
     const modelValue = options.model ?? "${{ vars.VISUAL_RECAP_MODEL || '' }}";
+    const runsOnValue = options.runsOn === undefined
+        ? "${{ vars.VISUAL_RECAP_RUNS_ON || '\"ubuntu-latest\"' }}"
+        : JSON.stringify(options.runsOn);
+    const gateRunsOnValue = options.gateRunsOn === undefined
+        ? "${{ vars.VISUAL_RECAP_GATE_RUNS_ON || 'ubuntu-latest' }}"
+        : JSON.stringify(options.gateRunsOn);
     return (`name: PR Visual Recap\n` +
         `\n` +
         `# Thin caller — the full workflow logic lives in BuilderIO/agent-native.\n` +
@@ -166,6 +174,8 @@ export function buildReusableCallerWorkflow(options = {}) {
         `      reasoning: \${{ vars.VISUAL_RECAP_REASONING || '' }}\n` +
         `      skill-source: \${{ vars.VISUAL_RECAP_SKILL_SOURCE || 'auto' }}\n` +
         `      secret-scan: \${{ vars.VISUAL_RECAP_SECRET_SCAN || 'high-confidence' }}\n` +
+        `      runs-on: ${runsOnValue}\n` +
+        `      gate-runs-on: ${gateRunsOnValue}\n` +
         `      # cli-version: "latest"  # pin to a specific @agent-native/core version\n` +
         ``);
 }
@@ -181,6 +191,8 @@ export function writePrVisualRecapReusableCallerWorkflow(baseDir, options = {})
         ref: options.ref,
         agent: options.agent,
         model: options.model,
+        runsOn: options.runsOn,
+        gateRunsOn: options.gateRunsOn,
     });
     if (fs.existsSync(file)) {
         const current = fs.readFileSync(file, "utf8");
@@ -330,6 +342,40 @@ function listGithubVariables(repo) {
         return null;
     }
 }
+function listGithubOrganizationVariables(repo) {
+    const result = gh([
+        "api",
+        "--paginate",
+        "--slurp",
+        `repos/${repo}/actions/organization-variables?per_page=30`,
+    ]);
+    if (!result.ok)
+        return null;
+    try {
+        const parsed = JSON.parse(result.stdout);
+        const pages = Array.isArray(parsed) ? parsed : [parsed];
+        const out = new Map();
+        for (const page of pages) {
+            if (!page || typeof page !== "object")
+                continue;
+            const variables = page.variables;
+            if (!Array.isArray(variables))
+                continue;
+            for (const variable of variables) {
+                if (!variable || typeof variable !== "object")
+                    continue;
+                const record = variable;
+                if (typeof record.name !== "string")
+                    continue;
+                out.set(record.name, typeof record.value === "string" ? record.value : "");
+            }
+        }
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
 function setGithubSecret(name, value, repo, dryRun) {
     if (!value)
         return "missing";
@@ -350,6 +396,61 @@ function setGithubVariable(name, value, repo, dryRun) {
         args.push("--repo", repo);
     return gh(args).ok ? "set" : "failed";
 }
+function listGithubRunners(repo) {
+    const result = gh([
+        "api",
+        "--paginate",
+        "--slurp",
+        `repos/${repo}/actions/runners?per_page=100`,
+    ]);
+    if (!result.ok)
+        return null;
+    try {
+        const parsed = JSON.parse(result.stdout);
+        const pages = Array.isArray(parsed) ? parsed : [parsed];
+        const runners = [];
+        for (const page of pages) {
+            if (!page || typeof page !== "object")
+                continue;
+            const entries = page.runners;
+            if (!Array.isArray(entries))
+                continue;
+            for (const entry of entries) {
+                if (!entry || typeof entry !== "object")
+                    continue;
+                const record = entry;
+                if (typeof record.name !== "string")
+                    continue;
+                const rawLabels = Array.isArray(record.labels) ? record.labels : [];
+                runners.push({
+                    name: record.name,
+                    status: typeof record.status === "string" ? record.status : "",
+                    labels: rawLabels.flatMap((label) => {
+                        if (typeof label === "string")
+                            return [label];
+                        if (!label || typeof label !== "object")
+                            return [];
+                        const name = label.name;
+                        return typeof name === "string" ? [name] : [];
+                    }),
+                });
+            }
+        }
+        return runners;
+    }
+    catch {
+        return null;
+    }
+}
+export function matchingRecapRunners(runners, requiredLabels) {
+    const required = requiredLabels.map((label) => label.toLowerCase());
+    return runners.filter((runner) => {
+        if (runner.status.toLowerCase() !== "online")
+            return false;
+        const labels = new Set(runner.labels.map((label) => label.toLowerCase()));
+        return required.every((label) => labels.has(label));
+    });
+}
 const OPENAI_COMPATIBLE_VARIABLE_REQUIREMENTS = [
     {
         name: "VISUAL_RECAP_BASE_URL",
@@ -357,6 +458,83 @@ const OPENAI_COMPATIBLE_VARIABLE_REQUIREMENTS = [
     },
     { name: "VISUAL_RECAP_MODEL", example: "provider-model-id" },
 ];
+const RECAP_RUNS_ON_REQUIREMENT = {
+    name: "VISUAL_RECAP_RUNS_ON",
+    example: '["self-hosted","linux","x64","visual-recap"]',
+};
+const RECAP_GATE_RUNS_ON_REQUIREMENT = {
+    name: "VISUAL_RECAP_GATE_RUNS_ON",
+    example: "visual-recap-gate",
+};
+/** Parse the JSON consumed by GitHub Actions `fromJSON(...)` for `runs-on`. */
+export function parseRecapRunsOn(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new Error('VISUAL_RECAP_RUNS_ON must be valid JSON, such as "ubuntu-latest" or ["self-hosted","linux","x64"]');
+    }
+    if (typeof parsed === "string") {
+        if (!/^(?:ubuntu|windows|macos)-[A-Za-z0-9.-]+$/.test(parsed)) {
+            throw new Error("VISUAL_RECAP_RUNS_ON JSON strings must name a standard GitHub-hosted ubuntu-, windows-, or macos- runner");
+        }
+        return {
+            json: JSON.stringify(parsed),
+            labels: [parsed],
+            selfHosted: false,
+        };
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0 || parsed.length > 20) {
+        throw new Error("VISUAL_RECAP_RUNS_ON must be a hosted runner JSON string or an array of 1-20 self-hosted labels");
+    }
+    if (parsed.some((label) => typeof label !== "string" ||
+        label.length === 0 ||
+        label.length > 100 ||
+        /[\p{C}]/u.test(label))) {
+        throw new Error("VISUAL_RECAP_RUNS_ON labels must be non-empty strings up to 100 characters without control characters");
+    }
+    const labels = parsed;
+    if (!labels.includes("self-hosted")) {
+        throw new Error('VISUAL_RECAP_RUNS_ON label arrays must include the exact "self-hosted" label');
+    }
+    if (new Set(labels.map((label) => label.toLowerCase())).size !== labels.length) {
+        throw new Error("VISUAL_RECAP_RUNS_ON labels must be unique");
+    }
+    return { json: JSON.stringify(labels), labels, selfHosted: true };
+}
+/** Validate the plain label used directly by the gate job's `runs-on`. */
+export function parseRecapGateRunsOn(value) {
+    const label = value.trim();
+    if (!/^[A-Za-z0-9._-]{1,100}$/.test(label)) {
+        throw new Error("VISUAL_RECAP_GATE_RUNS_ON must be one plain runner label (1-100 letters, numbers, dots, underscores, or hyphens)");
+    }
+    return label;
+}
+function recapRunsOnProblem(value) {
+    try {
+        parseRecapRunsOn(value);
+        return null;
+    }
+    catch (error) {
+        return {
+            requirement: RECAP_RUNS_ON_REQUIREMENT,
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function recapGateRunsOnProblem(value) {
+    try {
+        parseRecapGateRunsOn(value);
+        return null;
+    }
+    catch (error) {
+        return {
+            requirement: RECAP_GATE_RUNS_ON_REQUIREMENT,
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
 const RECAP_MODEL_PATTERN = /^[a-zA-Z0-9._-]{1,80}$/;
 const OPENAI_COMPATIBLE_RECAP_MODEL_PATTERN = /^[^\p{C}\p{Z}]{1,200}$/u;
 export function validateOpenAiCompatibleRecapVariables(input) {
@@ -427,6 +605,23 @@ export function buildRecapSetupPlan(input) {
             model: variableValues.VISUAL_RECAP_MODEL,
         })
         : [];
+    const runsOn = input.runsOn ?? envValue(env, "VISUAL_RECAP_RUNS_ON");
+    if (runsOn) {
+        const problem = recapRunsOnProblem(runsOn);
+        if (problem)
+            variableProblems.push(problem);
+        else
+            variableValues.VISUAL_RECAP_RUNS_ON = parseRecapRunsOn(runsOn).json;
+    }
+    const gateRunsOn = input.gateRunsOn ?? envValue(env, "VISUAL_RECAP_GATE_RUNS_ON");
+    if (gateRunsOn) {
+        const problem = recapGateRunsOnProblem(gateRunsOn);
+        if (problem)
+            variableProblems.push(problem);
+        else
+            variableValues.VISUAL_RECAP_GATE_RUNS_ON =
+                parseRecapGateRunsOn(gateRunsOn);
+    }
     return {
         agent,
         appUrl,
@@ -460,7 +655,16 @@ function runSetup(args) {
         appUrl: optionalArg(args, "app-url"),
         agent: optionalArg(args, "agent"),
         repo,
+        runsOn: optionalArg(args, "runs-on"),
+        gateRunsOn: optionalArg(args, "gate-runs-on"),
     });
+    const runnerProblem = plan.variableProblems.find((problem) => problem.requirement.name === "VISUAL_RECAP_RUNS_ON" ||
+        problem.requirement.name === "VISUAL_RECAP_GATE_RUNS_ON");
+    if (runnerProblem) {
+        process.stderr.write(`recap setup: ${runnerProblem.reason}.\n`);
+        process.exitCode = 1;
+        return;
+    }
     const lines = [
         reusable
             ? "PR Visual Recap setup (reusable workflow)"
@@ -478,6 +682,8 @@ function runSetup(args) {
             force,
             ref: optionalArg(args, "ref") ?? "main",
             agent: plan.agent !== "claude" ? plan.agent : undefined,
+            runsOn: plan.variableValues.VISUAL_RECAP_RUNS_ON,
+            gateRunsOn: plan.variableValues.VISUAL_RECAP_GATE_RUNS_ON,
         });
         if (result.status === "refused") {
             process.stderr.write(`recap setup: ${result.message}\n`);
@@ -573,6 +779,13 @@ function runDoctor(args) {
     const baseDir = process.cwd();
     const repo = resolveGithubRepo(optionalArg(args, "repo"));
     const variables = listGithubVariables(repo);
+    if (variables && repo) {
+        const organizationVariables = listGithubOrganizationVariables(repo);
+        for (const [name, value] of organizationVariables ?? []) {
+            if (!variables.has(name))
+                variables.set(name, value);
+        }
+    }
     const agent = normalizeRecapAgent(optionalArg(args, "agent") ??
         variables?.get("VISUAL_RECAP_AGENT") ??
         process.env.VISUAL_RECAP_AGENT);
@@ -662,6 +875,66 @@ function runDoctor(args) {
                 lines.push(`  Set it with: ${commandForMissingVariable(requirement.name, requirement.example, repo)}`);
             }
         }
+        const configuredRunsOn = variables.get("VISUAL_RECAP_RUNS_ON")?.trim();
+        if (!configuredRunsOn) {
+            lines.push('[ok] Recap runner: "ubuntu-latest".');
+        }
+        else {
+            const problem = recapRunsOnProblem(configuredRunsOn);
+            if (problem) {
+                ok = false;
+                lines.push(`[invalid] ${problem.reason}.`);
+                lines.push(`  Set it with: ${commandForMissingVariable(RECAP_RUNS_ON_REQUIREMENT.name, RECAP_RUNS_ON_REQUIREMENT.example, repo)}`);
+            }
+            else {
+                const runsOn = parseRecapRunsOn(configuredRunsOn);
+                lines.push(`[ok] Recap runner configuration: ${runsOn.json}.`);
+                if (runsOn.selfHosted && repo) {
+                    const runners = listGithubRunners(repo);
+                    if (!runners) {
+                        lines.push("[warn] Could not verify self-hosted runners with gh; repository Administration read access is required.");
+                    }
+                    else {
+                        const matches = matchingRecapRunners(runners, runsOn.labels);
+                        if (matches.length === 0) {
+                            ok = false;
+                            lines.push(`[missing] No online self-hosted runner matches: ${runsOn.labels.join(", ")}.`);
+                        }
+                        else {
+                            lines.push(`[ok] Matching online self-hosted runner: ${matches.map((runner) => runner.name).join(", ")}.`);
+                        }
+                    }
+                }
+            }
+        }
+        const configuredGateRunsOn = variables.get("VISUAL_RECAP_GATE_RUNS_ON")?.trim() || "ubuntu-latest";
+        const gateProblem = recapGateRunsOnProblem(configuredGateRunsOn);
+        if (gateProblem) {
+            ok = false;
+            lines.push(`[invalid] ${gateProblem.reason}.`);
+            lines.push(`  Set it with: ${commandForMissingVariable(RECAP_GATE_RUNS_ON_REQUIREMENT.name, RECAP_GATE_RUNS_ON_REQUIREMENT.example, repo)}`);
+        }
+        else {
+            const gateLabel = parseRecapGateRunsOn(configuredGateRunsOn);
+            lines.push(`[ok] Gate runner label for trusted same-repo authors: ${gateLabel}.`);
+            if (!/^(?:ubuntu|windows|macos)-[A-Za-z0-9.-]+$/.test(gateLabel) &&
+                repo) {
+                const runners = listGithubRunners(repo);
+                if (!runners) {
+                    lines.push("[warn] Could not verify the gate runner with gh; repository Administration read access is required.");
+                }
+                else {
+                    const matches = matchingRecapRunners(runners, [gateLabel]);
+                    if (matches.length === 0) {
+                        ok = false;
+                        lines.push(`[missing] No online self-hosted gate runner matches: ${gateLabel}.`);
+                    }
+                    else {
+                        lines.push(`[ok] Matching online gate runner: ${matches.map((runner) => runner.name).join(", ")}.`);
+                    }
+                }
+            }
+        }
     }
     process.stdout.write(`${lines.join("\n")}\n`);
     if (!ok)
@@ -3478,7 +3751,7 @@ function runAgentSummary(args) {
 const HELP = `npx @agent-native/core@latest recap — PR visual recap helpers (used by the GitHub Action)
 
 Usage:
-  npx @agent-native/core@latest recap setup [--repo owner/name] [--agent claude|codex|openai-compatible] [--app-url <url>] [--skip-secrets] [--dry-run] [--force]
+  npx @agent-native/core@latest recap setup [--repo owner/name] [--agent claude|codex|openai-compatible] [--app-url <url>] [--runs-on <json>] [--gate-runs-on <label>] [--skip-secrets] [--dry-run] [--force]
   npx @agent-native/core@latest recap doctor [--repo owner/name] [--agent claude|codex|openai-compatible] [--app-url <url>]
   npx @agent-native/core@latest recap collect-diff --base <baseSha> --head <headSha> [--out recap.diff] [--stat recap.stat]
   npx @agent-native/core@latest recap block-reference [--app-url <url>] [--out recap-blocks.md]
@@ -3531,11 +3804,22 @@ Usage:
     Write/refresh .github/workflows/pr-visual-recap.yml, then configure GitHub
     Actions secrets and variables with gh when values are available from env or
     the local Plans publish-token store. Missing values are printed as exact next
-    commands; secret values are sent to gh through stdin, never argv.
+    commands; secret values are sent to gh through stdin, never argv. Pass
+    --runs-on '["self-hosted","linux","x64","visual-recap"]' to opt into a
+    trusted self-hosted runner label set. In self-hosted-only repos, pass
+    --gate-runs-on visual-recap-gate for a dedicated, preferably ephemeral,
+    single-label gate runner. It is used only for trusted same-repo OWNER,
+    MEMBER, or COLLABORATOR authors. The stock gate does not check out the PR
+    tree; it evaluates workflow logic and PR metadata. Fork and untrusted PRs
+    use GitHub-hosted ubuntu-latest instead, so they may remain unscheduled when
+    a repository disables GitHub-hosted runners.
   npx @agent-native/core@latest recap doctor
     Check workflow presence/drift, local Plans publish-token availability, gh
     repo access, and required GitHub Actions secrets and variables for the
     selected backend, including provider-variable validity.
+    Self-hosted runner JSON and the plain gate runner label are validated, and
+    matching online runners are checked when the GitHub token has repository
+    Administration read access.
 `;
 export async function runRecap(argv) {
     const [sub, ...rest] = argv;