create-kelpie 0.2.0

package/templates/src/server.ts

@@ -0,0 +1,118 @@
+import { serve } from '@hono/node-server'
+import {
+  ConfigurationError,
+  ModuleBootError,
+  ModuleConfigFileError,
+  connectDatabase,
+  createApp,
+  createEmailSender,
+  createEventBus,
+  createIdFactory,
+  createLogger,
+  createTransactionScope,
+  loadConfig,
+  readModuleConfigFile,
+  registerModules,
+  resolveActorFrom,
+  runMigrations,
+} from '@kelpie/server'
+import type { CredentialDependencies } from '@kelpie/server'
+
+import { modules } from '../kelpie.config.ts'
+
+/**
+ * The entry point. It reads the environment, registers the configured modules,
+ * applies migrations, wires the dependencies, and serves.
+ *
+ * Registration runs before migrations. Modules declare their migrations
+ * directory while registering, so there is nothing to migrate until that pass
+ * has finished.
+ *
+ * `--no-migrate` skips the migration step, for deployments where one release
+ * step migrates and many instances then start.
+ */
+
+function reportFatal(message: string): void {
+  process.stderr.write(`${message}\n`)
+}
+
+async function start(): Promise<void> {
+  const config = loadConfig(process.env)
+  const logger = createLogger(config.logLevel)
+  const database = connectDatabase(config.databaseUrl, logger)
+  const events = createEventBus(logger)
+  const createId = createIdFactory()
+  const credentials: CredentialDependencies = { db: database.db, now: () => new Date() }
+  const moduleConfig = readModuleConfigFile(config.moduleConfigPath)
+  const contributions = await registerModules({
+    modules,
+    environment: process.env,
+    logger,
+    events,
+    moduleConfig,
+    resolveActor: (context) => resolveActorFrom(credentials, context),
+    services: {
+      db: database.db,
+      transaction: createTransactionScope({ db: database.db, bus: events, logger }),
+      email: createEmailSender(config.email, logger),
+      createId,
+      now: () => new Date(),
+    },
+  })
+
+  if (process.argv.includes('--no-migrate')) {
+    logger.info('skipping migrations', { reason: '--no-migrate' })
+  } else {
+    await runMigrations(database.db, contributions.schemas, logger)
+  }
+
+  const app = createApp({
+    logger,
+    probeDatabase: database.probe,
+    contributions,
+    credentials,
+    createId,
+  })
+
+  const server = serve({ fetch: app.fetch, port: config.port }, (address) => {
+    logger.info('listening', { port: address.port, runtimeMode: config.runtimeMode })
+  })
+
+  const shutdown = (signal: string): void => {
+    logger.info('shutting down', { signal })
+    server.close(() => {
+      // Drain before closing the pool: a handler mid-flight may still be writing.
+      void contributions.events
+        .drain()
+        .then(() => database.close())
+        .then(() => process.exit(0))
+    })
+  }
+
+  process.on('SIGINT', () => shutdown('SIGINT'))
+  process.on('SIGTERM', () => shutdown('SIGTERM'))
+}
+
+try {
+  await start()
+} catch (error: unknown) {
+  if (error instanceof ConfigurationError) {
+    reportFatal(error.message)
+    reportFatal('Check .env against the table in README.md.')
+    process.exit(1)
+  }
+
+  if (error instanceof ModuleConfigFileError) {
+    reportFatal(error.message)
+    reportFatal('Fix the file at KELPIE_MODULE_CONFIG_PATH, or unset it to let workspaces decide for themselves.')
+    process.exit(1)
+  }
+
+  if (error instanceof ModuleBootError) {
+    reportFatal(error.message)
+    reportFatal('Fix the module list in kelpie.config.ts, or the configuration it needs.')
+    process.exit(1)
+  }
+
+  throw error
+}

package/templates/tsconfig.server.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "types": ["node"],
+
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "verbatimModuleSyntax": true,
+    "allowImportingTsExtensions": true,
+    "erasableSyntaxOnly": true,
+
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src", "kelpie.config.ts"]
+}

package/templates/tsconfig.web.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "types": ["vite/client", "node"],
+    "jsx": "react-jsx",
+
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "verbatimModuleSyntax": true,
+    "allowImportingTsExtensions": true,
+    "erasableSyntaxOnly": true,
+
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["web", "vite.config.ts", "kelpie.ui.config.ts"]
+}

package/templates/vite.config.ts

@@ -0,0 +1,60 @@
+import { fileURLToPath } from 'node:url'
+
+import tailwindcss from '@tailwindcss/vite'
+import react from '@vitejs/plugin-react'
+import { defineConfig, loadEnv } from 'vite'
+
+const projectRoot = fileURLToPath(new URL('./', import.meta.url))
+
+/**
+ * The dev server proxies the API rather than pointing the browser at a second
+ * origin, so the UI runs against same-origin `/v1` in development exactly as it
+ * does in production.
+ */
+export default defineConfig(({ mode }) => {
+  // `loadEnv` rather than `process.env`, because `npm run dev:web` runs `vite`
+  // directly and nothing has read `.env` into the environment by then. Reading
+  // `process.env.WEB_PORT` here means the port in `.env` is silently ignored and
+  // Vite takes 5173, or the next free one, while README and .env both say
+  // otherwise.
+  //
+  // `API_PORT`, not `PORT`. Every process manager sets `PORT` to the port it
+  // wants the process it is launching to listen on, and a prefix that matched it
+  // would let that value win over `.env`. Vite would then proxy to itself: the
+  // page loads and every `/v1` call times out against the dev server it came
+  // from.
+  const environment = loadEnv(mode, projectRoot, ['API_', 'WEB_'])
+  const apiPort = environment.API_PORT
+
+  if (apiPort === undefined || apiPort.length === 0) {
+    throw new Error('API_PORT is not set. It belongs in .env, with the same value as PORT.')
+  }
+
+  const apiOrigin = `http://localhost:${apiPort}`
+
+  return {
+    root: fileURLToPath(new URL('./web', import.meta.url)),
+    envDir: projectRoot,
+    plugins: [react(), tailwindcss()],
+    build: {
+      outDir: fileURLToPath(new URL('./dist', import.meta.url)),
+      emptyOutDir: true,
+    },
+    server: {
+      port: Number(environment.WEB_PORT ?? 5173),
+      // Refuse rather than quietly taking the next port. A launcher that was
+      // told 5173 and got 5174 proxies nothing, and the README hands out an
+      // address that answers nothing.
+      strictPort: true,
+      proxy: {
+        '/v1': { target: apiOrigin, changeOrigin: false },
+        '/healthz': { target: apiOrigin, changeOrigin: false },
+        // The MCP page shows the endpoint at the origin the browser reached the
+        // app on, which in development is this dev server. Without the proxy
+        // that address is right in production and dead here, so anyone copying
+        // it out of the page would be debugging the wrong thing.
+        '/mcp': { target: apiOrigin, changeOrigin: false },
+      },
+    },
+  }
+})

package/templates/web/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>__PROJECT_NAME__</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>

package/templates/web/main.tsx

@@ -0,0 +1,23 @@
+import { KelpieApp, registerUiModules } from '@kelpie/ui'
+import '@kelpie/ui/styles.css'
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+
+import { uiModules } from '../kelpie.ui.config.ts'
+
+const container = document.getElementById('root')
+
+if (container === null) {
+  throw new Error('Expected an element with id "root" in index.html')
+}
+
+// Registration is build-time and happens once, above the root. A module
+// clashing with another fails here, at startup, rather than as a tab somebody
+// notices is missing a week later.
+const extensions = registerUiModules(uiModules)
+
+createRoot(container).render(
+  <StrictMode>
+    <KelpieApp extensions={extensions} />
+  </StrictMode>,
+)