create-kelpie 0.2.0

package/README.md

@@ -0,0 +1,72 @@
+# create-kelpie
+
+Scaffolds a self-hosted [Kelpie](https://github.com/velvet-tiger/kelpie) install.
+
+```bash
+npm create kelpie@latest
+```
+
+Kelpie is an open-source, agent-native CRM and company brain. It is composed at
+build time rather than shipped as a binary: an **assembly** is a small project
+that lists its modules and boots the runtime. This writes you one.
+
+There is nothing to clone. `@kelpie/server` and `@kelpie/ui` arrive as ordinary
+dependencies, and the files this writes are yours to edit and commit.
+
+## What it writes
+
+```
+package.json           @kelpie/server and @kelpie/ui, pinned to this version
+kelpie.config.ts       the server module list
+kelpie.ui.config.ts    the UI module list
+src/server.ts          the entry point: config, modules, migrations, serve
+web/index.html         the web entry
+web/main.tsx
+vite.config.ts         dev server, proxying /v1 to the API
+tsconfig.server.json
+tsconfig.web.json
+.env                   with a SECRET_ENCRYPTION_KEY generated for this project
+.gitignore
+README.md              how to run it, and what every variable does
+docker-compose.yml     Postgres, unless you said no
+```
+
+It writes files and stops. It does not run `npm install`, start Postgres, or
+boot anything, so when something fails you are looking at your own terminal
+rather than at output a scaffolder swallowed.
+
+## Options
+
+It prompts for what it cannot infer. Every answer is also a flag, so it runs
+unattended:
+
+```bash
+npm create kelpie@latest crm -- --yes --database-url postgres://user:pass@db:5432/kelpie --no-docker
+```
+
+| Flag | Does |
+| --- | --- |
+| `--name <name>` | Package name. Defaults to the directory name |
+| `--database-url <url>` | `postgres://` connection string |
+| `--port <port>` | API port, default 3000 |
+| `--web-port <port>` | Dev server port, default 5173 |
+| `--database-port <port>` | Host port for the bundled Postgres, default 5432 |
+| `--email-from <address>` | Address transactional mail comes from |
+| `--docker`, `--no-docker` | Write a `docker-compose.yml` for Postgres |
+| `--yes` | Take every default, never prompt |
+
+Without a terminal to prompt on, `--yes` is required. A scaffolder that quietly
+invents a database URL in CI writes a project that fails at boot, a long way
+from the cause.
+
+It refuses a directory that already contains anything.
+
+## Versions
+
+The generated manifest pins `@kelpie/server` and `@kelpie/ui` at this package's
+own version, and the four release together. `create-kelpie@0.3.0` writes a
+project asking for `@kelpie/server@^0.3.0`.
+
+## Licence
+
+AGPL-3.0-only.

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * `npm create kelpie` lands here.
+ *
+ * It writes an assembly and stops. It does not run `npm install`, start
+ * Postgres, or boot anything: the generated README says what to do next, and a
+ * scaffolder that installs for you is a scaffolder you cannot read the output
+ * of when the install fails.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;GAOG"}

package/dist/index.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * `npm create kelpie` lands here.
+ *
+ * It writes an assembly and stops. It does not run `npm install`, start
+ * Postgres, or boot anything: the generated README says what to do next, and a
+ * scaffolder that installs for you is a scaffolder you cannot read the output
+ * of when the install fails.
+ */
+import { relative } from 'node:path';
+import { USAGE, parseArguments, resolveOptions } from './options.js';
+import { ScaffoldError, scaffold } from './scaffold.js';
+function report(message) {
+    process.stdout.write(`${message}\n`);
+}
+async function main() {
+    const parsed = parseArguments(process.argv.slice(2));
+    if (parsed.help) {
+        report(USAGE);
+        return;
+    }
+    const options = await resolveOptions(parsed, process.stdin.isTTY === true);
+    const written = scaffold(options);
+    const here = relative(process.cwd(), options.directory) || '.';
+    report(`\nWrote ${written.length} files into ${here}/`);
+    report('');
+    report('Next:');
+    report(`  cd ${here}`);
+    report('  npm install');
+    if (options.docker) {
+        report('  docker compose up --detach --wait');
+    }
+    report('  npm run dev');
+    report('');
+    report(`Then open http://localhost:${options.webPort}/signup to create your account.`);
+    report(`${here}/README.md has the rest, including what every variable in .env does.`);
+}
+try {
+    await main();
+}
+catch (error) {
+    if (error instanceof ScaffoldError) {
+        process.stderr.write(`${error.message}\n`);
+        process.exit(1);
+    }
+    throw error;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAEpC,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AACpE,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAEvD,SAAS,MAAM,CAAC,OAAe;IAC7B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAA;AACtC,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAEpD,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAChB,MAAM,CAAC,KAAK,CAAC,CAAA;QAEb,OAAM;IACR,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,CAAA;IAC1E,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAA;IACjC,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,SAAS,CAAC,IAAI,GAAG,CAAA;IAE9D,MAAM,CAAC,WAAW,OAAO,CAAC,MAAM,eAAe,IAAI,GAAG,CAAC,CAAA;IACvD,MAAM,CAAC,EAAE,CAAC,CAAA;IACV,MAAM,CAAC,OAAO,CAAC,CAAA;IACf,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAA;IACtB,MAAM,CAAC,eAAe,CAAC,CAAA;IAEvB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,CAAC,qCAAqC,CAAC,CAAA;IAC/C,CAAC;IAED,MAAM,CAAC,eAAe,CAAC,CAAA;IACvB,MAAM,CAAC,EAAE,CAAC,CAAA;IACV,MAAM,CAAC,8BAA8B,OAAO,CAAC,OAAO,iCAAiC,CAAC,CAAA;IACtF,MAAM,CAAC,GAAG,IAAI,sEAAsE,CAAC,CAAA;AACvF,CAAC;AAED,IAAI,CAAC;IACH,MAAM,IAAI,EAAE,CAAA;AACd,CAAC;AAAC,OAAO,KAAc,EAAE,CAAC;IACxB,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;QACnC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,OAAO,IAAI,CAAC,CAAA;QAC1C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACjB,CAAC;IAED,MAAM,KAAK,CAAA;AACb,CAAC"}

package/dist/options.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 type { ScaffoldOptions } from './scaffold.ts';
+export declare const USAGE = "Scaffold a self-hosted Kelpie assembly.\n\n  npm create kelpie [directory] [options]\n\nOptions:\n  --name <name>            Package name. Defaults to the directory name\n  --database-url <url>     postgres:// connection string\n  --port <port>            API port (default 3000)\n  --web-port <port>        Dev server port (default 5173)\n  --database-port <port>   Host port for the bundled Postgres (default 5432)\n  --email-from <address>   Address transactional mail comes from\n  --docker, --no-docker    Write a docker-compose.yml for Postgres (default yes)\n  --yes                    Take every default; never prompt\n  --help                   This message\n\nWith --yes and no --database-url, the connection string points at the bundled\nPostgres. 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;
+}
+/**
+ * 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 declare function toPackageName(directoryName: string): string;
+export declare function parseArguments(argv: readonly string[]): ParsedArguments;
+export declare function generateSecretEncryptionKey(): string;
+export declare function bundledDatabaseUrl(port: number): string;
+/** This package's own version, which is the core version a scaffold pins. */
+export declare function readOwnVersion(): string;
+/**
+ * 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 declare function resolveOptions(parsed: ParsedArguments, interactive: boolean): Promise<ScaffoldOptions>;
+//# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAapD,eAAO,MAAM,KAAK,+yBAgB4C,CAAA;AAE9D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CACvB;AAgBD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAQ3D;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,eAAe,CAqCvE;AAED,wBAAgB,2BAA2B,IAAI,MAAM,CAEpD;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,IAAI,MAAM,CAevC;AAgCD;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,eAAe,EAAE,WAAW,EAAE,OAAO,GAAG,OAAO,CAAC,eAAe,CAAC,CAsC5G"}

package/dist/options.js

@@ -0,0 +1,172 @@
+/**
+ * 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.js';
+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.`;
+function parsePort(name, value, fallback) {
+    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) {
+    const cleaned = directoryName
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, '-')
+        .replace(/^[._-]+/, '')
+        .replace(/-+$/, '');
+    return cleaned.length > 0 ? cleaned : DEFAULT_DIRECTORY;
+}
+export function parseArguments(argv) {
+    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() {
+    return randomBytes(SECRET_KEY_BYTES).toString('base64');
+}
+export function bundledDatabaseUrl(port) {
+    return `postgres://kelpie:kelpie@localhost:${port}/kelpie`;
+}
+/** This package's own version, which is the core version a scaffold pins. */
+export function readOwnVersion() {
+    const manifestUrl = new URL('../package.json', import.meta.url);
+    const parsed = 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;
+    if (typeof version !== 'string') {
+        throw new ScaffoldError('create-kelpie has a non-string version in its manifest.');
+    }
+    return version;
+}
+function createPrompter() {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return {
+        async ask(question, fallback) {
+            const answer = (await rl.question(`${question} (${fallback}) `)).trim();
+            return answer.length > 0 ? answer : fallback;
+        },
+        async confirm(question, fallback) {
+            const answer = (await rl.question(`${question} (${fallback ? 'Y/n' : 'y/N'}) `)).trim().toLowerCase();
+            if (answer.length === 0) {
+                return fallback;
+            }
+            return answer.startsWith('y');
+        },
+        close() {
+            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, interactive) {
+    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();
+    }
+}
+//# sourceMappingURL=options.js.map

package/dist/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"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"}

package/dist/scaffold.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ */
+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 declare class ScaffoldError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare function assertWritable(directory: string): void;
+/** Writes the assembly. Returns the output paths, relative to the directory, in write order. */
+export declare function scaffold(options: ScaffoldOptions): readonly string[];
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,0FAA0F;IAC1F,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,qEAAqE;IACrE,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAA;IACpC,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED,wEAAwE;AACxE,qBAAa,aAAc,SAAQ,KAAK;IACtC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AA2DD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAkBtD;AAED,gGAAgG;AAChG,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,MAAM,EAAE,CAsBpE"}

package/dist/scaffold.js

@@ -0,0 +1,106 @@
+/**
+ * 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));
+/** A precondition failed. Reported as a message rather than a stack. */
+export class ScaffoldError extends Error {
+    constructor(message) {
+        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 = 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) {
+    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, tokens, source) {
+    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) {
+    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) {
+    assertWritable(options.directory);
+    const tokens = tokensFor(options);
+    const files = new Map(TEMPLATE_FILES);
+    if (options.docker) {
+        files.set(DOCKER_TEMPLATE, DOCKER_TEMPLATE);
+    }
+    const written = [];
+    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;
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "create-kelpie",
+  "version": "0.2.0",
+  "description": "Scaffold a self-hosted Kelpie assembly. Run it with npm create kelpie.",
+  "keywords": [
+    "kelpie",
+    "crm",
+    "scaffold",
+    "create",
+    "self-host"
+  ],
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velvet-tiger/kelpie.git",
+    "directory": "packages/create-kelpie"
+  },
+  "homepage": "https://github.com/velvet-tiger/kelpie/tree/main/packages/create-kelpie#readme",
+  "bugs": "https://github.com/velvet-tiger/kelpie/issues",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "create-kelpie": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "templates"
+  ],
+  "exports": {
+    ".": {
+      "kelpie-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "typecheck": "tsc --project tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "vitest": "^4.1.10"
+  }
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+/**
+ * `npm create kelpie` lands here.
+ *
+ * It writes an assembly and stops. It does not run `npm install`, start
+ * Postgres, or boot anything: the generated README says what to do next, and a
+ * scaffolder that installs for you is a scaffolder you cannot read the output
+ * of when the install fails.
+ */
+
+import { relative } from 'node:path'
+
+import { USAGE, parseArguments, resolveOptions } from './options.ts'
+import { ScaffoldError, scaffold } from './scaffold.ts'
+
+function report(message: string): void {
+  process.stdout.write(`${message}\n`)
+}
+
+async function main(): Promise<void> {
+  const parsed = parseArguments(process.argv.slice(2))
+
+  if (parsed.help) {
+    report(USAGE)
+
+    return
+  }
+
+  const options = await resolveOptions(parsed, process.stdin.isTTY === true)
+  const written = scaffold(options)
+  const here = relative(process.cwd(), options.directory) || '.'
+
+  report(`\nWrote ${written.length} files into ${here}/`)
+  report('')
+  report('Next:')
+  report(`  cd ${here}`)
+  report('  npm install')
+
+  if (options.docker) {
+    report('  docker compose up --detach --wait')
+  }
+
+  report('  npm run dev')
+  report('')
+  report(`Then open http://localhost:${options.webPort}/signup to create your account.`)
+  report(`${here}/README.md has the rest, including what every variable in .env does.`)
+}
+
+try {
+  await main()
+} catch (error: unknown) {
+  if (error instanceof ScaffoldError) {
+    process.stderr.write(`${error.message}\n`)
+    process.exit(1)
+  }
+
+  throw error
+}