Public: anyone can read this; the crew can change it.

Fleet query language and the fleet table: repos, runs, issues, apps, crew behind one visible query in the URL #10165

Closed opened this in answer to
Closed without merging

scout/forge:scout/446-fleet-query-language-and-the-fleet-table → main 2 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
8 files changed +752 −44
docs/FLEET.md +18 −3
@@ -18,7 +18,7 @@ curl -sX POST $FORGE/api/v1/fleet/ops/$ID/undo -H "authorization: Bearer $ADMIN"
1818
1919 ## The query
2020
21 A kind — `repo`, `run` or `issue` — then `field:value` terms, all of which
21 A kind — `repo`, `run` or `issue` (and, for the table only, `app` or `crew`) — then `field:value` terms, all of which
2222 must hold. `!` before a value negates it. `repo:owner/name` (or a bare name)
2323 works on every kind.
2424
@@ -28,9 +28,24 @@ works on every kind.
2828 | run | `repo` `owner` `name` `id` `state` `kind` `agent` `issue` |
2929 | issue | `repo` `owner` `name` `id` `number` `state` `assignee` (`none`) `label` |
3030
31 | app | `repo` `owner` `name` `slug` `access` `created` (date) |
32 | crew | `repo` `owner` `name` `member` `added` (date) |
33
34 Fields with an order take `>`, `>=`, `<`, `<=` after the colon (and after any
35 `!`): `run cost:>=1`, `issue created:<2026-09-01`, `run state:!ok cost:>0.5`.
36 They are `run` `cost` `created` `finished`; `issue` `number` `created`
37 `updated`; `repo` `created`. Dates are `YYYY-MM-DD` (or with `THH:MM`).
38
3139 Only rows you can read are selected. More than 500 rows is refused
32 (`too_many`), never cut. This grammar is `src/fleet/selection.ts`; the fleet
33 table (#446) grows it.
40 (`too_many`), never cut. This grammar is `src/fleet/selection.ts`.
41
42 ## The table
43
44 `/fleet?q=<query>&sort=<column>|-<column>&limit=&offset=` lists the rows the
45 same line selects, one page (100 rows by default, 1,000 at most), with the
46 total, sortable column headers, and the query line in the URL. A line that
47 does not parse is a 400 that says why. `src/fleet/table.ts` owns columns and
48 paging; `src/web/pages/fleet.ts` the page.
3449
3550 ## The actions
3651
forge.json +1 −1
@@ -6,7 +6,7 @@
66 "ready": 90
77 },
88 "check": {
9 "run": "bun x tsc --noEmit && bun scripts/test-shards.ts --timeout 60000 test/crew.test.ts test/crew-wrapup.test.ts test/crew-limits.test.ts test/crew-sandbox.test.ts test/steer.test.ts test/landing.test.ts test/decide.test.ts test/ledger.test.ts test/checks.test.ts test/dependencies.test.ts test/autonomy.test.ts test/studio.test.ts test/studio-words.test.ts test/forks.test.ts test/fork-flow.test.ts test/cross-repo-pull.test.ts test/pulls.test.ts test/apps.test.ts test/apps-adversarial.test.ts test/apps-busy.test.ts test/apps-token.test.ts test/web.test.ts test/git-trust.test.ts test/helpers.test.ts test/shards.test.ts test/migrate.test.ts test/vitals.test.ts test/asks.test.ts test/feed.test.ts test/feed-page.test.ts test/offline.test.ts test/share.test.ts test/cloud.test.ts test/run-secrets.test.ts test/forge-cloudflare.test.ts test/usage.test.ts test/standing.test.ts test/board-windows.test.ts test/spawn-plan.test.ts test/spawn.test.ts test/web-apps.test.ts test/fleet-ops.test.ts",
9 "run": "bun x tsc --noEmit && bun scripts/test-shards.ts --timeout 60000 test/crew.test.ts test/crew-wrapup.test.ts test/crew-limits.test.ts test/crew-sandbox.test.ts test/steer.test.ts test/landing.test.ts test/decide.test.ts test/ledger.test.ts test/checks.test.ts test/dependencies.test.ts test/autonomy.test.ts test/studio.test.ts test/studio-words.test.ts test/forks.test.ts test/fork-flow.test.ts test/cross-repo-pull.test.ts test/pulls.test.ts test/apps.test.ts test/apps-adversarial.test.ts test/apps-busy.test.ts test/apps-token.test.ts test/web.test.ts test/git-trust.test.ts test/helpers.test.ts test/shards.test.ts test/migrate.test.ts test/vitals.test.ts test/asks.test.ts test/feed.test.ts test/feed-page.test.ts test/offline.test.ts test/share.test.ts test/cloud.test.ts test/run-secrets.test.ts test/forge-cloudflare.test.ts test/usage.test.ts test/standing.test.ts test/board-windows.test.ts test/spawn-plan.test.ts test/spawn.test.ts test/web-apps.test.ts test/fleet-*.test.ts",
1010 "timeout": 1800
1111 }
1212 }
src/fleet/selection.ts +140 −38
@@ -4,9 +4,11 @@
44 * The line is a kind and then `field:value` terms, all of which must hold:
55 * `repo autonomy:autonomous`, `run state:queued repo:!trevato/forge`,
66 * `issue repo:engine label:bug assignee:none`. A value starting with `!`
7 * negates the term. This is the small grammar operations need to name their
8 * rows; the fleet table (#446) grows the language, and this module is the
9 * one seam it replaces.
7 * negates the term, and on a field with an order (a cost, a date, a number)
8 * the value may begin with `>`, `>=`, `<` or `<=`: `run cost:>=1`,
9 * `issue created:<2026-09-01`, `run state:!ok cost:>0.5`. The fleet table
10 * (`table.ts`, `/fleet`) reads the same language, and also selects `app`
11 * and `crew` rows, which no operation acts on.
1012 *
1113 * Only rows the viewer may read are ever selected — a repository you cannot
1214 * see is not refused, it is absent, the same ambiguity `not_found` keeps.
@@ -18,6 +20,9 @@ import type { User } from "../core/users.ts";
1820 import { err, ok, type Result } from "../kernel/result.ts";
1921
2022 export type FleetKind = "repo" | "run" | "issue";
23 /** What the fleet table can list: the operable kinds, and two it only reads. */
24 export type TableKind = FleetKind | "app" | "crew";
25 export type Op = "=" | ">" | ">=" | "<" | "<=";
2126
2227 /** More rows than this and the operator must narrow the query. */
2328 export const MAX_ROWS = 500;
@@ -28,18 +33,24 @@ export interface Term {
2833 readonly field: string;
2934 readonly value: string;
3035 readonly negate: boolean;
36 readonly op: Op;
3137 }
3238
33 export interface FleetQuery {
34 readonly kind: FleetKind;
39 export interface Query<K extends TableKind> {
40 readonly kind: K;
3541 readonly terms: readonly Term[];
3642 }
43 export type FleetQuery = Query<FleetKind>;
44 export type TableQuery = Query<TableKind>;
3745
3846 export type QueryError =
3947 | { code: "bad_query"; message: string }
4048 | { code: "too_many"; message: string };
4149
42 const KINDS: Record<string, FleetKind> = {
50 const KINDS: Record<string, TableKind> = {
51 app: "app",
52 apps: "app",
53 crew: "crew",
4354 repo: "repo",
4455 repos: "repo",
4556 run: "run",
@@ -60,7 +71,7 @@ const repoFields: Record<string, Predicate> = {
6071 name: (p) => `repo.name = ${p} COLLATE NOCASE`,
6172 };
6273
63 const FIELDS: Record<FleetKind, Record<string, Predicate>> = {
74 const FIELDS: Record<TableKind, Record<string, Predicate>> = {
6475 repo: {
6576 ...repoFields,
6677 id: (p) => `repo.id = ${p}`,
@@ -90,10 +101,44 @@ const FIELDS: Record<FleetKind, Record<string, Predicate>> = {
90101 `EXISTS (SELECT 1 FROM issue_label JOIN label ON label.id = issue_label.label_id
91102 WHERE issue_label.issue_id = issue.id AND label.name = ${p} COLLATE NOCASE)`,
92103 },
104 app: {
105 ...repoFields,
106 slug: (p) => `app.slug = ${p} COLLATE NOCASE`,
107 access: (p) => `app.access = ${p} COLLATE NOCASE`,
108 },
109 crew: {
110 ...repoFields,
111 member: (p) =>
112 `repo_crew.user_id IN (SELECT id FROM user AS m WHERE m.username = ${p} COLLATE NOCASE)`,
113 },
93114 };
94115
95 const FROM: Record<FleetKind, { table: string; from: string; order: string }> =
96 {
116 /**
117 * The fields that have an order, as the SQL expression they compare and
118 * whether the value is a number or a date. Only these take `>` and `<`.
119 */
120 type Ordered = { readonly expr: string; readonly as: "number" | "date" };
121 const ORDERED: Record<TableKind, Record<string, Ordered>> = {
122 repo: { created: { expr: "repo.created_at", as: "date" } },
123 run: {
124 cost: { expr: "run.cost_usd", as: "number" },
125 created: { expr: "run.created_at", as: "date" },
126 finished: { expr: "run.finished_at", as: "date" },
127 },
128 issue: {
129 number: { expr: "issue.number", as: "number" },
130 created: { expr: "issue.created_at", as: "date" },
131 updated: { expr: "issue.updated_at", as: "date" },
132 },
133 app: { created: { expr: "app.created_at", as: "date" } },
134 crew: { added: { expr: "repo_crew.added_at", as: "date" } },
135 };
136 const DATE = /^\d{4}-\d\d-\d\d(?:T\d\d:\d\d(?::\d\d(?:\.\d+)?)?Z?)?$/;
137
138 export const FROM: Record<
139 TableKind,
140 { table: string; from: string; order: string }
141 > = {
97142 repo: {
98143 table: "repo",
99144 from: "repo JOIN user ON user.id = repo.owner_id",
@@ -111,18 +156,40 @@ const FROM: Record<FleetKind, { table: string; from: string; order: string }> =
111156 JOIN user ON user.id = repo.owner_id`,
112157 order: "user.username, repo.name, issue.number",
113158 },
159 app: {
160 table: "app",
161 from: `app JOIN repo ON repo.id = app.repo_id
162 JOIN user ON user.id = repo.owner_id`,
163 order: "app.slug",
164 },
165 crew: {
166 table: "repo_crew",
167 from: `repo_crew JOIN repo ON repo.id = repo_crew.repo_id
168 JOIN user ON user.id = repo.owner_id`,
169 order: "user.username, repo.name, repo_crew.added_at",
170 },
114171 };
115172
116173 const bad = (message: string): Result<never, QueryError> =>
117174 err({ code: "bad_query", message });
118175
119 /** Read a query line. Every field is checked against its kind's list. */
176 /** Read a query line for an operation: only the kinds an action can act on. */
120177 export function parseQuery(text: string): Result<FleetQuery, QueryError> {
178 const q = parseTableQuery(text);
179 if (!q.ok) return q;
180 const kind = q.value.kind;
181 if (kind === "app" || kind === "crew")
182 return bad("an operation selects repo, run or issue rows");
183 return ok({ kind, terms: q.value.terms });
184 }
185
186 /** Read a query line. Every field is checked against its kind's list. */
187 export function parseTableQuery(text: string): Result<TableQuery, QueryError> {
121188 if (text.length > MAX_QUERY) return bad(`a query is at most ${MAX_QUERY} characters`);
122189 const [head, ...rest] = text.trim().split(/\s+/);
123190 const kind = KINDS[(head ?? "").toLowerCase()];
124191 if (kind === undefined)
125 return bad("a query starts with what it selects: repo, run or issue");
192 return bad("a query starts with what it selects: repo, run, issue, app or crew");
126193 if (rest.length > MAX_TERMS) return bad(`a query has at most ${MAX_TERMS} terms`);
127194 const terms: Term[] = [];
128195 for (const word of rest) {
@@ -131,17 +198,74 @@ export function parseQuery(text: string): Result<FleetQuery, QueryError> {
131198 let value = colon > 0 ? word.slice(colon + 1) : "";
132199 const negate = value.startsWith("!");
133200 if (negate) value = value.slice(1);
201 const opMatch = /^(>=|<=|>|<)/.exec(value);
202 const op = (opMatch?.[1] ?? "=") as Op;
203 if (opMatch) value = value.slice(op.length);
134204 if (field === "" || value === "")
135205 return bad(`"${word}" is not field:value`);
136 if (field !== "repo" && FIELDS[kind][field] === undefined)
206 const ordered = Object.hasOwn(ORDERED[kind], field)
207 ? ORDERED[kind][field]
208 : undefined;
209 if (field !== "repo" && ordered === undefined && FIELDS[kind][field] === undefined)
137210 return bad(
138 `${kind} has no field "${field}"; it has repo, ${Object.keys(FIELDS[kind]).join(", ")}`,
211 `${kind} has no field "${field}"; it has ${fieldNames(kind).join(", ")}`,
139212 );
140 terms.push({ field, value, negate });
213 if (op !== "=" && ordered === undefined)
214 return bad(`${field} has no order, so "${op}" does not apply to it`);
215 if (ordered?.as === "number" && !Number.isFinite(Number(value)))
216 return bad(`${field} is a number; "${value}" is not`);
217 if (ordered?.as === "date" && !DATE.test(value))
218 return bad(`${field} is a date like 2026-09-30; "${value}" is not`);
219 terms.push({ field, value, negate, op });
141220 }
142221 return ok({ kind, terms });
143222 }
144223
224 /** Every field a kind answers to, `repo` first. */
225 export const fieldNames = (kind: TableKind): string[] => [
226 ...new Set(["repo", ...Object.keys(FIELDS[kind]), ...Object.keys(ORDERED[kind])]),
227 ];
228
229 /**
230 * The WHERE clause a query means for `viewer`, with its bound parameters
231 * (`?1` is the viewer). Only readable repositories ever match. The one
232 * place a term becomes SQL: values are bound, never spliced.
233 */
234 export function whereFor(
235 viewer: User,
236 query: TableQuery,
237 ): { where: string; params: (string | number)[] } {
238 const params: (string | number)[] = [viewer.id];
239 const bind = (value: string | number): string => {
240 params.push(value);
241 return `?${params.length}`;
242 };
243 const where = [REPO_VISIBLE];
244 if (query.kind === "issue") where.push("issue.kind = 'issue'");
245 for (const term of query.terms) {
246 const ordered = Object.hasOwn(ORDERED[query.kind], term.field)
247 ? ORDERED[query.kind][term.field]
248 : undefined;
249 let sql: string;
250 if (term.field === "repo") {
251 // `owner/name`, or a bare name in any owner.
252 const slash = term.value.indexOf("/");
253 sql =
254 slash < 0
255 ? repoFields.name!(bind(term.value))
256 : `${repoFields.owner!(bind(term.value.slice(0, slash)))}
257 AND ${repoFields.name!(bind(term.value.slice(slash + 1)))}`;
258 } else if (ordered !== undefined)
259 sql = `${ordered.expr} ${term.op} ${bind(ordered.as === "number" ? Number(term.value) : term.value)}`;
260 else sql = FIELDS[query.kind][term.field]!(bind(term.value));
261 // COALESCE: a NULL comparison negated is still NULL, and `!x` must
262 // select the rows where x does not hold, including the empty ones.
263 const held = `COALESCE((${sql}), 0)`;
264 where.push(term.negate ? `NOT ${held}` : held);
265 }
266 return { where: where.join(" AND "), params };
267 }
268
145269 /**
146270 * The ids a query selects for `viewer`, in a stable order. More than
147271 * `MAX_ROWS` is refused rather than cut: an operation over the first 500
@@ -152,35 +276,13 @@ export function selectRows(
152276 viewer: User,
153277 query: FleetQuery,
154278 ): Result<string[], QueryError> {
155 const params: (string | number)[] = [viewer.id];
156 const bind = (value: string): string => {
157 params.push(value);
158 return `?${params.length}`;
159 };
160 const where = [REPO_VISIBLE];
161 if (query.kind === "issue") where.push("issue.kind = 'issue'");
162 for (const term of query.terms) {
163 let sql: string;
164 if (term.field === "repo") {
165 // `owner/name`, or a bare name in any owner.
166 const slash = term.value.indexOf("/");
167 sql =
168 slash < 0
169 ? repoFields.name!(bind(term.value))
170 : `${repoFields.owner!(bind(term.value.slice(0, slash)))}
171 AND ${repoFields.name!(bind(term.value.slice(slash + 1)))}`;
172 } else sql = FIELDS[query.kind][term.field]!(bind(term.value));
173 // COALESCE: a NULL comparison negated is still NULL, and `!x` must
174 // select the rows where x does not hold, including the empty ones.
175 const held = `COALESCE((${sql}), 0)`;
176 where.push(term.negate ? `NOT ${held}` : held);
177 }
279 const { where, params } = whereFor(viewer, query);
178280 const { table, from, order } = FROM[query.kind];
179281 params.push(MAX_ROWS + 1);
180282 const ids = db
181283 .query<{ id: string }, (string | number)[]>(
182284 `SELECT ${table}.id AS id FROM ${from}
183 WHERE ${where.join(" AND ")}
285 WHERE ${where}
184286 ORDER BY ${order} LIMIT ?${params.length}`,
185287 )
186288 .all(...params)
src/fleet/table.ts added +236
@@ -0,0 +1,236 @@
1 /**
2 * The fleet table's rows: one query line, one sort, one page of cells.
3 *
4 * The line is the language of `selection.ts` (so what the table shows is
5 * what an operation over the same line would act on), read by the same
6 * `whereFor` — only readable repositories ever appear. This module owns
7 * what selection does not: the columns of each kind, which of them sort,
8 * and the page. Every column and sort is a fixed SQL expression chosen from
9 * a list here; the URL only ever picks a name from that list.
10 */
11
12 import type { Database } from "bun:sqlite";
13 import type { User } from "../core/users.ts";
14 import { err, ok, type Result } from "../kernel/result.ts";
15 import {
16 FROM,
17 parseTableQuery,
18 whereFor,
19 type QueryError,
20 type TableKind,
21 } from "./selection.ts";
22
23 export const DEFAULT_LIMIT = 100;
24 export const MAX_LIMIT = 1000;
25
26 export interface Cell {
27 readonly text: string;
28 readonly href?: string;
29 /** Right-aligned: a count, a cost. */
30 readonly num?: boolean;
31 /** An ISO time, for the page to render as a time. */
32 readonly time?: boolean;
33 }
34
35 export interface Column {
36 readonly key: string;
37 readonly label: string;
38 readonly sortable: boolean;
39 }
40
41 export interface FleetTable {
42 readonly kind: TableKind;
43 readonly columns: readonly Column[];
44 readonly rows: readonly (readonly Cell[])[];
45 /** Rows matching, before the page. */
46 readonly total: number;
47 readonly offset: number;
48 readonly limit: number;
49 readonly sort: { readonly key: string; readonly desc: boolean };
50 }
51
52 interface Spec {
53 readonly key: string;
54 readonly label: string;
55 /** SELECT expression; also what sorting orders by. */
56 readonly expr: string;
57 readonly num?: boolean;
58 readonly time?: boolean;
59 /** Where a cell goes, given the row's owner/name and its own text. */
60 readonly href?: (base: string, text: string) => string;
61 }
62
63 const REPO = "user.username || '/' || repo.name";
64 const repoCol: Spec = {
65 key: "repo",
66 label: "Repo",
67 expr: REPO,
68 href: (base) => base,
69 };
70 const created = (expr: string): Spec => ({
71 key: "created",
72 label: "Created",
73 expr,
74 time: true,
75 });
76
77 const SPECS: Record<TableKind, readonly Spec[]> = {
78 repo: [
79 repoCol,
80 { key: "visibility", label: "Visibility", expr: "repo.visibility" },
81 { key: "autonomy", label: "Autonomy", expr: "repo.autonomy" },
82 {
83 key: "open",
84 label: "Open issues",
85 num: true,
86 expr: `(SELECT COUNT(*) FROM issue AS i WHERE i.repo_id = repo.id
87 AND i.kind = 'issue' AND i.state = 'open')`,
88 },
89 created("repo.created_at"),
90 ],
91 run: [
92 {
93 key: "id",
94 label: "Run",
95 expr: "run.id",
96 href: (base, text) => `${base}/runs/${text}`,
97 },
98 repoCol,
99 { key: "kind", label: "Kind", expr: "run.kind" },
100 { key: "state", label: "State", expr: "run.state" },
101 {
102 key: "agent",
103 label: "Agent",
104 expr: "COALESCE((SELECT a.username FROM user AS a WHERE a.id = run.actor_id), '')",
105 },
106 { key: "cost", label: "Cost", num: true, expr: "run.cost_usd" },
107 created("run.created_at"),
108 ],
109 issue: [
110 repoCol,
111 { key: "number", label: "#", num: true, expr: "issue.number" },
112 { key: "title", label: "Title", expr: "issue.title" },
113 { key: "state", label: "State", expr: "issue.state" },
114 {
115 key: "assignee",
116 label: "Assignee",
117 expr: "COALESCE((SELECT a.username FROM user AS a WHERE a.id = issue.assignee_id), '')",
118 },
119 { key: "updated", label: "Updated", expr: "issue.updated_at", time: true },
120 ],
121 app: [
122 { key: "slug", label: "App", expr: "app.slug", href: (base) => base },
123 repoCol,
124 { key: "access", label: "Access", expr: "app.access" },
125 created("app.created_at"),
126 ],
127 crew: [
128 repoCol,
129 {
130 key: "member",
131 label: "Member",
132 expr: "(SELECT m.username FROM user AS m WHERE m.id = repo_crew.user_id)",
133 },
134 { key: "added", label: "Added", expr: "repo_crew.added_at", time: true },
135 ],
136 };
137
138 /** The link a row's number or title points at, per kind. */
139 const ROW_HREF: Partial<Record<TableKind, string>> = {
140 issue: "issue.number",
141 };
142
143 export interface TableRequest {
144 readonly q: string;
145 /** `key` ascending, `-key` descending; empty for the kind's own order. */
146 readonly sort?: string;
147 readonly limit?: number;
148 readonly offset?: number;
149 }
150
151 const whole = (n: number | undefined, fallback: number, max: number): number =>
152 n === undefined || !Number.isInteger(n) || n < 0 ? fallback : Math.min(n, max);
153
154 /** Columns a kind shows; the page header reads this too. */
155 export const columnsOf = (kind: TableKind): Column[] =>
156 SPECS[kind].map(({ key, label }) => ({ key, label, sortable: true }));
157
158 export function fleetTable(
159 db: Database,
160 viewer: User,
161 req: TableRequest,
162 ): Result<FleetTable, QueryError> {
163 const parsed = parseTableQuery(req.q);
164 if (!parsed.ok) return parsed;
165 const query = parsed.value;
166 const specs = SPECS[query.kind];
167
168 const rawSort = req.sort ?? "";
169 const desc = rawSort.startsWith("-");
170 const key = desc ? rawSort.slice(1) : rawSort;
171 const sortSpec = specs.find((s) => s.key === key);
172 if (rawSort !== "" && sortSpec === undefined)
173 return err({
174 code: "bad_query",
175 message: `${query.kind} has no column "${key}" to sort by`,
176 });
177
178 const limit = whole(req.limit, DEFAULT_LIMIT, MAX_LIMIT) || DEFAULT_LIMIT;
179 const offset = whole(req.offset, 0, 1_000_000);
180 const { where, params } = whereFor(viewer, query);
181 const { from, order } = FROM[query.kind];
182
183 const select = specs.map((s, i) => `${s.expr} AS c${i}`).join(", ");
184 const orderBy = sortSpec
185 ? `${sortSpec.expr} ${desc ? "DESC" : "ASC"}, ${order}`
186 : order;
187 params.push(limit + 1, offset);
188 const fetched = db
189 .query<Record<string, string | number | null>, (string | number)[]>(
190 `SELECT user.username AS owner, repo.name AS name, ${select},
191 ${ROW_HREF[query.kind] ?? "NULL"} AS n
192 FROM ${from} WHERE ${where}
193 ORDER BY ${orderBy} LIMIT ?${params.length - 1} OFFSET ?${params.length}`,
194 )
195 .all(...params);
196
197 // One row past the page tells whether it is the whole: no second scan.
198 const raw = fetched.slice(0, limit);
199 const total =
200 offset === 0 && fetched.length <= limit
201 ? fetched.length
202 : (db
203 .query<{ n: number }, (string | number)[]>(
204 `SELECT COUNT(*) AS n FROM ${from} WHERE ${where}`,
205 )
206 .get(...params.slice(0, params.length - 2))?.n ?? 0);
207
208 const rows = raw.map((r) => {
209 const base = `/${r.owner}/${r.name}`;
210 return specs.map((s, i): Cell => {
211 const v = r[`c${i}`];
212 const text = v === null || v === undefined ? "" : String(v);
213 const shown =
214 s.key === "cost" && typeof v === "number" ? `$${v.toFixed(2)}` : text;
215 let href = s.href?.(base, text);
216 if (query.kind === "issue" && s.key === "title")
217 href = `${base}/issues/${r.n}`;
218 return {
219 text: shown,
220 ...(href !== undefined ? { href } : {}),
221 ...(s.num ? { num: true } : {}),
222 ...(s.time && text !== "" ? { time: true } : {}),
223 };
224 });
225 });
226
227 return ok({
228 kind: query.kind,
229 columns: columnsOf(query.kind),
230 rows,
231 total,
232 offset,
233 limit,
234 sort: { key, desc },
235 });
236 }
src/http/server.ts +2
@@ -112,6 +112,7 @@ import {
112112 newTellPage,
113113 tellPage,
114114 } from "../web/pages/issues.ts";
115 import { fleetPage } from "../web/pages/fleet.ts";
115116 import { globalMapPage, mapPage } from "../web/pages/map.ts";
116117 import {
117118 modeSubmit,
@@ -460,6 +461,7 @@ export function buildRouter(): Router<Handler> {
460461 router.add("GET", "/migrate/jobs/:job", migrationJobPage);
461462 // Every app on one canvas; a literal route, so it must sit above /:owner.
462463 router.add("GET", "/map", globalMapPage);
464 router.add("GET", "/fleet", fleetPage);
463465 // Live regions' own addresses (docs/STUDIO.md, "Live regions"): the
464466 // home's shelf and its "On you" card answer for themselves, so an event
465467 // fetches a region and not the page. Literal, above /:owner.
src/web/pages/fleet.ts added +146
@@ -0,0 +1,146 @@
1 /**
2 * /fleet — the fleet as one table. The query line is the whole state and
3 * lives in the URL (`?q=run state:failed cost:>1&sort=-cost`), so a view is
4 * a link: bookmark it, send it, run an operation over the same line.
5 * Server-rendered, no script; a sortable header is a link, the form is a
6 * plain GET.
7 */
8
9 import {
10 fleetTable,
11 type Cell,
12 type FleetTable,
13 } from "../../fleet/table.ts";
14 import type { Ctx } from "../../http/context.ts";
15 import { signInFirst, pageHead } from "../chrome.ts";
16 import { html, type Html } from "../html.ts";
17 import { page } from "../layout.ts";
18 import { btn, empty, pager, time } from "../ui.ts";
19
20 const DEFAULT_QUERY = "repo";
21 const HELP =
22 "repo, run, issue, app or crew, then field:value terms — !negates, > >= < <= compare cost, number and dates, repo:owner/name scopes.";
23
24 const fleetCss = `
25 .fleet-form { display: flex; gap: 8px; margin: 0 0 12px; }
26 .fleet-form input[name=q] { flex: 1; font-family: var(--mono); min-width: 0; }
27 .fleet-count { margin: 0 0 8px; color: var(--muted, inherit); font-size: 13px; }
28 .fleet-err { margin: 0 0 12px; color: var(--danger, #b00020); }
29 .fleet-table th a { color: inherit; text-decoration: none; }
30 .fleet-table th[aria-sort] a { text-decoration: underline; }
31 .fleet-table td.num, .fleet-table th.num { text-align: right; font-variant-numeric: tabular-nums; }
32 `;
33
34 /** A link to this page with some of its state changed. */
35 const href = (q: string, sort: string, offset: number, limit: number): string => {
36 const u = new URLSearchParams({ q });
37 if (sort !== "") u.set("sort", sort);
38 if (offset > 0) u.set("offset", String(offset));
39 if (limit !== 100) u.set("limit", String(limit));
40 return `/fleet?${u}`;
41 };
42
43 const cell = (c: Cell): Html => {
44 const inner = c.time ? time(c.text) : html`${c.text}`;
45 return html`<td class="${c.num ? "num" : ""}">
46 ${c.href ? html`<a href="${c.href}">${inner}</a>` : inner}
47 </td>`;
48 };
49
50 function tableHtml(q: string, t: FleetTable): Html {
51 return html`<div class="table-scroll">
52 <table class="table fleet-table" data-dense>
53 <thead>
54 <tr>
55 ${t.columns.map((col) => {
56 const active = t.sort.key === col.key;
57 // A first click sorts ascending; a second flips it.
58 const next = active && !t.sort.desc ? `-${col.key}` : col.key;
59 const aria = active
60 ? t.sort.desc
61 ? "descending"
62 : "ascending"
63 : null;
64 return html`<th scope="col" ${aria ? html`aria-sort="${aria}"` : null}>
65 <a href="${href(q, next, 0, t.limit)}">${col.label}</a>
66 </th>`;
67 })}
68 </tr>
69 </thead>
70 <tbody>
71 ${t.rows.map((r) => html`<tr>${r.map(cell)}</tr>`)}
72 </tbody>
73 </table>
74 </div>`;
75 }
76
77 // GET /fleet
78 export function fleetPage(ctx: Ctx): Response {
79 const viewer = ctx.auth.user;
80 if (!viewer) return signInFirst(ctx);
81 const p = ctx.url.searchParams;
82 const q = (p.get("q") ?? "").trim() || DEFAULT_QUERY;
83 const sort = p.get("sort") ?? "";
84 const result = fleetTable(ctx.app.db, viewer, {
85 q,
86 sort,
87 ...(p.has("limit") ? { limit: Number(p.get("limit")) } : {}),
88 ...(p.has("offset") ? { offset: Number(p.get("offset")) } : {}),
89 });
90
91 const form = html`<form class="fleet-form" method="get" action="/fleet" role="search">
92 <input
93 name="q"
94 value="${q}"
95 maxlength="500"
96 aria-label="Fleet query"
97 placeholder="${DEFAULT_QUERY}"
98 spellcheck="false"
99 autocomplete="off"
100 />
101 ${sort !== "" ? html`<input type="hidden" name="sort" value="${sort}" />` : null}
102 ${btn("Run", { type: "submit" })}
103 </form>`;
104
105 let body: Html;
106 let status = 200;
107 if (!result.ok) {
108 status = 400;
109 body = html`<p class="fleet-err" role="alert">${result.error.message}</p>
110 <p class="muted">${HELP}</p>`;
111 } else {
112 const t = result.value;
113 const end = t.offset + t.rows.length;
114 body = html`<p class="fleet-count" aria-live="polite">
115 ${t.total === 0
116 ? "No rows"
117 : `${t.offset + 1}–${end} of ${t.total} ${t.kind} rows`}
118 </p>
119 ${t.rows.length === 0
120 ? empty({
121 title: "Nothing matches",
122 note: "Only rows you can read are counted. Loosen the query or check the field names.",
123 })
124 : tableHtml(q, t)}
125 ${pager({
126 ...(t.offset > 0
127 ? { prev: href(q, sortOf(t), Math.max(0, t.offset - t.limit), t.limit) }
128 : {}),
129 ...(end < t.total ? { next: href(q, sortOf(t), end, t.limit) } : {}),
130 })}`;
131 }
132
133 return page(
134 {
135 ctx,
136 title: "Fleet",
137 body: html`${pageHead("Fleet", { sub: HELP })}${form}${body}`,
138 styleCss: fleetCss,
139 wide: true,
140 },
141 status,
142 );
143 }
144
145 const sortOf = (t: FleetTable): string =>
146 t.sort.key === "" ? "" : `${t.sort.desc ? "-" : ""}${t.sort.key}`;
test/fleet-ops.test.ts +2 −2
@@ -107,8 +107,8 @@ describe("fleet operations", () => {
107107 expect(q.ok && q.value).toEqual({
108108 kind: "repo",
109109 terms: [
110 { field: "autonomy", value: "assisted", negate: false },
111 { field: "repo", value: "alice/tools", negate: true },
110 { field: "autonomy", value: "assisted", negate: false, op: "=" },
111 { field: "repo", value: "alice/tools", negate: true, op: "=" },
112112 ],
113113 });
114114 for (const bad of ["", "pulls", "repo autonomy", "repo spent:4", "run label:x"]) {
test/fleet-table.test.ts added +207
@@ -0,0 +1,207 @@
1 /**
2 * The fleet query language and the fleet table: the parser (fields,
3 * comparisons, negation, `repo:` scoping, every refusal), the server-side
4 * query (only readable rows, sorted by a named column, counted), and /fleet
5 * itself — escaped, same URL same view, and 1,000 rows in under 100 ms.
6 */
7 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
8 import { mkdtemp, rm } from "node:fs/promises";
9 import { tmpdir } from "node:os";
10 import { join } from "node:path";
11 import { createApp, type App } from "../src/app.ts";
12 import { createRepo } from "../src/actions/repos.ts";
13 import { createSession } from "../src/core/sessions.ts";
14 import { createIssue } from "../src/core/issues.ts";
15 import { createRun } from "../src/core/runs.ts";
16 import { createUser, type User } from "../src/core/users.ts";
17 import { parseQuery, parseTableQuery } from "../src/fleet/selection.ts";
18 import { fleetTable } from "../src/fleet/table.ts";
19 import { serve, type Servers } from "../src/http/server.ts";
20
21 describe("fleet query parser", () => {
22 const ok = (q: string) => {
23 const r = parseTableQuery(q);
24 if (!r.ok) throw new Error(r.error.message);
25 return r.value;
26 };
27 test("terms, negation, comparisons and repo scoping", () => {
28 const q = ok("run state:!ok cost:>=1.5 repo:alice/tools created:<2026-09-01");
29 expect(q.kind).toBe("run");
30 expect(q.terms).toEqual([
31 { field: "state", value: "ok", negate: true, op: "=" },
32 { field: "cost", value: "1.5", negate: false, op: ">=" },
33 { field: "repo", value: "alice/tools", negate: false, op: "=" },
34 { field: "created", value: "2026-09-01", negate: false, op: "<" },
35 ]);
36 expect(ok("issue number:!<3").terms[0]).toMatchObject({ negate: true, op: "<" });
37 });
38 test("app and crew are table kinds, never operation kinds", () => {
39 expect(ok("app access:private").kind).toBe("app");
40 expect(ok("crew member:bot").kind).toBe("crew");
41 expect(parseQuery("app").ok).toBe(false);
42 expect(parseQuery("run cost:>1").ok).toBe(true);
43 });
44 test("refusals say why", () => {
45 const bad = (q: string) => {
46 const r = parseTableQuery(q);
47 return r.ok ? "" : r.error.message;
48 };
49 expect(bad("")).toContain("starts with");
50 expect(bad("run colour:red")).toContain('no field "colour"');
51 expect(bad("run state:>3")).toContain("no order");
52 expect(bad("run cost:>lots")).toContain("is a number");
53 expect(bad("run created:>yesterday")).toContain("is a date");
54 expect(bad("run cost:")).toContain("not field:value");
55 expect(bad("run " + "a:b ".repeat(21))).toContain("at most 20 terms");
56 expect(bad("run " + "x".repeat(600))).toContain("500 characters");
57 });
58 });
59
60 describe("fleet table", () => {
61 let dataDir: string;
62 let app: App;
63 let servers: Servers;
64 let alice: User;
65 let bob: User;
66 let aliceCookie: string;
67 let bobCookie: string;
68
69 const person = async (username: string, first = false) => {
70 const r = await createUser(app.db, {
71 username,
72 email: `${username}@forge.local`,
73 password: "a-good-passphrase",
74 adminIfFirst: first,
75 });
76 if (!r.ok) throw new Error(r.error);
77 return r.value;
78 };
79 const get = (path: string, cookie?: string) =>
80 fetch(`${servers.url}${path}`, {
81 headers: cookie ? { cookie } : {},
82 redirect: "manual",
83 });
84 const q = (viewer: User, line: string, extra = {}) => {
85 const r = fleetTable(app.db, viewer, { q: line, ...extra });
86 if (!r.ok) throw new Error(r.error.message);
87 return r.value;
88 };
89 const texts = (t: ReturnType<typeof q>, col: number) =>
90 t.rows.map((r) => r[col]!.text);
91
92 beforeAll(async () => {
93 dataDir = await mkdtemp(join(tmpdir(), "forge-fleet-table-"));
94 app = createApp({ dataDir, port: 0 });
95 servers = await serve(app);
96 await person("root", true);
97 alice = await person("alice");
98 bob = await person("bob");
99 aliceCookie = `forge_session=${createSession(app.db, alice.id).token}`;
100 bobCookie = `forge_session=${createSession(app.db, bob.id).token}`;
101 const mk = async (owner: User, name: string, visibility: "public" | "private") => {
102 const r = await createRepo(app, owner, { name, visibility });
103 if (!r.ok) throw new Error(String(r.error));
104 return r.value;
105 };
106 const tools = await mk(alice, "tools", "public");
107 const vault = await mk(alice, "vault", "private");
108 const cheap = createRun(app.db, { repoId: tools.id, kind: "deploy" });
109 const dear = createRun(app.db, { repoId: tools.id, kind: "deploy" });
110 createRun(app.db, { repoId: vault.id, kind: "deploy" });
111 app.db.query("UPDATE run SET cost_usd = 0.5 WHERE id = ?").run(cheap.id);
112 app.db.query("UPDATE run SET cost_usd = 3 WHERE id = ?").run(dear.id);
113 createIssue(app.db, { repoId: tools.id, authorId: alice.id, title: "<script>alert(1)</script>" });
114 createIssue(app.db, { repoId: vault.id, authorId: alice.id, title: "secret plan" });
115 // 1,000 more rows on one public repo, for the speed bar.
116 const bulk = await mk(bob, "bulk", "public");
117 app.db.transaction(() => {
118 for (let n = 0; n < 1000; n++)
119 createIssue(app.db, { repoId: bulk.id, authorId: bob.id, title: `bulk ${n}` });
120 })();
121 }, 60_000);
122 afterAll(async () => {
123 servers.stop();
124 await rm(dataDir, { recursive: true, force: true });
125 });
126
127 test("comparisons filter and negation inverts", () => {
128 expect(q(alice, "run cost:>1").total).toBe(1);
129 expect(q(alice, "run cost:>=0.5 repo:tools").total).toBe(2);
130 expect(q(alice, "run cost:!>1 repo:alice/tools").total).toBe(1);
131 expect(q(alice, "run cost:<0.1 repo:tools").total).toBe(0);
132 expect(q(alice, "run created:>2000-01-01 repo:tools").total).toBe(2);
133 expect(q(alice, "run created:<2000-01-01").total).toBe(0);
134 });
135
136 test("a repository the viewer cannot read is absent, not refused", () => {
137 expect(q(alice, "issue repo:vault").total).toBe(1);
138 expect(q(bob, "issue repo:vault").total).toBe(0);
139 expect(q(bob, "run repo:alice/vault").total).toBe(0);
140 expect(q(bob, "repo name:vault").total).toBe(0);
141 });
142
143 test("sorting by a named column, either way; unknown columns are refused", () => {
144 const up = q(alice, "run repo:tools", { sort: "cost" });
145 const down = q(alice, "run repo:tools", { sort: "-cost" });
146 expect(texts(up, 5)).toEqual(["$0.50", "$3.00"]);
147 expect(texts(down, 5)).toEqual(["$3.00", "$0.50"]);
148 const bad = fleetTable(app.db, alice, { q: "run", sort: "id; DROP TABLE run" });
149 expect(bad.ok).toBe(false);
150 expect(q(alice, "run").total).toBe(3);
151 });
152
153 test("app and crew rows read as tables", () => {
154 expect(q(alice, "app").total).toBe(0);
155 expect(q(alice, "crew").total).toBe(0);
156 });
157
158 test("paging: counts are the whole, rows are the page", () => {
159 const t = q(bob, "issue repo:bulk", { limit: 10, offset: 5 });
160 expect(t.total).toBe(1000);
161 expect(t.rows).toHaveLength(10);
162 expect(t.offset).toBe(5);
163 expect(q(bob, "issue repo:bulk", { limit: 99999 }).limit).toBe(1000);
164 });
165
166 test("/fleet needs a session, shows the query line, and escapes", async () => {
167 expect((await get("/fleet")).status).not.toBe(200);
168 const res = await get("/fleet?q=" + encodeURIComponent("issue repo:tools"), aliceCookie);
169 expect(res.status).toBe(200);
170 const body = await res.text();
171 expect(body).toContain('value="issue repo:tools"');
172 expect(body).toContain("1–1 of 1 issue rows");
173 expect(body).not.toContain("<script>alert(1)</script>");
174 expect(body).toContain("&lt;script&gt;alert(1)&lt;/script&gt;");
175 expect(res.headers.get("x-content-type-options")).toBe("nosniff");
176 });
177
178 test("a query that does not parse is a 400 that says why; the line is escaped", async () => {
179 const res = await get("/fleet?q=" + encodeURIComponent('run "><b>x:y'), aliceCookie);
180 expect(res.status).toBe(400);
181 const body = await res.text();
182 expect(body).not.toContain("<b>x:y");
183 expect(body).toContain('no field');
184 });
185
186 test("another viewer's page leaves out what they cannot read", async () => {
187 const body = await (await get("/fleet?q=issue", bobCookie)).text();
188 expect(body).not.toContain("secret plan");
189 expect(body).toContain("bulk 0");
190 });
191
192 test("1,000 rows render in under 100 ms", async () => {
193 const path = "/fleet?q=" + encodeURIComponent("issue repo:bulk") + "&limit=1000";
194 await get(path, bobCookie); // warm the sheet and the statement
195 const times: number[] = [];
196 let body = "";
197 for (let i = 0; i < 15; i++) {
198 const t0 = performance.now();
199 const res = await get(path, bobCookie);
200 body = await res.text();
201 times.push(performance.now() - t0);
202 if (times[i]! < 100) break; // the bar is the best of a few: a busy host is not the code
203 }
204 expect(body.match(/<tr>/g)!.length).toBe(1001); // the header and 1,000 rows
205 expect(Math.min(...times)).toBeLessThan(100);
206 }, 30_000);
207 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs