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

Absorb: how it fits packs, flows/radar and forge-to-forge #9699

Parked opened this
Closed without merging

mason/forge:mason/9545-absorb-how-it-fits-packs-flows-radar-and → main 3 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
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.
6868 - 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`.
6969 - 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.
7070
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
7179 ## Not done yet
7280
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.
7490
7591 ## Findings
7692
scripts/pack.ts +11
@@ -127,6 +127,17 @@ export function realHands(url: string, token: string, options: HandsOptions = {}
127127 if (r.ok) return { ok: true };
128128 return { ok: false, why: `the forge answered ${r.status}` };
129129 },
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 },
130141 async makeAgent(a) {
131142 const r = await fetch(`${url}/api/v1/agents`, {
132143 method: "POST",
src/actions/features.ts +17
@@ -31,6 +31,7 @@ import {
3131 setFeatureSettings as keepSettings,
3232 unabsorb,
3333 } from "../core/features.ts";
34 import { getFollow } from "../core/upstream_follow.ts";
3435 import { canRead, getRepoById, type Repo } from "../core/repos.ts";
3536 import type { User } from "../core/users.ts";
3637 import { resolveOid } from "../git/merge.ts";
@@ -74,6 +75,10 @@ export interface FeatureView {
7475 readonly page: string;
7576 /** The name and page the app declares now, when they differ from the absorbed ones: waits for an admin. */
7677 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;
7782 readonly absorbed: boolean;
7883 readonly absorbedBy: string | null;
7984 readonly absorbedAt: string | null;
@@ -119,6 +124,16 @@ async function readDeclaration(dir: string, tip: string): Promise<Result<Feature
119124 return parseFeature(parsed as Record<string, unknown>);
120125 }
121126
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
122137 /**
123138 * Whether the link to an app's feature shows on its page: the app is absorbed
124139 * 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
146161 absorbed !== undefined && spec !== undefined && (spec.name !== absorbed.name || spec.page !== absorbed.page)
147162 ? { name: spec.name, page: spec.page }
148163 : null,
164 forkOf: forkOf(app, repo),
165 following: following(app, repo),
149166 absorbed: absorbed !== undefined,
150167 absorbedBy: absorbed?.absorbedBy ?? null,
151168 absorbedAt: absorbed?.absorbedAt ?? null,
src/packs/deploy.ts +25 −5
@@ -20,6 +20,8 @@ export interface Hands {
2020 carryHistory(source: string, owner: string, name: string, branch: string | undefined): Promise<{ ok: true; branch?: string } | { ok: false; why: string }>;
2121 /** 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. */
2222 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 }>;
2325 makeAgent(a: Pack["crew"][number]): Promise<{ ok: true } | { ok: false; exists: boolean; why: string }>;
2426 }
2527
@@ -32,11 +34,27 @@ export interface Step {
3234 export async function deployPack(pack: Pack, hands: Hands): Promise<readonly Step[]> {
3335 const steps: Step[] = [];
3436 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 {
3553 const made = await hands.makeApp(app.name, `${app.description} (from ${app.source})`);
3654 if (!made.ok) {
3755 if (!made.exists) {
3856 steps.push({ what: `app ${app.name}`, state: "failed", note: made.why });
39 continue;
57 return;
4058 }
4159 // Kept: its history is not pushed again (that could overwrite work), but a
4260 // 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
4462 const branch = owner === undefined ? undefined : (app.branch ?? (await hands.defaultBranch(owner, app.name)));
4563 if (owner === undefined) {
4664 steps.push({ what: `app ${app.name}`, state: "kept", note: "already here" });
47 continue;
65 return;
4866 }
4967 const followed = await hands.follow(owner, app.name, app.source, branch);
5068 steps.push(
@@ -52,12 +70,12 @@ export async function deployPack(pack: Pack, hands: Hands): Promise<readonly Ste
5270 ? { what: `app ${app.name}`, state: "kept", note: "already here" }
5371 : { what: `app ${app.name}`, state: "failed", note: `already here, not followed: ${followed.why}` },
5472 );
55 continue;
73 return;
5674 }
5775 const carried = await hands.carryHistory(app.source, made.owner, app.name, app.branch);
5876 if (!carried.ok) {
5977 steps.push({ what: `app ${app.name}`, state: "failed", note: `made, history not carried: ${carried.why}` });
60 continue;
78 return;
6179 }
6280 const followed = await hands.follow(made.owner, app.name, app.source, app.branch ?? carried.branch);
6381 steps.push(
@@ -66,6 +84,9 @@ export async function deployPack(pack: Pack, hands: Hands): Promise<readonly Ste
6684 : { what: `app ${app.name}`, state: "failed", note: `history carried, not followed: ${followed.why}` },
6785 );
6886 }
87 }
88
89 async function addCrew(pack: Pack, hands: Hands, steps: Step[]): Promise<void> {
6990 for (const member of pack.crew) {
7091 const made = await hands.makeAgent(member);
7192 steps.push(
@@ -76,5 +97,4 @@ export async function deployPack(pack: Pack, hands: Hands): Promise<readonly Ste
7697 : { what: `crew ${member.username}`, state: "failed", note: made.why },
7798 );
7899 }
79 return steps;
80100 }
src/packs/pack.ts +10 −1
@@ -28,6 +28,8 @@ export interface PackApp {
2828 /** An https address of a public git repository, no credentials in it. */
2929 readonly source: string;
3030 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;
3133 }
3234
3335 export interface PackCrew {
@@ -122,7 +124,14 @@ export function parsePack(raw: string): Result<Pack, string> {
122124 const branch = r.branch === undefined ? undefined : text(r.branch, 100);
123125 if (r.branch !== undefined && (branch === undefined || !/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(branch)))
124126 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 });
126135 }
127136
128137 const crew: PackCrew[] = [];
src/web/pages/features.ts +4 −2
@@ -65,7 +65,9 @@ function featureRow(f: FeatureView) {
6565 ? html`<span class="danger">${f.problem}</span>`
6666 : html`${f.summary ?? ""}${when(f.summary !== null, () => html`<br />`)}${f.settings.length} setting${f.settings.length === 1 ? "" : "s"}${f.absorbed
6767 ? 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>`,
6971 trail: html`${when(f.pending !== null, () => html`<form class="row-fields" method="post" action="${base}/accept">
7072 <input type="hidden" name="name" value="${f.pending?.name ?? ""}" />
7173 <input type="hidden" name="page" value="${f.pending?.page ?? ""}" />
@@ -107,7 +109,7 @@ export async function featuresPage(ctx: Ctx): Promise<Response> {
107109 <h2>Features</h2>`,
108110 pad: false,
109111 },
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>`;
111113 const response = shell(ctx, "Features", body);
112114 notePhase(ctx.request, "render", performance.now() - rendering);
113115 return response;
test/features.test.ts +12 −1
@@ -15,7 +15,7 @@ import { join } from "node:path";
1515 import { statements } from "./helpers/statements.ts";
1616 import { expectWork } from "./helpers/work.ts";
1717 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";
1919 import { commitToBranch, createRepo } from "../src/actions/repos.ts";
2020 import { checkSetting, featureEnv, parseFeature, settingEnvName } from "../src/apps/feature.ts";
2121 import { featureVarsAt } from "../src/apps/feature_env.ts";
@@ -393,6 +393,17 @@ describe("absorbing an app", () => {
393393 expect(parseFeature({ feature: { name: "Settings" } }).ok).toBe(false);
394394 });
395395
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
396407 test("a value that does not fit changes nothing, and names the setting", async () => {
397408 const res = await api("PATCH", adaToken, "/radar/settings", { settings: { runDays: ["mon"], runHourUtc: 30 } });
398409 expect(res.status).toBe(422);
test/packs.test.ts +43
@@ -75,6 +75,10 @@ describe("deploy", () => {
7575 calls.push(`follow ${owner}/${name} ${source} ${branch}`);
7676 return { ok: true };
7777 },
78 async absorb(name) {
79 calls.push(`absorb ${name}`);
80 return { ok: true };
81 },
7882 async makeAgent(a) {
7983 calls.push(`agent ${a.username}`);
8084 return { ok: false, exists: false, why: "no" };
@@ -88,6 +92,45 @@ describe("deploy", () => {
8892 });
8993 });
9094
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
91134 describe("pages", () => {
92135 let dataDir: string;
93136 let app: App;

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs