Public: anyone can read this; the crew can change it.
Absorb: how it fits packs, flows/radar and forge-to-forge #9699
mason/forge:mason/9545-absorb-how-it-fits-packs-flows-radar-and → main 3 commits fork
8 files
changed +139
−10
docs/features/absorb.md +17 −1
| @@ -68,9 +68,25 @@ See `docs/features/absorb-review.md` for the findings of #9441. | ||
| 68 | 68 | - Code: `src/apps/feature.ts` (the declaration), `src/core/features.ts` (storage), `src/actions/features.ts` (the rules), `src/apps/feature_env.ts` (the environment), `src/web/pages/features.ts`, `src/http/api/features.ts`, `src/http/mcp/tools/features.ts`. |
| 69 | 69 | - Tests: `test/features.test.ts` holds the rules. `test/apps-features.test.ts` runs a real app: it absorbs the app, changes a setting and reads the variables back from the running process. |
| 70 | 70 | |
| 71 | ## In a pack | |
| 72 | ||
| 73 | A pack's app may say `"absorb": true`. Deploying the pack then absorbs that app after it is made and its history carried, as the deploying admin's act: it needs an `admin`-scope token, the forge records `app.absorbed` as for any absorb, and a refusal (not an admin, no declared feature) is a failed `absorb <name>` step while the rest of the pack goes on. It is a boolean on the app, never a setting; the pack parser still refuses `env`, `key` and `data`. | |
| 74 | ||
| 75 | ## On a fork | |
| 76 | ||
| 77 | A fork of an app carries its `feature` block, and declaring does nothing, so the fork is not absorbed. Settings stay behind: they belong to the forge that holds them, and are not copied. The Features row names the repository an app was forked from and the upstream it follows, so an admin sees whose declaration they are about to put in the menu. | |
| 78 | ||
| 71 | 79 | ## Not done yet |
| 72 | 80 | |
| 73 | The forge does not yet fire a feature's schedule, show its feed items, serve its MCP tools inside the forge's `/mcp`, keep `secret` settings or show its health on `/system`. | |
| 81 | An absorbed app is, today, a menu entry and typed settings, and nothing more. These are not built; each is an issue on the map: | |
| 82 | ||
| 83 | - firing a feature's schedule from the forge (the app runs its own timer); | |
| 84 | - the app's items in the feed; | |
| 85 | - the app's MCP tools inside the forge's `/mcp`; | |
| 86 | - `secret` settings; | |
| 87 | - the app's health on `/system`. | |
| 88 | ||
| 89 | The Features page says so rather than imply integration. | |
| 74 | 90 | |
| 75 | 91 | ## Findings |
| 76 | 92 |
scripts/pack.ts +11
| @@ -127,6 +127,17 @@ export function realHands(url: string, token: string, options: HandsOptions = {} | ||
| 127 | 127 | if (r.ok) return { ok: true }; |
| 128 | 128 | return { ok: false, why: `the forge answered ${r.status}` }; |
| 129 | 129 | }, |
| 130 | async absorb(name) { | |
| 131 | const r = await fetch(`${url}/api/v1/features/${encodeURIComponent(name)}`, { | |
| 132 | method: "PUT", | |
| 133 | headers: { authorization: `Bearer ${token}` }, | |
| 134 | }).catch(() => null); | |
| 135 | if (r === null) return { ok: false, why: `cannot reach ${url}` }; | |
| 136 | if (r.ok) return { ok: true }; | |
| 137 | if (r.status === 403) return { ok: false, why: "absorbing is a site admin's act: deploy with an admin-scope token" }; | |
| 138 | if (r.status === 422) return { ok: false, why: "the app declares no usable feature in forge.json" }; | |
| 139 | return { ok: false, why: `the forge answered ${r.status}` }; | |
| 140 | }, | |
| 130 | 141 | async makeAgent(a) { |
| 131 | 142 | const r = await fetch(`${url}/api/v1/agents`, { |
| 132 | 143 | method: "POST", |
src/actions/features.ts +17
| @@ -31,6 +31,7 @@ import { | ||
| 31 | 31 | setFeatureSettings as keepSettings, |
| 32 | 32 | unabsorb, |
| 33 | 33 | } from "../core/features.ts"; |
| 34 | import { getFollow } from "../core/upstream_follow.ts"; | |
| 34 | 35 | import { canRead, getRepoById, type Repo } from "../core/repos.ts"; |
| 35 | 36 | import type { User } from "../core/users.ts"; |
| 36 | 37 | import { resolveOid } from "../git/merge.ts"; |
| @@ -74,6 +75,10 @@ export interface FeatureView { | ||
| 74 | 75 | readonly page: string; |
| 75 | 76 | /** The name and page the app declares now, when they differ from the absorbed ones: waits for an admin. */ |
| 76 | 77 | readonly pending: { readonly name: string; readonly page: string } | null; |
| 78 | /** `owner/name` of the repository this one was forked from, when it is a fork. */ | |
| 79 | readonly forkOf: string | null; | |
| 80 | /** The address and branch the repository follows upstream, when it follows one. */ | |
| 81 | readonly following: string | null; | |
| 77 | 82 | readonly absorbed: boolean; |
| 78 | 83 | readonly absorbedBy: string | null; |
| 79 | 84 | readonly absorbedAt: string | null; |
| @@ -119,6 +124,16 @@ async function readDeclaration(dir: string, tip: string): Promise<Result<Feature | ||
| 119 | 124 | return parseFeature(parsed as Record<string, unknown>); |
| 120 | 125 | } |
| 121 | 126 | |
| 127 | function forkOf(app: App, repo: Repo): string | null { | |
| 128 | const parent = repo.forkParentId === null ? undefined : getRepoById(app.db, repo.forkParentId); | |
| 129 | return parent === undefined ? null : `${parent.ownerName}/${parent.name}`; | |
| 130 | } | |
| 131 | ||
| 132 | function following(app: App, repo: Repo): string | null { | |
| 133 | const f = getFollow(app.db, repo.id); | |
| 134 | return f?.enabled === true ? `${f.url} (${f.branch})` : null; | |
| 135 | } | |
| 136 | ||
| 122 | 137 | /** |
| 123 | 138 | * Whether the link to an app's feature shows on its page: the app is absorbed |
| 124 | 139 | * or its default branch declares a feature, a site admin's only, and read through `declaredFeature`'s cache by |
| @@ -146,6 +161,8 @@ function viewOf(record: AppRecord, repo: Repo, app: App, spec: FeatureSpec | und | ||
| 146 | 161 | absorbed !== undefined && spec !== undefined && (spec.name !== absorbed.name || spec.page !== absorbed.page) |
| 147 | 162 | ? { name: spec.name, page: spec.page } |
| 148 | 163 | : null, |
| 164 | forkOf: forkOf(app, repo), | |
| 165 | following: following(app, repo), | |
| 149 | 166 | absorbed: absorbed !== undefined, |
| 150 | 167 | absorbedBy: absorbed?.absorbedBy ?? null, |
| 151 | 168 | absorbedAt: absorbed?.absorbedAt ?? null, |
src/packs/deploy.ts +25 −5
| @@ -20,6 +20,8 @@ export interface Hands { | ||
| 20 | 20 | carryHistory(source: string, owner: string, name: string, branch: string | undefined): Promise<{ ok: true; branch?: string } | { ok: false; why: string }>; |
| 21 | 21 | /** Make the app follow `source` on `branch`, so Settings shows it and a new upstream commit shows as drift. No branch is a failure: a wrong one is never guessed. */ |
| 22 | 22 | follow(owner: string, name: string, source: string, branch: string | undefined): Promise<{ ok: true } | { ok: false; why: string }>; |
| 23 | /** Absorb the app as a feature, as the deploying admin (an admin-scope token); the forge records the event. */ | |
| 24 | absorb(name: string): Promise<{ ok: true } | { ok: false; why: string }>; | |
| 23 | 25 | makeAgent(a: Pack["crew"][number]): Promise<{ ok: true } | { ok: false; exists: boolean; why: string }>; |
| 24 | 26 | } |
| 25 | 27 | |
| @@ -32,11 +34,27 @@ export interface Step { | ||
| 32 | 34 | export async function deployPack(pack: Pack, hands: Hands): Promise<readonly Step[]> { |
| 33 | 35 | const steps: Step[] = []; |
| 34 | 36 | for (const app of pack.apps) { |
| 37 | const before = steps.length; | |
| 38 | await deployApp(app, hands, steps); | |
| 39 | const last = steps[steps.length - 1]; | |
| 40 | if (app.absorb === true && steps.length > before && last?.state !== "failed") steps.push(await absorbStep(app.name, hands)); | |
| 41 | } | |
| 42 | await addCrew(pack, hands, steps); | |
| 43 | return steps; | |
| 44 | } | |
| 45 | ||
| 46 | async function absorbStep(name: string, hands: Hands): Promise<Step> { | |
| 47 | const done = await hands.absorb(name); | |
| 48 | return done.ok ? { what: `absorb ${name}`, state: "done", note: "in the menu; settings under Settings > Features" } : { what: `absorb ${name}`, state: "failed", note: done.why }; | |
| 49 | } | |
| 50 | ||
| 51 | async function deployApp(app: Pack["apps"][number], hands: Hands, steps: Step[]): Promise<void> { | |
| 52 | { | |
| 35 | 53 | const made = await hands.makeApp(app.name, `${app.description} (from ${app.source})`); |
| 36 | 54 | if (!made.ok) { |
| 37 | 55 | if (!made.exists) { |
| 38 | 56 | steps.push({ what: `app ${app.name}`, state: "failed", note: made.why }); |
| 39 | continue; | |
| 57 | return; | |
| 40 | 58 | } |
| 41 | 59 | // Kept: its history is not pushed again (that could overwrite work), but a |
| 42 | 60 | // follow that an earlier, partial run never set is finished now. |
| @@ -44,7 +62,7 @@ export async function deployPack(pack: Pack, hands: Hands): Promise<readonly Ste | ||
| 44 | 62 | const branch = owner === undefined ? undefined : (app.branch ?? (await hands.defaultBranch(owner, app.name))); |
| 45 | 63 | if (owner === undefined) { |
| 46 | 64 | steps.push({ what: `app ${app.name}`, state: "kept", note: "already here" }); |
| 47 | continue; | |
| 65 | return; | |
| 48 | 66 | } |
| 49 | 67 | const followed = await hands.follow(owner, app.name, app.source, branch); |
| 50 | 68 | steps.push( |
| @@ -52,12 +70,12 @@ export async function deployPack(pack: Pack, hands: Hands): Promise<readonly Ste | ||
| 52 | 70 | ? { what: `app ${app.name}`, state: "kept", note: "already here" } |
| 53 | 71 | : { what: `app ${app.name}`, state: "failed", note: `already here, not followed: ${followed.why}` }, |
| 54 | 72 | ); |
| 55 | continue; | |
| 73 | return; | |
| 56 | 74 | } |
| 57 | 75 | const carried = await hands.carryHistory(app.source, made.owner, app.name, app.branch); |
| 58 | 76 | if (!carried.ok) { |
| 59 | 77 | steps.push({ what: `app ${app.name}`, state: "failed", note: `made, history not carried: ${carried.why}` }); |
| 60 | continue; | |
| 78 | return; | |
| 61 | 79 | } |
| 62 | 80 | const followed = await hands.follow(made.owner, app.name, app.source, app.branch ?? carried.branch); |
| 63 | 81 | steps.push( |
| @@ -66,6 +84,9 @@ export async function deployPack(pack: Pack, hands: Hands): Promise<readonly Ste | ||
| 66 | 84 | : { what: `app ${app.name}`, state: "failed", note: `history carried, not followed: ${followed.why}` }, |
| 67 | 85 | ); |
| 68 | 86 | } |
| 87 | } | |
| 88 | ||
| 89 | async function addCrew(pack: Pack, hands: Hands, steps: Step[]): Promise<void> { | |
| 69 | 90 | for (const member of pack.crew) { |
| 70 | 91 | const made = await hands.makeAgent(member); |
| 71 | 92 | steps.push( |
| @@ -76,5 +97,4 @@ export async function deployPack(pack: Pack, hands: Hands): Promise<readonly Ste | ||
| 76 | 97 | : { what: `crew ${member.username}`, state: "failed", note: made.why }, |
| 77 | 98 | ); |
| 78 | 99 | } |
| 79 | return steps; | |
| 80 | 100 | } |
src/packs/pack.ts +10 −1
| @@ -28,6 +28,8 @@ export interface PackApp { | ||
| 28 | 28 | /** An https address of a public git repository, no credentials in it. */ |
| 29 | 29 | readonly source: string; |
| 30 | 30 | readonly branch?: string; |
| 31 | /** Absorb the app as a forge feature when deployed: the deploying admin's act, never a setting. */ | |
| 32 | readonly absorb?: boolean; | |
| 31 | 33 | } |
| 32 | 34 | |
| 33 | 35 | export interface PackCrew { |
| @@ -122,7 +124,14 @@ export function parsePack(raw: string): Result<Pack, string> { | ||
| 122 | 124 | const branch = r.branch === undefined ? undefined : text(r.branch, 100); |
| 123 | 125 | if (r.branch !== undefined && (branch === undefined || !/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(branch))) |
| 124 | 126 | return bad(`app "${appName}" has an unusable "branch"`); |
| 125 | apps.push({ name: appName, description: about, source, ...(branch === undefined ? {} : { branch }) }); | |
| 127 | if (r.absorb !== undefined && typeof r.absorb !== "boolean") return bad(`app "${appName}" has an unusable "absorb": true or false`); | |
| 128 | apps.push({ | |
| 129 | name: appName, | |
| 130 | description: about, | |
| 131 | source, | |
| 132 | ...(branch === undefined ? {} : { branch }), | |
| 133 | ...(r.absorb === true ? { absorb: true } : {}), | |
| 134 | }); | |
| 126 | 135 | } |
| 127 | 136 | |
| 128 | 137 | const crew: PackCrew[] = []; |
src/web/pages/features.ts +4 −2
| @@ -65,7 +65,9 @@ function featureRow(f: FeatureView) { | ||
| 65 | 65 | ? html`<span class="danger">${f.problem}</span>` |
| 66 | 66 | : html`${f.summary ?? ""}${when(f.summary !== null, () => html`<br />`)}${f.settings.length} setting${f.settings.length === 1 ? "" : "s"}${f.absorbed |
| 67 | 67 | ? html` · absorbed by ${f.absorbedBy ?? "someone"}` |
| 68 | : null}`}<br /><span id="sw-${f.slug}">${switchNote(f)}</span>`, | |
| 68 | : null}`}<br /><span class="muted small">${f.forkOf !== null ? html`Fork of <span class="mono">${f.forkOf}</span>` : "Not a fork"}${f.following !== null | |
| 69 | ? html` · follows <span class="mono">${f.following}</span>` | |
| 70 | : null}${when(f.forkOf !== null || f.following !== null, () => html` · settings do not travel with a fork`)}</span><br /><span id="sw-${f.slug}">${switchNote(f)}</span>`, | |
| 69 | 71 | trail: html`${when(f.pending !== null, () => html`<form class="row-fields" method="post" action="${base}/accept"> |
| 70 | 72 | <input type="hidden" name="name" value="${f.pending?.name ?? ""}" /> |
| 71 | 73 | <input type="hidden" name="page" value="${f.pending?.page ?? ""}" /> |
| @@ -107,7 +109,7 @@ export async function featuresPage(ctx: Ctx): Promise<Response> { | ||
| 107 | 109 | <h2>Features</h2>`, |
| 108 | 110 | pad: false, |
| 109 | 111 | }, |
| 110 | )}`; | |
| 112 | )}<p class="muted small">An absorbed app is a menu link and typed settings for now: its health and feed items do not appear in the forge yet. <a href="${DOCS}">How an app declares a feature</a></p>`; | |
| 111 | 113 | const response = shell(ctx, "Features", body); |
| 112 | 114 | notePhase(ctx.request, "render", performance.now() - rendering); |
| 113 | 115 | return response; |
test/features.test.ts +12 −1
| @@ -15,7 +15,7 @@ import { join } from "node:path"; | ||
| 15 | 15 | import { statements } from "./helpers/statements.ts"; |
| 16 | 16 | import { expectWork } from "./helpers/work.ts"; |
| 17 | 17 | import { createApp, type App } from "../src/app.ts"; |
| 18 | import { absorbApp, acceptDeclaration, declaresFeature, absorbedForNav, declaredFeature, changeFeatureSettings, getFeature, unabsorbApp } from "../src/actions/features.ts"; | |
| 18 | import { absorbApp, acceptDeclaration, declaresFeature, absorbedForNav, declaredFeature, changeFeatureSettings, getFeature, listFeatures, unabsorbApp } from "../src/actions/features.ts"; | |
| 19 | 19 | import { commitToBranch, createRepo } from "../src/actions/repos.ts"; |
| 20 | 20 | import { checkSetting, featureEnv, parseFeature, settingEnvName } from "../src/apps/feature.ts"; |
| 21 | 21 | import { featureVarsAt } from "../src/apps/feature_env.ts"; |
| @@ -393,6 +393,17 @@ describe("absorbing an app", () => { | ||
| 393 | 393 | expect(parseFeature({ feature: { name: "Settings" } }).ok).toBe(false); |
| 394 | 394 | }); |
| 395 | 395 | |
| 396 | test("the Features row says where the app comes from and that settings stay behind on a fork", async () => { | |
| 397 | const page = await (await web(adaCookie, "/settings/features")).text(); | |
| 398 | expect(page).toContain("Not a fork"); | |
| 399 | expect(page).not.toContain("settings do not travel with a fork"); | |
| 400 | const listed = await listFeatures(app, ada); | |
| 401 | if (!listed.ok) throw new Error(listed.error); | |
| 402 | const radar = listed.value.find((f) => f.slug === "radar")!; | |
| 403 | expect(radar.forkOf).toBeNull(); | |
| 404 | expect(radar.following).toBeNull(); | |
| 405 | }); | |
| 406 | ||
| 396 | 407 | test("a value that does not fit changes nothing, and names the setting", async () => { |
| 397 | 408 | const res = await api("PATCH", adaToken, "/radar/settings", { settings: { runDays: ["mon"], runHourUtc: 30 } }); |
| 398 | 409 | expect(res.status).toBe(422); |
test/packs.test.ts +43
| @@ -75,6 +75,10 @@ describe("deploy", () => { | ||
| 75 | 75 | calls.push(`follow ${owner}/${name} ${source} ${branch}`); |
| 76 | 76 | return { ok: true }; |
| 77 | 77 | }, |
| 78 | async absorb(name) { | |
| 79 | calls.push(`absorb ${name}`); | |
| 80 | return { ok: true }; | |
| 81 | }, | |
| 78 | 82 | async makeAgent(a) { |
| 79 | 83 | calls.push(`agent ${a.username}`); |
| 80 | 84 | return { ok: false, exists: false, why: "no" }; |
| @@ -88,6 +92,45 @@ describe("deploy", () => { | ||
| 88 | 92 | }); |
| 89 | 93 | }); |
| 90 | 94 | |
| 95 | describe("absorb", () => { | |
| 96 | const hands = (calls: string[], absorbOk = true): Hands => ({ | |
| 97 | makeApp: async (name) => (name === "gone" ? { ok: false, exists: false, why: "x" } : { ok: true, owner: "me" }), | |
| 98 | defaultBranch: async () => "main", | |
| 99 | carryHistory: async () => ({ ok: true }), | |
| 100 | follow: async () => ({ ok: true }), | |
| 101 | absorb: async (name) => { | |
| 102 | calls.push(name); | |
| 103 | return absorbOk ? { ok: true } : { ok: false, why: "refused" }; | |
| 104 | }, | |
| 105 | makeAgent: async () => ({ ok: true }), | |
| 106 | }); | |
| 107 | const app = (name: string, extra: object = {}) => ({ name, description: "d", source: "https://github.com/a/" + name, ...extra }); | |
| 108 | ||
| 109 | test("parses a boolean absorb and refuses anything else", () => { | |
| 110 | const ok = parse({ ...good, apps: [app("one", { absorb: true }), app("two")] }); | |
| 111 | if (!ok.ok) throw new Error(ok.error); | |
| 112 | expect(ok.value.apps[0]!.absorb).toBe(true); | |
| 113 | expect("absorb" in ok.value.apps[1]!).toBe(false); | |
| 114 | expect(parse({ ...good, apps: [app("one", { absorb: "yes" })] }).ok).toBe(false); | |
| 115 | }); | |
| 116 | ||
| 117 | test("deploy absorbs only the apps that say so, after they are made", async () => { | |
| 118 | const calls: string[] = []; | |
| 119 | const pack = parse({ ...good, crew: [], apps: [app("one", { absorb: true }), app("two"), app("gone", { absorb: true })] }); | |
| 120 | if (!pack.ok) throw new Error(pack.error); | |
| 121 | const steps = await deployPack(pack.value, hands(calls)); | |
| 122 | expect(calls).toEqual(["one"]); | |
| 123 | expect(steps.map((s) => `${s.what}:${s.state}`)).toEqual(["app one:done", "absorb one:done", "app two:done", "app gone:failed"]); | |
| 124 | }); | |
| 125 | ||
| 126 | test("a refused absorb is reported and the rest go on", async () => { | |
| 127 | const pack = parse({ ...good, crew: [], apps: [app("one", { absorb: true }), app("two")] }); | |
| 128 | if (!pack.ok) throw new Error(pack.error); | |
| 129 | const steps = await deployPack(pack.value, hands([], false)); | |
| 130 | expect(steps.map((s) => `${s.what}:${s.state}`)).toEqual(["app one:done", "absorb one:failed", "app two:done"]); | |
| 131 | }); | |
| 132 | }); | |
| 133 | ||
| 91 | 134 | describe("pages", () => { |
| 92 | 135 | let dataDir: string; |
| 93 | 136 | let app: App; |
new above
offline