redweb 0.16.1 → 0.16.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redweb",
-  "version": "0.16.1",
+  "version": "0.16.2",
   "description": "A small Node.js foundation for HTTP, WebSockets, multiplayer services, and server-rendered HTML",
   "main": "index.js",
   "types": "index.d.ts",

package/recipes/foundation/README.md

@@ -0,0 +1,7 @@
+# Neutral application foundation
+
+The default initializer creates a working TypeScript/TSX application without choosing a product domain. Replace `HomePage` with your pages, then add socket routes and application services as needed.
+
+Use `--with auth,multiplayer` when the project needs those dependency sets. `auth` adds Express, Zod, their TypeScript declarations, and the Node version required by Redweb's native-SQLite authentication path. `multiplayer` adds Redweb Client and Zod. Capabilities adjust the manifest without copying dashboard, chat, counter, or match-example source. Use an explicit `--template` only when you want a complete example walkthrough.
+
+Run `npm test` for the real HTTP and lifecycle checks. Pass `--bare` only when you intentionally do not want the test directory, test scripts, or test-only coverage dependency; the runnable source, assets, build scripts, and development setup stay the same.

package/recipes/foundation/app.test.cjs

@@ -0,0 +1,15 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { listen } = require('./network.cjs');
+
+test('neutral application foundation serves real HTML and CSS', { timeout: 10000 }, async t => {
+    const origin = await listen(t);
+    const response = await fetch(origin);
+    assert.equal(response.status, 200);
+    const document = await response.text();
+    assert.match(document, /<h1>Redweb is ready\.<\/h1>/);
+    const css = document.match(/<link rel="stylesheet" href="([^"]+)"/)[1];
+    const stylesheet = await fetch(`${origin}${css}`);
+    assert.equal(stylesheet.status, 200);
+    assert.match(await stylesheet.text(), /\.home/);
+});

package/recipes/foundation/app.tsx

@@ -0,0 +1,12 @@
+import { defineApp, page } from 'redweb';
+
+@page('/', { live: false, css: 'app.css' })
+export class HomePage {
+    render() {
+        return <main class="home"><h1>Redweb is ready.</h1><p>Replace this page with your application.</p></main>;
+    }
+}
+
+export const app = defineApp({ pages: [HomePage], port: Number(process.env.PORT ?? 8181), templateRoot: __dirname });
+
+if (require.main === module) app.run();

package/src/cli/ProjectInitializer.js

@@ -11,7 +11,7 @@ class ProjectInitializer {
 
     initialize(target, options = {}) {
         const root = path.resolve(target);
-        const templateFiles = projectFiles(this.version, options.template);
+        const templateFiles = projectFiles(this.version, options.template ?? null, undefined, options);
         const files = options.existing ? templateFiles.filter(file => file.path === 'tsconfig.json') : templateFiles;
         return new FilePlan(root, files).write({ dryRun: options.dryRun });
     }

package/src/cli/arguments.js

@@ -1,15 +1,17 @@
 'use strict';
 
-const { TEMPLATES } = require('./templates');
+const { CAPABILITIES, TEMPLATES } = require('./templates');
 const { KINDS } = require('./ProjectAddition');
 
 const USAGE = [
-    `Usage: redweb init [directory] [--template ${TEMPLATES.join('|')}] [--existing] [--dry-run] [--json]`,
+    `Usage: redweb init [directory] [--with ${CAPABILITIES.join(',')}] [--template ${TEMPLATES.join('|')}] [--bare] [--existing] [--dry-run] [--json]`,
     '       redweb doctor [directory] [--port number] [--json]',
     `       redweb add <${KINDS.join('|')}> <name> [directory] [--config file] [--source-dir dir] [--test-dir dir] [--dry-run] [--json]`,
     '       redweb --help | --version',
     '',
-    '--existing creates only a missing tsconfig.json; no starter or package changes.',
+    '--existing creates only a missing tsconfig.json; no starter or package changes.',
+    '--with adds neutral capability dependencies without generating example-domain code.',
+    '--bare omits generated tests; templates remain explicit examples.',
     '--dry-run reports planned files without writing anything.',
     'doctor inspects configuration without executing application code or repairing files.',
 ].join('\n') + '\n';
@@ -18,7 +20,7 @@ function parseArguments(args) {
     const [command = '--help', ...rest] = args;
     if (['--help', '-h', '--version'].includes(command) && !rest.length) return { command };
     if (!['init', 'doctor', 'add'].includes(command)) throw new Error('Unknown command. Run redweb --help.');
-    const result = { command, target: '.', existing: false, dryRun: false, json: false, port: null };
+    const result = { command, target: '.', existing: false, dryRun: false, json: false, port: null };
     if (command === 'add') {
         result.kind = rest.shift();
         result.name = rest.shift();
@@ -37,25 +39,35 @@ function parseArguments(args) {
         if (seen.has(value)) throw new Error(`Duplicate option: ${value}`);
         seen.add(value);
         if (value === '--json') result.json = true;
-        else if (value === '--existing' && command === 'init') result.existing = true;
+        else if (value === '--existing' && command === 'init') result.existing = true;
+        else if (value === '--bare' && command === 'init') result.bare = true;
         else if (value === '--dry-run' && ['init', 'add'].includes(command)) result.dryRun = true;
         else if (command === 'add' && ['--config', '--source-dir', '--test-dir'].includes(value)) {
             const argument = rest[++i];
             if (!argument || argument.startsWith('-')) throw new Error(`${value} requires a path.`);
             result[{ '--config': 'configFile', '--source-dir': 'sourceDir', '--test-dir': 'testDir' }[value]] = argument;
         }
-        else if (value === '--template' && command === 'init') {
+        else if (value === '--template' && command === 'init') {
             const template = rest[++i];
             if (!TEMPLATES.includes(template)) throw new Error(`--template must be one of: ${TEMPLATES.join(', ')}.`);
-            result.template = template;
-        }
+            result.template = template;
+        }
+        else if (value === '--with' && command === 'init') {
+            const raw = rest[++i];
+            if (!raw || raw.startsWith('-')) throw new Error('--with requires a comma-separated capability list.');
+            const capabilities = raw.split(',');
+            if (capabilities.some(capability => !CAPABILITIES.includes(capability)) || new Set(capabilities).size !== capabilities.length) {
+                throw new Error(`--with must contain unique capabilities from: ${CAPABILITIES.join(', ')}.`);
+            }
+            result.with = capabilities;
+        }
         else if (value === '--port' && command === 'doctor') {
             const port = rest[++i];
             if (!/^\d+$/.test(port) || Number(port) > 65535) throw new Error('--port must be an integer from 0 through 65535.');
             result.port = Number(port);
         } else throw new Error(`Unknown option for ${command}: ${value}`);
     }
-    if (result.existing && result.template) throw new Error('--existing and --template cannot be combined.');
+    if (result.existing && (result.template || result.with || result.bare)) throw new Error('--existing cannot be combined with --template, --with, or --bare.');
     return result;
 }
 

package/src/cli/run.js

@@ -36,9 +36,18 @@ async function run(args, cwd, version) {
             return { exitCode: 0, stdout: `${output}\n`, stderr: '' };
         }
         const result = new ProjectInitializer(version).initialize(root, options);
-        const report = { schemaVersion: 1, operation: 'init', dryRun: options.dryRun, ...result };
-        const output = options.json ? JSON.stringify(report) : [
-            `${options.dryRun ? 'Planned initialization' : 'Initialization complete'} in ${result.root}`,
+        const report = {
+            schemaVersion: 1,
+            operation: 'init',
+            dryRun: options.dryRun,
+            foundation: options.template ?? 'default',
+            capabilities: options.with ?? [],
+            tests: !options.bare,
+            ...result,
+        };
+        const output = options.json ? JSON.stringify(report) : [
+            `${options.dryRun ? 'Planned initialization' : 'Initialization complete'} in ${result.root}`,
+            `Foundation: ${options.template ? `example template "${options.template}"` : 'neutral default'}; capabilities: ${options.with?.join(', ') || 'base'}; tests: ${options.bare ? 'omitted' : 'included'}.`,
             `Created: ${result.created.join(', ')}`,
             `Kept existing: ${result.skipped.join(', ')}`,
             `Planned: ${result.planned.join(', ')}`,

package/src/cli/templates.js

@@ -3,11 +3,18 @@
 const fs = require('fs');
 const path = require('path');
 
-const json = value => `${JSON.stringify(value, null, 2)}\n`;
-const TEMPLATES = Object.freeze(['realtime', 'chat', 'site', 'socket', 'dashboard', 'http-ws']);
-
-function projectFiles(version, template = 'realtime', root = path.resolve(__dirname, '../..')) {
-    if (!TEMPLATES.includes(template)) throw new Error('Unknown starter template.');
+const json = value => `${JSON.stringify(value, null, 2)}\n`;
+const TEMPLATES = Object.freeze(['realtime', 'chat', 'site', 'socket', 'dashboard', 'http-ws']);
+const CAPABILITIES = Object.freeze(['auth', 'multiplayer']);
+
+function projectFiles(version, template = null, root = path.resolve(__dirname, '../..'), options = {}) {
+    if (template !== null && !TEMPLATES.includes(template)) throw new Error('Unknown starter template.');
+    if (options.with !== undefined && !Array.isArray(options.with)) throw new TypeError('Initializer capabilities must be an array.');
+    const capabilities = new Set(options.with || []);
+    if ([...capabilities].some(capability => !CAPABILITIES.includes(capability))) throw new Error('Unknown initializer capability.');
+    const selected = template ?? 'foundation';
+    const authenticated = template === 'dashboard' || capabilities.has('auth');
+    const multiplayer = capabilities.has('multiplayer');
     const { devDependencies, dependencies, overrides } = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
     const read = relative => fs.readFileSync(path.join(root, 'recipes', relative), 'utf8');
     const manifest = {
@@ -16,18 +23,22 @@ function projectFiles(version, template = 'realtime', root = path.resolve(__dirn
             build: 'tsc && node scripts/copy-assets.cjs',
             start: 'node dist/app.js',
             dev: 'nodemon',
-            test: 'npm run build && node --test test/app.test.cjs test/lifecycle.test.cjs',
-            'test:coverage': 'npm run build && c8 --all --src=dist --include=dist/** --reporter=text --reporter=json node --test test/app.test.cjs test/lifecycle.test.cjs',
+            ...(!options.bare ? {
+                test: 'npm run build && node --test test/app.test.cjs test/lifecycle.test.cjs',
+                'test:coverage': 'npm run build && c8 --all --src=dist --include=dist/** --reporter=text --reporter=json node --test test/app.test.cjs test/lifecycle.test.cjs',
+            } : {}),
         },
         dependencies: {
             redweb: `^${version}`,
-            ...(['chat', 'socket', 'dashboard'].includes(template) ? { zod: devDependencies.zod } : {}),
-            ...(template === 'dashboard' ? { express: dependencies.express } : {}),
+            ...(['chat', 'socket', 'dashboard'].includes(template) || authenticated || multiplayer ? { zod: devDependencies.zod } : {}),
+            ...(authenticated ? { express: dependencies.express } : {}),
+            ...(multiplayer ? { 'redweb-client': dependencies['redweb-client'] } : {}),
         },
         overrides,
         devDependencies: {
-            typescript: devDependencies.typescript, nodemon: devDependencies.nodemon, ws: dependencies.ws, c8: devDependencies.c8,
-            ...(template === 'dashboard' ? {
+            typescript: devDependencies.typescript, nodemon: devDependencies.nodemon, ws: dependencies.ws,
+            ...(!options.bare ? { c8: devDependencies.c8 } : {}),
+            ...(authenticated ? {
                 '@types/node': devDependencies['redweb-dashboard-types'].replace('npm:@types/node@', ''),
                 '@types/express': dependencies['@types/express'],
             } : {}),
@@ -40,10 +51,10 @@ function projectFiles(version, template = 'realtime', root = path.resolve(__dirn
             delay: 200,
         },
     };
-    if (template === 'dashboard') {
-        manifest.engines = { node: '>=22.13.0' };
-        manifest.scripts['add-user'] = 'npm run build && node dist/admin.js';
-        manifest.scripts['test:coverage'] += ' test/rate-window.test.cjs';
+    if (authenticated) manifest.engines = { node: '>=22.13.0' };
+    if (template === 'dashboard') {
+        manifest.scripts['add-user'] = 'npm run build && node dist/admin.js';
+        if (!options.bare) manifest.scripts['test:coverage'] += ' test/rate-window.test.cjs';
     }
     const files = [
         { path: 'package.json', content: json(manifest) },
@@ -52,13 +63,15 @@ function projectFiles(version, template = 'realtime', root = path.resolve(__dirn
             compilerOptions: { rootDir: 'src', outDir: 'dist', sourceMap: true },
             include: ['src/**/*.ts', 'src/**/*.tsx'],
         }) },
-        { path: 'src/app.tsx', content: read(`${template}/app.tsx`) },
-        { path: 'src/app.css', content: read(`${template === 'dashboard' ? template : 'shared'}/app.css`) },
-        { path: 'scripts/copy-assets.cjs', content: read('shared/copy-assets.cjs') },
-        { path: 'test/network.cjs', content: read('shared/network.cjs') },
-        { path: 'test/app.test.cjs', content: read(`${template}/app.test.cjs`) },
-        { path: 'test/lifecycle.test.cjs', content: read('shared/lifecycle.test.cjs') },
-        { path: 'README.md', content: `${read('shared/README.md')}\n${read(`${template}/README.md`)}` },
+        { path: 'src/app.tsx', content: read(`${selected}/app.tsx`) },
+        { path: 'src/app.css', content: read(`${selected === 'dashboard' ? selected : 'shared'}/app.css`) },
+        { path: 'scripts/copy-assets.cjs', content: read('shared/copy-assets.cjs') },
+        ...(!options.bare ? [
+            { path: 'test/network.cjs', content: read('shared/network.cjs') },
+            { path: 'test/app.test.cjs', content: read(`${selected}/app.test.cjs`) },
+            { path: 'test/lifecycle.test.cjs', content: read('shared/lifecycle.test.cjs') },
+        ] : []),
+        { path: 'README.md', content: `${read('shared/README.md')}\n${read(`${selected}/README.md`)}` },
         { path: '.gitignore', content: 'node_modules/\ndist/\ncoverage/\n.env\ndata/\n*.sqlite\n*.sqlite-wal\n*.sqlite-shm\n' },
     ];
     if (template === 'chat') {
@@ -75,7 +88,7 @@ function projectFiles(version, template = 'realtime', root = path.resolve(__dirn
     }
     if (template === 'dashboard') {
         files.push({ path: '.npmrc', content: 'engine-strict=true\n' });
-        files.push({ path: 'test/rate-window.test.cjs', content: read('dashboard/rate-window.test.cjs') });
+        if (!options.bare) files.push({ path: 'test/rate-window.test.cjs', content: read('dashboard/rate-window.test.cjs') });
         for (const name of ['store.ts', 'auth.ts', 'cards.tsx', 'admin.ts']) {
             files.push({ path: `src/${name}`, content: read(`dashboard/${name}`) });
         }
@@ -83,4 +96,4 @@ function projectFiles(version, template = 'realtime', root = path.resolve(__dirn
     return Object.freeze(files.map(Object.freeze));
 }
 
-module.exports = { projectFiles, TEMPLATES };
+module.exports = { projectFiles, CAPABILITIES, TEMPLATES };

package/src/docs/Documentation.js

@@ -77,8 +77,8 @@ class Documentation {
             : `> Documentation for Redweb ${this.channel}. Install that exact version when following these examples.`;
     }
 
-    setup(template) {
-        if (!TEMPLATES.includes(template)) throw new Error('Unknown starter template.');
+    setup(template) {
+        if (!TEMPLATES.includes(template)) throw new Error('Unknown starter template.');
         const acceptance = `${template === 'dashboard' ? 'npm run add-user -- alice\n' : ''}npm test\nnpm run dev`;
         return this.channel === 'unreleased'
             ? [
@@ -86,8 +86,18 @@ class Documentation {
                 fence(`npx --yes --package TARBALL redweb init my-${template} --template ${template}\ncd my-${template}\nnpm install --save-exact TARBALL\n${acceptance}`, 'sh'),
                 'This prerelease Redweb artifact is development-only until its release checks finish. For released applications, use an available versioned release guide.',
             ].join('\n\n')
-            : fence(`npx --yes redweb@${this.channel} init my-${template} --template ${template}\ncd my-${template}\nnpm install --save-exact redweb@${this.channel}\n${acceptance}`, 'sh');
-    }
+            : fence(`npx --yes redweb@${this.channel} init my-${template} --template ${template}\ncd my-${template}\nnpm install --save-exact redweb@${this.channel}\n${acceptance}`, 'sh');
+    }
+
+    foundationSetup() {
+        return this.channel === 'unreleased'
+            ? [
+                'Replace `TARBALL` with the absolute path to the matching Redweb tarball produced by `npm pack` (quoted if it contains spaces):',
+                fence('npx --yes --package TARBALL redweb init my-app\ncd my-app\nnpm install --save-exact TARBALL\nnpm test\nnpm run dev', 'sh'),
+                'This prerelease Redweb artifact is development-only until its release checks finish.',
+            ].join('\n\n')
+            : fence(`npx --yes redweb@${this.channel} init my-app\ncd my-app\nnpm install --save-exact redweb@${this.channel}\nnpm test\nnpm run dev`, 'sh');
+    }
 
     recipe(template) {
         const files = projectFiles(this.manifest.version, template, this.root).map(file => ({ ...file, content: normalize(file.content) }));