v3: fullstack line (ORM, global IDs, queues, pages) → main

.changeset/analyzer-tolerate-nonnull-selectors.md

@@ -0,0 +1,15 @@
+---
+'@getcronit/pylon': patch
+---
+
+Let the usePaginatedData selector analyzer see through type-only wrappers.
+
+A connection selector on a nullable single-entity lookup —
+`usePaginatedData(q => q.post({ id })!.comments)` — needs a `!` (or an `as`) to satisfy the
+type-checker, since the client types a single-entity accessor as nullable. But the selector
+path walker only recognized identifiers, property accesses, calls, and parentheses, so the
+`NonNullExpression` made it bail with "usePaginatedData expects a connection selector".
+
+The walker now sees through `NonNullExpression` and `AsExpression` (both erased at runtime, so
+the connection PATH is unchanged), matching the non-paginated `useData` analyzer, which already
+strips non-null assertions.

.changeset/consolidate-fat-package.md

@@ -0,0 +1,27 @@
+---
+'@getcronit/pylon': major
+---
+
+Consolidate the monorepo into a single batteries-included `@getcronit/pylon` package.
+
+The previously separate `@getcronit/pylon-{db,ir,query,queues,auth,pages,dev}`
+packages are now folded into `@getcronit/pylon` and exposed as subpath exports.
+The `pylon` CLI now ships from `@getcronit/pylon` itself (no separate
+`@getcronit/pylon-dev`).
+
+### Migration
+
+- Replace feature imports with the matching subpath:
+  - `@getcronit/pylon-db` → `@getcronit/pylon/db`
+  - `@getcronit/pylon-ir` → `@getcronit/pylon/ir`
+  - `@getcronit/pylon-query` → `@getcronit/pylon/query`
+  - `@getcronit/pylon-queues` → `@getcronit/pylon/queues`
+  - `@getcronit/pylon-auth` → `@getcronit/pylon/auth` (`/contract`, `/zitadel` preserved)
+  - `@getcronit/pylon-pages` → `@getcronit/pylon/pages`
+- Plugin factories now live under a per-feature `/plugin` subpath:
+  - `useDatabase` → `@getcronit/pylon/db/plugin`
+  - `useQueues` → `@getcronit/pylon/queues/plugin`
+  - `useIdentity` → `@getcronit/pylon/auth/plugin`
+  - `usePages` → `@getcronit/pylon/pages/plugin`
+- Drop every `@getcronit/pylon-*` dependency from your `package.json` and depend on
+  `@getcronit/pylon` alone. The `pylon` binary comes from it.

.changeset/create-pylon-rolldown-build.md

@@ -0,0 +1,9 @@
+---
+'create-pylon': patch
+---
+
+Build `create-pylon` with rolldown instead of esbuild. esbuild was removed when the repo
+standardized its build pipeline on rolldown, which left `create-pylon`'s build script
+calling a binary that no longer exists (`esbuild: not found`). It now bundles the CLI via
+a `rolldown.config.mjs` — same output shape (single ESM file, deps external, shebang
+preserved).

.changeset/create-pylon-v3-templates.md

@@ -0,0 +1,60 @@
+---
+'create-pylon': major
+---
+
+Update the scaffold templates to the v3 contract — every runtime `create-pylon` produced
+failed on its first `pylon build`.
+
+The templates still emitted the pre-`Pylon`-class shape: a named `export const graphql`
+plus a `serve(app, …)` side effect in the entry. Since the compiler now type-introspects
+the DEFAULT export, Node projects died with "Pylon entry must export default the app",
+while Bun and Cloudflare Workers projects got further on `export default app` (the empty
+singleton) and then failed with the far less obvious "Query root type must be provided" —
+their resolvers silently dropped.
+
+- The entry is now `export default new Pylon({graphql})` and is identical across runtimes:
+  pure, with no import-time serving side effect.
+- Serving is declared in `pylon.config.ts`. Node scaffolds get `useNodeServer()`, ordered
+  last so the port binds only after every route (including the usePages catch-all) is
+  mounted; Bun, Deno and workerd need no plugin — they serve the default export of the
+  built `.pylon/server.mjs` themselves.
+- Dropped `pylon dev -c "<cmd>"` from the Bun, Deno and Cloudflare Workers scripts. `pylon
+  dev` is direct in-process execution now and rejects `-c` outright.
+- Deno projects get a `package.json`. `pylon dev`/`pylon build` are Node processes, and
+  Node's TypeScript loader reads the nearest `package.json` for ESM-vs-CJS — without
+  `"type": "module"` the build failed on `require(esm)` loading `pylon.config.ts`. It also
+  becomes the single source of truth for the dependency, so `deno.json` drops its duplicate
+  `imports` entry. Its `start` task uses `deno serve` (`deno run` does not serve a default
+  export).
+- Dropped the now-unneeded `@hono/node-server` dependency from Node scaffolds (the entry no
+  longer imports it, and `@getcronit/pylon` depends on it).
+- Fixed both Dockerfiles running `{npm,bun} run pylon build`, which is not a script in the
+  generated `package.json`.
+
+Pages templates: the starter Button carried a typo'd `inline-flexxx` class, which Tailwind
+does not generate — the button silently lost `display: inline-flex` and the
+`items-center justify-center gap-2` layout that depends on it. `components.json` also
+pointed `tailwind.config` at a `tailwind.config.js` the scaffold never emits; the scaffold
+is Tailwind v4 (theme in `globals.css` under `@theme`), so that field is now `""`, which is
+what `npx shadcn@latest add …` reads to target the v4 component shape.
+
+Pages templates, Tailwind v4: the theme block is now `@theme inline`. A plain `@theme`
+emits `--color-background: hsl(var(--background))` into `:root`, where custom-property
+substitution happens once — the resolved colour then inherits down as a literal, so a
+nested `.dark` re-declaring `--background` never reached it and `bg-background` (and even
+`dark:bg-card`) stayed light. That contradicted the scaffold's own
+`@custom-variant dark (&:is(.dark *))`, which targets descendants of `.dark` rather than
+requiring it on `<html>`. Both scopings now work.
+
+Pages templates: the root layout is typed with the exported `LayoutProps` instead of an
+ad-hoc `{children: React.ReactNode}`, so the starter shows that a layout also receives
+`params`, `searchParams`, `path` and `context`.
+
+CLI: a bare `--features` (no values) crashed with `features is not iterable`; it now means
+"no features". Added `--no-install` and `-y, --yes` so the CLI can run unattended in
+scripts and CI.
+
+A new e2e (`e2e/tests/create-pylon-scaffold.e2e.test.ts`) scaffolds every runtime and
+feature combination with the shipped binary, runs the shipped `pylon build` on each, and
+boots the built Node artifact to query it over HTTP — so the templates cannot drift away
+from the framework unnoticed again.

.changeset/dev-alias-node-selection.md

@@ -0,0 +1,19 @@
+---
+'@getcronit/pylon': patch
+---
+
+Fix `usePaginatedData`/`useData` node selections collapsing to `{ id }` in dev.
+
+The dev pages analyzer runs a ts-morph project that maps every non-relative import to an
+empty dummy (so third-party packages don't need to be parsed). That dummy also swallowed the
+app's own `@/*` path aliases, so a page importing its components and the connection node type
+via `@/…` (e.g. `DataGridColumn<AuditEvent>` from `@/components` + `@/.pylon/client`) left the
+project too thin for the connection pass to trace inline node-field reads — the selection
+collapsed to `node { id }`. On soft navigation the client then fetched partial nodes,
+normalized them, and components reading the missing fields (`e.actorLabel`, `e.metadata`)
+threw. The production rolldown build was unaffected because it feeds the whole module graph
+through the analyzer (every file already loaded by absolute path).
+
+Dev now hands the analyzer the app's `tsconfig.json` so `@/*` resolves to real files, and the
+per-module eager-loader follows imports transitively (through aliases, stopping at
+`node_modules`) — so the dev selection matches the build byte-for-byte.

.changeset/dev-inspector-port.md

@@ -0,0 +1,24 @@
+---
+'@getcronit/pylon': patch
+---
+
+Improve `pylon dev` debugging and quiet a dev-server warning.
+
+- **`pylon dev --inspect [port]`** (and `--inspect-brk`) opens the Node inspector on
+  the dev process itself — the one that runs your resolvers — so breakpoints bind and
+  you get a single clean debug target. It works through a package manager
+  (`pnpm pylon dev --inspect`) because it doesn't rely on an inherited `--inspect` flag
+  that the package-manager wrapper would grab first.
+- When dev *is* launched with an inherited inspector (`node --inspect …/pylon dev` or
+  `NODE_OPTIONS=--inspect`), the flag is now stripped from what the bundler workers
+  inherit (`NODE_OPTIONS` + `execArgv`), so they no longer race the app for the port —
+  no more `Starting inspector … address already in use` stack, and DevTools attaches to
+  your code instead of a worker.
+- Filtered a spurious `optimizeDeps.esbuildOptions … deprecated` warning from the pages
+  dev server. It originates in `@vitejs/plugin-react` (the version compatible with the
+  transitional `rolldown-vite`); rolldown-vite honors the option but warns, and the fix
+  upstream needs Vite 8. The warning is dropped until those majors line up.
+- With a debugger attached, the dev logger now splits its output cleanly: the terminal
+  keeps a single pretty line per record while the Chrome DevTools console receives the
+  full record as an expandable, inspectable object (via `inspector.console`, which
+  bypasses stdout) — no more multi-line object dumps in the terminal.

.changeset/dev-runner-loaders.md

@@ -0,0 +1,19 @@
+---
+'@getcronit/pylon': patch
+---
+
+`pylon dev`: externalize all node_modules in the backend runner + add JSON/CSS loader hooks.
+
+The dev runner now sets `ssr.external: true` so every dependency loads natively through Node
+instead of Vite's SSR transform — routing CJS packages through the transform ESM-ifies them and
+breaks their dynamic `require`s. That native-load path then needs two Node module hooks (registered
+before the app boots):
+
+- **JSON** — Node's ESM loader requires an explicit `with { type: 'json' }` attribute, so a
+  dependency doing a bare `require('./x.json')` (e.g. `i18n-iso-countries`'s `langs/*.json`) threw
+  `ERR_IMPORT_ATTRIBUTE_MISSING`. The resolve hook stamps `type: 'json'` on `.json` URLs.
+- **CSS** — a server-side `import 'pkg/x.css'` is meaningless for SSR (styles ship via the client
+  build) and Node can't load `.css`; the load hook returns an empty module instead of crashing.
+
+Together with keeping node_modules external in the build, this lets apps that pull in packages with
+dynamic data `require`s or bare CSS imports run `pylon dev` and `pylon build`.

.changeset/dev-version-mismatch-reload.md

@@ -0,0 +1,12 @@
+---
+'@getcronit/pylon': patch
+---
+
+Fix an infinite reload loop in dev on pages that refetch on mount.
+
+The query fetcher reloads the page when a response's `X-Pylon-Version` header differs from the
+client's `window.__PYLON_VERSION__` (a production signal to pull a fresh client after a deploy).
+In dev the client is stamped `'dev'` while the server sends the content-hashed pages-manifest
+version, so they ALWAYS differ — and any page that refetches on mount (e.g. `usePaginatedData`'s
+SWR revalidation) looped: fetch → version mismatch → reload → refetch → reload. The check now
+no-ops in dev (client version `'dev'`), where HMR handles updates.

.changeset/dev-watch-source-only.md

@@ -0,0 +1,12 @@
+---
+'@getcronit/pylon': patch
+---
+
+Fix `pylon dev` reload loop: only react to source-code edits, not runtime file writes.
+
+The dev watcher watched the whole project and full-reloaded the browser on any file change
+(outside node_modules/.pylon/.git). A request whose resolver wrote a file into the project at
+runtime — a media thumbnail, cache, log, upload — tripped the watcher, which reloaded the
+page, which re-ran the request, which wrote again: an infinite reload loop on that route. The
+watcher now reacts only to source extensions (.ts/.tsx/.js/.jsx/.mjs/.cjs/.css) and logs which
+file triggered a reload, so runtime data writes no longer cause reloads.

.changeset/gold-boxes-switch.md

@@ -0,0 +1,17 @@
+---
+'@getcronit/pylon': major
+---
+
+- Integrated `@getcronit/pylon-builder` directly into `@getcronit/pylon-dev`.
+  - Removed the `pylon-builder` package.
+  - The builder now utilizes the `esbuild` watch mode for development. This is a much faster and more efficient way to build the project.
+- Implemented `pm2` for process management:
+  - `pm2` is now used to manage the `pylon-dev` server. After files are built, the server is restarted automatically.
+  - The stdout and stderr logs are logged directly with `consola`.
+- Now builds a cross-environment client in `.pylon/client` using `gqty`. This will be used for pylon/pages.
+
+### Breaking Change: Removed Client Generation Feature
+
+- **What**: The client generation feature has been removed.
+- **Why**: We have decided to use `gqty` directly to streamline the development process and reduce complexity.
+- **How to Update**: Consumers should now use the [GQty CLI](https://gqty.dev/api-reference/cli#basic-usage) directly to generate their clients. Update your build scripts and development workflows to integrate `gqty` as described in the GQty documentation.

.changeset/in-context-analyzer.md

@@ -0,0 +1,44 @@
+---
+'@getcronit/pylon': minor
+---
+
+Compiled documents carry `@inContext`, so resolvers are locale-correct with no per-query
+wiring.
+
+```ts
+Query: {
+  productName: async (id: number): Promise<string> =>
+    (await ProductTranslation.objects
+      .filter({productId: id, locale: getLocale() ?? 'en'})
+      .first())?.name ?? (await Product.objects.get({id})).name
+}
+```
+
+```tsx
+const data = useData()
+data.product({id}).name        // German on /de, French on /fr — nothing passed at the call site
+```
+
+With `usePages({i18n})` configured, every operation the analyzer compiles is emitted as
+`query page_0($__locale: String) @inContext(locale: $__locale)`, and the query client supplies
+the locale. Queries and mutations both — a mutation returns localized content too.
+
+The locale is held **per client**, not in a module-level variable: the SSR pass builds one
+client per request, so concurrent renders in different locales cannot bleed into each other.
+The browser has one client and one locale, because switching locale is a document navigation.
+
+It is merged into the variables **before** the cache key is computed, at every entry point
+that computes one (`fetch`, `ensure`, `revalidate`, `refetch`) — otherwise one path would read
+a different slot than another wrote. Verified end to end:
+
+```
+qd09ab19da988723b~1emsiz4  →  {"serverGreeting": "Server: hallo"}
+qd09ab19da988723b~1emubph  →  {"serverGreeting": "Server: bonjour"}
+```
+
+Same document, different variables hash. With the locale in a header these would have been one
+entry, and one language would have served the other's data.
+
+Documented in the i18n guide, including why a resolver cannot simply read the page's request
+context: the SSR pass reaches GraphQL through a separate in-process request, and after
+hydration there is no page request at all.

.changeset/in-context-dev-parity.md

@@ -0,0 +1,25 @@
+---
+'@getcronit/pylon': patch
+---
+
+Fix `@inContext` missing from client documents under `pylon dev`, and drop the dead
+`createPagesClient` export.
+
+`pylon dev` builds the SSR bundle with the rolldown analyzer and the CLIENT bundle with the
+Vite one. Only the rolldown path was told about `i18n`, so dev shipped a server that knew the
+locale and a client that did not: SSR rendered German, then the first refetch sent a
+directive-less document and the page flipped to English. Production was unaffected — the
+worst place for a difference to live, since dev is where it would be seen and dismissed.
+
+Reproduced in a browser before fixing: the wire carried `query page_0 { serverGreeting }` with
+no variables, and the DOM went `Server: hallo` → `Server: hello`.
+
+The dev server now reads the `usePages` plugin's own options — `usePages` in dev is only a
+`pages/` directory check, so the plugin is the sole source of whether i18n is configured — and
+`Plugin.options` exposes them, since options passed to a plugin factory are otherwise captured
+in its closure.
+
+Also removes `createPagesClient` from the generated client. It was introduced with the
+pylon-query layer and never called by anything; parameterising it with a locale (as an earlier
+pass did) was polish on dead code. Apps needing a per-request SSR client can use
+`createPylonQueryClient` from `@getcronit/pylon/query`, which takes a locale.

.changeset/in-context-directive.md

@@ -0,0 +1,37 @@
+---
+'@getcronit/pylon': minor
+---
+
+`@inContext` — per-operation request context, read by resolvers.
+
+```graphql
+query Products($__locale: String) @inContext(locale: $__locale) {
+  products { name }
+}
+```
+
+```ts
+import {getLocale} from '@getcronit/pylon'
+
+Query: {
+  greeting: (): string => translations[getLocale() ?? 'en'] ?? translations.en
+}
+```
+
+The directive is defined in every emitted schema, read in `onExecute`, and exposed to
+resolvers through `getLocale()` / `getInContext()`. A locale may be an inline literal or a
+variable; the variable form is what compiled documents will use, so one document serves every
+locale.
+
+**Why a directive rather than an HTTP header.** `pylon-query` keys its store on
+`documentId ~ variablesHash(variables)` and nothing else. With the locale in a header, the
+same document with the same variables would be the same cache entry — English and German
+results colliding on one key, in the client store and the hydration envelope alike. Putting
+the context in the document makes it part of the cache key by construction. Shopify's
+Storefront API arrived at the same directive for the same reason.
+
+`getLocale()` returns `undefined` when the operation states no locale, rather than defaulting:
+the caller did not ask, so the resolver decides what neutral means.
+
+This is the server half. Automatic injection into `useData`-compiled documents — so a pages
+app gets locale-correct resolvers with no per-query wiring — is the remaining piece.

.changeset/inline-json-imports.md

@@ -0,0 +1,17 @@
+---
+'@getcronit/pylon': patch
+---
+
+Inline JSON imports in the build instead of externalizing them.
+
+Both the pages SSR build and the backend transpile externalized everything under
+`node_modules`, including `.json`. A bundler-visible `import x from "pkg/x.json"` (e.g. the app
+importing `i18n-iso-countries/langs/de.json`) therefore survived to runtime, where Node's
+strict ESM loader rejects it for lacking a `with { type: 'json' }` attribute
+(`ERR_IMPORT_ATTRIBUTE_MISSING`) — crashing a plain `node .pylon/server.mjs` / standalone
+artifact at plugin setup.
+
+`.json` is now inlined by rolldown (its default, and what the client bundle already did),
+keeping the output runtime-agnostic (no attribute, no loose file) rather than relying on a
+per-runtime Node loader hook. A dependency that dynamically `require`s its OWN data files at
+runtime is unaffected: its JS stays external, so those requires still resolve from disk.

.changeset/legible-fk-violations.md

@@ -0,0 +1,14 @@
+---
+'@getcronit/pylon': patch
+---
+
+Surface foreign-key violations with a message a human can act on.
+
+A manyToMany link whose owner or target row doesn't exist failed with Postgres's opaque
+`insert or update … violates foreign key constraint "<hash>"` — no hint at WHICH side, WHICH id,
+or WHICH relation, buried under a kysely/pg stack. `ManyToManyManager.add`/`set` now map the
+23503 SQLSTATE (via the new `foreignKeyViolation` helper + `ForeignKeyViolationError`) to a
+message that names the missing model and id from the driver's `detail` — e.g. *"Cannot link
+ProductVariant ↔ ProductOptionValue: ProductOptionValue \"…\" does not exist. It was referenced
+but not found — likely created out of order, or removed earlier in the same operation."* — with
+the driver error kept as `cause`. This mirrors the existing unique-violation (23505) mapping.

.changeset/legible-plugin-setup-errors.md

@@ -0,0 +1,15 @@
+---
+'@getcronit/pylon': patch
+---
+
+Make plugin-setup failures legible.
+
+When a plugin's `setup()` threw, the framework wrapped it by stringifying the original error's
+full `.stack` into a NEW error's message. Node then printed that blob PLUS the wrapper's own
+stack — a duplicated, nested wall of text with the actual one-line cause (e.g. "Module …/de.json
+needs an import attribute of type: json") buried in the middle.
+
+The wrapper now keeps its message to one human-readable line (the underlying error's `.message`)
+and attaches the original error via `cause`, so Node renders a clean `[cause]:` chain with the
+real stack intact. Built-in plugins that lacked a `name` (`usePages` → `pages`, `useQueues` →
+`queues`) now set one, so the failing plugin is named in the message instead of shown as `#1`.