create-ultimabase 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# create-ultimabase
+
+## 0.1.1
+
+### Patch Changes
+
+- The published starter starts: `ultimabase dev` runs `dist/serve.js`, and `@ultimabase/realtime`, which `@ultimabase/graphql` and `@ultimabase/rest` import, is a required peer the starter lists.
+
+## 0.1.0
+
+### Minor Changes
+
+- 0e885c4: The first release: the kernel, its adapters, transports and plugins, the testing helpers and the starter.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# create-ultimabase
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Writes a new UltimaBase application, ready to start: its models, a test and its server. Run it with `npm create ultimabase`.
+
+Documentation: [Quickstart](https://ultimabase.dev/docs/quickstart).

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

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

package/dist/cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// The `create-ultimabase` bin (D-130).
+import { main, processIo } from './main.js';
+process.exitCode = await main(process.argv.slice(2), processIo());

package/dist/main.d.ts

@@ -0,0 +1,16 @@
+export type Io = {
+    readonly cwd: string;
+    /** `npm_config_user_agent`, which names the package manager that ran it. */
+    readonly userAgent: string | undefined;
+    /** Asks in a terminal; `undefined` elsewhere. */
+    readonly ask: ((question: string) => Promise<string>) | undefined;
+    readonly print: (text: string) => void;
+    readonly fail: (text: string) => void;
+};
+/** A question asked on `input` and `output`, a terminal. */
+export declare const terminal: (input: NodeJS.ReadableStream, output: NodeJS.WritableStream) => (question: string) => Promise<string>;
+/** The process's directory, package manager, terminal and output. */
+export declare function processIo(): Io;
+/** Writes the starter; the process's exit code. */
+export declare function main(args: readonly string[], io: Io): Promise<number>;
+//# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,EAAE,GAAG;IAChB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,iDAAiD;IACjD,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAA;IACjE,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IACtC,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CACrC,CAAA;AAmBD,4DAA4D;AAC5D,eAAO,MAAM,QAAQ,UACZ,MAAM,CAAC,cAAc,UAAU,MAAM,CAAC,cAAc,gBAC3C,MAAM,KAAG,OAAO,CAAC,MAAM,CAOvC,CAAA;AAEF,qEAAqE;AACrE,wBAAgB,SAAS,IAAI,EAAE,CAa9B;AAYD,mDAAmD;AACnD,wBAAsB,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA4B3E"}

package/dist/main.js

@@ -0,0 +1,79 @@
+// `npm create ultimabase [directory]` (D-130): writes the starter in an empty
+// directory, installs nothing, and prints the next commands.
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { createInterface } from 'node:readline/promises';
+import { basename, relative, resolve } from 'node:path';
+import { write } from './starter.js';
+const usage = 'Usage: npm create ultimabase [directory]';
+const fallback = 'my-app';
+/** npm's rule for a new package's name. */
+const named = (name) => name.length <= 214 && /^[a-z0-9~-][a-z0-9._~-]*$/u.test(name);
+const managerOf = (userAgent) => {
+    const name = userAgent?.split('/')[0];
+    return name === 'yarn' || name === 'pnpm' ? name : 'npm';
+};
+const steps = {
+    npm: ['npm install', 'npm run dev'],
+    yarn: ['yarn', 'yarn dev'],
+    pnpm: ['pnpm install', 'pnpm dev'],
+};
+/** A question asked on `input` and `output`, a terminal. */
+export const terminal = (input, output) => async (question) => {
+    const line = createInterface({ input, output });
+    try {
+        return await line.question(question);
+    }
+    finally {
+        line.close();
+    }
+};
+/** The process's directory, package manager, terminal and output. */
+export function processIo() {
+    const tty = process.stdin.isTTY && process.stdout.isTTY;
+    return {
+        cwd: process.cwd(),
+        userAgent: process.env['npm_config_user_agent'],
+        ask: tty ? terminal(process.stdin, process.stdout) : undefined,
+        print: (text) => {
+            console.log(text);
+        },
+        fail: (text) => {
+            console.error(text);
+        },
+    };
+}
+async function directoryOf(io) {
+    if (io.ask === undefined)
+        return fallback;
+    const answer = (await io.ask(`? Project name: (${fallback}) `)).trim();
+    return answer === '' ? fallback : answer;
+}
+const empty = (target) => !existsSync(target) ||
+    (statSync(target).isDirectory() && readdirSync(target).length === 0);
+/** Writes the starter; the process's exit code. */
+export async function main(args, io) {
+    const [given, ...more] = args;
+    if (more.length > 0 || given?.startsWith('-') === true) {
+        io.fail(usage);
+        return 1;
+    }
+    const directory = given ?? (await directoryOf(io));
+    const target = resolve(io.cwd, directory);
+    const name = basename(target);
+    if (!named(name)) {
+        io.fail(`${name} cannot name a package: use lowercase letters, digits, '-', '.' and '_'.`);
+        return 1;
+    }
+    if (!empty(target)) {
+        io.fail(`${directory} is not an empty directory.`);
+        return 1;
+    }
+    const manager = managerOf(io.userAgent);
+    write(target, name, manager);
+    const cd = relative(io.cwd, target) === ''
+        ? []
+        : [`cd ${/\s/u.test(directory) ? `"${directory}"` : directory}`];
+    const next = [...cd, ...steps[manager]].map((step) => `  ${step}`);
+    io.print(`\nCreated ${name}. Next:\n\n${next.join('\n')}\n`);
+    return 0;
+}

package/dist/starter.d.ts

@@ -0,0 +1,13 @@
+export type Manager = 'npm' | 'yarn' | 'pnpm';
+/** The packages the starter runs beside UltimaBase's, as the repository tests them. */
+export declare const others: {
+    readonly '@types/node': '^24.19.2';
+    readonly graphql: '^17.0.2';
+    readonly vite: '^8.3.4';
+    readonly vitest: '^5.0.5';
+};
+/** `create-ultimabase`'s version, which the official packages share (D-60). */
+export declare function ownVersion(): string;
+/** Writes the starter named `name` in `target`, an empty or missing directory. */
+export declare function write(target: string, name: string, manager: Manager): void;
+//# sourceMappingURL=starter.d.ts.map

package/dist/starter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"starter.d.ts","sourceRoot":"","sources":["../src/starter.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAA;AAI7C,uFAAuF;AACvF,eAAO,MAAM,MAAM;aAClB,aAAa,EAAE,UAAU;aACzB,OAAO,EAAE,SAAS;aAClB,IAAI,EAAE,QAAQ;aACd,MAAM,EAAE,QAAQ;CACP,CAAA;AAEV,+EAA+E;AAC/E,wBAAgB,UAAU,IAAI,MAAM,CAKnC;AAiDD,kFAAkF;AAClF,wBAAgB,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAS1E"}

package/dist/starter.js

@@ -0,0 +1,69 @@
+// The starter's files (D-130): the template as it is, its `gitignore` as
+// `.gitignore`, and the package.json and README that name the application.
+import { cpSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const template = fileURLToPath(new URL('../template', import.meta.url));
+/** The packages the starter runs beside UltimaBase's, as the repository tests them. */
+export const others = {
+    '@types/node': '^24.19.2',
+    graphql: '^17.0.2',
+    vite: '^8.3.4',
+    vitest: '^5.0.5',
+};
+/** `create-ultimabase`'s version, which the official packages share (D-60). */
+export function ownVersion() {
+    const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    return String(Reflect.get(Object(manifest), 'version'));
+}
+const manifestOf = (name) => {
+    const ours = `^${ownVersion()}`;
+    return {
+        name,
+        private: true,
+        type: 'module',
+        engines: { node: '>=24.7.0' },
+        scripts: {
+            dev: 'ultimabase dev',
+            start: 'ultimabase start',
+            test: 'vitest',
+        },
+        dependencies: {
+            '@ultimabase/graphql': ours,
+            '@ultimabase/http': ours,
+            '@ultimabase/realtime': ours,
+            graphql: others.graphql,
+            ultimabase: ours,
+        },
+        devDependencies: {
+            '@types/node': others['@types/node'],
+            '@ultimabase/testing': ours,
+            vite: others.vite,
+            vitest: others.vitest,
+        },
+    };
+};
+/** How `manager` runs a script other than `start` and `test`. */
+const run = (manager) => manager === 'npm' ? 'npm run' : manager;
+const readme = (name, manager) => `# ${name}
+
+An UltimaBase application. Node runs its TypeScript as it is written.
+
+- \`${run(manager)} dev\` serves it on http://localhost:3000, GraphQL on
+  \`/graphql\`, and restarts it when a file changes; \`PORT\` sets another
+  port.
+- \`${manager} start\` serves it in production.
+- \`${manager} test\` runs its tests, each on a new in-memory database.
+
+\`src/models.ts\` declares the models, \`src/app.ts\` the database and the
+plugins, and \`ultimabase.config.ts\` names the application the
+\`ultimabase\` command runs.
+`;
+/** Writes the starter named `name` in `target`, an empty or missing directory. */
+export function write(target, name, manager) {
+    mkdirSync(target, { recursive: true });
+    cpSync(template, target, { recursive: true });
+    renameSync(join(target, 'gitignore'), join(target, '.gitignore'));
+    writeFileSync(join(target, 'package.json'), `${JSON.stringify(manifestOf(name), undefined, '\t')}\n`);
+    writeFileSync(join(target, 'README.md'), readme(name, manager));
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "create-ultimabase",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Writes a new UltimaBase application: npm create ultimabase.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "homepage": "https://ultimabase.dev/docs/quickstart",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrEkinox/ultimabase.git",
+    "directory": "packages/create-ultimabase"
+  },
+  "engines": {
+    "node": ">=24.7.0"
+  },
+  "bin": "./dist/cli.js",
+  "files": [
+    "dist",
+    "src",
+    "template",
+    "!src/**/*.test.ts",
+    "!src/test"
+  ],
+  "scripts": {
+    "prepack": "rm -rf dist && yarn run -T tsc --project tsconfig.build.json"
+  },
+  "publishConfig": {
+    "bin": "./dist/cli.js"
+  },
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "@ultimabase/graphql": "0.1.1",
+    "@ultimabase/http": "0.1.1",
+    "@ultimabase/testing": "0.1.1",
+    "graphql": "17.0.2",
+    "ultimabase": "0.1.1",
+    "vite": "8.3.4",
+    "vitest": "5.0.5"
+  }
 }

package/src/cli.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// The `create-ultimabase` bin (D-130).
+import { main, processIo } from './main.ts'
+
+process.exitCode = await main(process.argv.slice(2), processIo())

package/src/main.ts

@@ -0,0 +1,103 @@
+// `npm create ultimabase [directory]` (D-130): writes the starter in an empty
+// directory, installs nothing, and prints the next commands.
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { createInterface } from 'node:readline/promises'
+import { basename, relative, resolve } from 'node:path'
+import type { Manager } from './starter.ts'
+import { write } from './starter.ts'
+
+export type Io = {
+	readonly cwd: string
+	/** `npm_config_user_agent`, which names the package manager that ran it. */
+	readonly userAgent: string | undefined
+	/** Asks in a terminal; `undefined` elsewhere. */
+	readonly ask: ((question: string) => Promise<string>) | undefined
+	readonly print: (text: string) => void
+	readonly fail: (text: string) => void
+}
+
+const usage = 'Usage: npm create ultimabase [directory]'
+const fallback = 'my-app'
+
+/** npm's rule for a new package's name. */
+const named = (name: string): boolean =>
+	name.length <= 214 && /^[a-z0-9~-][a-z0-9._~-]*$/u.test(name)
+
+const managerOf = (userAgent: string | undefined): Manager => {
+	const name = userAgent?.split('/')[0]
+	return name === 'yarn' || name === 'pnpm' ? name : 'npm'
+}
+const steps: Record<Manager, readonly string[]> = {
+	npm: ['npm install', 'npm run dev'],
+	yarn: ['yarn', 'yarn dev'],
+	pnpm: ['pnpm install', 'pnpm dev'],
+}
+
+/** A question asked on `input` and `output`, a terminal. */
+export const terminal =
+	(input: NodeJS.ReadableStream, output: NodeJS.WritableStream) =>
+	async (question: string): Promise<string> => {
+		const line = createInterface({ input, output })
+		try {
+			return await line.question(question)
+		} finally {
+			line.close()
+		}
+	}
+
+/** The process's directory, package manager, terminal and output. */
+export function processIo(): Io {
+	const tty = process.stdin.isTTY && process.stdout.isTTY
+	return {
+		cwd: process.cwd(),
+		userAgent: process.env['npm_config_user_agent'],
+		ask: tty ? terminal(process.stdin, process.stdout) : undefined,
+		print: (text) => {
+			console.log(text)
+		},
+		fail: (text) => {
+			console.error(text)
+		},
+	}
+}
+
+async function directoryOf(io: Io): Promise<string> {
+	if (io.ask === undefined) return fallback
+	const answer = (await io.ask(`? Project name: (${fallback}) `)).trim()
+	return answer === '' ? fallback : answer
+}
+
+const empty = (target: string): boolean =>
+	!existsSync(target) ||
+	(statSync(target).isDirectory() && readdirSync(target).length === 0)
+
+/** Writes the starter; the process's exit code. */
+export async function main(args: readonly string[], io: Io): Promise<number> {
+	const [given, ...more] = args
+	if (more.length > 0 || given?.startsWith('-') === true) {
+		io.fail(usage)
+		return 1
+	}
+	const directory = given ?? (await directoryOf(io))
+	const target = resolve(io.cwd, directory)
+	const name = basename(target)
+	if (!named(name)) {
+		io.fail(
+			`${name} cannot name a package: use lowercase letters, digits, '-', '.' and '_'.`,
+		)
+		return 1
+	}
+	if (!empty(target)) {
+		io.fail(`${directory} is not an empty directory.`)
+		return 1
+	}
+	const manager = managerOf(io.userAgent)
+	write(target, name, manager)
+	const cd =
+		relative(io.cwd, target) === ''
+			? []
+			: [`cd ${/\s/u.test(directory) ? `"${directory}"` : directory}`]
+	const next = [...cd, ...steps[manager]].map((step) => `  ${step}`)
+	io.print(`\nCreated ${name}. Next:\n\n${next.join('\n')}\n`)
+	return 0
+}

package/src/starter.ts

@@ -0,0 +1,90 @@
+// The starter's files (D-130): the template as it is, its `gitignore` as
+// `.gitignore`, and the package.json and README that name the application.
+import {
+	cpSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	writeFileSync,
+} from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export type Manager = 'npm' | 'yarn' | 'pnpm'
+
+const template = fileURLToPath(new URL('../template', import.meta.url))
+
+/** The packages the starter runs beside UltimaBase's, as the repository tests them. */
+export const others = {
+	'@types/node': '^24.19.2',
+	graphql: '^17.0.2',
+	vite: '^8.3.4',
+	vitest: '^5.0.5',
+} as const
+
+/** `create-ultimabase`'s version, which the official packages share (D-60). */
+export function ownVersion(): string {
+	const manifest: unknown = JSON.parse(
+		readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+	)
+	return String(Reflect.get(Object(manifest), 'version'))
+}
+
+const manifestOf = (name: string): object => {
+	const ours = `^${ownVersion()}`
+	return {
+		name,
+		private: true,
+		type: 'module',
+		engines: { node: '>=24.7.0' },
+		scripts: {
+			dev: 'ultimabase dev',
+			start: 'ultimabase start',
+			test: 'vitest',
+		},
+		dependencies: {
+			'@ultimabase/graphql': ours,
+			'@ultimabase/http': ours,
+			'@ultimabase/realtime': ours,
+			graphql: others.graphql,
+			ultimabase: ours,
+		},
+		devDependencies: {
+			'@types/node': others['@types/node'],
+			'@ultimabase/testing': ours,
+			vite: others.vite,
+			vitest: others.vitest,
+		},
+	}
+}
+
+/** How `manager` runs a script other than `start` and `test`. */
+const run = (manager: Manager): string =>
+	manager === 'npm' ? 'npm run' : manager
+
+const readme = (name: string, manager: Manager): string => `# ${name}
+
+An UltimaBase application. Node runs its TypeScript as it is written.
+
+- \`${run(manager)} dev\` serves it on http://localhost:3000, GraphQL on
+  \`/graphql\`, and restarts it when a file changes; \`PORT\` sets another
+  port.
+- \`${manager} start\` serves it in production.
+- \`${manager} test\` runs its tests, each on a new in-memory database.
+
+\`src/models.ts\` declares the models, \`src/app.ts\` the database and the
+plugins, and \`ultimabase.config.ts\` names the application the
+\`ultimabase\` command runs.
+`
+
+/** Writes the starter named `name` in `target`, an empty or missing directory. */
+export function write(target: string, name: string, manager: Manager): void {
+	mkdirSync(target, { recursive: true })
+	cpSync(template, target, { recursive: true })
+	renameSync(join(target, 'gitignore'), join(target, '.gitignore'))
+	writeFileSync(
+		join(target, 'package.json'),
+		`${JSON.stringify(manifestOf(name), undefined, '\t')}\n`,
+	)
+	writeFileSync(join(target, 'README.md'), readme(name, manager))
+}

package/template/gitignore

@@ -0,0 +1 @@
+node_modules

package/template/src/app.test.ts

@@ -0,0 +1,20 @@
+// Each test runs the application on a new in-memory database and a free port.
+import { testApplication } from '@ultimabase/testing'
+import { master } from 'ultimabase'
+import { expect, it } from 'vitest'
+import { app } from './app.ts'
+import { Post } from './models.ts'
+
+const running = testApplication(app)
+
+it('lists the posts over GraphQL', async () => {
+	await Post.create({ data: { title: 'Hello' } }, { as: master })
+	const response = await fetch(`${running.url}/graphql`, {
+		method: 'POST',
+		headers: { 'content-type': 'application/json' },
+		body: JSON.stringify({ query: '{ posts { edges { node { title } } } }' }),
+	})
+	expect(await response.json()).toEqual({
+		data: { posts: { edges: [{ node: { title: 'Hello' } }] } },
+	})
+})

package/template/src/app.ts

@@ -0,0 +1,16 @@
+// The application: its database, its plugins and its models.
+import { graphqlPlugin } from '@ultimabase/graphql'
+import { httpPlugin } from '@ultimabase/http'
+import { defineApp, memory } from 'ultimabase'
+import { Post } from './models.ts'
+
+export const app = defineApp({
+	// For PostgreSQL: postgres({ url: process.env['DATABASE_URL'] }) from @ultimabase/postgres.
+	database: memory(),
+	plugins: [
+		httpPlugin(),
+		graphqlPlugin(),
+		// For REST too: restPlugin() from @ultimabase/rest.
+	],
+	models: [Post],
+})

package/template/src/models.ts

@@ -0,0 +1,11 @@
+// The application's models: each one a table, its fields and who may
+// read and write it.
+import { allow, defineModel } from 'ultimabase'
+
+export const Post = defineModel({
+	name: 'Post',
+	fields: (f) => ({
+		title: f.string(),
+	}),
+	// Anyone may read and write posts; see `allow` for the other rules.
+}).with({ access: allow.public })

package/template/tsconfig.json

@@ -0,0 +1,17 @@
+{
+	// For the editor: Node runs the TypeScript as it is written.
+	"compilerOptions": {
+		"target": "ES2024",
+		"module": "NodeNext",
+		"strict": true,
+		"exactOptionalPropertyTypes": true,
+		"noUncheckedIndexedAccess": true,
+		"verbatimModuleSyntax": true,
+		"erasableSyntaxOnly": true,
+		"allowImportingTsExtensions": true,
+		"noEmit": true,
+		"skipLibCheck": true,
+		"types": ["node"]
+	},
+	"include": ["src", "ultimabase.config.ts"]
+}

package/template/ultimabase.config.ts

@@ -0,0 +1,2 @@
+// What `ultimabase dev` and `ultimabase start` run: the application.
+export { app as default } from './src/app.ts'