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

Parked opened this
Closed without merging

mason/forge:mason/8159-mcp-preview-says-whether-the-environment → main 2 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
7 files changed +149 −16
docs/MCP.md +1 −1
@@ -130,7 +130,7 @@ for a tunnel and a forge that sleeps.
130130 | `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 | |
131131 | `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 |
132132 | `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 | |
134134 | `probe` | knock on a running app's doors as nobody, a user and an admin; the ones that disobey its contract | |
135135 | `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 |
136136 | `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";
1414 import { canRead, getRepoById } from "../core/repos.ts";
1515 import { getUserById, type User } from "../core/users.ts";
1616 import { resolveAppHostname } from "./proxy.ts";
17 import { appsRuntime } from "./runtime.ts";
18 import { servingSays, servingState, type ServingInput, type ServingState } from "./serving_words.ts";
1719
1820 export interface PreviewView {
1921 readonly app: string;
@@ -23,6 +25,12 @@ export interface PreviewView {
2325 readonly firstFailure: string | null;
2426 readonly logUrl: string | null;
2527 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 };
2634 }
2735
2836 export type PreviewRefusal = "foreign" | "no_such_app" | "no_such_pull";
@@ -50,11 +58,13 @@ export function previewOf(
5058 let firstFailure: string | null = null;
5159 let logUrl: string | null = null;
5260 let pullIssueId: string | undefined;
61 let foundPull: ServingInput["pull"];
5362 if (number !== undefined) {
5463 const found = getPull(db, repo.id, Number(number));
5564 if (found === undefined || !mayView(db, repo, found, user))
5665 return { ok: false, error: "no_such_pull", number: Number(number) };
5766 pullIssueId = found.id;
67 foundPull = found;
5868 pull = { number: found.number, title: found.title };
5969 const { state, run } = checkSummary(db, found.id, found.headOid);
6070 check =
@@ -73,8 +83,19 @@ export function previewOf(
7383 const who = run.actorId === null ? undefined : getUserById(db, run.actorId);
7484 if (who !== undefined) working.add(who.username);
7585 }
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 };
7697 return {
7798 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 },
79100 };
80101 }
src/apps/proxy.ts +5 −13
@@ -14,6 +14,7 @@
1414 * directory — so guessing a hostname yields the forge's own "not found".
1515 */
1616
17 import { isAbsent, isGone, notServingSays, type ServingInput } from "./serving_words.ts";
1718 import { compressBytes, MIN_BYTES, negotiate } from "../http/compress.ts";
1819 import type { Database } from "bun:sqlite";
1920 import { getIssue, type Issue } from "../core/issues.ts";
@@ -1597,22 +1598,13 @@ export function unavailable(
15971598 ? undefined
15981599 : getIssue(runtime.app.db, target.app.repoId, at.pull);
15991600 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);
16011603 // Nothing was ever deployed for an open pull: also a 404, for the same
16021604 // edge, since there is nothing at this address yet. A stopped or failed
16031605 // 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);
16161608 const links = discoveryLinks(runtime, target);
16171609 const report = links.length > 0;
16181610 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";
44
55 export const tool: Tool = {
66 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",
88 description:
99 "An app URL's pull, check, first failure, log.",
1010 inputSchema: {
test/mcp-preview.test.ts +13
@@ -11,6 +11,7 @@ import { AppsRuntime } from "../src/apps/runtime.ts";
1111 import { newApp } from "../src/actions/apps.ts";
1212 import { openPull } from "../src/actions/pulls.ts";
1313 import { commitToBranch } from "../src/actions/repos.ts";
14 import { getAppByRepo } from "../src/core/apps.ts";
1415 import { getRepo } from "../src/core/repos.ts";
1516 import { claimRun, createRun, finishRun } from "../src/core/runs.ts";
1617 import { getPull } from "../src/core/pulls.ts";
@@ -110,7 +111,19 @@ describe("MCP preview", () => {
110111 firstFailure: null,
111112 logUrl: null,
112113 working: [],
114 serving: expect.anything(),
113115 });
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);
114127 });
115128
116129 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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs