create-soda 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 falsea3
+
+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/README.md

@@ -1,3 +1,30 @@
-# Temporary Holding Version
+# create-soda
 
-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.
+Creates a [Soda](https://github.com/getsodajs/soda) project.
+
+```bash
+bun create soda my-app
+```
+
+or `npm create soda@latest my-app`. Then:
+
+```bash
+cd my-app
+bun install
+bun dev
+```
+
+The project has a users module (service, controller, test), a guard passing the current user to handlers, CORS and graceful shutdown.
+
+## Options
+
+| Option | |
+|---|---|
+| `[directory]` | where to create the project; asked in a terminal, `soda-app` otherwise |
+| `--overwrite` | empty a non-empty directory first (`.git` is kept) |
+| `--no-interactive` | never ask, for scripts and CI |
+| `--core-version <range>` | version of `@getsoda/core` to depend on |
+
+## License
+
+[MIT](./LICENSE)

package/core-version.json

@@ -0,0 +1 @@
+{"version":"0.1.1"}

package/dist/index.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/**
+ * @module
+ * `create-soda`: creates a Soda project.
+ *
+ * ```bash
+ * bun create soda my-app
+ * npm create soda@latest my-app
+ * ```
+ *
+ * Interactive in a terminal, flag-driven otherwise (CI, scripts). Uses only
+ * Node built-ins, so it runs the same under `npm create` (Node) and `bun create`.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, relative, resolve } from 'node:path';
+import { stdin, stdout } from 'node:process';
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+import { createProject, detectPackageManager, emptyDir, formatTargetDir, isEmptyDir, isValidPackageName, toValidPackageName, } from './project.js';
+const DEFAULT_DIR = 'soda-app';
+const HELP = `Usage: create-soda [directory] [options]
+
+Creates a Soda project. Interactive in a terminal.
+
+Options:
+  --overwrite                   empty the directory if it is not empty
+  --interactive, --no-interactive
+                                force or disable questions
+  --core-version <range>        version of @getsoda/core to depend on
+  -h, --help                    show this help
+`;
+const parseArguments = (args) => {
+    let dir;
+    let overwrite = false;
+    let interactive;
+    let coreVersion;
+    let help = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--overwrite') {
+            overwrite = true;
+        }
+        else if (arg === '--interactive' || arg === '--no-interactive') {
+            interactive = arg === '--interactive';
+        }
+        else if (arg === '--core-version') {
+            coreVersion = args[++i];
+        }
+        else if (arg === '-h' || arg === '--help') {
+            help = true;
+        }
+        else if (arg.startsWith('-')) {
+            throw new Error(`Unknown option ${arg}\n\n${HELP}`);
+        }
+        else {
+            dir ??= arg;
+        }
+    }
+    return { dir, overwrite, interactive, coreVersion, help };
+};
+/** Version range of `@getsoda/core`: written next to the build, or read from the monorepo when run from sources. */
+const readCoreVersion = () => {
+    const built = fileURLToPath(new URL('../core-version.json', import.meta.url));
+    if (existsSync(built)) {
+        return `^${JSON.parse(readFileSync(built, 'utf8')).version}`;
+    }
+    const workspace = fileURLToPath(new URL('../../core/package.json', import.meta.url));
+    return `^${JSON.parse(readFileSync(workspace, 'utf8')).version}`;
+};
+const main = async () => {
+    const args = parseArguments(process.argv.slice(2));
+    if (args.help) {
+        stdout.write(HELP);
+        return;
+    }
+    const interactive = args.interactive ?? stdin.isTTY === true;
+    const prompt = interactive ? createInterface({ input: stdin, output: stdout }) : undefined;
+    try {
+        let dir = args.dir === undefined ? '' : formatTargetDir(args.dir);
+        if (dir === '' && prompt !== undefined) {
+            dir = formatTargetDir((await prompt.question(`Project directory (${DEFAULT_DIR}): `)) || DEFAULT_DIR);
+        }
+        dir ||= DEFAULT_DIR;
+        if (!(await isEmptyDir(dir))) {
+            const overwrite = args.overwrite ||
+                (prompt !== undefined &&
+                    /^y(?:es)?$/i.test(await prompt.question(`${dir} is not empty. Remove its files and continue? (y/N) `)));
+            if (!overwrite) {
+                throw new Error(`${dir} is not empty; choose another directory or pass --overwrite`);
+            }
+            await emptyDir(dir);
+        }
+        let name = toValidPackageName(basename(resolve(dir)));
+        if (prompt !== undefined) {
+            const answer = (await prompt.question(`Package name (${name}): `)).trim();
+            if (answer !== '' && !isValidPackageName(answer)) {
+                throw new Error(`"${answer}" is not a valid npm package name`);
+            }
+            name = answer || name;
+        }
+        await createProject({
+            dir,
+            name,
+            coreVersion: args.coreVersion ?? readCoreVersion(),
+            template: fileURLToPath(new URL('../template', import.meta.url)),
+        });
+        const manager = detectPackageManager(process.env.npm_config_user_agent);
+        const cd = relative(process.cwd(), resolve(dir));
+        stdout.write(`\nCreated ${name} in ${resolve(dir)}\n\nNext steps:\n`);
+        if (cd !== '') {
+            stdout.write(`  cd ${cd.includes(' ') ? JSON.stringify(cd) : cd}\n`);
+        }
+        stdout.write(`  ${manager} install\n  ${manager === 'npm' ? 'npm run' : manager} dev\n`);
+    }
+    finally {
+        prompt?.close();
+    }
+};
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});

package/dist/project.js

@@ -0,0 +1,68 @@
+/**
+ * @module
+ * Creating a project from the template: names, target directory, files.
+ *
+ * Rules from `create-vite`: the target directory is cleaned of characters
+ * file systems refuse, a directory holding only `.git` counts as empty, the
+ * package name is made valid for npm, and `.gitignore` is stored as
+ * `_gitignore` because npm drops `.gitignore` files from published packages.
+ */
+import { existsSync } from 'node:fs';
+import { cp, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+/** Template files renamed when copied. */
+const RENAMED = { _gitignore: '.gitignore' };
+/** `' my-app/ '` → `'my-app'`. */
+export const formatTargetDir = (dir) => dir
+    .trim()
+    .replace(/[<>:"\\|?*]/g, '')
+    .replace(/\/+$/, '');
+export const isValidPackageName = (name) => /^(?:@[a-z\d\-*~][a-z\d\-*._~]*\/)?[a-z\d\-~][a-z\d\-._~]*$/.test(name);
+/** `'My App'` → `'my-app'`. */
+export const toValidPackageName = (name) => name
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/^[._]/, '')
+    .replace(/[^a-z\d\-~]+/g, '-');
+/** `true` for a missing directory, an empty one, or one holding only `.git`. */
+export const isEmptyDir = async (dir) => {
+    if (!existsSync(dir)) {
+        return true;
+    }
+    const entries = await readdir(dir);
+    return entries.length === 0 || (entries.length === 1 && entries[0] === '.git');
+};
+/** Removes everything in `dir` but `.git`. */
+export const emptyDir = async (dir) => {
+    for (const entry of await readdir(dir)) {
+        if (entry !== '.git') {
+            await rm(join(dir, entry), { recursive: true, force: true });
+        }
+    }
+};
+/**
+ * Copies the template into `dir`, renames `_gitignore`, sets the package name and the core version.
+ */
+export const createProject = async (options) => {
+    const root = resolve(options.dir);
+    await cp(options.template, root, { recursive: true });
+    for (const [from, to] of Object.entries(RENAMED)) {
+        if (existsSync(join(root, from))) {
+            await rename(join(root, from), join(root, to));
+        }
+    }
+    const manifestPath = join(root, 'package.json');
+    const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+    manifest.name = options.name ?? toValidPackageName(basename(root));
+    manifest.dependencies['@getsoda/core'] = options.coreVersion;
+    await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+};
+/**
+ * Package manager the command was run with, from `npm_config_user_agent`
+ * (`bun/1.4.3 npm/? node/v24…` → `bun`). Defaults to `bun`.
+ */
+export const detectPackageManager = (userAgent) => {
+    const name = userAgent?.split(' ')[0]?.split('/')[0];
+    return name === undefined || name === '' ? 'bun' : name;
+};

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "create-soda",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Create a Soda project: bun create soda my-app",
+  "keywords": [
+    "soda",
+    "bun",
+    "create",
+    "scaffold",
+    "template"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getsodajs/soda.git",
+    "directory": "packages/create-soda"
+  },
+  "homepage": "https://github.com/getsodajs/soda/tree/main/packages/create-soda#readme",
+  "bugs": {
+    "url": "https://github.com/getsodajs/soda/issues"
+  },
+  "type": "module",
+  "bin": {
+    "create-soda": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "template",
+    "core-version.json"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && bun scripts/write-core-version.ts"
+  }
+}

package/template/README.md

@@ -0,0 +1,21 @@
+# Soda app
+
+Created with `create-soda`. Requires [Bun](https://bun.sh).
+
+```bash
+bun install
+bun dev        # bun --hot: reloads on change
+bun test
+bun typecheck
+```
+
+- `src/main.ts`: creates the application, CORS, graceful shutdown.
+- `src/users`: a module with a service, a controller and a test.
+- `src/auth/auth.guard.ts`: a guard passing the current user to handlers.
+
+Try it:
+
+```bash
+curl -X POST localhost:3000/users -H 'authorization: Bearer ann' -H 'content-type: application/json' -d '{"name":"Bo"}'
+curl localhost:3000/users/1
+```

package/template/_gitignore

@@ -0,0 +1,11 @@
+node_modules
+dist
+*.tgz
+coverage
+
+.env
+.env.local
+.env.*.local
+
+.DS_Store
+.idea

package/template/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "soda-app",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun --hot src/main.ts",
+    "start": "bun src/main.ts",
+    "test": "bun test",
+    "typecheck": "bun check"
+  },
+  "dependencies": {
+    "@getsoda/core": "workspace",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^7.0.2"
+  }
+}

package/template/src/app.module.ts

@@ -0,0 +1,5 @@
+import { Module } from '@getsoda/core'
+import { UsersModule } from './users/users.module.ts'
+
+@Module({ imports: [UsersModule] })
+export class AppModule {}

package/template/src/auth/auth.guard.ts

@@ -0,0 +1,26 @@
+import { ContextKey } from '@getsoda/core'
+import type { CanActivate, Context } from '@getsoda/core'
+
+export interface CurrentUser {
+  readonly name: string
+}
+
+/** The user the guard found; handlers read it with `ctx.get(CURRENT_USER)` or `value(CURRENT_USER)`. */
+export const CURRENT_USER = new ContextKey<CurrentUser>('currentUser')
+
+/**
+ * Accepts `Authorization: Bearer <name>`. A placeholder: verify real tokens here.
+ */
+export class AuthGuard implements CanActivate {
+  canActivate(ctx: Context): boolean {
+    const header = ctx.header('authorization')
+
+    if (header === undefined || !header.startsWith('Bearer ')) {
+      return false
+    }
+
+    ctx.set(CURRENT_USER, { name: header.slice('Bearer '.length) })
+
+    return true
+  }
+}

package/template/src/main.ts

@@ -0,0 +1,9 @@
+import { cors, createApp } from '@getsoda/core'
+import { AppModule } from './app.module.ts'
+
+const app = await createApp(AppModule, {
+  middleware: [cors({ origin: process.env.CORS_ORIGIN ?? '*' })],
+})
+
+app.enableShutdownSignals()
+await app.listen(Number(process.env.PORT ?? 3000))

package/template/src/users/users.controller.ts

@@ -0,0 +1,35 @@
+import { body, Controller, Get, inject, int, NotFoundException, param, Post, UseGuards, value } from '@getsoda/core'
+import { z } from 'zod'
+import { AuthGuard, CURRENT_USER } from '../auth/auth.guard.ts'
+import type { CurrentUser } from '../auth/auth.guard.ts'
+import { UsersService } from './users.service.ts'
+import type { User } from './users.service.ts'
+
+const CreateUser = z.object({ name: z.string().trim().min(1) })
+
+@Controller('users')
+export class UsersController {
+  readonly #users = inject(UsersService)
+
+  @Get()
+  list(): User[] {
+    return this.#users.list()
+  }
+
+  @Get(':id', [param('id', int())])
+  findOne(id: number): User {
+    const user = this.#users.find(id)
+
+    if (user === undefined) {
+      throw new NotFoundException(`User ${id} not found`)
+    }
+
+    return user
+  }
+
+  @Post([body(CreateUser), value(CURRENT_USER)])
+  @UseGuards(AuthGuard)
+  create(input: z.infer<typeof CreateUser>, currentUser: CurrentUser): User {
+    return this.#users.create(input.name, currentUser.name)
+  }
+}

package/template/src/users/users.module.ts

@@ -0,0 +1,6 @@
+import { Module } from '@getsoda/core'
+import { UsersController } from './users.controller.ts'
+import { UsersService } from './users.service.ts'
+
+@Module({ providers: [UsersService], controllers: [UsersController] })
+export class UsersModule {}

package/template/src/users/users.service.ts

@@ -0,0 +1,29 @@
+import { inject, Logger } from '@getsoda/core'
+
+export interface User {
+  readonly id: number
+  readonly name: string
+  readonly createdBy: string
+}
+
+export class UsersService {
+  readonly #logger = inject(Logger).child('UsersService')
+  readonly #users = new Map<number, User>()
+
+  list(): User[] {
+    return [...this.#users.values()]
+  }
+
+  find(id: number): User | undefined {
+    return this.#users.get(id)
+  }
+
+  create(name: string, createdBy: string): User {
+    const user = { id: this.#users.size + 1, name, createdBy }
+
+    this.#users.set(user.id, user)
+    this.#logger.log('User created', { id: user.id })
+
+    return user
+  }
+}

package/template/src/users/users.test.ts

@@ -0,0 +1,34 @@
+import { afterAll, expect, test } from 'bun:test'
+import { createApp } from '@getsoda/core'
+import { AppModule } from '../app.module.ts'
+
+const app = await createApp(AppModule, { logger: false })
+const server = await app.listen(0)
+const url = (path: string) => new URL(path, server.url)
+
+afterAll(() => app.close())
+
+test('creates a user when authenticated', async () => {
+  const response = await fetch(url('/users'), {
+    method: 'POST',
+    headers: { authorization: 'Bearer ann', 'content-type': 'application/json' },
+    body: JSON.stringify({ name: 'Bo' }),
+  })
+
+  expect(response.status).toBe(201)
+  expect(await response.json()).toEqual({ id: 1, name: 'Bo', createdBy: 'ann' })
+  expect(await (await fetch(url('/users/1'))).json()).toEqual({ id: 1, name: 'Bo', createdBy: 'ann' })
+})
+
+test('refuses anonymous writes, invalid bodies and unknown users', async () => {
+  const anonymous = await fetch(url('/users'), { method: 'POST', body: '{}' })
+  const invalid = await fetch(url('/users'), {
+    method: 'POST',
+    headers: { authorization: 'Bearer ann', 'content-type': 'application/json' },
+    body: JSON.stringify({ name: '' }),
+  })
+
+  expect(anonymous.status).toBe(403)
+  expect(invalid.status).toBe(400)
+  expect((await fetch(url('/users/999'))).status).toBe(404)
+})

package/template/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "types": ["bun"],
+
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true
+  }
+}