redweb 0.12.0 → 0.13.0

package/src/async/BoundedOperation.js

@@ -0,0 +1,62 @@
+'use strict';
+
+class OperationInterrupted extends Error {
+    constructor(reason) {
+        super('Operation did not complete within its lifetime.');
+        this.reason = reason;
+    }
+}
+
+/** Shared, browser-safe lifetime boundary; it cannot preempt synchronous JS. */
+class BoundedOperation {
+    constructor(timeoutMs = 5000) {
+        if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647) throw new TypeError('Timeout must be an integer between 1 and 2147483647.');
+        this.timeoutMs = timeoutMs;
+        Object.freeze(this);
+    }
+
+    async run(operation, signal) {
+        if (signal?.aborted) throw new OperationInterrupted('cancelled');
+        let timer, abort, interruption;
+        const controller = new AbortController();
+        const started = performance.now();
+        const checkpoint = () => {
+            if (interruption) throw interruption;
+            if (signal?.aborted) throw (interruption = new OperationInterrupted('cancelled'));
+            if (performance.now() - started >= this.timeoutMs) throw (interruption = new OperationInterrupted('timeout'));
+        };
+        try {
+            const interrupted = new Promise((_, reject) => {
+                const interrupt = reason => {
+                    // Timer delivery is itself terminal, even if clock sampling
+                    // has not yet reached the nominal deadline. Latch before
+                    // abort listeners can reenter a checkpoint.
+                    interruption ||= new OperationInterrupted(reason);
+                    reject(interruption);
+                    controller.abort();
+                };
+                timer = setTimeout(() => interrupt('timeout'), this.timeoutMs);
+                abort = () => interrupt('cancelled');
+                signal?.addEventListener('abort', abort, { once: true });
+            });
+            const work = Promise.resolve().then(async () => {
+                checkpoint();
+                const value = await operation(controller.signal, checkpoint);
+                checkpoint();
+                return value;
+            });
+            return await Promise.race([work, interrupted]);
+        } catch (error) {
+            if (error instanceof OperationInterrupted) {
+                interruption ||= error;
+                controller.abort();
+            }
+            throw error;
+        } finally {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', abort);
+        }
+    }
+}
+
+module.exports = { BoundedOperation, OperationInterrupted };

package/src/cli/ActionReferences.js

@@ -0,0 +1,193 @@
+'use strict';
+
+const { UNKNOWN } = require('./StaticSource');
+const TemplateRenderer = require('../htmx/TemplateRenderer');
+
+const ACTIONS = new Set(['rw-click', 'rw-submit']);
+const DIRECTIVES = new Set([...ACTIONS, 'data-rw-component']);
+
+/** Static names only. Application constructors, decorators and render functions never run. */
+class ActionReferences {
+    constructor(inspector) {
+        this.inspector = inspector;
+        this.ts = inspector.ts;
+        this.read = inspector.syntax;
+        this.descriptions = new Map();
+    }
+
+    unknown(node, reason) {
+        this.inspector.finding('ACTION_REFERENCE_UNRESOLVED', node, reason,
+            'Use a literal action name on an intrinsic HTML element, or verify this dynamic binding with a real browser test. Doctor does not execute render code.', 'warning');
+    }
+
+    decorators(node) {
+        return (this.ts.getDecorators(node) || []).map(decorator => {
+            const expression = decorator.expression;
+            return this.ts.isCallExpression(expression) ? this.read.api(expression.expression) : null;
+        });
+    }
+
+    describe(node, seen = new Set()) {
+        if (this.descriptions.has(node)) return this.descriptions.get(node);
+        if (node === UNKNOWN || seen.has(node) || seen.size >= 64 || !this.read.spend() || !this.ts.isClassDeclaration(node)) return { names: new Set(), members: new Map(), uncertain: true };
+        seen.add(node);
+        const ts = this.ts;
+        const base = this.read.base(node);
+        const inherited = base === UNKNOWN || this.read.api(base) === 'LivePage'
+            ? { names: new Set(), members: new Map(), uncertain: false } : this.describe(this.read.resolve(base), seen);
+        const names = new Set(inherited.names);
+        const members = new Map(inherited.members);
+        let uncertain = inherited.uncertain || this.read.resolve(node) === UNKNOWN || this.decorators(node).some(name => !['page', 'site.page', 'component'].includes(name));
+        for (const member of node.members) {
+            if (ts.isClassStaticBlockDeclaration(member)) uncertain = true;
+            if (ts.isConstructorDeclaration(member)) {
+                for (const parameter of member.parameters) if (parameter.modifiers?.length) {
+                    const name = parameter.name.getText();
+                    names.delete(name);
+                    members.set(name, parameter);
+                    uncertain = true;
+                }
+            }
+            if (!member.name) continue;
+            const name = ts.isComputedPropertyName(member.name) ? this.read.text(member.name.expression) : member.name.text;
+            if (name === UNKNOWN) { uncertain = true; continue; }
+            if (member.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.StaticKeyword)) continue;
+            members.set(name, member);
+            names.delete(name);
+            const decorators = this.decorators(member);
+            if (decorators.some(api => !['action', 'state', 'view'].includes(api))) uncertain = true;
+            if (ts.isMethodDeclaration(member) && decorators.length === 1 && decorators[0] === 'action' && !ts.isPrivateIdentifier(member.name)) names.add(name);
+        }
+        // Assignments or escaping `this` can replace decorator-exposed methods after construction.
+        const pending = [...node.members];
+        while (pending.length && this.read.spend()) {
+            const current = pending.pop();
+            if (ts.isClassDeclaration(current) || ts.isClassExpression(current)) continue;
+            if (current.kind === ts.SyntaxKind.ThisKeyword && !((ts.isPropertyAccessExpression(current.parent) || ts.isElementAccessExpression(current.parent)) && current.parent.expression === current)) uncertain = true;
+            if (ts.isBinaryExpression(current) && current.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && current.operatorToken.kind <= ts.SyntaxKind.LastAssignment) {
+                const left = current.left;
+                if (ts.isObjectLiteralExpression(left) || ts.isArrayLiteralExpression(left)) uncertain = true;
+                if (ts.isElementAccessExpression(left) && left.expression.kind === ts.SyntaxKind.ThisKeyword) uncertain = true;
+                if (ts.isPropertyAccessExpression(left) && left.expression.kind === ts.SyntaxKind.ThisKeyword && names.has(left.name.text)) uncertain = true;
+            }
+            if (ts.isDeleteExpression(current) || ts.isPrefixUnaryExpression(current) || ts.isPostfixUnaryExpression(current)) {
+                const target = current.expression || current.operand;
+                if ((ts.isPropertyAccessExpression(target) || ts.isElementAccessExpression(target)) && target.expression.kind === ts.SyntaxKind.ThisKeyword && (ts.isElementAccessExpression(target) || names.has(target.name.text))) uncertain = true;
+            }
+            ts.forEachChild(current, child => { pending.push(child); });
+        }
+        const result = { names, members, uncertain };
+        this.descriptions.set(node, result);
+        return result;
+    }
+
+    check(owner, name, node, ambiguous) {
+        const description = this.describe(owner);
+        if (name === UNKNOWN || ambiguous || description.uncertain || (typeof name === 'string' && name.includes('&'))) {
+            this.unknown(node, 'The action name or its owning class cannot be established statically.');
+        } else if (typeof name !== 'string' || !name || name.length > 128 || ['__proto__', 'prototype', 'constructor'].includes(name)) {
+            this.inspector.finding('ACTION_REFERENCE_INVALID', node, 'Action names must be non-empty strings of at most 128 characters and cannot use reserved member names.', 'Use the exact name of a public @action() method.');
+        } else if (!description.names.has(name)) {
+            this.inspector.finding('ACTION_NOT_EXPOSED', node, `No public @action() method named "${name}" is exposed by this class.`, 'Correct the binding name or explicitly decorate the intended instance method with @action().');
+        }
+    }
+
+    jsx(owner, element) {
+        const ts = this.ts;
+        const attributes = element.attributes.properties;
+        let ambiguous = !ts.isIdentifier(element.tagName) || !/^[a-z]/.test(element.tagName.text);
+        for (let parent = element; parent && parent !== owner; parent = parent.parent) {
+            const opening = ts.isJsxElement(parent) ? parent.openingElement : (ts.isJsxOpeningElement(parent) || ts.isJsxSelfClosingElement(parent)) ? parent : null;
+            if (opening && (!ts.isIdentifier(opening.tagName) || !/^[a-z]/.test(opening.tagName.text) || opening.attributes.properties.some(attribute => ts.isJsxSpreadAttribute(attribute) || attribute.name.getText().toLowerCase() === 'data-rw-component'))) ambiguous = true;
+        }
+        for (const attribute of attributes) {
+            if (ts.isJsxSpreadAttribute(attribute)) {
+                this.unknown(attribute, 'Spread JSX attributes may introduce or replace an action binding or component scope.');
+                continue;
+            }
+            const key = attribute.name.getText().toLowerCase();
+            if (!ACTIONS.has(key)) continue;
+            const value = attribute.initializer;
+            const name = !value ? null : this.read.text(ts.isJsxExpression(value) ? value.expression : value);
+            this.check(owner, name, attribute, ambiguous);
+        }
+    }
+
+    markup(owner, markup, node, filename) {
+        if (markup.length > 1024 * 1024) { this.unknown(node, 'HTML action inspection exceeds the 1 MiB per-template limit.'); return; }
+        const source = filename ? this.ts.createSourceFile(filename, markup, this.ts.ScriptTarget.Latest, true) : null;
+        const bindings = [];
+        let scoped = false;
+        try {
+            TemplateRenderer.mapTags(markup, (tag, nameEnd, position) => {
+                const fields = TemplateRenderer.attributes(tag, nameEnd, DIRECTIVES);
+                if (fields.has('data-rw-component')) scoped = true;
+                for (const [key, name] of fields) if (ACTIONS.has(key)) bindings.push({ name, position });
+                return tag;
+            });
+        } catch {
+            this.unknown(node, 'Malformed or interpolated HTML attributes prevent reliable action inspection.');
+            return;
+        }
+        for (const { name, position } of bindings) {
+            const location = source ? { getSourceFile: () => source, getStart: () => position } : node;
+            this.check(owner, name, location, scoped);
+        }
+    }
+
+    inspect(owner) {
+        if (!this.decorators(owner).some(name => ['page', 'site.page', 'component'].includes(name))) return;
+        const ts = this.ts;
+        const description = this.describe(owner);
+        const pending = [...description.members.values()];
+        const visited = new Set();
+        if (description.uncertain && !description.members.has('render') && this.read.base(owner) !== UNKNOWN) {
+            this.unknown(owner, 'Inherited render code is not statically available.');
+        }
+        const renderer = description.members.get('render');
+        let renderFunction = renderer;
+        if (renderer && !ts.isMethodDeclaration(renderer)) {
+            const initializer = this.read.resolve(renderer.initializer);
+            if (initializer === UNKNOWN || !(ts.isArrowFunction(initializer) || ts.isFunctionExpression(initializer))) {
+                this.unknown(renderer, 'The render implementation is not a statically available method or function.');
+                visited.add(renderer);
+            }
+            else {
+                renderFunction = initializer;
+                pending.push(initializer);
+                if (!ts.isBlock(initializer.body)) this.output(owner, initializer.body, pending);
+            }
+        }
+        while (pending.length && this.read.spend()) {
+            const node = pending.pop();
+            if (visited.has(node)) continue;
+            visited.add(node);
+            if (ts.isClassDeclaration(node) || ts.isClassExpression(node)) continue;
+            if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) this.jsx(owner, node);
+            if (ts.isTaggedTemplateExpression(node) && this.read.api(node.tag) === 'html') {
+                if (ts.isNoSubstitutionTemplateLiteral(node.template)) this.markup(owner, node.template.text, node);
+                else this.unknown(node, 'Interpolated HTML can introduce markup or change action ownership.');
+            }
+            if (ts.isReturnStatement(node) && node.expression) {
+                let method = node.parent;
+                while (method && !ts.isFunctionLike(method)) method = method.parent;
+                if (method === renderFunction) this.output(owner, node.expression, pending);
+            }
+            ts.forEachChild(node, child => { pending.push(child); });
+        }
+    }
+
+    output(owner, expression, pending) {
+        const ts = this.ts;
+        const node = this.read.resolve(expression);
+        if (node !== UNKNOWN) {
+            if (ts.isStringLiteralLike(node)) { this.markup(owner, node.text, expression); return; }
+            if (ts.isJsxElement(node) || ts.isJsxFragment(node) || ts.isJsxSelfClosingElement(node) || (ts.isTaggedTemplateExpression(node) && this.read.api(node.tag) === 'html')) { pending.push(node); return; }
+            if (ts.isConditionalExpression(node)) { this.output(owner, node.whenTrue, pending); this.output(owner, node.whenFalse, pending); return; }
+            if ([ts.SyntaxKind.NullKeyword, ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword, ts.SyntaxKind.NumericLiteral].includes(node.kind)) return;
+        }
+        this.unknown(expression, 'Dynamic render output may introduce action bindings or change their ownership.');
+    }
+}
+
+module.exports = ActionReferences;

package/src/cli/AdditionLayout.js

@@ -0,0 +1,140 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { resolveDependency, readConfig } = require('./ProjectConfig');
+const { assertSafePath } = require('./FilePlan');
+
+/** Read TypeScript's effective layout without evaluating application modules. */
+class AdditionLayout {
+    constructor(root, { configFile = 'tsconfig.json', sourceDir } = {}) {
+        this.root = root;
+        this.configFile = configFile;
+        assertSafePath(path.resolve(root, configFile), root);
+        const compiler = resolveDependency(root, 'typescript');
+        if (!compiler) throw new Error('TypeScript is missing. Run npm install --save-dev typescript.');
+        this.ts = require(compiler);
+        if (Number(this.ts.version.split('.')[0]) < 5) throw new Error('Add requires TypeScript 5 or newer.');
+        this.config = this.read();
+        const options = this.config.options;
+        if (this.config.projectReferences?.length || options.outFile || options.noEmit || options.emitDeclarationOnly) {
+            throw new Error('Select a single emitting TypeScript project with --config; project references, outFile and disabled JavaScript emission are unsupported.');
+        }
+        const { ModuleKind, ModuleResolutionKind } = this.ts;
+        if (![ModuleKind.CommonJS, ModuleKind.Node16, ModuleKind.NodeNext].includes(options.module) ||
+            options.moduleResolution === ModuleResolutionKind.Bundler) {
+            throw new Error('Add requires Node-compatible TypeScript emission (CommonJS, Node16 or NodeNext), not a custom bundler.');
+        }
+        if (!options.rootDir && !sourceDir) throw new Error('Source layout is ambiguous. Set rootDir or pass --source-dir relative to the project.');
+        this.sourceDir = path.resolve(root, sourceDir || options.rootDir);
+        assertSafePath(path.join(this.sourceDir, '__redweb_source_check.ts'), root);
+    }
+
+    read(host = this.ts.sys) {
+        const { config, syntaxError } = readConfig(this.ts, this.root, this.configFile, host);
+        const errors = syntaxError ? [syntaxError] : config.errors.filter(error => error.code !== 18003);
+        if (errors.length) throw new Error(errors.map(error => this.ts.flattenDiagnosticMessageText(error.messageText, '\n')).join('\n'));
+        return config;
+    }
+
+    prospective(filename) {
+        const { ts, root } = this;
+        // TypeScript owns include/exclude glob semantics. Its runtime matcher is
+        // version-checked rather than approximated with a second glob language.
+        const matchFiles = requireMatcher(ts.matchFiles);
+        const absolute = path.resolve(root, filename).replaceAll('\\', '/');
+        const virtualDirectories = new Map();
+        for (let current = absolute; path.dirname(current) !== current; current = path.dirname(current)) {
+            virtualDirectories.set(path.dirname(current), current);
+        }
+        const host = {
+            ...ts.sys,
+            readDirectory: (directory, extensions, excludes, includes, depth) => [...new Set([
+                ...ts.sys.readDirectory(directory, extensions, excludes, includes, depth),
+                ...matchFiles(directory, extensions, excludes, includes, ts.sys.useCaseSensitiveFileNames, root, depth,
+                    entry => {
+                        const added = virtualDirectories.get(path.resolve(entry).replaceAll('\\', '/'));
+                        return { files: added === absolute ? [path.basename(added)] : [],
+                            directories: added && added !== absolute ? [path.basename(added)] : [] };
+                    }, ts.sys.realpath),
+            ])],
+        };
+        const config = this.read(host);
+        return { config, absolute, virtualDirectories };
+    }
+
+    includes(filename) {
+        const { config, absolute } = this.prospective(filename);
+        return config.fileNames.some(value => path.resolve(value) === path.resolve(absolute));
+    }
+
+    outputFor(filename, content) {
+        const { ts, root } = this;
+        const { config, absolute, virtualDirectories } = this.prospective(filename);
+        if (!config.fileNames.some(value => path.resolve(value) === path.resolve(absolute))) {
+            throw new Error(`${filename} is excluded from ${this.configFile}. Adjust the configuration yourself or choose --source-dir.`);
+        }
+        // Compiler options and syntactic diagnostics require no application execution.
+        const compilerHost = ts.createCompilerHost(config.options);
+        const readSource = compilerHost.readFile;
+        const fileExists = compilerHost.fileExists;
+        const directoryExists = compilerHost.directoryExists;
+        compilerHost.getCurrentDirectory = () => root;
+        compilerHost.readFile = name => path.resolve(name) === path.resolve(absolute) ? content : readSource(name);
+        compilerHost.fileExists = name => path.resolve(name) === path.resolve(absolute) || fileExists(name);
+        compilerHost.directoryExists = name => virtualDirectories.has(path.resolve(name).replaceAll('\\', '/')) || directoryExists(name);
+        const program = ts.createProgram(config.fileNames, config.options, compilerHost);
+        const sourceFile = program.getSourceFile(absolute);
+        const errors = [...program.getOptionsDiagnostics(), ...program.getSyntacticDiagnostics(sourceFile), ...program.getSemanticDiagnostics(sourceFile)];
+        if (errors.length) throw new Error(errors.map(error => ts.flattenDiagnosticMessageText(error.messageText, '\n')).join('\n'));
+        const emitted = emissionMap(ts, program);
+        const output = emitted.get(absolute);
+        if (!output) throw new Error('Expected one Node JavaScript output for the new source file.');
+        assertSafePath(path.resolve(output), root);
+        if (!config.options.rootDir) {
+            const previousHost = ts.createCompilerHost(this.config.options);
+            previousHost.getCurrentDirectory = () => root;
+            const previous = ts.createProgram(this.config.fileNames, this.config.options, previousHost);
+            for (const [file, previousOutput] of emissionMap(ts, previous)) {
+                if (emitted.get(file) !== previousOutput) {
+                    throw new Error('Adding this source would relocate existing compiled files. Set an explicit rootDir before adding it.');
+                }
+            }
+        }
+        const emittedModule = [ts.ModuleKind.Node16, ts.ModuleKind.NodeNext].includes(config.options.module)
+            ? sourceFile.impliedNodeFormat === ts.ModuleKind.ESNext : false;
+        if (packageIsModule(path.dirname(output)) !== emittedModule) {
+            throw new Error('Source and output module formats disagree with package.json type. Fix the layout; add does not copy or rewrite package manifests.');
+        }
+        return path.relative(root, output).replaceAll('\\', '/');
+    }
+}
+
+function emissionMap(ts, program) {
+    const outputs = new Map();
+    const result = program.emit(undefined, (filename, _text, _bom, _error, sources) => {
+        if (!/\.[cm]?js$/.test(filename)) return;
+        for (const source of sources) {
+            const name = path.resolve(source.fileName).replaceAll('\\', '/');
+            outputs.set(name, filename);
+        }
+    });
+    if (result.diagnostics.length) throw new Error(result.diagnostics.map(error => ts.flattenDiagnosticMessageText(error.messageText, '\n')).join('\n'));
+    return outputs;
+}
+
+function requireMatcher(matcher) {
+    if (typeof matcher !== 'function') throw new Error('This TypeScript compiler lacks the file matcher needed for a safe preview.');
+    return matcher;
+}
+
+function packageIsModule(directory) {
+    for (let current = directory; ; current = path.dirname(current)) {
+        const manifest = path.join(current, 'package.json');
+        if (fs.existsSync(manifest)) return JSON.parse(fs.readFileSync(manifest, 'utf8')).type === 'module';
+        if (path.dirname(current) === current) return false;
+    }
+}
+
+module.exports = AdditionLayout;
+module.exports.requireMatcher = requireMatcher;

package/src/cli/FilePlan.js

@@ -0,0 +1,94 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/** Shared, exclusive-create writer. A plan is preflighted fully, never silently overwritten. */
+class FilePlan {
+    constructor(root, files) {
+        this.root = path.resolve(root);
+        this.files = files;
+    }
+
+    write({ dryRun = false, existing = 'skip' } = {}) {
+        if (!['skip', 'reject'].includes(existing)) throw new Error('Unknown existing-file policy.');
+        const created = [], skipped = [], planned = [], destinations = new Map();
+        for (const file of this.files) {
+            const destination = path.resolve(this.root, file.path);
+            assertSafePath(destination, this.root);
+            registerDestination(destinations, this.root, destination);
+            const entry = fs.lstatSync(destination, { throwIfNoEntry: false });
+            if (entry) {
+                if (!entry.isFile()) throw new Error(`Expected a file at ${destination}; nothing was written.`);
+                if (existing === 'reject') throw new Error(`Refusing to overwrite ${destination}; nothing was written.`);
+                skipped.push(file.path);
+            } else planned.push(file);
+        }
+        if (!dryRun) {
+            let attempted;
+            try {
+                for (const file of planned) {
+                    attempted = file.path;
+                    const destination = path.resolve(this.root, file.path);
+                    assertSafePath(destination, this.root);
+                    fs.mkdirSync(path.dirname(destination), { recursive: true });
+                    fs.writeFileSync(destination, file.content, { encoding: 'utf8', flag: 'wx' });
+                    created.push(file.path);
+                }
+            } catch (error) {
+                throw new Error(`${error.message} Completed before failure: ${created.length ? created.join(', ') : 'none'}. Attempted: ${attempted}; that file or its directories may exist.`, { cause: error });
+            }
+        }
+        return Object.freeze({ root: this.root, created: Object.freeze(created), skipped: Object.freeze(skipped),
+            planned: Object.freeze(planned.map(file => file.path)) });
+    }
+}
+
+function registerDestination(nodes, root, destination) {
+    const parts = path.relative(root, destination).split(path.sep);
+    let current = root;
+    for (let index = 0; index < parts.length; index++) {
+        current = path.join(current, parts[index]);
+        const kind = index === parts.length - 1 ? 'file' : 'directory';
+        const key = current.toLowerCase(), previous = nodes.get(key);
+        if (previous && (previous.path !== current || previous.kind !== kind || kind === 'file')) {
+            throw new Error(`Conflicting planned destination: ${current}`);
+        }
+        nodes.set(key, { path: current, kind });
+    }
+}
+
+function assertSafePath(destination, root) {
+    const relative = path.relative(root, destination);
+    if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error(`Destination must be a file inside the project: ${destination}`);
+    }
+    for (const part of destination.slice(path.parse(destination).root.length).split(path.sep)) {
+        if (/[<>:"\\|?*\u0000-\u001f]/.test(part) || /[. ]$/.test(part) || part.length > 255 ||
+            /^(con|conin\$|conout\$|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part.normalize('NFKC'))) {
+            throw new Error(`Nonportable destination segment: ${part}`);
+        }
+    }
+    const ancestors = [];
+    for (let current = destination; ; current = path.dirname(current)) {
+        ancestors.push(current);
+        if (path.dirname(current) === current) break;
+    }
+    // Check parents before descendants: POSIX lstat throws ENOTDIR below a file,
+    // and no descendant should be inspected through an unchecked symbolic link.
+    for (const current of ancestors.reverse()) {
+        const entry = fs.lstatSync(current, { throwIfNoEntry: false });
+        if (entry?.isSymbolicLink()) throw new Error(`Refusing to initialize through a symbolic link: ${current}`);
+        if (current !== destination && entry && !entry.isDirectory()) throw new Error(`Expected a directory at ${current}; nothing was written.`);
+        const parent = path.dirname(current);
+        if (parent === current) continue;
+        // Portable plans must not create case aliases even on a case-sensitive host.
+        if ((current === root || current.startsWith(`${root}${path.sep}`)) && fs.lstatSync(parent, { throwIfNoEntry: false })?.isDirectory()) {
+            const name = path.basename(current);
+            const alias = fs.readdirSync(parent).find(value => value.toLowerCase() === name.toLowerCase() && value !== name);
+            if (alias) throw new Error(`Case-colliding destination: ${current} conflicts with ${alias}`);
+        }
+    }
+}
+
+module.exports = { FilePlan, assertSafePath };

package/src/cli/ProjectAddition.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const AdditionLayout = require('./AdditionLayout');
+const { FilePlan } = require('./FilePlan');
+const { resolveDependency } = require('./ProjectConfig');
+
+const KINDS = Object.freeze(['page', 'component', 'socket-route']);
+const relative = (root, file) => path.relative(root, file).replaceAll('\\', '/');
+const fill = (template, values) => template.replace(/__([A-Z]+)__/g, (_, key) => values[key]);
+
+class ProjectAddition {
+    add(target, { kind, name, dryRun = false, testDir = 'test', ...layoutOptions }) {
+        if (!KINDS.includes(kind)) throw new Error(`Addition kind must be ${KINDS.join(', ')}.`);
+        if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(name) || name.length > 64) {
+            throw new Error('Use a lowercase kebab-case name, starting with a letter (maximum 64 characters).');
+        }
+        const root = path.resolve(target);
+        const manifest = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+        for (const dependency of ['redweb', 'ws', ...(kind === 'socket-route' ? ['zod'] : [])]) {
+            const runtime = dependency !== 'ws';
+            if (!(manifest.dependencies?.[dependency] || (!runtime && manifest.devDependencies?.[dependency])) || !resolveDependency(root, dependency)) {
+                throw new Error(`${dependency} must be explicitly declared and installed. Run npm install ${runtime ? '' : '--save-dev '}${dependency}.`);
+            }
+        }
+        const layout = new AdditionLayout(root, layoutOptions);
+        if (kind !== 'socket-route' && (layout.config.options.jsxImportSource !== 'redweb' ||
+            ![layout.ts.JsxEmit.ReactJSX, layout.ts.JsxEmit.ReactJSXDev].includes(layout.config.options.jsx))) {
+            throw new Error('Use Redweb JSX settings: extend redweb/tsconfig.json.');
+        }
+        const className = name.split('-').map(part => part[0].toUpperCase() + part.slice(1)).join('') +
+            { page: 'Page', component: 'Component', 'socket-route': 'Route' }[kind];
+        const directory = { page: 'pages', component: 'components', 'socket-route': 'socket-routes' }[kind];
+        const source = relative(root, path.join(layout.sourceDir, directory, `${name}.${kind === 'socket-route' ? 'ts' : 'tsx'}`));
+        const read = file => fs.readFileSync(path.resolve(__dirname, '../../recipes/add', file), 'utf8');
+        const values = { NAME: name, CLASS: className, TITLE: name.split('-').join(' '), KIND: kind,
+            DECORATOR: kind, DECORATION: kind === 'page' ? `@page('/${name}')` : '@component()' };
+        const content = fill(read(kind === 'socket-route' ? 'socket-route.ts' : 'live.tsx'), values);
+        const testFile = relative(root, path.resolve(root, testDir, `${name}.${kind}.test.cjs`));
+        if (layout.includes(testFile)) throw new Error('The generated CJS test would enter TypeScript compilation. Choose --test-dir outside the configured inputs or explicitly exclude that test directory.');
+        const output = layout.outputFor(source, content);
+        const files = [
+            { path: source, content },
+            { path: testFile, content: fill(read('artifact.test.cjs'), { ...values,
+                IMPORT: JSON.stringify(relative(path.dirname(path.resolve(root, testFile)), path.resolve(root, output))) }) },
+        ];
+        const result = new FilePlan(root, files).write({ dryRun, existing: 'reject' });
+        return { ...result, kind, name, source, output, test: testFile,
+            registration: { status: 'pending', export: className,
+                importFromProjectRoot: `import { ${className} } from ${JSON.stringify('./' + source.replace(/\.tsx?$/, '.js'))};`,
+                instruction: kind === 'component' ? `Import ${className} from ${source}, create a page field such as widget = new ${className}(), and render {this.widget}.`
+                    : kind === 'page' ? `Import ${className} from ${source} and add it to your start([...]) page list.`
+                        : `Import ${className} from ${source} and add it to your SocketServer routes list.` },
+            verification: { build: ['npx', 'tsc', '-p', layout.configFile], test: ['node', '--test', testFile],
+                note: 'Run the build, then the test from the project root. Existing package scripts and registrations are unchanged.' } };
+    }
+}
+
+module.exports = { ProjectAddition, KINDS };

package/src/cli/ProjectConfig.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { createRequire } = require('module');
+
+function resolveDependency(root, name) {
+    const requireFromProject = createRequire(path.join(root, 'package.json'));
+    let current = root;
+    while (true) {
+        const candidate = path.join(current, 'node_modules', name);
+        if (fs.existsSync(candidate)) return requireFromProject.resolve(candidate);
+        const parent = path.dirname(current);
+        if (parent === current) return null;
+        current = parent;
+    }
+}
+
+function readConfig(ts, root, filename = 'tsconfig.json', host = ts.sys) {
+    const configPath = path.resolve(root, filename).replaceAll('\\', '/');
+    const read = ts.readConfigFile(configPath, host.readFile);
+    if (read.error) return { syntaxError: read.error };
+    return { config: ts.parseJsonConfigFileContent(read.config, host, path.dirname(configPath), undefined, configPath) };
+}
+
+module.exports = { resolveDependency, readConfig };