Public: anyone can read this; nobody can change it.

Absorb: an app becomes one of the forge's features #75

Closed opened this view on origin

Closed without the crew

opened this view on origin

Absorb lets the forge take one of its own apps in as a feature, without a line of the app's code moving into the forge. The app keeps its repository, its cell, its data and its deploys. The forge gives it a place in the menu and keeps its settings, typed by what the app declares.

Ben is running this on his forge (forge-apps.benjivers.com) now, with his radar app absorbed. From the forge's settings he can change which days the radar runs, at what hour, and whether its web scout is on, with no change to the radar's code.

How an app opts in

"feature": {
  "name": "Radar",
  "page": "/",
  "settings": {
    "runDays":    { "type": "days", "default": ["mon", "thu"], "label": "Run on" },
    "runHourUtc": { "type": "int",  "default": 13, "min": 0, "max": 23, "label": "Hour (UTC)" },
    "scout":      { "type": "bool", "default": true, "label": "Search the web for ideas" }
  }
}

The types are bool, int (min/max), string, choice, days and list. The block is fail-closed like the rest of forge.json: a wrong one is refused with the field named, including two keys that would collide on one env var.

What absorbing does

  • Who: a site admin absorbs from Settings → Features, PUT /api/v1/features/:slug, or the features MCP tool. The tool is on the ask-first list, since absorbing restarts the app and changes the menu.
  • Menu: the app appears in the user menu for whoever can read its repository. It opens through /apps/open, so a private one needs no second sign-in. Absorbing widens no access.
  • Settings: /settings/features/:slug is a form typed by the declaration (also PATCH /api/v1/features/:slug/settings). A value that doesn't fit is refused with the setting named, and nothing is kept.
  • The app: its process starts with FORGE_FEATURE=1 and a FORGE_SETTING_<NAME> per setting, read from the commit being started. appEnv lets through only those names, never one the forge sets itself. The start, a wake and the app's terminal all get them. A change redeploys the app, the same way an env change does.
  • Un-absorbing puts it back as an ordinary app and keeps the values for the next absorb.
  • Events: app.absorbed, app.unabsorbed, and app.feature_settings (which names the keys, never the values).

What it adds

  • src/apps/feature.ts, src/apps/feature_env.ts, src/core/features.ts, and one additive migration (pinned)
  • src/actions/features.ts
  • src/web/pages/features.ts
  • src/http/api/features.ts with 5 OpenAPI rows, and src/http/mcp/tools/features.ts
  • Small hooks in process.ts, runtime.ts, tty.ts, layout.ts (the menu), settings_routes.ts, origins.ts (the sidebar), activity.ts and conversation_confirm.ts
  • Docs in docs/features/absorb.md and the env rows in docs/APPS.md

Tests

test/features.test.ts (14 tests) holds the rules:

  • Declaring alone does nothing.
  • A repository's own admin is refused (403); a stranger gets 404.
  • A read-scope token can't absorb, and an app that declares no feature can't be absorbed.
  • A bad value keeps nothing.
  • Un-absorbing keeps the values.
  • A stranger never sees the menu entry.
  • An app is never handed FORGE_TOKEN, PORT or FORGE_APP_DATA through a feature.

On a Mac, on this branch (rebased onto 0.7.394):

  • tsc is clean, and bun scripts/gate.ts passes against main.
  • These guards pass: openapi coverage and routes, route-timing coverage, api-list-shape, api-reference, design-audit, audit, danger-buttons, web-phone, hollow, reserved-names, studio, shards, check-list, repo-head-quiet, mcp, conversation-confirm.
  • schema-migrations fails 2 tests here exactly as on main: the Mac's Bun 1.3.9 banner, and main's unpinned 20261104120000-flow-return.

On Ben's forge, the same change ran the full suite on his box. The only failures were ones his main also has there (browser captures, git's date format).

Not in this

These would be the next slices if you want them: a schedule the forge fires instead of the app's own timer, feed items, the app's MCP tools inside the forge's /mcp, secret settings, and a health row on /system.

🤖 Generated with Claude Code

commented

Thanks Ben. Absorb is on the forge trunk now (forge.open-platform.sh/trevato/forge), with your commit kept as yours: 9e74449c. Two fixes on top: an unapproved guest preview gets no feature settings, and only production can rename the menu entry. The trunk lives at forge.open-platform.sh now, so send future work there, from your forge as a followed source or as a pull; this mirror is going away. Closing this one since it landed.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs