pastoria 0.0.1 → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# pastoria
+
+## 1.0.1
+
+### Patch Changes
+
+- Pastoria alpha version for testing

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025 Ryan Delaney
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/package.json

@@ -1,14 +1,30 @@
 {
   "name": "pastoria",
-  "version": "0.0.1",
+  "version": "1.0.1",
+  "description": "Pastoria Development CLI",
+  "license": "MIT",
   "type": "module",
-  "bin": "./src/index.mts",
+  "bin": {
+    "pastoria": "src/index.mts"
+  },
   "dependencies": {
+    "@tailwindcss/vite": "^4.1.14",
+    "@vitejs/plugin-react": "^5.0.4",
+    "commander": "^14.0.1",
+    "cookie-parser": "^1.4.7",
+    "dotenv": "^16.6.1",
+    "express": "^5.1.0",
     "picocolors": "^1.1.1",
-    "ts-morph": "^26.0.0"
+    "ts-morph": "^26.0.0",
+    "vite": "^7.1.9",
+    "vite-plugin-cjs-interop": "^2.3.0"
   },
   "devDependencies": {
-    "@types/node": "20.3.1",
-    "typescript": "^5.9.2"
+    "@types/node": "^22.12.0",
+    "typescript": "^5.9.2",
+    "pastoria-runtime": "1.0.1"
+  },
+  "scripts": {
+    "check:types": "tsc --noEmit"
   }
-}
+}

package/src/build.mts

@@ -0,0 +1,127 @@
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+import {cjsInterop} from 'vite-plugin-cjs-interop';
+import {build, type BuildEnvironmentOptions, type Plugin} from 'vite';
+
+// TODO: Only emit `App` code if _app exits.
+const PASTORIA_CLIENT_ENTRY = `// Generated by Pastoria.
+import {createRouterApp} from '#genfiles/router/router';
+import {App} from '#src/pages/_app';
+import {hydrateRoot} from 'react-dom/client';
+
+async function main() {
+  const RouterApp = await createRouterApp();
+  hydrateRoot(document, <RouterApp App={App} />);
+}
+
+main();
+`;
+
+// TODO: Remove hard-coded context import here.
+const PASTORIA_ENTRY_SERVER = `// Generated by Pastoria.
+import {JSResource} from '#genfiles/router/js_resource';
+import {
+  listRoutes,
+  router__createAppFromEntryPoint,
+  router__loadEntryPoint,
+} from '#genfiles/router/router';
+import {getSchema} from '#genfiles/schema/schema';
+import {Context} from '#src/lib/server/context';
+import {App} from '#src/pages/_app';
+import {GraphQLSchema, specifiedDirectives} from 'graphql';
+import {createRouterHandler} from 'pastoria-runtime/server';
+import type {Manifest} from 'vite';
+
+const schemaConfig = getSchema().toConfig();
+const schema = new GraphQLSchema({
+  ...schemaConfig,
+  directives: [...specifiedDirectives, ...schemaConfig.directives],
+});
+
+export function createHandler(
+  persistedQueries: Record<string, string>,
+  manifest?: Manifest,
+) {
+  return createRouterHandler(
+    listRoutes(),
+    JSResource.srcOfModuleId,
+    router__loadEntryPoint,
+    router__createAppFromEntryPoint,
+    App,
+    schema,
+    () => new Context(),
+    persistedQueries,
+    manifest,
+  );
+}
+`;
+
+function pastoriaEntryPlugin(): Plugin {
+  const clientEntryModuleId = 'virtual:pastoria-entry-client.tsx';
+  const serverEntryModuleId = 'virtual:pastoria-entry-server.tsx';
+
+  return {
+    name: 'pastoria-entry',
+    resolveId(id) {
+      if (id === clientEntryModuleId) {
+        return clientEntryModuleId; // Return without \0 prefix so React plugin can see .tsx extension
+      } else if (id === serverEntryModuleId) {
+        return serverEntryModuleId;
+      }
+    },
+    load(id) {
+      if (id === clientEntryModuleId) {
+        return PASTORIA_CLIENT_ENTRY;
+      } else if (id === serverEntryModuleId) {
+        return PASTORIA_ENTRY_SERVER;
+      }
+    },
+  };
+}
+
+export const CLIENT_BUILD: BuildEnvironmentOptions = {
+  outDir: 'dist/client',
+  rollupOptions: {
+    input: 'virtual:pastoria-entry-client.tsx',
+  },
+};
+
+export const SERVER_BUILD: BuildEnvironmentOptions = {
+  outDir: 'dist/server',
+  ssr: true,
+  rollupOptions: {
+    input: 'virtual:pastoria-entry-server.tsx',
+  },
+};
+
+export function createBuildConfig(buildEnv: BuildEnvironmentOptions) {
+  return {
+    appType: 'custom' as const,
+    build: {
+      ...buildEnv,
+      assetsInlineLimit: 0,
+      manifest: true,
+      ssrManifest: true,
+    },
+    plugins: [
+      pastoriaEntryPlugin(),
+      tailwindcss(),
+      react({babel: {plugins: ['relay']}}),
+      cjsInterop({
+        dependencies: ['react-relay', 'react-relay/hooks', 'relay-runtime'],
+      }),
+    ],
+  };
+}
+
+export async function createBuild() {
+  const clientBuild = await build({
+    ...createBuildConfig(CLIENT_BUILD),
+    configFile: false,
+  });
+
+  const serverBuild = await build({
+    ...createBuildConfig(SERVER_BUILD),
+    configFile: false,
+  });
+}

package/src/devserver.mts

@@ -0,0 +1,53 @@
+import cookieParser from 'cookie-parser';
+import dotenv from 'dotenv';
+import express from 'express';
+import {readFile} from 'node:fs/promises';
+import pc from 'picocolors';
+import {createServer as createViteServer, type Manifest} from 'vite';
+import {CLIENT_BUILD, createBuildConfig} from './build.mts';
+
+interface PersistedQueries {
+  [hash: string]: string;
+}
+
+interface ServerEntry {
+  createHandler(
+    persistedQueries: PersistedQueries,
+    manifest?: Manifest,
+  ): express.Router;
+}
+
+export async function startDevserver(opts: {port: string}) {
+  dotenv.config();
+
+  const buildConfig = createBuildConfig(CLIENT_BUILD);
+  const vite = await createViteServer({
+    ...buildConfig,
+    configFile: false,
+    server: {middlewareMode: true},
+  });
+
+  const app = express();
+  app.use(cookieParser());
+  app.use(vite.middlewares);
+  app.use(async (req, res, next) => {
+    const persistedQueries = JSON.parse(
+      await readFile('__generated__/persisted_queries.json', 'utf-8'),
+    );
+
+    const {createHandler} = (await vite.ssrLoadModule(
+      'virtual:pastoria-entry-server.tsx',
+    )) as ServerEntry;
+
+    const handler = createHandler(persistedQueries);
+    handler(req, res, next);
+  });
+
+  app.listen(Number(opts.port), (err) => {
+    if (err) {
+      console.error(err);
+    } else {
+      console.log(pc.cyan(`Listening on port ${opts.port}!`));
+    }
+  });
+}

package/src/generate.mts

@@ -0,0 +1,277 @@
+/**
+ * @fileoverview Router Code Generator
+ *
+ * This script generates type-safe router configuration files by scanning TypeScript
+ * source code for JSDoc annotations. It's part of the "Pastoria" routing framework.
+ *
+ * How it works:
+ * 1. Scans all TypeScript files in the project for exported functions/classes
+ * 2. Looks for JSDoc tags: @route, @resource, and @param
+ * 3. Generates three files from templates:
+ *    - js_resource.ts: Resource configuration for lazy loading
+ *    - router.tsx: Client-side router with type-safe routes
+ *    - server_router.ts: Server-side router configuration
+ *
+ * Usage:
+ * - Add @route <route-name> to functions to create routes
+ * - Add @param <name> <type> to document route parameters
+ * - Add @resource <resource-name> to exports for lazy loading
+ *
+ * The generator automatically creates Zod schemas for route parameters based on
+ * TypeScript types, enabling runtime validation and type safety.
+ */
+
+import {readFile} from 'node:fs/promises';
+import * as path from 'node:path';
+import {default as pc} from 'picocolors';
+import {Project, SourceFile, Symbol, SyntaxKind, ts, TypeFlags} from 'ts-morph';
+
+const JS_RESOURCE_FILENAME = '__generated__/router/js_resource.ts';
+const JS_RESOURCE_TEMPLATE = path.join(
+  path.dirname(new URL(import.meta.url).pathname),
+  '../templates/js_resource.ts',
+);
+
+const ROUTER_FILENAME = '__generated__/router/router.tsx';
+const ROUTER_TEMPLATE = path.join(
+  path.dirname(new URL(import.meta.url).pathname),
+  '../templates/router.tsx',
+);
+
+async function loadRouterFiles(project: Project) {
+  async function loadSourceFile(fileName: string, templateFileName: string) {
+    const template = await readFile(templateFileName, 'utf-8');
+    const warningComment = `/*
+ * This file was generated by \`pastoria\`.
+ * Do not modify this file directly. Instead, edit the template at ${path.basename(templateFileName)}.
+ */
+
+`;
+    return project.createSourceFile(fileName, warningComment + template, {
+      overwrite: true,
+    });
+  }
+
+  const [jsResource, router] = await Promise.all([
+    loadSourceFile(JS_RESOURCE_FILENAME, JS_RESOURCE_TEMPLATE),
+    loadSourceFile(ROUTER_FILENAME, ROUTER_TEMPLATE),
+  ]);
+
+  return {jsResource, router} as const;
+}
+
+type RouterResource = {
+  resourceName: string;
+  sourceFile: SourceFile;
+  symbol: Symbol;
+};
+
+type RouterRoute = {
+  routeName: string;
+  sourceFile: SourceFile;
+  symbol: Symbol;
+  params: Map<string, ts.Type>;
+};
+
+function collectRouterNodes(project: Project) {
+  const resources: RouterResource[] = [];
+  const routes: RouterRoute[] = [];
+
+  function visitRouterNodes(sourceFile: SourceFile) {
+    // TODO: Skip sourceFile if a pastora JSDoc tag isn't used at all.
+    sourceFile.getExportSymbols().forEach((symbol) => {
+      let routerResource = null as RouterResource | null;
+      let routerRoute = null as RouterRoute | null;
+      const routeParams = new Map<string, ts.Type>();
+
+      function visitJSDocTags(tag: ts.JSDoc | ts.JSDocTag) {
+        if (ts.isJSDoc(tag)) {
+          tag.tags?.forEach(visitJSDocTags);
+        } else if (ts.isJSDocParameterTag(tag)) {
+          const typeNode = tag.typeExpression?.type;
+          const tc = project.getTypeChecker().compilerObject;
+
+          const type =
+            typeNode == null
+              ? tc.getUnknownType()
+              : tc.getTypeFromTypeNode(typeNode);
+
+          routeParams.set(tag.name.getText(), type);
+        } else if (typeof tag.comment === 'string') {
+          switch (tag.tagName.getText()) {
+            case 'route': {
+              routerRoute = {
+                routeName: tag.comment,
+                sourceFile,
+                symbol,
+                params: routeParams,
+              };
+              break;
+            }
+            case 'resource': {
+              routerResource = {
+                resourceName: tag.comment,
+                sourceFile,
+                symbol,
+              };
+              break;
+            }
+          }
+        }
+      }
+
+      symbol
+        .getDeclarations()
+        .flatMap((decl) => ts.getJSDocCommentsAndTags(decl.compilerNode))
+        .forEach(visitJSDocTags);
+
+      if (routerRoute != null) routes.push(routerRoute);
+      if (routerResource != null) resources.push(routerResource);
+    });
+  }
+
+  project.getSourceFiles().forEach(visitRouterNodes);
+  return {resources, routes} as const;
+}
+
+function zodSchemaOfType(tc: ts.TypeChecker, t: ts.Type): string {
+  if (t.getFlags() & TypeFlags.String) {
+    return `z.pipe(z.string(), z.transform(decodeURIComponent))`;
+  } else if (t.getFlags() & TypeFlags.Number) {
+    return `z.coerce.number<number>()`;
+  } else if (t.getFlags() & TypeFlags.Null) {
+    return `z.preprocess(s => s == null ? undefined : s, z.undefined())`;
+  } else if (t.isUnion()) {
+    const isRepresentingOptional =
+      t.types.length === 2 &&
+      t.types.some((s) => s.getFlags() & TypeFlags.Null);
+
+    if (isRepresentingOptional) {
+      const nonOptionalType = t.types.find(
+        (s) => !(s.getFlags() & TypeFlags.Null),
+      )!;
+
+      return `z.pipe(z.nullish(${zodSchemaOfType(tc, nonOptionalType)}), z.transform(s => s == null ? undefined : s))`;
+    } else {
+      return `z.union([${t.types.map((it) => zodSchemaOfType(tc, it)).join(', ')}])`;
+    }
+  } else if (tc.isArrayLikeType(t)) {
+    const typeArg = tc.getTypeArguments(t as ts.TypeReference)[0];
+    const argZodSchema =
+      typeArg == null ? `z.any()` : zodSchemaOfType(tc, typeArg);
+
+    return `z.array(${argZodSchema})`;
+  } else {
+    console.log('Could not handle type:', tc.typeToString(t));
+    return `z.any()`;
+  }
+}
+
+export async function generatePastoriaArtifacts() {
+  const targetDir = process.cwd();
+  const project = new Project({
+    tsConfigFilePath: path.join(targetDir, 'tsconfig.json'),
+  });
+
+  const tc = project.getTypeChecker().compilerObject;
+  const routerFiles = await loadRouterFiles(project);
+  const routerNodes = collectRouterNodes(project);
+
+  const resourceConf = routerFiles.jsResource
+    .getVariableDeclarationOrThrow('RESOURCE_CONF')
+    .getInitializerIfKindOrThrow(SyntaxKind.AsExpression)
+    .getExpressionIfKindOrThrow(SyntaxKind.ObjectLiteralExpression);
+
+  resourceConf.getPropertyOrThrow('noop').remove();
+  for (const {resourceName, sourceFile, symbol} of routerNodes.resources) {
+    const filePath = path.relative(process.cwd(), sourceFile.getFilePath());
+    const moduleSpecifier =
+      routerFiles.jsResource.getRelativePathAsModuleSpecifierTo(
+        sourceFile.getFilePath(),
+      );
+
+    resourceConf.addPropertyAssignment({
+      name: `"${resourceName}"`,
+      initializer: (writer) => {
+        writer.block(() => {
+          writer
+            .writeLine(`src: "${filePath}",`)
+            .writeLine(
+              `loader: () => import("${moduleSpecifier}").then(m => m.${symbol.getName()})`,
+            );
+        });
+      },
+    });
+
+    console.log(
+      'Created resource',
+      pc.cyan(resourceName),
+      'for',
+      pc.green(symbol.getName()),
+      'exported from',
+      pc.yellow(filePath),
+    );
+  }
+
+  const routerConf = routerFiles.router
+    .getVariableDeclarationOrThrow('ROUTER_CONF')
+    .getInitializerIfKindOrThrow(SyntaxKind.AsExpression)
+    .getExpressionIfKindOrThrow(SyntaxKind.ObjectLiteralExpression);
+
+  routerConf.getPropertyOrThrow('noop').remove();
+
+  let entryPointImportIndex = 0;
+  for (const {routeName, sourceFile, symbol, params} of routerNodes.routes) {
+    const importAlias = `e${entryPointImportIndex++}`;
+    const filePath = path.relative(process.cwd(), sourceFile.getFilePath());
+    const moduleSpecifier =
+      routerFiles.router.getRelativePathAsModuleSpecifierTo(
+        sourceFile.getFilePath(),
+      );
+
+    routerFiles.router.addImportDeclaration({
+      moduleSpecifier,
+      namedImports: [
+        {
+          name: symbol.getName(),
+          alias: importAlias,
+        },
+      ],
+    });
+
+    routerConf.addPropertyAssignment({
+      name: `"${routeName}"`,
+      initializer: (writer) => {
+        writer
+          .write('{')
+          .indent(() => {
+            writer.writeLine(`entrypoint: ${importAlias},`);
+            if (params.size === 0) {
+              writer.writeLine(`schema: z.object({})`);
+            } else {
+              writer.writeLine(`schema: z.object({`);
+              for (const [paramName, paramType] of Array.from(params)) {
+                writer.writeLine(
+                  `  ${paramName}: ${zodSchemaOfType(tc, paramType)},`,
+                );
+              }
+
+              writer.writeLine('})');
+            }
+          })
+          .write('} as const');
+      },
+    });
+
+    console.log(
+      'Created route',
+      pc.cyan(routeName),
+      'for',
+      pc.green(symbol.getName()),
+      'exported from',
+      pc.yellow(filePath),
+    );
+  }
+
+  await Promise.all([routerFiles.jsResource.save(), routerFiles.router.save()]);
+}

package/src/index.mts

@@ -1,297 +1,30 @@
 #!/usr/bin/env node --experimental-strip-types
-/**
- * @fileoverview Router Code Generator
- *
- * This script generates type-safe router configuration files by scanning TypeScript
- * source code for JSDoc annotations. It's part of the "Pastoria" routing framework.
- *
- * How it works:
- * 1. Scans all TypeScript files in the project for exported functions/classes
- * 2. Looks for JSDoc tags: @route, @resource, and @param
- * 3. Generates three files from templates:
- *    - js_resource.ts: Resource configuration for lazy loading
- *    - router.tsx: Client-side router with type-safe routes
- *    - server_router.ts: Server-side router configuration
- *
- * Usage:
- * - Add @route <route-name> to functions to create routes
- * - Add @param <name> <type> to document route parameters
- * - Add @resource <resource-name> to exports for lazy loading
- *
- * The generator automatically creates Zod schemas for route parameters based on
- * TypeScript types, enabling runtime validation and type safety.
- *
- * Roadmap:
- * 1. [DONE] Type-safe router APIs - Generate strongly typed navigation functions
- * 2. Support for useTransition during routing - React 19 concurrent features
- * 3. Support for metadata management in <head>
- * 4. HTML manual generator suitable to be read by LLMs - Auto-generated docs
- */
 
-import {readFile} from 'node:fs/promises';
-import * as path from 'node:path';
-import {default as pc} from 'picocolors';
-import {Project, SourceFile, Symbol, SyntaxKind, ts, TypeFlags} from 'ts-morph';
-
-const JS_RESOURCE_FILENAME = '__generated__/router/js_resource.ts';
-const JS_RESOURCE_TEMPLATE = path.join(
-  path.dirname(new URL(import.meta.url).pathname),
-  '../templates/js_resource.ts',
-);
-
-const ROUTER_FILENAME = '__generated__/router/router.tsx';
-const ROUTER_TEMPLATE = path.join(
-  path.dirname(new URL(import.meta.url).pathname),
-  '../templates/router.tsx',
-);
-
-const SERVER_ROUTER_FILENAME = '__generated__/router/server_router.ts';
-const SERVER_ROUTER_TEMPLATE = path.join(
-  path.dirname(new URL(import.meta.url).pathname),
-  '../templates/server_router.ts',
-);
-
-async function loadRouterFiles(project: Project) {
-  async function loadSourceFile(fileName: string, templateFileName: string) {
-    const template = await readFile(templateFileName, 'utf-8');
-    const warningComment = `/*
- * This file was generated by \`pastoria\`.
- * Do not modify this file directly. Instead, edit the template at ${path.basename(templateFileName)}.
- */
-
-`;
-    return project.createSourceFile(fileName, warningComment + template, {
-      overwrite: true,
-    });
-  }
-
-  const [jsResource, router, serverRouter] = await Promise.all([
-    loadSourceFile(JS_RESOURCE_FILENAME, JS_RESOURCE_TEMPLATE),
-    loadSourceFile(ROUTER_FILENAME, ROUTER_TEMPLATE),
-    loadSourceFile(SERVER_ROUTER_FILENAME, SERVER_ROUTER_TEMPLATE),
-  ]);
-
-  return {jsResource, router, serverRouter} as const;
-}
-
-type RouterResource = {
-  resourceName: string;
-  sourceFile: SourceFile;
-  symbol: Symbol;
-};
-
-type RouterRoute = {
-  routeName: string;
-  sourceFile: SourceFile;
-  symbol: Symbol;
-  params: Map<string, ts.Type>;
-};
-
-function collectRouterNodes(project: Project) {
-  const resources: RouterResource[] = [];
-  const routes: RouterRoute[] = [];
-
-  function visitRouterNodes(sourceFile: SourceFile) {
-    sourceFile.getExportSymbols().forEach((symbol) => {
-      let routerResource = null as RouterResource | null;
-      let routerRoute = null as RouterRoute | null;
-      const routeParams = new Map<string, ts.Type>();
-
-      function visitJSDocTags(tag: ts.JSDoc | ts.JSDocTag) {
-        if (ts.isJSDoc(tag)) {
-          tag.tags?.forEach(visitJSDocTags);
-        } else if (ts.isJSDocParameterTag(tag)) {
-          const typeNode = tag.typeExpression?.type;
-          const tc = project.getTypeChecker().compilerObject;
-
-          const type =
-            typeNode == null
-              ? tc.getUnknownType()
-              : tc.getTypeFromTypeNode(typeNode);
-
-          routeParams.set(tag.name.getText(), type);
-        } else if (typeof tag.comment === 'string') {
-          switch (tag.tagName.getText()) {
-            case 'route': {
-              routerRoute = {
-                routeName: tag.comment,
-                sourceFile,
-                symbol,
-                params: routeParams,
-              };
-              break;
-            }
-            case 'resource': {
-              routerResource = {
-                resourceName: tag.comment,
-                sourceFile,
-                symbol,
-              };
-              break;
-            }
-          }
-        }
-      }
-
-      symbol
-        .getDeclarations()
-        .flatMap((decl) => ts.getJSDocCommentsAndTags(decl.compilerNode))
-        .forEach(visitJSDocTags);
-
-      if (routerRoute != null) routes.push(routerRoute);
-      if (routerResource != null) resources.push(routerResource);
-    });
-  }
-
-  project.getSourceFiles().forEach(visitRouterNodes);
-  return {resources, routes} as const;
-}
-
-function zodSchemaOfType(tc: ts.TypeChecker, t: ts.Type): string {
-  if (t.getFlags() & TypeFlags.String) {
-    return `z.pipe(z.string(), z.transform(decodeURIComponent))`;
-  } else if (t.getFlags() & TypeFlags.Number) {
-    return `z.coerce.number<number>()`;
-  } else if (t.getFlags() & TypeFlags.Null) {
-    return `z.preprocess(s => s == null ? undefined : s, z.undefined())`;
-  } else if (t.isUnion()) {
-    const isRepresentingOptional =
-      t.types.length === 2 &&
-      t.types.some((s) => s.getFlags() & TypeFlags.Null);
-
-    if (isRepresentingOptional) {
-      const nonOptionalType = t.types.find(
-        (s) => !(s.getFlags() & TypeFlags.Null),
-      )!;
-
-      return `z.pipe(z.nullish(${zodSchemaOfType(tc, nonOptionalType)}), z.transform(s => s == null ? undefined : s))`;
-    } else {
-      return `z.union([${t.types.map((it) => zodSchemaOfType(tc, it)).join(', ')}])`;
-    }
-  } else if (tc.isArrayLikeType(t)) {
-    const typeArg = tc.getTypeArguments(t as ts.TypeReference)[0];
-    const argZodSchema =
-      typeArg == null ? `z.any()` : zodSchemaOfType(tc, typeArg);
-
-    return `z.array(${argZodSchema})`;
-  } else {
-    console.log('Could not handle type:', tc.typeToString(t));
-    return `z.any()`;
-  }
-}
-
-async function main() {
-  const targetDir = path.resolve(process.argv[2] || process.cwd());
-  process.chdir(targetDir);
-  const project = new Project({
-    tsConfigFilePath: path.join(targetDir, 'tsconfig.json'),
-  });
-  const tc = project.getTypeChecker().compilerObject;
-
-  const routerFiles = await loadRouterFiles(project);
-  const routerNodes = collectRouterNodes(project);
-
-  const resourceConf = routerFiles.jsResource
-    .getVariableDeclarationOrThrow('RESOURCE_CONF')
-    .getInitializerIfKindOrThrow(SyntaxKind.AsExpression)
-    .getExpressionIfKindOrThrow(SyntaxKind.ObjectLiteralExpression);
-
-  resourceConf.getPropertyOrThrow('noop').remove();
-  for (const {resourceName, sourceFile, symbol} of routerNodes.resources) {
-    const filePath = path.relative(process.cwd(), sourceFile.getFilePath());
-    const moduleSpecifier =
-      routerFiles.jsResource.getRelativePathAsModuleSpecifierTo(
-        sourceFile.getFilePath(),
-      );
-
-    resourceConf.addPropertyAssignment({
-      name: `"${resourceName}"`,
-      initializer: (writer) => {
-        writer.block(() => {
-          writer
-            .writeLine(`src: "${filePath}",`)
-            .writeLine(
-              `loader: () => import("${moduleSpecifier}").then(m => m.${symbol.getName()})`,
-            );
-        });
-      },
-    });
-
-    console.log(
-      'Created resource',
-      pc.cyan(resourceName),
-      'for',
-      pc.green(symbol.getName()),
-      'exported from',
-      pc.yellow(filePath),
-    );
-  }
-
-  const routerConf = routerFiles.router
-    .getVariableDeclarationOrThrow('ROUTER_CONF')
-    .getInitializerIfKindOrThrow(SyntaxKind.AsExpression)
-    .getExpressionIfKindOrThrow(SyntaxKind.ObjectLiteralExpression);
-
-  routerConf.getPropertyOrThrow('noop').remove();
-
-  let entryPointImportIndex = 0;
-  for (const {routeName, sourceFile, symbol, params} of routerNodes.routes) {
-    const importAlias = `e${entryPointImportIndex++}`;
-    const filePath = path.relative(process.cwd(), sourceFile.getFilePath());
-    const moduleSpecifier =
-      routerFiles.router.getRelativePathAsModuleSpecifierTo(
-        sourceFile.getFilePath(),
-      );
-
-    routerFiles.router.addImportDeclaration({
-      moduleSpecifier,
-      namedImports: [
-        {
-          name: symbol.getName(),
-          alias: importAlias,
-        },
-      ],
-    });
-
-    routerConf.addPropertyAssignment({
-      name: `"${routeName}"`,
-      initializer: (writer) => {
-        writer
-          .write('{')
-          .indent(() => {
-            writer.writeLine(`entrypoint: ${importAlias},`);
-            if (params.size === 0) {
-              writer.writeLine(`schema: z.object({})`);
-            } else {
-              writer.writeLine(`schema: z.object({`);
-              for (const [paramName, paramType] of Array.from(params)) {
-                writer.writeLine(
-                  `  ${paramName}: ${zodSchemaOfType(tc, paramType)},`,
-                );
-              }
-
-              writer.writeLine('})');
-            }
-          })
-          .write('} as const');
-      },
-    });
-
-    console.log(
-      'Created route',
-      pc.cyan(routeName),
-      'for',
-      pc.green(symbol.getName()),
-      'exported from',
-      pc.yellow(filePath),
-    );
-  }
-
-  await Promise.all([
-    routerFiles.jsResource.save(),
-    routerFiles.router.save(),
-    routerFiles.serverRouter.save(),
-  ]);
-}
-
-main().catch(console.error);
+import {program} from 'commander';
+import packageData from '../package.json' with {type: 'json'};
+import {generatePastoriaArtifacts} from './generate.mts';
+import {startDevserver} from './devserver.mts';
+import {createBuild} from './build.mts';
+
+program
+  .name('pastoria')
+  .description(packageData.description)
+  .version(packageData.version);
+
+program
+  .command('gen')
+  .description('Run Pastoria code generation')
+  .action(generatePastoriaArtifacts);
+
+program
+  .command('dev')
+  .description('Start the pastoria devserver')
+  .option('--port <port>', 'Port the devserver will listen on', '3000')
+  .action(startDevserver);
+
+program
+  .command('build')
+  .description('Creates a production build of the project')
+  .action(createBuild);
+
+program.parseAsync();

package/templates/router.tsx

@@ -1,8 +1,15 @@
+import {
+  AnyPreloadedEntryPoint,
+  EnvironmentProvider,
+  relayClientEnvironment,
+  RouterOps,
+} from 'pastoria-runtime';
 import {createRouter} from 'radix3';
 import {
   AnchorHTMLAttributes,
   createContext,
   PropsWithChildren,
+  StrictMode,
   Suspense,
   useCallback,
   useContext,
@@ -10,22 +17,16 @@ import {
   useMemo,
   useState,
 } from 'react';
+import {preinit, preloadModule} from 'react-dom';
 import {
   EntryPoint,
   EntryPointContainer,
-  EnvironmentProviderOptions,
-  IEnvironmentProvider,
   loadEntryPoint,
-  PreloadedEntryPoint,
+  RelayEnvironmentProvider,
   useEntryPointLoader,
 } from 'react-relay/hooks';
-import {OperationDescriptor, PayloadData} from 'relay-runtime';
-import type {Manifest} from 'vite';
 import * as z from 'zod/v4-mini';
 
-export type AnyPreloadedEntryPoint = PreloadedEntryPoint<any>;
-export type RouterOps = [OperationDescriptor, PayloadData][];
-
 type RouterConf = typeof ROUTER_CONF;
 const ROUTER_CONF = {
   noop: {
@@ -121,9 +122,7 @@ function useLocation(initialPath?: string) {
   return [location, setLocation] as const;
 }
 
-export function router__hydrateStore(
-  provider: IEnvironmentProvider<EnvironmentProviderOptions>,
-) {
+export function router__hydrateStore(provider: EnvironmentProvider) {
   const env = provider.getEnvironment(null);
   if ('__router_ops' in window) {
     const ops = (window as any).__router_ops as RouterOps;
@@ -134,7 +133,7 @@ export function router__hydrateStore(
 }
 
 export async function router__loadEntryPoint(
-  provider: IEnvironmentProvider<EnvironmentProviderOptions>,
+  provider: EnvironmentProvider,
   initialPath?: string,
 ) {
   if (!initialPath) initialPath = window.location.href;
@@ -159,12 +158,63 @@ const RouterContext = createContext<RouterContextValue>({
   setLocation: () => {},
 });
 
+const REACT_REFRESH_SCRIPT = `
+import RefreshRuntime from 'http://localhost:3000/@react-refresh'
+RefreshRuntime.injectIntoGlobalHook(window)
+window.$RefreshReg$ = () => {}
+window.$RefreshSig$ = () => (type) => type
+window.__vite_plugin_react_preamble_installed__ = true`;
+
 export function router__createAppFromEntryPoint(
-  provider: IEnvironmentProvider<EnvironmentProviderOptions>,
   initialEntryPoint: AnyPreloadedEntryPoint | null,
+  provider: EnvironmentProvider,
   initialPath?: string,
 ) {
-  function RouterApp() {
+  const env = provider.getEnvironment(null);
+
+  function RouterShell({
+    preloadModules,
+    preloadStylesheets,
+    children,
+  }: PropsWithChildren<{
+    preloadModules?: string[];
+    preloadStylesheets?: string[];
+  }>) {
+    for (const m of preloadModules ?? []) {
+      preloadModule(m, {as: 'script'});
+    }
+
+    for (const s of preloadStylesheets ?? []) {
+      preinit(s, {as: 'style'});
+    }
+
+    return (
+      <StrictMode>
+        <RelayEnvironmentProvider environment={env}>
+          <html>
+            <head>
+              <meta charSet="utf-8" />
+              <meta
+                name="viewport"
+                content="width=device-width, initial-scale=1"
+              />
+
+              {process.env.NODE_ENV !== 'production' && (
+                <script
+                  type="module"
+                  dangerouslySetInnerHTML={{__html: REACT_REFRESH_SCRIPT}}
+                />
+              )}
+            </head>
+
+            <body>{children}</body>
+          </html>
+        </RelayEnvironmentProvider>
+      </StrictMode>
+    );
+  }
+
+  function RouterCore() {
     const [location, setLocation] = useLocation(initialPath);
     const routerContextValue = useMemo(
       (): RouterContextValue => ({
@@ -213,16 +263,34 @@ export function router__createAppFromEntryPoint(
     );
   }
 
-  RouterApp.bootstrap = (manifest?: Manifest): string | null => null;
+  function RouterApp(props: {
+    preloadModules?: string[];
+    preloadStylesheets?: string[];
+    App?: React.ComponentType<PropsWithChildren<{}>> | null;
+  }) {
+    return (
+      <RouterShell
+        preloadModules={props.preloadModules}
+        preloadStylesheets={props.preloadStylesheets}
+      >
+        {props.App == null ? (
+          <RouterCore />
+        ) : (
+          <props.App children={<RouterCore />} />
+        )}
+      </RouterShell>
+    );
+  }
+
   return RouterApp;
 }
 
-export async function createRouterApp(
-  provider: IEnvironmentProvider<EnvironmentProviderOptions>,
-) {
+export async function createRouterApp() {
+  const provider = relayClientEnvironment;
+
   router__hydrateStore(provider);
   const ep = await router__loadEntryPoint(provider);
-  return router__createAppFromEntryPoint(provider, ep);
+  return router__createAppFromEntryPoint(ep, provider);
 }
 
 export function usePath() {

package/tsconfig.json

@@ -11,7 +11,8 @@
     "downlevelIteration": true,
     "types": ["node"],
     "lib": ["ES2022"],
-    "noEmit": true
+    "noEmit": true,
+    "allowImportingTsExtensions": true
   },
   "include": ["src/**/*"],
   "exclude": ["node_modules", "dist"]

package/templates/server_router.ts

@@ -1,112 +0,0 @@
-import {
-  EnvironmentProviderOptions,
-  IEnvironmentProvider,
-  OperationDescriptor,
-  PreloadedQuery,
-} from 'react-relay/hooks';
-import {
-  createOperationDescriptor,
-  GraphQLResponse,
-  GraphQLSingularResponse,
-  OperationType,
-  PayloadData,
-  PreloadableQueryRegistry,
-} from 'relay-runtime';
-import serialize from 'serialize-javascript';
-import type {Manifest} from 'vite';
-import {JSResource} from './js_resource';
-import {
-  AnyPreloadedEntryPoint,
-  router__createAppFromEntryPoint,
-  router__loadEntryPoint,
-  RouterOps,
-} from './router';
-
-type AnyPreloadedQuery = PreloadedQuery<OperationType>;
-
-function router__bootstrapScripts(
-  entryPoint: AnyPreloadedEntryPoint,
-  ops: RouterOps,
-  manifest?: Manifest,
-) {
-  let bootstrap = `
-      <script type="text/javascript">
-        window.__router_ops = ${serialize(ops)};
-      </script>`;
-
-  const rootModuleSrc = JSResource.srcOfModuleId(entryPoint.rootModuleID);
-  if (rootModuleSrc == null) return bootstrap;
-
-  function crawlImports(moduleName: string) {
-    const chunk = manifest?.[moduleName];
-    if (!chunk) return;
-
-    chunk.imports?.forEach(crawlImports);
-    bootstrap =
-      `<link rel="modulepreload" href="${chunk.file}" />\n` + bootstrap;
-  }
-
-  crawlImports(rootModuleSrc);
-  return bootstrap;
-}
-
-async function router__ensureQueryFlushed(
-  query: AnyPreloadedQuery,
-): Promise<GraphQLResponse> {
-  return new Promise((resolve, reject) => {
-    if (query.source == null) {
-      resolve({data: {}});
-    } else {
-      query.source.subscribe({
-        next: resolve,
-        error: reject,
-      });
-    }
-  });
-}
-
-async function router__loadQueries(entryPoint: AnyPreloadedEntryPoint) {
-  const preloadedQueryOps: [OperationDescriptor, PayloadData][] = [];
-  for (const query of Object.values(
-    entryPoint?.queries ?? {},
-  ) as PreloadedQuery<OperationType>[]) {
-    try {
-      const payload = await router__ensureQueryFlushed(query);
-      const concreteRequest =
-        query.id == null ? null : PreloadableQueryRegistry.get(query.id);
-
-      if (concreteRequest != null) {
-        const desc = createOperationDescriptor(
-          concreteRequest,
-          query.variables,
-        );
-
-        preloadedQueryOps.push([
-          desc,
-          (payload as GraphQLSingularResponse).data!,
-        ]);
-      }
-    } catch (e) {
-      console.error(e);
-      throw e;
-    }
-  }
-
-  return preloadedQueryOps;
-}
-
-export async function createRouterServerApp(
-  provider: IEnvironmentProvider<EnvironmentProviderOptions>,
-  initialPath: string,
-) {
-  const ep = await router__loadEntryPoint(provider, initialPath);
-  const ops = ep != null ? await router__loadQueries(ep) : [];
-  const RouterApp = router__createAppFromEntryPoint(provider, ep, initialPath);
-
-  if (ep != null) {
-    RouterApp.bootstrap = (manifest) =>
-      router__bootstrapScripts(ep, ops, manifest);
-  }
-
-  return RouterApp;
-}