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

Adapter app shape: sync an external system into the forge, with a contract the forge can audit #10034

Closed opened this
Closed without merging

I restarted this branch from main and landed the first slice of #437: forge.json gains an optional top-level adapter block, validated in one module, src/apps/adapter.ts. The rest of #437 is split into #10035, #10036 and #10037. Why the restart.

Notes

stopped closed without shipping deploy 408c616

opened this

I restarted this branch from main and landed the first slice of #437: forge.json gains an optional top-level adapter block, validated in one module, src/apps/adapter.ts. The rest of #437 is split into #10035, #10036 and #10037.

Why the restart. The old branch was about 4,950 commits behind main. Main has since rebuilt every file it touched: migrations are now one file each with pins, and the run table, the app runtime and the studio page are all different. The issue says to start fresh from main. Pushes here must be fast-forward, so the first commit is a merge whose tree is exactly main's (d3abdb3a). That merge removes the old attempt; nothing from it is carried over except the validation logic, which I rewrote against the current manifest.

What changed

  • src/apps/adapter.ts: parseAdapter checks the block's three parts and fails the deploy with the bad field named, like the rest of the manifest:
    • source: a name, plus 1–8 bare host names (no scheme, port or wildcard).
    • schedule.every: whole seconds, from 10 seconds to one week.
    • config: up to 32 typed fields. A secret takes ref, the name of an environment variable, and a value on a secret is refused.
  • Outbound hosts: every source host must also be listed in the top-level egress. The cell's existing proxy already refuses any host not in egress, so a source host the app could never reach is refused at deploy time.
  • src/apps/manifest.ts: calls the parser after egress and sets adapter on the manifest only when one is declared, so other code that builds manifests is untouched.
  • Docs: docs/ADAPTERS.md describes the block and says plainly that the /pull contract does not exist yet. docs/APPS.md and docs/REFERENCE.md link to it.
  • test/adapter.test.ts: covers the module directly and through parseManifest, including a source host missing from egress and a secret given a value.

Not done here (open issues; #437 now waits on all three)

  • #10035: a template adapter with an idempotent POST /pull and its own tests.
  • #10036: the forge calls /pull on the schedule and records each pull as a run, with a new migration and run kind.
  • #10037: the app page shows last pull, next pull and cursor; it waits on #10036.

Checks. The gate and bun x tsc --noEmit pass. scripts/fast.ts picked 1,688 test files (about 144 minutes) because manifest.ts is widely used, so I ran the manifest, egress and docs suites myself. Five tests fail, and none of them involve this change:

  • test/scaffold.test.ts (strict typecheck) and test/prompts.test.ts (Instagram hour) fail the same way on main without this change.
  • Three test/looks.test.ts captures need /usr/bin/chromium, which the sandbox doesn't have.

To try it: add "egress": ["api.ledger.example"] and the example block from docs/ADAPTERS.md to an app's forge.json and deploy. Then remove the host from egress: the deploy fails with forge.json: adapter.source.hosts: … must also be named in the top-level egress.

🤖 Generated with Claude Code

Closes #437

commented

I restarted this branch from main and landed the first slice of #437: forge.json gains an optional top-level adapter block, validated in one module, src/apps/adapter.ts. The rest of #437 is split into #10035, #10036 and #10037.

Why the restart. The old branch was about 4,950 commits behind main. Main has since rebuilt every file it touched: migrations are now one file each with pins, and the run table, the app runtime and the studio page are all different. The issue says to start fresh from main. Pushes here must be fast-forward, so the first commit is a merge whose tree is exactly main's (d3abdb3a). That merge removes the old attempt; nothing from it is carried over except the validation logic, which I rewrote against the current manifest.

What changed

  • src/apps/adapter.ts: parseAdapter checks the block's three parts and fails the deploy with the bad field named, like the rest of the manifest:
    • source: a name, plus 1–8 bare host names (no scheme, port or wildcard).
    • schedule.every: whole seconds, from 10 seconds to one week.
    • config: up to 32 typed fields. A secret takes ref, the name of an environment variable, and a value on a secret is refused.
  • Outbound hosts: every source host must also be listed in the top-level egress. The cell's existing proxy already refuses any host not in egress, so a source host the app could never reach is refused at deploy time.
  • src/apps/manifest.ts: calls the parser after egress and sets adapter on the manifest only when one is declared, so other code that builds manifests is untouched.
  • Docs: docs/ADAPTERS.md describes the block and says plainly that the /pull contract does not exist yet. docs/APPS.md and docs/REFERENCE.md link to it.
  • test/adapter.test.ts: covers the module directly and through parseManifest, including a source host missing from egress and a secret given a value.

Not done here (open issues; #437 now waits on all three)

  • #10035: a template adapter with an idempotent POST /pull and its own tests.
  • #10036: the forge calls /pull on the schedule and records each pull as a run, with a new migration and run kind.
  • #10037: the app page shows last pull, next pull and cursor; it waits on #10036.

Checks. The gate and bun x tsc --noEmit pass. scripts/fast.ts picked 1,688 test files (about 144 minutes) because manifest.ts is widely used, so I ran the manifest, egress and docs suites myself. Five tests fail, and none of them involve this change:

  • test/scaffold.test.ts (strict typecheck) and test/prompts.test.ts (Instagram hour) fail the same way on main without this change.
  • Three test/looks.test.ts captures need /usr/bin/chromium, which the sandbox doesn't have.

To try it: add "egress": ["api.ledger.example"] and the example block from docs/ADAPTERS.md to an app's forge.json and deploy. Then remove the host from egress: the deploy fails with forge.json: adapter.source.hosts: … must also be named in the top-level egress.

🤖 Generated with Claude Code

commented

Declined: the conflicts this task names are already gone. While I was merging, another run restarted the branch on the fork (scout/forge, which git push targets). It merged main (d3abdb3a, a merge of bab9b71a), added slice one of #437 in 408c6160 (the adapter block, validated in src/apps/adapter.ts), rewrote #10034's description, and split the rest of #437 into #10035, #10036 and #10037. That head merges cleanly with current main (39411c60); I checked with git merge-tree. Run log: https://forge.open-platform.sh/trevato/forge/runs/01m6zkb1j99j2dfcfpqe0pjfyb

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs