redweb 0.12.0 → 0.13.1

package/src/cli/ProjectDoctor.js

@@ -0,0 +1,112 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const net = require('net');
+const SourceInspector = require('./SourceInspector');
+const { resolveDependency, readConfig } = require('./ProjectConfig');
+
+function issue(code, file, message, suggestion, severity = 'error') {
+    return { code, severity, file, message, suggestion };
+}
+
+function nodeIssue(version) {
+    if (Number(version.split('.')[0]) >= 18) return null;
+    return issue('NODE_UNSUPPORTED', null, `Node ${version} is outside Redweb's supported range.`, 'Use a supported Node.js release (18 or newer).');
+}
+
+function projectNodeIssue(version, requirement) {
+    if (requirement === undefined) return null;
+    const minimum = typeof requirement === 'string' && /^>=\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(requirement);
+    if (!minimum) return issue('PROJECT_NODE_UNCHECKED', 'package.json', 'The project Node range could not be checked by doctor.', 'Check engines.node using npm install; doctor understands minimum-version ranges such as >=22.13.0.', 'warning');
+    const current = version.split('.').map(Number);
+    const required = minimum.slice(1).map(value => Number(value || 0));
+    const difference = required.findIndex((value, index) => value !== current[index]);
+    if (difference < 0 || current[difference] > required[difference]) return null;
+    return issue('PROJECT_NODE_UNSUPPORTED', 'package.json', `Node ${version} does not meet this project's ${requirement} requirement.`, `Install Node ${required.join('.')} or newer before running this application.`);
+}
+
+function inspectTypeScript(root, issues) {
+    // TypeScript's diagnostic attachment expects normalized separators on Windows.
+    const configPath = path.join(root, 'tsconfig.json').replaceAll('\\', '/');
+    const typescriptPath = resolveDependency(root, 'typescript');
+    if (!typescriptPath) issues.push(issue('TYPESCRIPT_MISSING', 'package.json', 'TypeScript is not installed for this project.', 'Run npm install --save-dev typescript.'));
+    if (!fs.existsSync(configPath)) {
+        issues.push(issue('CONFIG_MISSING', 'tsconfig.json', 'No editor-discoverable TypeScript configuration was found.', 'Run redweb init --existing, then inspect the generated configuration.'));
+        return;
+    }
+    if (!typescriptPath) return;
+    const ts = require(typescriptPath);
+    if (Number(ts.version.split('.')[0]) < 5) {
+        issues.push(issue('TYPESCRIPT_UNSUPPORTED', 'package.json', `TypeScript ${ts.version} is not supported by these diagnostics.`, 'Install TypeScript 5 or newer; Redweb standard decorators and contract types require it.'));
+        return;
+    }
+    const { config, syntaxError } = readConfig(ts, root);
+    if (syntaxError) {
+        issues.push(issue('CONFIG_INVALID', 'tsconfig.json', ts.flattenDiagnosticMessageText(syntaxError.messageText, '\n'), 'Correct the configuration syntax and run doctor again.'));
+        return;
+    }
+    if (config.errors.length) {
+        for (const error of config.errors) issues.push(issue('CONFIG_INVALID', 'tsconfig.json', ts.flattenDiagnosticMessageText(error.messageText, '\n'), 'Resolve the TypeScript configuration diagnostic, including missing extends targets or source files.'));
+        return;
+    }
+    if (config.options.jsxImportSource !== 'redweb' || ![ts.JsxEmit.ReactJSX, ts.JsxEmit.ReactJSXDev].includes(config.options.jsx)) {
+        issues.push(issue('JSX_RUNTIME_MISMATCH', 'tsconfig.json', 'The effective JSX configuration does not use Redweb.', 'Extend redweb/tsconfig.json, or set jsx to react-jsx and jsxImportSource to redweb.'));
+    }
+    if (config.options.experimentalDecorators) {
+        issues.push(issue('LEGACY_DECORATORS', 'tsconfig.json', 'Legacy decorators are enabled; the starter examples use standard decorators.', 'Set experimentalDecorators to false for standard decorator examples.', 'warning'));
+    }
+    return new SourceInspector(ts, root, config).inspect();
+}
+
+function inspectPort(port) {
+    return new Promise(resolve => {
+        const server = net.createServer();
+        server.once('error', error => resolve(issue('PORT_UNAVAILABLE', null, `Cannot bind 127.0.0.1:${port} (${error.code}).`, 'Choose another port or stop the process that owns it.')));
+        server.listen(port, '127.0.0.1', () => server.close(() => resolve(null)));
+    });
+}
+
+class ProjectDoctor {
+    constructor(cliVersion) {
+        this.cliVersion = cliVersion;
+    }
+
+    async inspect(target, port = null) {
+        const root = path.resolve(target);
+        const issues = [nodeIssue(process.versions.node)].filter(Boolean);
+        const projectManifest = path.join(root, 'package.json');
+        if (fs.existsSync(projectManifest)) {
+            const finding = projectNodeIssue(process.versions.node, JSON.parse(fs.readFileSync(projectManifest, 'utf8')).engines?.node);
+            if (finding) issues.push(finding);
+        }
+        const manifestPath = resolveDependency(root, 'redweb/package.json');
+        let installedVersion = null;
+        if (!manifestPath) {
+            issues.push(issue('REDWEB_MISSING', 'package.json', 'Redweb is not installed for this project.', 'Run npm install redweb.'));
+        } else {
+            installedVersion = JSON.parse(fs.readFileSync(manifestPath, 'utf8')).version;
+            if (installedVersion !== this.cliVersion) {
+                issues.push(issue('CLI_VERSION_MISMATCH', 'package.json', `CLI ${this.cliVersion} is inspecting Redweb ${installedVersion}.`, 'Use the locally installed CLI with npx --no-install redweb doctor.', 'warning'));
+            }
+        }
+        const inspected = inspectTypeScript(root, issues);
+        if (inspected) issues.push(...inspected.issues);
+        if (port !== null) {
+            const unavailable = await inspectPort(port);
+            if (unavailable) issues.push(unavailable);
+        }
+        return {
+            schemaVersion: 1,
+            operation: 'doctor',
+            root,
+            installedVersion,
+            checks: ['node', 'redweb-version', 'typescript-config', ...(inspected ? ['source-assets', 'source-routes', 'source-handlers', 'source-actions'] : []), ...(port === null ? [] : ['loopback-port'])],
+            source: inspected?.source || null,
+            ok: !issues.some(value => value.severity === 'error'),
+            issues,
+        };
+    }
+}
+
+module.exports = { ProjectDoctor, nodeIssue, projectNodeIssue };

package/src/cli/ProjectInitializer.js

@@ -1,30 +1,20 @@
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const { projectFiles } = require('./templates');
-
-class ProjectInitializer {
-    constructor(version) {
-        this.files = projectFiles(version);
-    }
-
-    initialize(target) {
-        const root = path.resolve(target);
-        const created = [];
-        const skipped = [];
-        for (const file of this.files) {
-            const destination = path.join(root, file.path);
-            fs.mkdirSync(path.dirname(destination), { recursive: true });
-            if (fs.existsSync(destination)) {
-                skipped.push(file.path);
-                continue;
-            }
-            fs.writeFileSync(destination, file.content, { encoding: 'utf8', flag: 'wx' });
-            created.push(file.path);
-        }
-        return Object.freeze({ root, created: Object.freeze(created), skipped: Object.freeze(skipped) });
-    }
-}
-
-module.exports = ProjectInitializer;
+'use strict';
+
+const path = require('path');
+const { projectFiles } = require('./templates');
+const { FilePlan } = require('./FilePlan');
+
+class ProjectInitializer {
+    constructor(version) {
+        this.version = version;
+    }
+
+    initialize(target, options = {}) {
+        const root = path.resolve(target);
+        const templateFiles = projectFiles(this.version, options.template);
+        const files = options.existing ? templateFiles.filter(file => file.path === 'tsconfig.json') : templateFiles;
+        return new FilePlan(root, files).write({ dryRun: options.dryRun });
+    }
+}
+
+module.exports = ProjectInitializer;

package/src/cli/SourceInspector.js

@@ -0,0 +1,207 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { StaticSource, UNKNOWN } = require('./StaticSource');
+const ActionReferences = require('./ActionReferences');
+
+const MAX_FILES = 256;
+const MAX_BYTES = 8 * 1024 * 1024;
+
+function outside(root, file) {
+    const relative = path.relative(root, file);
+    return relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
+}
+
+class SourceInspector {
+    constructor(ts, root, config) {
+        this.ts = ts;
+        this.root = root;
+        this.config = config;
+        this.issues = [];
+        this.reported = new Set();
+        this.registrations = 0;
+    }
+
+    finding(code, node, message, suggestion, severity = 'error') {
+        const file = typeof node === 'string' ? node : node.getSourceFile().fileName;
+        const location = typeof node === 'string' ? {} : (() => {
+            const point = node.getSourceFile().getLineAndCharacterOfPosition(node.getStart());
+            return { line: point.line + 1, column: point.character + 1 };
+        })();
+        const entry = { code, severity, file: path.relative(this.root, file).replaceAll('\\', '/'), ...location, message, suggestion };
+        const key = JSON.stringify(entry);
+        if (!this.reported.has(key)) { this.reported.add(key); this.issues.push(entry); }
+    }
+
+    unknown(node, subject) {
+        this.finding('SOURCE_UNRESOLVED', node, `${subject} is not statically known.`,
+            'Use explicit constants/arrays for inspection, or verify this dynamic configuration with application tests. Doctor does not execute it.', 'warning');
+    }
+
+    inspect() {
+        const ts = this.ts;
+        const sources = new Map();
+        const pendingFiles = [...this.config.fileNames];
+        const visited = new Set();
+        let bytes = 0;
+        for (const file of pendingFiles) {
+            if (visited.has(file) || /\.d\.[cm]?ts$/.test(file)) continue;
+            visited.add(file);
+            try {
+                const details = fs.statSync(file);
+                if (!details.isFile()) throw new TypeError('Source is not a regular file.');
+                const size = details.size;
+                if (sources.size >= MAX_FILES || size > MAX_BYTES - bytes) {
+                    this.finding('SOURCE_LIMIT', file, 'Source inspection reached its 256-file or 8 MiB limit.', 'Split large projects into smaller TypeScript configurations for inspection.', 'warning');
+                    continue;
+                }
+                const content = fs.readFileSync(file, 'utf8');
+                bytes += Buffer.byteLength(content);
+                const source = ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true);
+                sources.set(path.resolve(file), source);
+                for (const dependency of ts.preProcessFile(content).importedFiles) {
+                    if (!dependency.fileName.startsWith('.')) continue;
+                    const imported = ts.resolveModuleName(dependency.fileName, file, this.config.options, ts.sys).resolvedModule;
+                    if (imported && !outside(this.root, imported.resolvedFileName)) pendingFiles.push(imported.resolvedFileName);
+                }
+                for (const diagnostic of source.parseDiagnostics) {
+                    this.finding('SOURCE_SYNTAX', file, ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'), 'Correct the source syntax, then run doctor again.');
+                }
+            } catch (error) {
+                this.finding('SOURCE_UNREADABLE', file, `Cannot inspect source (${error.code || error.name}).`, 'Check that this configured source is a readable file.');
+            }
+        }
+        // No imports, plugins, or application modules execute. Project source imports are parsed, not loaded.
+        const options = { ...this.config.options, noLib: true, noResolve: true, types: [], noEmit: true };
+        const host = ts.createCompilerHost(options);
+        host.getSourceFile = file => sources.get(path.resolve(file));
+        const program = ts.createProgram([...sources.keys()], options, host);
+        this.syntax = new StaticSource(ts, program);
+        this.actions = new ActionReferences(this);
+        for (const source of sources.values()) {
+            const pending = [source];
+            while (pending.length) {
+                const node = pending.pop();
+                this.visit(node);
+                ts.forEachChild(node, child => { pending.push(child); });
+            }
+        }
+        if (this.syntax.limited) this.finding('SOURCE_LIMIT', path.join(this.root, 'tsconfig.json'),
+            'Source expressions exceeded the 50,000-operation or 4,096-entry expansion limit.',
+            'Simplify large spread/alias structures or validate the dynamic configuration with application tests.', 'warning');
+        return { issues: this.issues, source: { files: sources.size, registrations: this.registrations, mode: 'static-source', unresolved: this.issues.filter(issue => issue.severity === 'warning').length } };
+    }
+
+    visit(node) {
+        const ts = this.ts;
+        const read = this.syntax;
+        if (ts.isClassDeclaration(node)) {
+            this.actions.inspect(node);
+            const options = read.constructorArgument(node, 'SocketRoute');
+            if (options !== UNKNOWN) this.group(read.property(options, 'handlers'), 'handler', node);
+        }
+        if (!ts.isCallExpression(node) && !ts.isNewExpression(node)) return;
+        const api = read.api(node.expression);
+        const args = node.arguments || [];
+        if (['start', 'exportStatic', 'site.export'].includes(api)) {
+            this.group(args[0], 'page', node, args[1]);
+        } else if (api === 'LiveHtmlServer') {
+            this.group(read.property(args[0], 'pages'), 'page', node, args[0]);
+        } else if (['SocketServer', 'SecureSocketServer'].includes(api)) {
+            const routes = read.property(args[0], 'routes');
+            if (routes !== undefined) this.group(routes, 'route', node);
+        } else if (api === 'SocketRoute') {
+            this.group(read.property(args[0], 'handlers'), 'handler', node);
+        }
+    }
+
+    page(expression) {
+        const node = this.syntax.resolve(expression);
+        if (node === UNKNOWN || !this.ts.isClassDeclaration(node)) return null;
+        const decorators = this.ts.getDecorators(node) || [];
+        if (decorators.length !== 1) return null;
+        for (const decorator of decorators) {
+            const call = decorator.expression;
+            if (this.ts.isCallExpression(call) && ['page', 'site.page'].includes(this.syntax.api(call.expression))) return call;
+        }
+        return null;
+    }
+
+    name(expression, kind) {
+        const read = this.syntax;
+        if (kind === 'page') return read.text(this.page(expression)?.arguments[0]);
+        if (kind === 'route') return read.text(read.property(read.constructorArgument(expression, 'SocketRoute'), 'path'));
+        const node = read.resolve(expression);
+        if (node !== UNKNOWN && this.ts.isCallExpression(node) && read.api(node.expression) === 'contract.handler') return read.text(node.arguments[0]);
+        return read.text(read.constructorArgument(expression, 'BaseHandler'));
+    }
+
+    group(expression, kind, registration, options) {
+        this.registrations++;
+        const known = new Map();
+        for (const item of this.syntax.elements(expression)) {
+            const name = this.name(item, kind);
+            if (name === UNKNOWN) { this.unknown(registration, `${kind} registration`); continue; }
+            if (known.has(name)) {
+                this.finding(kind === 'handler' ? 'DUPLICATE_HANDLER' : 'DUPLICATE_ROUTE', registration,
+                    `Duplicate ${kind} "${name}" in the same registration.`, 'Keep one registration per path/message type in this server or route.');
+            }
+            known.set(name, item);
+            if (kind === 'page') this.assets(this.page(item), options, registration);
+        }
+    }
+
+    assets(page, options, registration) {
+        const read = this.syntax;
+        const configuredRoot = read.property(options, 'templateRoot');
+        let root;
+        if (configuredRoot !== undefined) {
+            const literal = read.text(configuredRoot);
+            if (literal !== UNKNOWN) root = path.resolve(this.root, literal);
+            else if (configuredRoot !== UNKNOWN && configuredRoot.getText() === '__dirname' && !read.checker.getSymbolAtLocation(configuredRoot)?.valueDeclaration) root = path.dirname(configuredRoot.getSourceFile().fileName);
+            else { this.unknown(registration, 'Asset templateRoot'); return; }
+        }
+        if (read.api(page.expression) === 'site.page') {
+            const site = read.resolve(read.resolve(page.expression).expression);
+            const shared = read.property(site.arguments[0], 'css');
+            const names = shared === undefined ? [] : read.elements(shared).map(item => read.text(item));
+            this.assetFields(page.arguments[1], page, root, ['template']);
+            if (names.includes(UNKNOWN)) this.unknown(site, 'Shared stylesheet provenance');
+            else this.assetFields(page.arguments[1], page, root, ['css'], new Set(names));
+            this.assetFields(site.arguments[0], site, root, ['css']);
+        } else this.assetFields(page.arguments[1], page, root);
+    }
+
+    assetFields(options, declaration, explicitRoot, fields = ['css', 'template'], skip = new Set()) {
+        const read = this.syntax;
+        for (const field of fields) {
+            const expression = read.property(options, field);
+            if (expression === undefined) continue;
+            for (const item of read.elements(expression)) {
+                const file = read.text(item);
+                if (file === UNKNOWN) { this.unknown(declaration, `Page ${field}`); continue; }
+                if (skip.has(file)) continue;
+                const root = explicitRoot || path.dirname(declaration.getSourceFile().fileName);
+                const resolved = path.resolve(root, file);
+                if (outside(root, resolved)) {
+                    this.finding('ASSET_OUTSIDE_ROOT', declaration, `Page ${field} "${file}" escapes its asset root.`, 'Keep assets within the page directory or the explicit templateRoot.');
+                    continue;
+                }
+                try {
+                    if (outside(fs.realpathSync(root), fs.realpathSync(resolved))) {
+                        this.finding('ASSET_OUTSIDE_ROOT', declaration, `Page ${field} "${file}" resolves through a link outside its asset root.`, 'Use an asset within the configured root.');
+                    } else if (!fs.statSync(resolved).isFile()) {
+                        this.finding('ASSET_NOT_FILE', declaration, `Page ${field} "${file}" is not a file.`, 'Point this declaration to a CSS or HTML file.');
+                    } else if (field === 'template' && fs.statSync(resolved).size <= 1024 * 1024) {
+                        this.actions.markup(declaration.parent.parent, fs.readFileSync(resolved, 'utf8'), declaration, resolved);
+                    } else if (field === 'template') this.actions.unknown(declaration, 'HTML action inspection exceeds the 1 MiB per-template limit.');
+                } catch (error) {
+                    this.finding('ASSET_UNAVAILABLE', declaration, `Page ${field} "${file}" is unavailable (${error.code}).`, 'Create/correct the asset at its source root and include it in the production asset-copy step.');
+                }
+            }
+        }
+    }
+}
+
+module.exports = SourceInspector;

package/src/cli/StaticSource.js

@@ -0,0 +1,192 @@
+'use strict';
+
+const UNKNOWN = Symbol('not statically known');
+
+// A deliberately small syntax reader, not an evaluator: it never calls application functions.
+class StaticSource {
+    constructor(ts, program) {
+        this.ts = ts;
+        this.checker = program.getTypeChecker();
+        this.remaining = 50000;
+        this.limited = false;
+        this.tainted = new Set();
+        this.arrays = new Map();
+        for (const source of program.getSourceFiles()) {
+            const pending = [source];
+            while (pending.length) {
+                const node = pending.pop();
+                if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+                    if (!this.api(node.expression) && !this.redwebSuper(node)) {
+                        if (ts.isPropertyAccessExpression(node.expression) || ts.isElementAccessExpression(node.expression)) this.taint(node.expression.expression);
+                        for (const argument of node.arguments || []) this.taint(argument, true);
+                    }
+                } else if (ts.isBinaryExpression(node) && node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && node.operatorToken.kind <= ts.SyntaxKind.LastAssignment) {
+                    this.taint(node.left, true);
+                    this.taint(node.right);
+                } else if (ts.isDeleteExpression(node) || ts.isPostfixUnaryExpression(node) || ts.isPrefixUnaryExpression(node)) {
+                    this.taint(node.operand || node.expression);
+                } else if ((ts.isReturnStatement(node) || ts.isYieldExpression(node)) && node.expression) this.taint(node.expression);
+                else if (ts.isArrowFunction(node) && !ts.isBlock(node.body)) this.taint(node.body);
+                else if (ts.isForOfStatement(node)) this.taint(node.expression);
+                else if (node.initializer && (
+                    ts.isPropertyDeclaration(node) || ts.isParameter(node) ||
+                    (ts.isVariableDeclaration(node) && (ts.isBindingPattern(node.name) || !(node.parent.flags & ts.NodeFlags.Const)))
+                )) this.taint(node.initializer);
+                ts.forEachChild(node, child => { pending.push(child); });
+            }
+        }
+    }
+
+    spend() {
+        if (--this.remaining >= 0) return true;
+        this.limited = true;
+        return false;
+    }
+
+    redwebSuper(node) {
+        const owner = node.parent?.parent?.parent;
+        return Boolean(node.expression.kind === this.ts.SyntaxKind.SuperKeyword && owner && this.ts.isConstructorDeclaration(owner) &&
+            ['SocketRoute', 'BaseHandler'].includes(this.api(this.base(owner.parent))));
+    }
+
+    taint(expression, bindingWrite = false) {
+        const pending = [expression], seen = new Set();
+        while (pending.length && this.spend()) {
+            const node = pending.pop();
+            if (seen.has(node)) continue;
+            seen.add(node);
+            if (this.ts.isIdentifier(node)) {
+                const value = this.resolve(node, new Set(), true);
+                if (value !== UNKNOWN && (this.ts.isArrayLiteralExpression(value) || this.ts.isObjectLiteralExpression(value) || (bindingWrite && this.ts.isClassDeclaration(value)))) {
+                    this.tainted.add(value);
+                    pending.push(value);
+                }
+            }
+            this.ts.forEachChild(node, child => { pending.push(child); });
+        }
+    }
+
+    resolve(node, seen = new Set(), ignoreTaint = false) {
+        const ts = this.ts;
+        if (!this.spend() || !node || node === UNKNOWN || seen.has(node) || seen.size >= 64 || (!ignoreTaint && this.tainted.has(node))) return UNKNOWN;
+        seen.add(node);
+        if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node) || ts.isNonNullExpression(node)) {
+            return this.resolve(node.expression, seen, ignoreTaint);
+        }
+        if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+            const owner = this.resolve(node.expression, new Set(seen), ignoreTaint);
+            if (owner !== UNKNOWN && ts.isObjectLiteralExpression(owner)) {
+                const key = ts.isPropertyAccessExpression(node) ? node.name.text : this.text(node.argumentExpression);
+                return this.resolve(this.property(owner, key, new Set(), ignoreTaint), seen, ignoreTaint);
+            }
+        }
+        if (!ts.isIdentifier(node)) return node;
+        let symbol = ts.isShorthandPropertyAssignment(node.parent)
+            ? this.checker.getShorthandAssignmentValueSymbol(node.parent) : this.checker.getSymbolAtLocation(node);
+        const imported = symbol?.declarations?.[0];
+        if (imported && (ts.isImportSpecifier(imported) || ts.isNamespaceImport(imported)) && this.moduleName(imported).startsWith('redweb')) return imported;
+        if (symbol?.flags & ts.SymbolFlags.Alias) symbol = this.checker.getAliasedSymbol(symbol);
+        const declaration = symbol?.valueDeclaration;
+        if (!declaration) return UNKNOWN;
+        if (ts.isVariableDeclaration(declaration)) {
+            if (!(declaration.parent.flags & ts.NodeFlags.Const)) return UNKNOWN;
+            return this.resolve(declaration.initializer, seen, ignoreTaint);
+        }
+        if (ts.isClassDeclaration(declaration) || ts.isFunctionDeclaration(declaration)) return !ignoreTaint && this.tainted.has(declaration) ? UNKNOWN : declaration;
+        return UNKNOWN;
+    }
+
+    moduleName(imported) {
+        let node = imported;
+        while (!this.ts.isImportDeclaration(node)) node = node.parent;
+        return node.moduleSpecifier.text;
+    }
+
+    api(expression, seen = new Set()) {
+        const ts = this.ts;
+        const node = this.resolve(expression);
+        if (node === UNKNOWN || seen.has(node) || seen.size >= 64) return null;
+        seen.add(node);
+        if (ts.isImportSpecifier(node) && ['redweb', 'redweb/contract'].includes(this.moduleName(node))) {
+            return (node.propertyName || node.name).text;
+        }
+        if (ts.isPropertyAccessExpression(node)) {
+            const owner = this.resolve(node.expression);
+            if (owner !== UNKNOWN && ts.isNamespaceImport(owner) && ['redweb', 'redweb/contract'].includes(this.moduleName(owner))) return node.name.text;
+            if (owner !== UNKNOWN && ts.isCallExpression(owner)) {
+                const factory = this.api(owner.expression, seen);
+                if (factory === 'defineSite' && ['page', 'export'].includes(node.name.text)) return `site.${node.name.text}`;
+                if (factory === 'defineSocketContract' && node.name.text === 'handler') return 'contract.handler';
+            }
+        }
+        return null;
+    }
+
+    text(expression) {
+        const node = this.resolve(expression);
+        return node !== UNKNOWN && this.ts.isStringLiteralLike(node) ? node.text : UNKNOWN;
+    }
+
+    property(expression, name, seen = new Set(), ignoreTaint = false) {
+        if (!expression) return undefined;
+        const node = this.resolve(expression, new Set(), ignoreTaint);
+        const ts = this.ts;
+        if (node === UNKNOWN || !ts.isObjectLiteralExpression(node) || seen.has(node) || seen.size >= 64) return UNKNOWN;
+        seen.add(node);
+        let value;
+        for (const field of node.properties) {
+            if (ts.isSpreadAssignment(field)) {
+                const spread = this.property(field.expression, name, new Set(seen), ignoreTaint);
+                if (spread !== undefined) value = spread;
+            } else {
+                const key = ts.isComputedPropertyName(field.name) ? this.text(field.name.expression) : field.name.text;
+                if (key === UNKNOWN) value = UNKNOWN;
+                else if (key === name) value = ts.isPropertyAssignment(field) ? field.initializer : ts.isShorthandPropertyAssignment(field) ? field.name : UNKNOWN;
+            }
+        }
+        return value;
+    }
+
+    elements(expression, seen = new Set()) {
+        const node = this.resolve(expression);
+        if (node === UNKNOWN || seen.has(node) || seen.size >= 64) return [UNKNOWN];
+        seen.add(node);
+        if (!this.ts.isArrayLiteralExpression(node)) return [node];
+        if (this.arrays.has(node)) return this.arrays.get(node);
+        const result = [];
+        for (const element of node.elements) {
+            const entries = this.ts.isSpreadElement(element) ? this.elements(element.expression, new Set(seen)) : [this.resolve(element)];
+            if (result.length + entries.length > 4096) { this.limited = true; return [UNKNOWN]; }
+            result.push(...entries);
+        }
+        this.arrays.set(node, result);
+        return result;
+    }
+
+    base(node) {
+        const clause = node.heritageClauses?.find(value => value.token === this.ts.SyntaxKind.ExtendsKeyword);
+        return clause ? clause.types[0].expression : UNKNOWN;
+    }
+
+    constructorArgument(expression, api, seen = new Set()) {
+        const node = this.resolve(expression);
+        if (node === UNKNOWN || seen.has(node) || seen.size >= 64 || !this.ts.isClassDeclaration(node)) return UNKNOWN;
+        seen.add(node);
+        const base = this.base(node);
+        const constructor = node.members.find(member => this.ts.isConstructorDeclaration(member));
+        const property = api === 'SocketRoute' ? 'path' : 'name';
+        if (node.members.some(member => member.name && (this.ts.isComputedPropertyName(member.name) || member.name.text === property))) return UNKNOWN;
+        if (this.ts.getDecorators(node)?.length || node.members.some(member =>
+            this.ts.isClassStaticBlockDeclaration(member) || (this.ts.isPropertyDeclaration(member) && member.initializer) ||
+            (this.ts.canHaveDecorators(member) && this.ts.getDecorators(member)?.length))) return UNKNOWN;
+        if (constructor?.parameters.some(parameter => parameter.modifiers?.some(modifier =>
+            [this.ts.SyntaxKind.PublicKeyword, this.ts.SyntaxKind.PrivateKeyword, this.ts.SyntaxKind.ProtectedKeyword, this.ts.SyntaxKind.ReadonlyKeyword].includes(modifier.kind)))) return UNKNOWN;
+        if (this.api(base) !== api) return constructor ? UNKNOWN : this.constructorArgument(base, api, seen);
+        if (constructor?.body?.statements.length !== 1) return UNKNOWN;
+        const statement = constructor?.body?.statements.find(item => this.ts.isExpressionStatement(item) &&
+            this.ts.isCallExpression(item.expression) && item.expression.expression.kind === this.ts.SyntaxKind.SuperKeyword);
+        return statement?.expression.arguments[0] || UNKNOWN;
+    }
+}
+
+module.exports = { StaticSource, UNKNOWN };

package/src/cli/arguments.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const { TEMPLATES } = require('./templates');
+const { KINDS } = require('./ProjectAddition');
+
+const USAGE = [
+    `Usage: redweb init [directory] [--template ${TEMPLATES.join('|')}] [--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.',
+    '--dry-run reports planned files without writing anything.',
+    'doctor inspects configuration without executing application code or repairing files.',
+].join('\n') + '\n';
+
+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 };
+    if (command === 'add') {
+        result.kind = rest.shift();
+        result.name = rest.shift();
+        if (!KINDS.includes(result.kind) || !result.name || result.name.startsWith('-')) throw new Error('Add requires a kind and name. Run redweb --help.');
+    }
+    let targetSeen = false;
+    const seen = new Set();
+    for (let i = 0; i < rest.length; i += 1) {
+        const value = rest[i];
+        if (!value.startsWith('-')) {
+            if (targetSeen) throw new Error('Only one project directory is allowed.');
+            result.target = value;
+            targetSeen = true;
+            continue;
+        }
+        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 === '--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') {
+            const template = rest[++i];
+            if (!TEMPLATES.includes(template)) throw new Error(`--template must be one of: ${TEMPLATES.join(', ')}.`);
+            result.template = template;
+        }
+        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.');
+    return result;
+}
+
+module.exports = { parseArguments, USAGE };

package/src/cli/formatCommand.js

@@ -0,0 +1,10 @@
+'use strict';
+
+/** Explicit argv remains authoritative; human output is quoted for the host shell. */
+function formatCommand(args, platform = process.platform) {
+    return platform === 'win32'
+        ? '& ' + args.map(value => `'${value.replaceAll("'", "''")}'`).join(' ')
+        : args.map(value => `'${value.replaceAll("'", "'\\''")}'`).join(' ');
+}
+
+module.exports = formatCommand;