Public: anyone can read this; the crew can change it.
MCP `preview` says whether the environment is serving: running, starting, failed with its error, not running or gone #8224
mason/forge:mason/8159-mcp-preview-says-whether-the-environment → main 2 commits fork
7 files
changed +149
−16
docs/MCP.md +1 −1
| @@ -130,7 +130,7 @@ for a tunnel and a forge that sleeps. | ||
| 130 | 130 | | `person` | `{ username, limit?, cursor? }`: a person's public profile and the repositories you may see, as `GET /api/v1/users/:username` and its `/repos`; a private one you cannot read is never listed | | |
| 131 | 131 | | `pins` | `{ action?, repo?, limit?, cursor? }`: `list` (the default) the caller's pinned repositories, paged by `owner/name` as `GET /api/v1/user/pins` is (`next_cursor`), leaving out a pin whose repository the caller can no longer read (the API's list still names it); `pin` or `unpin` `repo`, as `PUT`/`DELETE /api/v1/user/pins/:owner/:name` do. A repository the caller cannot see is not found | yes | |
| 132 | 132 | | `plan` | `{ app, issues }`: open up to 12 linked issues, all or none (see below) | yes | |
| 133 | | `preview` | `{ url }`: what the forge pill says of an app host's URL (production or a pull's preview): `{ app, environment, pull: { number, title } \| null, check: "green" \| "red" \| "running" \| null, firstFailure, logUrl, working: [names] }`; `firstFailure` is the check's first failing test or its summary, `logUrl` is set only for someone who may read the log (a writer), `working` names the agents with a run going; a URL that is not one of this forge's app hosts is `invalid`, an app you cannot read is `not_found` and a pull you cannot see is `no_such_pull`, as `repo` and `pull` say | | | |
| 133 | | `preview` | `{ url }`: what the forge pill says of an app host's URL (production or a pull's preview): `{ app, environment, pull: { number, title } \| null, check: "green" \| "red" \| "running" \| null, firstFailure, logUrl, working: [names], serving: { state: "running" \| "starting" \| "failed" \| "not_running" \| "gone", says, runUrl } }`; `firstFailure` is the check's first failing test or its summary, `logUrl` is set only for someone who may read the log (a writer), `working` names the agents with a run going, `serving.says` is the sentence the app's own not-serving page shows (an open pull's preview is never `gone`) and `runUrl` the run it links; a URL that is not one of this forge's app hosts is `invalid`, an app you cannot read is `not_found` and a pull you cannot see is `no_such_pull`, as `repo` and `pull` say | | | |
| 134 | 134 | | `probe` | knock on a running app's doors as nobody, a user and an admin; the ones that disobey its contract | | |
| 135 | 135 | | `profile` | `{ displayName?, email?, commitEmail? }`: your own profile (`publicUser` and `emailVerified`, never the address); with an argument it changes it by the rules of `PATCH /api/v1/user`, and needs admin scope: only a site admin can mint such a token, so most people sign in to `/mcp` with their password | yes | |
| 136 | 136 | | `prompts` | (admin scope) `{ repo, action, kind?, token?, at?, id? }`: list, add, run or remove an app's prompt sources (Instagram), as the `…/prompts` API does; the token goes in once and is never shown; listed only for an admin-scope token, and only the repository's admin may use it | yes | |
src/apps/preview_view.ts +22 −1
| @@ -14,6 +14,8 @@ import { mayView, mayViewId } from "../core/sealed.ts"; | ||
| 14 | 14 | import { canRead, getRepoById } from "../core/repos.ts"; |
| 15 | 15 | import { getUserById, type User } from "../core/users.ts"; |
| 16 | 16 | import { resolveAppHostname } from "./proxy.ts"; |
| 17 | import { appsRuntime } from "./runtime.ts"; | |
| 18 | import { servingSays, servingState, type ServingInput, type ServingState } from "./serving_words.ts"; | |
| 17 | 19 | |
| 18 | 20 | export interface PreviewView { |
| 19 | 21 | readonly app: string; |
| @@ -23,6 +25,12 @@ export interface PreviewView { | ||
| 23 | 25 | readonly firstFailure: string | null; |
| 24 | 26 | readonly logUrl: string | null; |
| 25 | 27 | readonly working: readonly string[]; |
| 28 | /** Whether anything answers at the address, in the words the proxy's page uses. */ | |
| 29 | readonly serving: { | |
| 30 | readonly state: ServingState; | |
| 31 | readonly says: string; | |
| 32 | readonly runUrl: string | null; | |
| 33 | }; | |
| 26 | 34 | } |
| 27 | 35 | |
| 28 | 36 | export type PreviewRefusal = "foreign" | "no_such_app" | "no_such_pull"; |
| @@ -50,11 +58,13 @@ export function previewOf( | ||
| 50 | 58 | let firstFailure: string | null = null; |
| 51 | 59 | let logUrl: string | null = null; |
| 52 | 60 | let pullIssueId: string | undefined; |
| 61 | let foundPull: ServingInput["pull"]; | |
| 53 | 62 | if (number !== undefined) { |
| 54 | 63 | const found = getPull(db, repo.id, Number(number)); |
| 55 | 64 | if (found === undefined || !mayView(db, repo, found, user)) |
| 56 | 65 | return { ok: false, error: "no_such_pull", number: Number(number) }; |
| 57 | 66 | pullIssueId = found.id; |
| 67 | foundPull = found; | |
| 58 | 68 | pull = { number: found.number, title: found.title }; |
| 59 | 69 | const { state, run } = checkSummary(db, found.id, found.headOid); |
| 60 | 70 | check = |
| @@ -73,8 +83,19 @@ export function previewOf( | ||
| 73 | 83 | const who = run.actorId === null ? undefined : getUserById(db, run.actorId); |
| 74 | 84 | if (who !== undefined) working.add(who.username); |
| 75 | 85 | } |
| 86 | const runtime = appsRuntime(app); | |
| 87 | const status = runtime?.envStatus(target.app, target.env); | |
| 88 | const input: ServingInput = { status, preview: number !== undefined, pull: foundPull }; | |
| 89 | const serving = { | |
| 90 | state: servingState(input), | |
| 91 | says: servingSays(input), | |
| 92 | runUrl: | |
| 93 | runtime === undefined || status?.runId === undefined | |
| 94 | ? null | |
| 95 | : `${runtime.options.forgeUrl}/runs/${status.runId}`, | |
| 96 | }; | |
| 76 | 97 | return { |
| 77 | 98 | ok: true, |
| 78 | value: { app: name, environment: target.env, pull, check, firstFailure, logUrl, working: [...working] }, | |
| 99 | value: { app: name, environment: target.env, pull, check, firstFailure, logUrl, working: [...working], serving }, | |
| 79 | 100 | }; |
| 80 | 101 | } |
src/apps/proxy.ts +5 −13
| @@ -14,6 +14,7 @@ | ||
| 14 | 14 | * directory — so guessing a hostname yields the forge's own "not found". |
| 15 | 15 | */ |
| 16 | 16 | |
| 17 | import { isAbsent, isGone, notServingSays, type ServingInput } from "./serving_words.ts"; | |
| 17 | 18 | import { compressBytes, MIN_BYTES, negotiate } from "../http/compress.ts"; |
| 18 | 19 | import type { Database } from "bun:sqlite"; |
| 19 | 20 | import { getIssue, type Issue } from "../core/issues.ts"; |
| @@ -1597,22 +1598,13 @@ export function unavailable( | ||
| 1597 | 1598 | ? undefined |
| 1598 | 1599 | : getIssue(runtime.app.db, target.app.repoId, at.pull); |
| 1599 | 1600 | const preview = target.env !== "production"; |
| 1600 | const gone = preview && (pull === undefined || pull.state === "closed"); | |
| 1601 | const serving: ServingInput = { status, preview, pull }; | |
| 1602 | const gone = isGone(serving); | |
| 1601 | 1603 | // Nothing was ever deployed for an open pull: also a 404, for the same |
| 1602 | 1604 | // edge, since there is nothing at this address yet. A stopped or failed |
| 1603 | 1605 | // environment keeps its 502. |
| 1604 | const absent = preview && !gone && status === undefined; | |
| 1605 | const message = | |
| 1606 | reason ?? | |
| 1607 | (deploying | |
| 1608 | ? "A new version is starting." | |
| 1609 | : state === "failed" || (state === "asleep" && status?.error !== undefined) | |
| 1610 | ? (status?.error ?? "The last deploy failed.") | |
| 1611 | : gone | |
| 1612 | ? "This preview is gone: its pull was closed, and its data with it." | |
| 1613 | : absent | |
| 1614 | ? "The preview is not running. It starts again with the next push to the pull, or with app_deploy redeploy." | |
| 1615 | : "Nothing is running here yet."); | |
| 1606 | const absent = isAbsent(serving); | |
| 1607 | const message = reason ?? notServingSays(serving); | |
| 1616 | 1608 | const links = discoveryLinks(runtime, target); |
| 1617 | 1609 | const report = links.length > 0; |
| 1618 | 1610 | const runLink = |
src/apps/serving_words.ts added +59
| @@ -0,0 +1,59 @@ | ||
| 1 | /** | |
| 2 | * Whether an environment is serving, in words: the one place the proxy's | |
| 3 | * not-serving page and the MCP `preview` tool take their sentence from, so a | |
| 4 | * person at the address and an agent handed it read the same thing. | |
| 5 | * Plain data in, plain data out. | |
| 6 | */ | |
| 7 | ||
| 8 | import { redactSecrets } from "../kernel/log.ts"; | |
| 9 | import type { EnvStatus } from "./runtime.ts"; | |
| 10 | ||
| 11 | export type ServingState = "running" | "starting" | "failed" | "not_running" | "gone"; | |
| 12 | ||
| 13 | export interface ServingInput { | |
| 14 | readonly status: EnvStatus | undefined; | |
| 15 | /** A pull's preview, not production. */ | |
| 16 | readonly preview: boolean; | |
| 17 | /** The pull behind a preview: absent when it does not exist. An open pull is never gone. */ | |
| 18 | readonly pull: { readonly state: string } | undefined; | |
| 19 | } | |
| 20 | ||
| 21 | /** A preview is gone when its pull is closed, merged or no longer exists. */ | |
| 22 | export function isGone(input: ServingInput): boolean { | |
| 23 | return input.preview && (input.pull === undefined || input.pull.state === "closed"); | |
| 24 | } | |
| 25 | ||
| 26 | /** An open pull whose environment was never deployed. */ | |
| 27 | export function isAbsent(input: ServingInput): boolean { | |
| 28 | return input.preview && !isGone(input) && input.status === undefined; | |
| 29 | } | |
| 30 | ||
| 31 | export function servingState(input: ServingInput): ServingState { | |
| 32 | const state = input.status?.state ?? "stopped"; | |
| 33 | if (state === "deploying") return "starting"; | |
| 34 | if (state === "failed" || (state === "asleep" && input.status?.error !== undefined)) return "failed"; | |
| 35 | if (isGone(input)) return "gone"; | |
| 36 | if (state === "running") return "running"; | |
| 37 | return "not_running"; | |
| 38 | } | |
| 39 | ||
| 40 | /** The sentence the not-serving page shows. A build log's text is redacted. */ | |
| 41 | export function notServingSays(input: ServingInput): string { | |
| 42 | switch (servingState(input)) { | |
| 43 | case "starting": | |
| 44 | return "A new version is starting."; | |
| 45 | case "failed": | |
| 46 | return redactSecrets(input.status?.error ?? "The last deploy failed."); | |
| 47 | case "gone": | |
| 48 | return "This preview is gone: its pull was closed, and its data with it."; | |
| 49 | default: | |
| 50 | return isAbsent(input) | |
| 51 | ? "The preview is not running. It starts again with the next push to the pull, or with app_deploy redeploy." | |
| 52 | : "Nothing is running here yet."; | |
| 53 | } | |
| 54 | } | |
| 55 | ||
| 56 | /** `notServingSays`, or that the environment is serving. */ | |
| 57 | export function servingSays(input: ServingInput): string { | |
| 58 | return servingState(input) === "running" ? "It is serving." : notServingSays(input); | |
| 59 | } |
src/http/mcp/tools/preview.ts +1 −1
| @@ -4,7 +4,7 @@ import { good, bad, type Tool } from "../shared.ts"; | ||
| 4 | 4 | |
| 5 | 5 | export const tool: Tool = { |
| 6 | 6 | name: "preview", |
| 7 | doc: "`{ url }`: what the forge pill says of an app host's URL (production or a pull's preview): `{ app, environment, pull: { number, title } \\| null, check: \"green\" \\| \"red\" \\| \"running\" \\| null, firstFailure, logUrl, working: [names] }`; `firstFailure` is the check's first failing test or its summary, `logUrl` is set only for someone who may read the log (a writer), `working` names the agents with a run going; a URL that is not one of this forge's app hosts is `invalid`, an app you cannot read is `not_found` and a pull you cannot see is `no_such_pull`, as `repo` and `pull` say", | |
| 7 | doc: "`{ url }`: what the forge pill says of an app host's URL (production or a pull's preview): `{ app, environment, pull: { number, title } \\| null, check: \"green\" \\| \"red\" \\| \"running\" \\| null, firstFailure, logUrl, working: [names], serving: { state: \"running\" \\| \"starting\" \\| \"failed\" \\| \"not_running\" \\| \"gone\", says, runUrl } }`; `firstFailure` is the check's first failing test or its summary, `logUrl` is set only for someone who may read the log (a writer), `working` names the agents with a run going, `serving.says` is the sentence the app's own not-serving page shows (an open pull's preview is never `gone`) and `runUrl` the run it links; a URL that is not one of this forge's app hosts is `invalid`, an app you cannot read is `not_found` and a pull you cannot see is `no_such_pull`, as `repo` and `pull` say", | |
| 8 | 8 | description: |
| 9 | 9 | "An app URL's pull, check, first failure, log.", |
| 10 | 10 | inputSchema: { |
test/mcp-preview.test.ts +13
| @@ -11,6 +11,7 @@ import { AppsRuntime } from "../src/apps/runtime.ts"; | ||
| 11 | 11 | import { newApp } from "../src/actions/apps.ts"; |
| 12 | 12 | import { openPull } from "../src/actions/pulls.ts"; |
| 13 | 13 | import { commitToBranch } from "../src/actions/repos.ts"; |
| 14 | import { getAppByRepo } from "../src/core/apps.ts"; | |
| 14 | 15 | import { getRepo } from "../src/core/repos.ts"; |
| 15 | 16 | import { claimRun, createRun, finishRun } from "../src/core/runs.ts"; |
| 16 | 17 | import { getPull } from "../src/core/pulls.ts"; |
| @@ -110,7 +111,19 @@ describe("MCP preview", () => { | ||
| 110 | 111 | firstFailure: null, |
| 111 | 112 | logUrl: null, |
| 112 | 113 | working: [], |
| 114 | serving: expect.anything(), | |
| 113 | 115 | }); |
| 116 | // The app really deploys here, so the state is the runtime's own to say. | |
| 117 | const { state, says } = r.value.serving; | |
| 118 | expect(["starting", "failed", "running", "not_running"]).toContain(state); | |
| 119 | expect(says.length).toBeGreaterThan(0); | |
| 120 | }); | |
| 121 | ||
| 122 | test("an open pull's preview is never gone, and says what the page says", async () => { | |
| 123 | const r = await tool(bobRw, { url: host(`hello--${redPull}`) }); | |
| 124 | expect(r.value.serving.state).not.toBe("gone"); | |
| 125 | const status = runtime.envStatus(getAppByRepo(app.db, getRepo(app.db, "alice", "hello")!.id)!, `pull-${redPull}`); | |
| 126 | expect(r.value.serving.runUrl === null).toBe(status?.runId === undefined); | |
| 114 | 127 | }); |
| 115 | 128 | |
| 116 | 129 | test("a preview URL with a red check says the pull, the failure and the log", async () => { |
test/serving-words.test.ts added +48
| @@ -0,0 +1,48 @@ | ||
| 1 | /** | |
| 2 | * One sentence for an environment that is not serving, shared by the proxy's | |
| 3 | * page and the MCP `preview` tool: a test per state. | |
| 4 | */ | |
| 5 | import { expect, test } from "bun:test"; | |
| 6 | import type { EnvStatus } from "../src/apps/runtime.ts"; | |
| 7 | import { notServingSays, servingSays, servingState } from "../src/apps/serving_words.ts"; | |
| 8 | ||
| 9 | const env = (state: EnvStatus["state"], error?: string): EnvStatus => | |
| 10 | ({ env: "production", state, commitOid: "a", url: "", error }) as EnvStatus; | |
| 11 | const open = { state: "open" }; | |
| 12 | ||
| 13 | test("running", () => { | |
| 14 | const input = { status: env("running"), preview: true, pull: open }; | |
| 15 | expect(servingState(input)).toBe("running"); | |
| 16 | expect(servingSays(input)).toBe("It is serving."); | |
| 17 | }); | |
| 18 | ||
| 19 | test("starting", () => { | |
| 20 | const input = { status: env("deploying"), preview: false, pull: undefined }; | |
| 21 | expect(servingState(input)).toBe("starting"); | |
| 22 | expect(servingSays(input)).toBe("A new version is starting."); | |
| 23 | }); | |
| 24 | ||
| 25 | test("failed carries its error, redacted", () => { | |
| 26 | const input = { status: env("failed", "boom token abcdefghijklmnopqrstuvwxyz"), preview: true, pull: open }; | |
| 27 | expect(servingState(input)).toBe("failed"); | |
| 28 | expect(servingSays(input)).toBe("boom [redacted]"); | |
| 29 | expect(servingSays({ status: env("failed"), preview: false, pull: undefined })).toBe("The last deploy failed."); | |
| 30 | }); | |
| 31 | ||
| 32 | test("not running: an open pull's preview is never gone", () => { | |
| 33 | const never = { status: undefined, preview: true, pull: open }; | |
| 34 | expect(servingState(never)).toBe("not_running"); | |
| 35 | expect(servingSays(never)).toContain("starts again with the next push"); | |
| 36 | const stopped = { status: env("stopped"), preview: true, pull: open }; | |
| 37 | expect(servingState(stopped)).toBe("not_running"); | |
| 38 | expect(servingState({ status: undefined, preview: false, pull: undefined })).toBe("not_running"); | |
| 39 | expect(servingSays({ status: undefined, preview: false, pull: undefined })).toBe("Nothing is running here yet."); | |
| 40 | }); | |
| 41 | ||
| 42 | test("gone: a closed or missing pull", () => { | |
| 43 | for (const pull of [{ state: "closed" }, undefined]) { | |
| 44 | const input = { status: env("running"), preview: true, pull }; | |
| 45 | expect(servingState(input)).toBe("gone"); | |
| 46 | expect(notServingSays(input)).toContain("This preview is gone"); | |
| 47 | } | |
| 48 | }); |
new above
offline