create-kelpie 0.2.0

package/src/options.ts

@@ -0,0 +1,229 @@
+/**
+ * Turns argv and, where it has to, the operator, into `ScaffoldOptions`.
+ *
+ * Everything non-deterministic lives here: the generated key, the prompts, and
+ * reading this package's own version. `scaffold` itself is a pure function of
+ * what this produces, which is what makes it testable.
+ */
+
+import { randomBytes } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { basename, resolve } from 'node:path'
+import { createInterface } from 'node:readline/promises'
+import { parseArgs } from 'node:util'
+
+import { ScaffoldError } from './scaffold.ts'
+import type { ScaffoldOptions } from './scaffold.ts'
+
+const DEFAULT_DIRECTORY = 'kelpie'
+const DEFAULT_PORT = 3000
+const DEFAULT_WEB_PORT = 5173
+const DEFAULT_DATABASE_PORT = 5432
+const DEFAULT_EMAIL_FROM = 'kelpie@example.com'
+
+/** The service requires 32 bytes; anything shorter is rejected at boot. */
+const SECRET_KEY_BYTES = 32
+
+const HIGHEST_PORT = 65535
+
+export const USAGE = `Scaffold a self-hosted Kelpie assembly.
+
+  npm create kelpie [directory] [options]
+
+Options:
+  --name <name>            Package name. Defaults to the directory name
+  --database-url <url>     postgres:// connection string
+  --port <port>            API port (default ${DEFAULT_PORT})
+  --web-port <port>        Dev server port (default ${DEFAULT_WEB_PORT})
+  --database-port <port>   Host port for the bundled Postgres (default ${DEFAULT_DATABASE_PORT})
+  --email-from <address>   Address transactional mail comes from
+  --docker, --no-docker    Write a docker-compose.yml for Postgres (default yes)
+  --yes                    Take every default; never prompt
+  --help                   This message
+
+With --yes and no --database-url, the connection string points at the bundled
+Postgres. Without a terminal to prompt on, --yes is required.`
+
+export interface ParsedArguments {
+  readonly directory: string | undefined
+  readonly name: string | undefined
+  readonly databaseUrl: string | undefined
+  readonly emailFrom: string | undefined
+  readonly port: number
+  readonly webPort: number
+  readonly databasePort: number
+  readonly docker: boolean | undefined
+  readonly yes: boolean
+  readonly help: boolean
+}
+
+function parsePort(name: string, value: string | undefined, fallback: number): number {
+  if (value === undefined) {
+    return fallback
+  }
+
+  const port = Number(value)
+
+  if (!Number.isInteger(port) || port < 1 || port > HIGHEST_PORT) {
+    throw new ScaffoldError(`${name} must be a port number between 1 and ${HIGHEST_PORT}. It is "${value}".`)
+  }
+
+  return port
+}
+
+/**
+ * npm package names are lowercase, and a directory name often is not. Anything
+ * that cannot be salvaged falls back rather than failing: the name is cosmetic
+ * in a private package.
+ */
+export function toPackageName(directoryName: string): string {
+  const cleaned = directoryName
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^[._-]+/, '')
+    .replace(/-+$/, '')
+
+  return cleaned.length > 0 ? cleaned : DEFAULT_DIRECTORY
+}
+
+export function parseArguments(argv: readonly string[]): ParsedArguments {
+  const { values, positionals } = parseArgs({
+    args: [...argv],
+    allowPositionals: true,
+    options: {
+      name: { type: 'string' },
+      'database-url': { type: 'string' },
+      'email-from': { type: 'string' },
+      port: { type: 'string' },
+      'web-port': { type: 'string' },
+      'database-port': { type: 'string' },
+      docker: { type: 'boolean' },
+      // parseArgs has no native --no-x, so the negation is its own flag.
+      'no-docker': { type: 'boolean' },
+      yes: { type: 'boolean', short: 'y' },
+      help: { type: 'boolean', short: 'h' },
+    },
+  })
+
+  if (values.docker === true && values['no-docker'] === true) {
+    throw new ScaffoldError('--docker and --no-docker contradict each other.')
+  }
+
+  const docker = values['no-docker'] === true ? false : values.docker === true ? true : undefined
+
+  return {
+    directory: positionals[0],
+    name: values.name,
+    databaseUrl: values['database-url'],
+    emailFrom: values['email-from'],
+    port: parsePort('--port', values.port, DEFAULT_PORT),
+    webPort: parsePort('--web-port', values['web-port'], DEFAULT_WEB_PORT),
+    databasePort: parsePort('--database-port', values['database-port'], DEFAULT_DATABASE_PORT),
+    docker,
+    yes: values.yes === true,
+    help: values.help === true,
+  }
+}
+
+export function generateSecretEncryptionKey(): string {
+  return randomBytes(SECRET_KEY_BYTES).toString('base64')
+}
+
+export function bundledDatabaseUrl(port: number): string {
+  return `postgres://kelpie:kelpie@localhost:${port}/kelpie`
+}
+
+/** This package's own version, which is the core version a scaffold pins. */
+export function readOwnVersion(): string {
+  const manifestUrl = new URL('../package.json', import.meta.url)
+  const parsed: unknown = JSON.parse(readFileSync(manifestUrl, 'utf8'))
+
+  if (typeof parsed !== 'object' || parsed === null || !('version' in parsed)) {
+    throw new ScaffoldError('create-kelpie cannot read its own version.')
+  }
+
+  const { version } = parsed as { version: unknown }
+
+  if (typeof version !== 'string') {
+    throw new ScaffoldError('create-kelpie has a non-string version in its manifest.')
+  }
+
+  return version
+}
+
+interface Prompter {
+  ask(question: string, fallback: string): Promise<string>
+  confirm(question: string, fallback: boolean): Promise<boolean>
+  close(): void
+}
+
+function createPrompter(): Prompter {
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+
+  return {
+    async ask(question: string, fallback: string): Promise<string> {
+      const answer = (await rl.question(`${question} (${fallback}) `)).trim()
+
+      return answer.length > 0 ? answer : fallback
+    },
+    async confirm(question: string, fallback: boolean): Promise<boolean> {
+      const answer = (await rl.question(`${question} (${fallback ? 'Y/n' : 'y/N'}) `)).trim().toLowerCase()
+
+      if (answer.length === 0) {
+        return fallback
+      }
+
+      return answer.startsWith('y')
+    },
+    close(): void {
+      rl.close()
+    },
+  }
+}
+
+/**
+ * Fills the gaps argv left, asking where there is a terminal to ask on.
+ *
+ * Without one, `--yes` is required rather than assumed. A scaffolder that
+ * silently invents a database URL in CI writes a project that fails at boot,
+ * some distance from the cause.
+ */
+export async function resolveOptions(parsed: ParsedArguments, interactive: boolean): Promise<ScaffoldOptions> {
+  if (!interactive && !parsed.yes) {
+    throw new ScaffoldError(
+      'There is no terminal to prompt on. Pass --yes to take the defaults, and --database-url to point at your database.',
+    )
+  }
+
+  const prompter = interactive && !parsed.yes ? createPrompter() : undefined
+
+  try {
+    const directoryName =
+      parsed.directory ?? (await prompter?.ask('Directory', DEFAULT_DIRECTORY)) ?? DEFAULT_DIRECTORY
+    const directory = resolve(process.cwd(), directoryName)
+    const projectName = parsed.name ?? toPackageName(basename(directory))
+    const docker = parsed.docker ?? (await prompter?.confirm('Write a docker-compose.yml for Postgres?', true)) ?? true
+
+    const defaultDatabaseUrl = bundledDatabaseUrl(parsed.databasePort)
+    const databaseUrl =
+      parsed.databaseUrl ?? (await prompter?.ask('DATABASE_URL', defaultDatabaseUrl)) ?? defaultDatabaseUrl
+
+    const emailFrom =
+      parsed.emailFrom ?? (await prompter?.ask('Send mail from', DEFAULT_EMAIL_FROM)) ?? DEFAULT_EMAIL_FROM
+
+    return {
+      directory,
+      projectName,
+      databaseUrl,
+      emailFrom,
+      port: parsed.port,
+      webPort: parsed.webPort,
+      databasePort: parsed.databasePort,
+      docker,
+      secretEncryptionKey: generateSecretEncryptionKey(),
+      coreVersion: readOwnVersion(),
+    }
+  } finally {
+    prompter?.close()
+  }
+}

package/src/scaffold.ts

@@ -0,0 +1,146 @@
+/**
+ * Writes a Kelpie assembly into a directory.
+ *
+ * Everything here is deterministic: the caller supplies the generated secret and
+ * every other value, so a test can assert on exact output. `resolveOptions` in
+ * `options.ts` is where the non-deterministic parts live.
+ */
+
+import { mkdirSync, readFileSync, readdirSync, existsSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** Resolves the same from `src/` and from `dist/`; both sit one level down. */
+const templateDirectory = fileURLToPath(new URL('../templates/', import.meta.url))
+
+export interface ScaffoldOptions {
+  /** Absolute path of the directory to write into. Created if missing. */
+  readonly directory: string
+  readonly projectName: string
+  readonly databaseUrl: string
+  readonly emailFrom: string
+  readonly port: number
+  readonly webPort: number
+  /** The host port `docker-compose.yml` publishes Postgres on. Ignored without `docker`. */
+  readonly databasePort: number
+  readonly docker: boolean
+  /** 32 bytes of base64. Generated per project by `resolveOptions`. */
+  readonly secretEncryptionKey: string
+  /** The `@kelpie/*` version range the generated manifest asks for. */
+  readonly coreVersion: string
+}
+
+/** A precondition failed. Reported as a message rather than a stack. */
+export class ScaffoldError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ScaffoldError'
+  }
+}
+
+/**
+ * Template path to output path.
+ *
+ * `env` and `gitignore` are renamed rather than stored under their real names
+ * because npm silently drops a file called `.gitignore` from a published
+ * tarball, and a stray `.env` in the package directory is a trap regardless.
+ */
+const TEMPLATE_FILES: ReadonlyMap<string, string> = new Map([
+  ['package.json', 'package.json'],
+  ['kelpie.config.ts', 'kelpie.config.ts'],
+  ['kelpie.ui.config.ts', 'kelpie.ui.config.ts'],
+  ['src/server.ts', 'src/server.ts'],
+  ['web/index.html', 'web/index.html'],
+  ['web/main.tsx', 'web/main.tsx'],
+  ['vite.config.ts', 'vite.config.ts'],
+  ['tsconfig.server.json', 'tsconfig.server.json'],
+  ['tsconfig.web.json', 'tsconfig.web.json'],
+  ['README.md', 'README.md'],
+  ['env', '.env'],
+  ['gitignore', '.gitignore'],
+])
+
+/** Written only when the project takes the bundled Postgres. */
+const DOCKER_TEMPLATE = 'docker-compose.yml'
+
+/** Anything left matching this after substitution is a token nobody filled in. */
+const UNRESOLVED_TOKEN = /__[A-Z][A-Z0-9_]*__/
+
+function tokensFor(options: ScaffoldOptions): ReadonlyMap<string, string> {
+  return new Map([
+    ['__PROJECT_NAME__', options.projectName],
+    ['__CORE_VERSION__', options.coreVersion],
+    ['__DATABASE_URL__', options.databaseUrl],
+    ['__DATABASE_PORT__', String(options.databasePort)],
+    ['__EMAIL_FROM__', options.emailFrom],
+    ['__PORT__', String(options.port)],
+    ['__WEB_PORT__', String(options.webPort)],
+    ['__SECRET_ENCRYPTION_KEY__', options.secretEncryptionKey],
+  ])
+}
+
+function render(template: string, tokens: ReadonlyMap<string, string>, source: string): string {
+  let rendered = template
+
+  for (const [token, value] of tokens) {
+    rendered = rendered.replaceAll(token, value)
+  }
+
+  const leftover = UNRESOLVED_TOKEN.exec(rendered)
+
+  if (leftover !== null) {
+    throw new ScaffoldError(`The template ${source} still contains ${leftover[0]} after substitution.`)
+  }
+
+  return rendered
+}
+
+/**
+ * Refuses a directory that already holds anything, so a mistyped path cannot
+ * overwrite a project. Dotfiles count; a directory with a `.git` in it is
+ * someone's repository.
+ */
+export function assertWritable(directory: string): void {
+  if (!existsSync(directory)) {
+    return
+  }
+
+  const entries = readdirSync(directory)
+
+  if (entries.length > 0) {
+    throw new ScaffoldError(
+      `${directory} is not empty. It holds ${entries.length} entr${entries.length === 1 ? 'y' : 'ies'}, ` +
+        'including ' +
+        entries
+          .slice(0, 3)
+          .map((entry) => `"${entry}"`)
+          .join(', ') +
+        '. Pick an empty directory, or a path that does not exist yet.',
+    )
+  }
+}
+
+/** Writes the assembly. Returns the output paths, relative to the directory, in write order. */
+export function scaffold(options: ScaffoldOptions): readonly string[] {
+  assertWritable(options.directory)
+
+  const tokens = tokensFor(options)
+  const files = new Map(TEMPLATE_FILES)
+
+  if (options.docker) {
+    files.set(DOCKER_TEMPLATE, DOCKER_TEMPLATE)
+  }
+
+  const written: string[] = []
+
+  for (const [source, target] of files) {
+    const template = readFileSync(join(templateDirectory, source), 'utf8')
+    const destination = join(options.directory, target)
+
+    mkdirSync(dirname(destination), { recursive: true })
+    writeFileSync(destination, render(template, tokens, source))
+    written.push(target)
+  }
+
+  return written
+}

package/templates/README.md

@@ -0,0 +1,97 @@
+# __PROJECT_NAME__
+
+A self-hosted [Kelpie](https://github.com/velvet-tiger/kelpie) install.
+
+These files are yours. Kelpie itself arrives as `@kelpie/server` and
+`@kelpie/ui` in `node_modules`; what is checked in here is the assembly that
+composes them: which modules are on, and how the service starts.
+
+## Running it
+
+```bash
+npm install
+```
+
+Then start Postgres, if you took the `docker-compose.yml`:
+
+```bash
+docker compose up --detach --wait
+```
+
+Then:
+
+```bash
+npm run dev
+```
+
+The API listens on the `PORT` in `.env` and the UI on `WEB_PORT`. The UI proxies
+API calls, so your browser only talks to one address.
+
+Confirm it is up:
+
+```bash
+curl -s http://localhost:__WEB_PORT__/healthz
+```
+
+You should see `{"status":"ok","database":"up"}`. A `"status":"degraded"`
+response means Postgres is not reachable.
+
+Then open <http://localhost:__WEB_PORT__/signup> and create an account.
+Passwords need at least 12 characters. Signup names your workspace, invites your
+team, and leaves you on People with a starter handbook in place.
+
+Kelpie does not send email yet. Invitation and password-reset links print to the
+API's log. Copy them from there to follow either flow.
+
+## Adding a module
+
+`kelpie.config.ts` is the server module list and `kelpie.ui.config.ts` is the UI
+one. Install a module, add it to the relevant array, restart. Boot fails loudly
+on an unknown id or an unmet dependency rather than starting without it.
+
+## Configuration
+
+Everything below is required unless marked optional. A missing or invalid value
+stops the service at boot and lists every problem at once.
+
+| Variable | Values |
+| --- | --- |
+| `NODE_ENV` | `development`, `test`, or `production` |
+| `PORT` | The API's listen port. Bound exactly; the service fails if it is taken |
+| `API_PORT` | The same number again, for the dev server's proxy |
+| `WEB_PORT` | The Vite dev server's port. Development only |
+| `DATABASE_URL` | A `postgres://` or `postgresql://` connection string |
+| `LOG_LEVEL` | `debug`, `info`, `warn`, or `error` |
+| `EMAIL_PROVIDER` | `log`. Writes invitations and resets to the log instead of sending them |
+| `EMAIL_FROM` | The address transactional mail comes from |
+| `SECRET_ENCRYPTION_KEY` | 32 bytes of base64, generated for this project |
+| `SECRET_ENCRYPTION_KEY_PREVIOUS` | Optional. Set only while rotating the key above |
+| `WEBHOOK_DELIVERY_RETENTION_DAYS` | Optional, default 30 |
+
+### Rotating the encryption key
+
+Replacing `SECRET_ENCRYPTION_KEY` makes every secret sealed under the old one
+unreadable, so rotate rather than replace:
+
+1. Move the current key to `SECRET_ENCRYPTION_KEY_PREVIOUS` and put a new one in
+   `SECRET_ENCRYPTION_KEY`.
+2. Deploy. New secrets seal under the new key; existing ones still read with the
+   previous one.
+3. Re-encrypt everything still under the old key. Safe to run more than once.
+4. Remove `SECRET_ENCRYPTION_KEY_PREVIOUS` and deploy again.
+
+## Upgrading
+
+```bash
+npm update @kelpie/server @kelpie/ui
+```
+
+Migrations apply at boot. Read the
+[changelog](https://github.com/velvet-tiger/kelpie/blob/main/CHANGELOG.md)
+first: while the major version is `0`, a minor bump may break the API.
+
+## License
+
+Kelpie is AGPL-3.0. Running a modified version as a network service obliges you
+to offer its source to your users. These assembly files are yours; the
+obligation attaches to Kelpie itself.

package/templates/docker-compose.yml

@@ -0,0 +1,26 @@
+# Postgres for this Kelpie install.
+#
+# The credentials are fixed here and repeated in .env. They are not secret and
+# the container is not reachable from outside this machine. For anything other
+# than local use, point DATABASE_URL at a real database and delete this file.
+services:
+  db:
+    image: postgres:18-alpine
+    environment:
+      POSTGRES_USER: kelpie
+      POSTGRES_PASSWORD: kelpie
+      POSTGRES_DB: kelpie
+    ports:
+      - "__DATABASE_PORT__:5432"
+    # Postgres 18 images want the whole directory mounted, not the data
+    # subdirectory, so a later pg_upgrade can cross versions in place.
+    volumes:
+      - kelpie_db_data:/var/lib/postgresql
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready --username kelpie --dbname kelpie"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+volumes:
+  kelpie_db_data:

package/templates/env

@@ -0,0 +1,27 @@
+# Generated by `npm create kelpie`. Keep it out of version control.
+
+NODE_ENV=development
+LOG_LEVEL=info
+
+# The API binds this exact port and fails if it is taken.
+PORT=__PORT__
+
+# The same number again, for the Vite dev server's proxy. It needs its own name
+# because a process manager sets PORT to the port it wants Vite on, and Vite
+# would then proxy to itself.
+API_PORT=__PORT__
+
+# The Vite dev server's own port.
+WEB_PORT=__WEB_PORT__
+
+DATABASE_URL=__DATABASE_URL__
+
+# Seals secrets the service reads back, such as webhook signing secrets. This
+# one was generated for this project. Losing it makes those secrets unreadable;
+# changing it needs the rotation procedure in README.md.
+SECRET_ENCRYPTION_KEY=__SECRET_ENCRYPTION_KEY__
+
+# `log` writes invitations and password resets to the log instead of sending
+# them. Real providers ship as modules.
+EMAIL_PROVIDER=log
+EMAIL_FROM=__EMAIL_FROM__

package/templates/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+
+# Holds SECRET_ENCRYPTION_KEY and your database credentials.
+.env
+.env.local

package/templates/kelpie.config.ts

@@ -0,0 +1,21 @@
+import { coreModules } from '@kelpie/server'
+import type { KelpieModule } from '@kelpie/server'
+
+/**
+ * The server module list, and the only place it is declared.
+ *
+ * Boot registers these in order, after resolving what each one requires. An
+ * unknown id, an unmet dependency, or invalid module configuration stops boot
+ * rather than starting a service that is missing a feature.
+ *
+ * Add a module by installing it and putting it in this array:
+ *
+ *   import { smtpEmail } from '@kelpie/module-smtp-email'
+ *
+ *   export const modules: readonly KelpieModule[] = [...coreModules, smtpEmail]
+ *
+ * Removing one from `coreModules` is possible too, but core modules depend on
+ * each other, so boot will tell you if you have taken out something another
+ * module needs.
+ */
+export const modules: readonly KelpieModule[] = [...coreModules]

package/templates/kelpie.ui.config.ts

@@ -0,0 +1,14 @@
+import type { UiModule } from '@kelpie/ui'
+
+/**
+ * The UI module list, and the only place it is declared.
+ *
+ * Separate from `kelpie.config.ts` because that one is imported by the Node
+ * entry point, and a UI module pulls React in with it. The two lists differ
+ * anyway: a module can contribute to one surface without the other, and most
+ * do.
+ *
+ * Empty is the supported state. Core pages look finished with every slot
+ * unfilled.
+ */
+export const uiModules: readonly UiModule[] = []

package/templates/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "dev": "concurrently --names api,web --prefix-colors blue,magenta \"npm run dev:api\" \"npm run dev:web\"",
+    "dev:api": "node --watch --env-file-if-exists=.env src/server.ts",
+    "dev:web": "vite",
+    "start": "node --env-file-if-exists=.env src/server.ts",
+    "build": "vite build",
+    "typecheck": "tsc --project tsconfig.server.json && tsc --project tsconfig.web.json"
+  },
+  "dependencies": {
+    "@hono/node-server": "^2.0.12",
+    "@kelpie/server": "^__CORE_VERSION__",
+    "@kelpie/ui": "^__CORE_VERSION__",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.3.3",
+    "@types/node": "^26.1.2",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "@vitejs/plugin-react": "^6.0.5",
+    "concurrently": "^9.2.4",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^5.9.3",
+    "vite": "^8.2.0"
+  }
+}