Skip to content

docs: say what comes after a green test, for the layout that exists - #8

Merged
pyramation merged 1 commit into
mainfrom
docs/next-after-a-green-test
Aug 10, 2026
Merged

docs: say what comes after a green test, for the layout that exists#8
pyramation merged 1 commit into
mainfrom
docs/next-after-a-green-test

Conversation

@pyramation

Copy link
Copy Markdown
Contributor

Summary

Supersedes #7, which found a real gap — both feature READMEs stop at the test command, so the step after a green test is a guess — but wrote it against a layout this repository no longer has, and asserted two things about the page lane that are not true.

Why #7 cannot be merged as-is: it adds READMEs under {typescript,python}/{job,sync,page}, six directories that #6 replaced with two surfaces (typescript/gql, typescript/sql) plus handler/{node-multi-method,python}. That is the merge conflict, and merging it would land six files no scaffold ever reads. Kind is a flag now, not a template — which both current READMEs already explain.

The two claims worth catching before they became the documented design:

  • "features/auth and features/sso … their pages/ is a Next.js app generated into the image at build time rather than committed." There is no Next.js anywhere: features/auth/pages/ was deleted, features/sso/pages/ holds nothing but node_modules (leftover, worth removing there), and a page image is generated from a nested manifest of plain handlers. What docs: say what comes after the template is installed #7 read as "generated, not committed" is an empty directory.
  • "route and accessChannels sit at the top level while this feature has one method." They are per method by design and survive registration as such; features/checkout is the reference across all three lanes from a single manifest:
checkout:quote      -                  -           # job
checkout:session    ["sync"]  /session              # sync
checkout:callback   ["page"]  /callback  image: features/checkout/pages

What this PR keeps from #7 is the part that checks out — fun up --k8s, fun register --apply / --dry-run, and the No service URL for "<task>" symptom of a method that never registered. One correction there too: registration failure is not merely unswallowed, it process.exit(1)s the bring-up (commands/up.ts), so the sentence says that instead of implying you might miss it.

Added to typescript/gql/README.md and typescript/sql/README.md: a Next section, and a page paragraph saying a page is a lane rather than a UI framework, and that a feature serving a site declares a second nested image:

handlers/handler.json          "type": "node-multi-method"   the sync/job methods
handlers/pages/handler.json    "type": "node-page"           the routes a browser lands on

features/auth is that reference — one page image, four landings. Docs only, placeholder tokens untouched, scripts/check-templates.mjs green.

Link to Devin session: https://app.devin.ai/sessions/f3d7c42c8aea4065a2c2f8d780d6bdee
Requested by: @pyramation

The two feature READMEs stop at the test command, so the step after a green test
is a guess: nothing says the feature reaches a real stack through `fun up --k8s`,
that registration reads the same `handler.json` the test reads, or that an
unregistered method's only symptom arrives later as `No service URL for ...`.

Adds a Next section to both, and a page paragraph: a page is a lane rather than a
UI framework, and a feature serving a site puts those methods in a second nested
manifest (`handlers/pages/handler.json`, `"type": "node-page"`) that the platform
builds as its own image — `route` and `accessChannels` being per method, as
`features/checkout` shows across all three lanes.

Docs only; placeholder tokens untouched.
@pyramation pyramation self-assigned this Aug 9, 2026
@devin-ai-integration

Copy link
Copy Markdown

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment, CI, and merge conflict monitoring

@pyramation
pyramation merged commit 15de6c4 into main Aug 10, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant