V3

.changeset/gold-boxes-switch.md

@@ -0,0 +1,17 @@
+---
+'@getcronit/pylon-dev': 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/popular-pugs-serve.md

@@ -0,0 +1,40 @@
+---
+'@getcronit/pylon': minor
+'@getcronit/pylon-dev': minor
+---
+
+Extend plugin system with setup, middleware, and build functions.
+The viewer is now integrated via a built-in `useViewer` plugin.
+
+Custom plugins can now access the app instance and register routes, middleware, and custom build steps.
+
+```ts
+import {Plugin} from '@getcronit/pylon'
+
+export function myPlugin(): Plugin {
+  return {
+    setup(app) {
+      app.use((req, res, next) => {
+        console.log('Request:', req.url)
+        next()
+      })
+
+      app.get('/hello', (req, res) => {
+        res.send('Hello, World!')
+      })
+    },
+    middleware: (c, next) => {
+      // This middleware will be inserted higher in the middleware stack
+      console.log('Middleware:', c.req.url)
+      next()
+    },
+    build: async () => {
+      // Custom esbuild build
+      const ctx = await esbuild.context(...)
+
+      // Must return the context
+      return ctx
+    }
+  }
+}
+```

.changeset/real-horses-smash.md

@@ -0,0 +1,5 @@
+---
+'@getcronit/pylon-dev': patch
+---
+
+Fix broken field descriptions in schema parsing

.changeset/rotten-ravens-sin.md

@@ -0,0 +1,26 @@
+---
+'@getcronit/pylon': minor
+---
+
+Add `usePages` plugin to support file-based (Fullstack React) routing. https://github.com/getcronit/pylon/issues/69
+
+```ts
+import {app, usePages, PylonConfig} from '@getcronit/pylon'
+
+export const graphql = {
+  Query: {
+    hello: () => {
+      return 'Hello, world!'
+    },
+    post: (slug: string) => {
+      return {title: `Post: ${slug}`, content: 'This is a blog post.'}
+    }
+  }
+}
+
+export const config: PylonConfig = {
+  plugins: [usePages()] // Enables the Pages Router
+}
+
+export default app
+```

.changeset/shy-countries-help.md

@@ -0,0 +1,13 @@
+---
+'@getcronit/pylon': minor
+---
+
+Show a fallback page for the landing page and unhandled routes / 404s.
+
+This behavior can be disabled via the pylon config:
+
+```ts
+export const config: PylonConfig = {
+  landingPage: false
+}
+```

.changeset/slimy-garlics-battle.md

@@ -0,0 +1,13 @@
+---
+'create-pylon': patch
+---
+
+- Use `consola` for clearer interactive prompts and logs.
+- Remove `--client`, `--client-path`, and `--client-port` flags in favor of [GQty CLI](https://gqty.dev/api-reference/cli#basic-usage)
+- Improved package manager detection and dependency installation. https://github.com/getcronit/pylon/issues/73
+- Removed `--template` flag in favor of `--features` flag. Each runtime can now support multiple features which pre-configure the project for different use-cases.
+  Currently supported features:
+  - `pages`: React SSR Pages with file-based routing
+  - `auth`: OIDC Authentication (Primarily for ZITADEL but can be used with any OIDC provider)
+- The success message now only shows the `deploy` script if it is available.
+- Improved error handling and messaging.

.changeset/soft-goats-run.md

@@ -0,0 +1,36 @@
+---
+'@getcronit/pylon': major
+---
+
+**Summary:**
+This changeset introduces a major overhaul to the built-in authentication system. The new implementation automatically sets up `/auth/login`, `/auth/callback`, and `/auth/logout` routes, injects an `auth` object into the context, and manages token cookies. Role-based route protection is now enhanced via `authMiddleware` and the updated `requireAuth` decorator, configurable through the streamlined `useAuth` plugin.
+
+---
+
+**Breaking Changes:**
+
+- **WHAT:**  
+  The authentication configuration has been completely revamped. The previous manual setup is replaced by the `useAuth` plugin. Custom authentication route definitions are no longer necessary, and existing middleware or decorator usage may require adjustments.
+
+- **WHY:**  
+  This change was implemented to simplify authentication setup, reduce boilerplate, improve security by automating context and cookie management, and offer better role-based access control.
+
+- **HOW:**  
+  Consumers should:
+  1. Remove any custom authentication route setups.
+  2. Update their configuration to use the new `useAuth` plugin as shown below:
+     ```typescript
+     export const config: PylonConfig = {
+       plugins: [
+         useAuth({
+           issuer: 'https://test-0o6zvq.zitadel.cloud',
+           endpoint: '/auth',
+           keyPath: 'key.json'
+         })
+       ]
+     }
+     ```
+  3. Replace previous authentication middleware or decorators with the updated `requireAuth` and `authMiddleware` APIs.
+  4. Test the new authentication endpoints (`/auth/login`, `/auth/callback`, and `/auth/logout`) to ensure proper integration.
+
+Ensure you update your code accordingly to avoid disruptions in your authentication flow.

.changeset/young-islands-bow.md

@@ -0,0 +1,16 @@
+---
+'@getcronit/pylon': minor
+---
+
+- Option to disable the playground and introspection in the Pylon configuration. https://github.com/getcronit/pylon/issues/72
+
+### Example
+
+To disable the playground and introspection, set the `graphiql` property to `false` in your Pylon configuration:
+
+```ts
+export const config: PylonConfig = {
+  // Disable the playground and introspection
+  graphiql: false
+}
+```

.gitignore

@@ -9,4 +9,6 @@ node_modules
 
 bun.lockb
 
-.DS_Store
+.DS_Store
+
+examples

docs/pages/docs/core-concepts/built-in-authentication-and-authorization.mdx

@@ -2,65 +2,86 @@ import {Callout} from '@components/callout'
 
 # Built-in Authentication and Authorization
 
-Discover how Pylon simplifies user authentication and authorization with its comprehensive built-in features, empowering you to secure your web services effortlessly.
+Pylon now offers an enhanced, streamlined authentication system. With this update, the auth endpoint automatically creates routes for **/auth/login**, **/auth/callback**, and **/auth/logout**. When a user authenticates, Pylon sets an `auth` object in the context variables and automatically manages a cookie with the token—simplifying session management and ensuring a secure experience.
+
+---
 
 ## General Setup
 
-Before diving into authentication and authorization with Pylon, it's essential to set up your environment and configure the necessary components. Pylon's built-in authentication system follows the OIDC standard and is currently tightly integrated with ZITADEL for user management and access control.
+Before you begin, configure your environment to integrate with your authentication provider (e.g., ZITADEL). The new configuration uses the `useAuth` plugin to initialize authentication routes and settings.
 
-1. **Environment Variables:**
-   Ensure you have the required environment variables set up in your project:
+```typescript
+import {
+  app,
+  PylonConfig,
+  requireAuth,
+  useAuth,
+  authMiddleware
+} from '@getcronit/pylon'
+
+export const config: PylonConfig = {
+  plugins: [
+    useAuth({
+      issuer: 'https://test-0o6zvq.zitadel.cloud',
+      endpoint: '/auth', // optional, default is '/auth'
+      keyPath: 'key.json' // optional, default is 'key.json'
+    })
+  ]
+}
+```
 
-   ```
-   AUTH_ISSUER=https://test-0o6zvq.zitadel.cloud
-   AUTH_PROJECT_ID=<your_auth_project_id>
-   ```
+**How it works:**
 
-2. **Integration with ZITADEL:**
-   To enable Pylon to authenticate users and manage access control, you need to integrate it with ZITADEL. Follow the documentation provided by ZITADEL to set up projects, applications, keys, and roles.
-   [ZITADEL Projects Documentation](https://zitadel.com/docs/guides/manage/console/projects)
+- **Auth Routes:**  
+  The plugin automatically creates routes for:
+
+  - `/auth/login`
+  - `/auth/callback`
+  - `/auth/logout`
+
+- **Context & Cookie:**  
+  After authentication, an `auth` object is added to your context, and a cookie containing the token is set for subsequent requests.
 
 <Callout type="note" title="Important">
-  Pylon requires a **API** application with the **Private JWT Key** type to
-  authenticate users and manage access control.
+  Ensure that your API application is configured to use a **Private JWT Key**
+  type for secure token management.
 </Callout>
 
+---
+
 ## Authentication Example
 
-Pylon makes authentication seamless by providing a straightforward integration with ZITADEL. Here's how you can set up authentication in your Pylon project:
+To protect sensitive data, use the `requireAuth` decorator. In the example below, any user trying to access the data must be authenticated:
 
 ```typescript
-import {app, auth, requireAuth} from '@getcronit/pylon'
-
-// Define your sensitive data service
+// Define a service for sensitive data
 class SensitiveData {
   @requireAuth()
   static async getData() {
     return 'Sensitive Data'
   }
 }
 
+// Expose the resolver via GraphQL
 export const graphql = {
   Query: {
     sensitiveData: SensitiveData.getData
   }
 }
 
-app.use('*', auth.initialize())
-
 export default app
 ```
 
-In this example, the `requireAuth()` decorator ensures that users are authenticated before accessing sensitive data. You can also specify roles to restrict access to certain data based on user permissions.
+In this setup, the `@requireAuth()` decorator ensures that only authenticated users can access the `getData` method. If the user is not authenticated, they will be redirected to the login flow at `/auth/login`.
 
 ---
 
 ## Authorization Example
 
-Authorization in Pylon allows you to control access to specific resources based on user roles and permissions. Here's how you can implement authorization in your Pylon project:
+If you need to restrict access based on roles, you can pass a roles array to the `requireAuth` decorator. For instance, the following example limits access to users with the `"admin"` role:
 
 ```typescript
-// Define your sensitive data service
+// Define a service for admin-only data
 class SensitiveData {
   @requireAuth({
     roles: ['admin']
@@ -70,72 +91,63 @@ class SensitiveData {
   }
 }
 
-// Define your GraphQL schema
+// Expose the resolver via GraphQL
 export const graphql = {
   Query: {
     sensitiveAdminData: SensitiveData.getAdminData
   }
 }
 
-app.use('*', auth.initialize())
-
 export default app
 ```
 
-In this example, the `requireAuth()` decorator ensures that only authenticated users with the "admin" role can access the `getAdminData()` function. You can customize roles and permissions according to your application's requirements.
+Only authenticated users who have the `"admin"` role will be allowed to access `getAdminData()`. Roles should be managed in your authentication provider (e.g., ZITADEL) for centralized control over permissions.
 
-Roles can be defined in ZITADEL and assigned to users to control access to specific resources. By integrating Pylon with ZITADEL, you can easily manage roles and permissions for your application.
-For more information on setting up roles in ZITADEL, refer to the [ZITADEL Roles Documentation](https://zitadel.com/docs/guides/manage/console/roles).
+---
 
-## Securing Routes
+## Securing Routes with Middleware
 
-Securing routes in Pylon involves enforcing authentication and, optionally, authorization for specific endpoints or routes. Here's how you can secure a route in your Pylon project:
+In addition to securing individual resolvers, you can enforce authentication and authorization for entire routes using the new `authMiddleware`. For example, to secure a specific REST endpoint:
 
 ```typescript
-import {auth, requireAuth} from '@getcronit/pylon'
-
-// Define your sensitive data service
-class SensitiveData {
-  static async getData() {
-    return 'Sensitive Data'
-  }
+import {authMiddleware} from '@getcronit/pylon'
 
-  @requireAuth({
+// Secure all routes under /admin to only allow users with the 'admin' role
+app.use(
+  '/admin',
+  authMiddleware({
     roles: ['admin']
   })
-  static async getAdminData() {
-    return 'Admin Data'
-  }
-}
+)
 
-export const graphql = {
-  Query: {
-    sensitiveData: SensitiveData.getData,
-    sensitiveAdminData: SensitiveData.getAdminData
+// Secure specific route to only allow users with the 'admin' role
+app.get(
+  '/secure',
+  authMiddleware({
+    roles: ['admin']
+  }),
+  c => {
+    return c.json({data: 'sensitive'})
   }
-}
-
-// Enforce authentication for all routes
-app.use('*', auth.initialize())
-
-// Secure a specific route with authentication and authorization
-app.use('/admin', auth.requireAuth({roles: ['admin']}))
-
+)
 export default app
 ```
 
-In this example, we're securing the `/admin` route to ensure that only authenticated users with the "admin" role can access it. By using the `requireAuth()` middleware from Pylon's authentication module, we enforce both authentication and authorization for this specific route.
+In this case, any request to the `/admin` route will first pass through `authMiddleware`, ensuring that the user is authenticated and has the required `"admin"` role.
+The same applies to the `/secure` route, which is secured with the `authMiddleware` middleware.
 
-You can customize the route and the required roles according to your application's requirements. This ensures that sensitive endpoints are protected, providing a secure environment for your users' data and resources.
+---
 
 ## Further Resources
 
-For detailed instructions on setting up projects, applications, keys, and roles in ZITADEL, refer to the ZITADEL documentation:
+For additional guidance on integrating with your authentication provider, please refer to the following resources:
 
 - [ZITADEL Projects Documentation](https://zitadel.com/docs/guides/manage/console/projects)
 - [ZITADEL Applications Documentation](https://zitadel.com/docs/guides/manage/console/applications#api)
 - [ZITADEL Roles Documentation](https://zitadel.com/docs/guides/manage/console/roles)
 
+---
+
 ## Conclusion
 
-With Pylon's built-in authentication and authorization features, you can easily secure your web services and control access to sensitive data, providing a seamless and secure user experience.
+With the new built-in authentication and authorization features, Pylon makes securing your web services simpler than ever. The automatic route creation, context management, and cookie handling streamline the login flow, while decorators and middleware give you granular control over access to your application’s data and routes. Enjoy a secure and seamless user experience with minimal configuration!