Skip to content

next: identity, agents, the generated app, docs, CLI and add-ons - #4

Draft
amagdy46 wants to merge 210 commits into
mainfrom
next
Draft

amagdy46 wants to merge 210 commits into
mainfrom
next

Conversation

@amagdy46

@amagdy46 amagdy46 commented Nov 18, 2026 •

Copy link
Copy Markdown
Owner

The integration branch for everything after 0.2.1. It builds on #3 (release-0.2.1), so until #3 merges this diff also shows those commits. Work lands here only after a fresh-context review and a run of the gate; this description is kept current.

Merged so far

  • Identity. A new mark ("struck ef": a maker's punch with ef struck through it, the e and the f one bar), replacing the stacked-layers logo. Every asset is generated from one source file with pnpm brand, and a test fails when one is stale: logos and lockups for light and dark, the social preview, a favicon for generated apps, a "made with efforge" badge in generated READMEs, a one-line terminal intro, and docs/brand.md. ADR 0006.

  • The generated app. A stack-aware landing page and a capabilities dashboard: one card per capability with a live demo beside the real source (only a marked region of each file reaches the browser), a layer graph, and a registry by which an add-on contributes its card (docs/capability-cards.md, ADR 0008). Cards so far: runtime, database, auth, realtime. Real tests with test layers replace the placeholder. On auth stacks every card server function requires a session.

  • efforge for coding agents. A documented --json contract for create, add and list (docs/json.md, JSON Schemas): one document on stdout, stable error codes, and on every error a fix that is either a command doing what the caller was trying to do or null with the facts as data. Every fix is built in src/fix.ts; a seeded property test follows fixes over hundreds of bad invocations and asserts nothing unasked is created. An agent skill (skills/efforge/SKILL.md), llms.txt, and a "For coding agents" section in the README. ADR 0007. This changes the 0.2.x --json shapes, so it ships in 0.3.0; the skill states that minimum.

  • Core docs. docs/architecture.md with one diagram (and the same facts as text), docs/testing.md, a page per add-on generated from the manifests (pnpm docs:addons), issue forms, a pull request template and SECURITY.md. Tests fail when a page, the diagram, a quoted sample or an "Add it" command goes stale.

  • The generated README and AGENTS.md. Stack-aware sections (run, scripts, layout, capabilities, deploy for wrangler or Alchemy) that efforge add keeps true by rewriting marked regions; a seeded property test proves no user text outside a well-formed region is lost. One local-settings file per stack, and an example file a fresh clone can copy. Fixes pnpm db:generate on Drizzle stacks, the wrangler deploy script and db:migrate --remote on D1.

In progress

  • Cards for storage, email, workflows, AI and browser, and a hardening pass on the generated app's session guard.
  • upgrade and doctor; presets, the add picker, info and graph.

Still to come

The README rewrite, and the observability, rpc and cluster add-ons.

0.2.0 crashed on start because @effect/platform-node's own range resolved
@effect/platform-node-shared to 4.1.4. A bundled CLI resolves nothing on the
user's machine. pnpm smoke:pack installs the packed tarball with npm in an
empty directory and runs it; release.yml runs it before publishing.
drizzle-orm and effect-cf peer on @effect/sql-* with open ranges, so pnpm
installed 4.1.4 drivers next to effect 4.0.5 and every database stack failed
to build. The generated pnpm-workspace.yaml now overrides each family
released with effect to the effect pin; add writes the overrides into older
projects at their own effect version. Wildcard overrides need pnpm 12.17,
so generated projects pin pnpm 12.21.0. The e2e harness checks the real
lockfile and pnpm peers check after every install.
…ilter

Vitest 5.1 joins describe and test names with " > ", so -t "stacks build
<case>$" matches nothing and skips every case.
effect and @effect/* 4.1.4, effect-cf 0.59.0, alchemy beta.87,
better-auth 1.7.25, vite-plus 1.7.0, @effect/tsgo 0.70.0, oxlint 1.94.0,
drizzle-orm and drizzle-kit to the official 1.0.0-rc.5, and the rest of
bump.ts's list. vitest stays at 5.1.0, the copy vite-plus 1.7.0 bundles.

vite-plus 1.7 runs type-aware lint on its bundled tsrs, so the tsgolint
that effect-tsgo patches went unused and lint failed on an unknown
effecttsgo rule. The lint and check scripts now run through
effect-tsgo vp. bump.ts checks pins against tsgo's supported table and
vite-plus's bundle. The browser extra's lockfile and image tag follow
playwright 1.65.1.
alchemy 2.0.0-beta.87 moved the Cloudflare provider out of the alchemy
package (alchemy/Cloudflare no longer exists) into @alchemy.run/cloudflare.
The e2e peer check now fails on required or Effect peers only, and names
the one upstream mismatch it tolerates (alchemy's runtime pulls unenv rc.25
next to @cloudflare/unenv-preset's exact rc.24 peer).
# Conflicts:
#	CONTRIBUTING.md
#	docs/limits.md
#	scripts/smoke-pack.ts
… add; release publishes the tarball it tested; CI runs the add e2e case
… a subpath after Z, unknown commands and characters)
…, ligature, avatar, badge edge

pnpm brand now writes the README header and the generated app's badge line from repo in
source.ts, and measures the lockup canvas and the ligature box from the paths, so swapping
the mark or wordmark is one file. Unused values are gone. New ligature-light/dark.svg (the
guide already told people to use them). The avatar is the master colourway on Paper. The
badge has a 1 px Steel edge at 35% so it keeps its shape on GitHub dark.
… Effect overrides, scope the effect override to Effect 4, refresh an unedited dashboard so the realtime demo shows
…t checks git status and the warning, a test that --json --log-level=nope stays one JSON error
…igrations check reads it: add says it after an add-on that brings a migration and after a run that never migrated, create, upgrade and Interrupted documents the same
…ng; HEAD on a signed link answers like GET; a card footer fits its entries on one row; the AI layer needs LLM_* settings (a saved key only with organizations); efforge/no-whole-file-import covers packages/; the storage AGENTS.md line about Not configured holds only with settings.ts; the AI section has one parenthesis and says what guards askModel; docs on the guard and add's notes
… never inside a command or a path; the wrapper moves to src/wrap.ts. The landing page's add line is formatted as the generated config wants
…2e: an upgraded 0.2.0 wrangler project runs pnpm run deploy --dry-run
…shboard kept server/mailer.ts at 0.2.1 but moved the Mailer it builds, and failed typecheck); a held server file of efforge's gets requireSession on auth stacks, its hash recorded, so the project's lint passes after the upgrade (the owner-edit upgrade cases failed on the merge of next and cards)
…apped stderr, upgrade's scripts and env) into cards: next's migrate step replaces this branch's rule, its test keeps covering every add-on that ships a migration; the README's Before you deploy says npx -y
…r, no --wizard, upgrade's scripts and env) into readme: cli.md keeps next's line on the global flags
…xt's colours and its who-can-call-it note, light and dark; the demo types npx -y create-efforge add email and shows the email card add now writes. readme:screenshots builds with the CLI it runs in (no --cli)
…ll runs as written without a prompt: npx -y create-efforge, npx -y skills add ... --yes, an add-on page's create line with --yes. noninteractive.test.ts reads those documents too (a bare npm create efforge my-app, the way in for a person at the prompts, is the one exception), and docs-add-commands runs each page's create line
…ayer and the graph, filled by the new addTelemetry transform; a test that every layer AppLayer composes is an exported constant, shared by reference
…ps your formatting, and writes a test and a card with the service; each capability has a test layer and a test; what auth protects by default and that sign-up is open until disableSignUp closes it; the pictures' alt texts follow them. upgrading.md: the 0.2.0 example re-run with this CLI (32 new files, the root deploy script and wrangler, runtime.ts held, deploy --dry-run after it)
…out at vitest's 5 s default on a busy machine
…ject's own middleware cannot answer a signed-out caller before it
…xit and useServerCall decodes it into the error's class, fields included; core service errors are Schema.TaggedError, a driver's cause is ServerOnly; the nine cards show the error they received; a refused call is told apart (rejected)
…server function's call is one named after it (nameCall); a test over every add-on's templates holds new ones to it
…hrough JSON as its class, its cause left behind; no core service error is a Data.TaggedError
…nd handling it in a component, spans, layer constants, restarting pnpm dev after a dependency, the Local Explorer), capability-cards, architecture's request flow, testing, ADR 0013, CHANGELOG
…a project made between releases) still answers { ok, value }, and the client reads it; upgrade e2e cases for a project made by next, with an owner's own Data.TaggedError service on runOutcome and useServerCall
…ail server functions); generated-code test loads settings.ts beside lib/outcome.ts
…next commit, each with and without owner edits)
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