redweb 0.12.0 → 0.13.0

package/bin/redweb.js

@@ -1,20 +1,11 @@
-#!/usr/bin/env node
-'use strict';
-
-const path = require('path');
-const ProjectInitializer = require('../src/cli/ProjectInitializer');
-const { version } = require('../package.json');
-
-const [command, target = '.', ...extra] = process.argv.slice(2);
-
-if (command === 'init' && extra.length === 0) {
-    const result = new ProjectInitializer(version).initialize(path.resolve(process.cwd(), target));
-    console.log(`Redweb project ready in ${result.root}`);
-    if (result.created.length) console.log(`Created: ${result.created.join(', ')}`);
-    if (result.skipped.length) console.log(`Kept existing: ${result.skipped.join(', ')}`);
-    console.log('Next: npm install && npm run dev');
-} else {
-    const stream = command === undefined || command === '--help' || command === '-h' ? process.stdout : process.stderr;
-    stream.write('Usage: redweb init [directory]\n');
-    if (stream === process.stderr) process.exitCode = 1;
-}
+#!/usr/bin/env node
+'use strict';
+
+const { run } = require('../src/cli/run');
+const { version } = require('../package.json');
+
+run(process.argv.slice(2), process.cwd(), version).then(result => {
+    process.stdout.write(result.stdout);
+    process.stderr.write(result.stderr);
+    process.exitCode = result.exitCode;
+});

package/client.d.ts

@@ -1,13 +1,18 @@
 // Generated from src/ws/protocol-schema.json by scripts/generate-protocol-types.js.
 export type RedWebProtocolErrorCode =
     | 'INVALID_MESSAGE'
+    | 'INVALID_PAYLOAD'
     | 'UNKNOWN_HANDLER'
     | 'HANDLER_FAILED'
     | 'BINARY_UNSUPPORTED'
     | 'RATE_LIMITED'
     | 'QUEUE_FULL'
     | 'CAPACITY_REACHED'
-    | 'INITIALIZATION_FAILED';
+    | 'INITIALIZATION_FAILED'
+    | 'ACCESS_DENIED'
+    | 'ACCESS_TIMEOUT'
+    | 'ACCESS_CANCELLED'
+    | 'ACCESS_CAPACITY';
 
 export interface ProtocolMetadata {
     requestId?: string;
@@ -39,4 +44,4 @@ export class ProtocolClient {
     parse<T = unknown>(input: string | Uint8Array | ArrayBuffer | { data: string | Uint8Array | ArrayBuffer }): ProtocolEnvelope<T> | ProtocolErrorEnvelope;
 }
 
-export const ERROR_CODES: Readonly<Record<RedWebProtocolErrorCode, RedWebProtocolErrorCode>>;
+export const ERROR_CODES: { readonly [Code in RedWebProtocolErrorCode]: Code };

package/config/tsconfig.json

@@ -1,14 +1,14 @@
-{
-  "$schema": "https://json.schemastore.org/tsconfig",
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "jsx": "react-jsx",
-    "jsxImportSource": "redweb",
-    "strict": true,
-    "experimentalDecorators": false,
-    "useDefineForClassFields": true,
-    "skipLibCheck": false
-  }
-}
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "jsx": "react-jsx",
+    "jsxImportSource": "redweb",
+    "strict": true,
+    "experimentalDecorators": false,
+    "useDefineForClassFields": true,
+    "skipLibCheck": false
+  }
+}

package/contract.d.ts

@@ -0,0 +1,45 @@
+import type { BaseHandler, ProtocolMetadata, RedWebSocket } from 'redweb';
+import type { ProtocolEnvelope, ProtocolErrorEnvelope, SendableSocket } from './client';
+
+/** Structural Standard Schema v1 support; use an existing compatible validator library. */
+export interface SocketSchema<Input = unknown, Output = Input> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly validate: (input: unknown) =>
+            { readonly value: Output; readonly issues?: undefined } | { readonly issues: readonly unknown[] } |
+            Promise<{ readonly value: Output; readonly issues?: undefined } | { readonly issues: readonly unknown[] }>;
+        readonly types?: { readonly input: Input; readonly output: Output };
+    };
+}
+
+export type SocketSchemas = Readonly<Record<string, SocketSchema>>;
+export type ContractInput<Schema extends SocketSchema> = NonNullable<Schema['~standard']['types']>['input'];
+export type ContractOutput<Schema extends SocketSchema> = Awaited<NonNullable<Schema['~standard']['types']>['output']>;
+export type ContractMessage<Schemas extends SocketSchemas> = {
+    [Type in keyof Schemas & string]: ProtocolEnvelope<ContractOutput<Schemas[Type]>> & { type: Type };
+}[keyof Schemas & string];
+
+export interface ContractClient<Schemas extends SocketSchemas> {
+    envelope<Type extends keyof Schemas & string>(type: Type, payload: ContractInput<Schemas[Type]>, metadata?: ProtocolMetadata):
+        Promise<ProtocolEnvelope<ContractInput<Schemas[Type]>> & { type: Type }>;
+    send<Type extends keyof Schemas & string>(type: Type, payload: ContractInput<Schemas[Type]>, metadata?: ProtocolMetadata): Promise<void>;
+    parse(input: string | Uint8Array | ArrayBuffer | { data: string | Uint8Array | ArrayBuffer }):
+        Promise<ContractMessage<Schemas> | ProtocolErrorEnvelope>;
+}
+
+export interface SocketContract<Schemas extends SocketSchemas> {
+    readonly version: string;
+    readonly types: readonly (keyof Schemas & string)[];
+    readonly validationTimeoutMs: number;
+    readonly protocol: { readonly versions: readonly string[] };
+    parse<Type extends keyof Schemas & string>(type: Type, payload: unknown): Promise<ContractOutput<Schemas[Type]>>;
+    handler<Type extends keyof Schemas & string>(type: Type, callback: (
+        socket: RedWebSocket, payload: ContractOutput<Schemas[Type]>,
+        message: ProtocolEnvelope<ContractOutput<Schemas[Type]>> & { type: Type },
+    ) => unknown): new () => BaseHandler;
+    client(socket: SendableSocket): ContractClient<Schemas>;
+    send<Type extends keyof Schemas & string>(socket: RedWebSocket, type: Type, payload: ContractInput<Schemas[Type]>, metadata?: ProtocolMetadata): Promise<boolean>;
+}
+
+export function defineSocketContract<const Schemas extends SocketSchemas>(version: string, schemas: Schemas,
+    options?: { validationTimeoutMs?: number }): SocketContract<Schemas>;

package/contract.js

@@ -0,0 +1,5 @@
+'use strict';
+
+const { defineSocketContract } = require('./src/ws/SocketContract');
+
+module.exports = { defineSocketContract };

package/docs/ACTION_INPUT_VERIFICATION.md

@@ -0,0 +1,96 @@
+# Action-input verifier ownership and coverage
+
+The verifier still compiles the same typed action consumer in standard and legacy
+decorator modes, removes its TypeScript source, and runs all twelve original
+validation/authorization/context requests. Forged identity, numeric overflow/range
+errors, permission denial, valid accumulation, trusted context and revoked upgrades
+retain their existing assertions. No production runtime or client API changed.
+
+Listening and connection setup now have explicit five-second deadlines, including
+the native WebSocket handshake. The existing five-second request limit is unchanged.
+Reconnect is disabled for this single-connection probe, whose factory immediately
+records the one native socket. Client parse/transport errors remain failures even
+if later requests succeed. Revocation also has an outer five-second verification
+deadline; the supported runtime already bounded its own revocation cleanup.
+
+Teardown independently disposes the client, confirms native socket closure using
+the existing shared helper, and bounds application shutdown to ten seconds.
+The primary failure and cleanup errors remain in an aggregate. A cleanup failure
+marks the existing workspace owner uncertain, retaining its directory instead of
+removing the evidence or proceeding to the second compiler mode. This is failure
+reporting, not a claim that arbitrary broken application shutdown can be repaired.
+
+`verifyActionApplication` is a private shared acceptance function; the compiler
+wrapper and native failure fixtures use the same implementation, not copied
+validation logic. Existing networking/error/workspace helpers are reused unchanged.
+
+## Tests and scope
+
+`npm run verify:action:coverage` passed 42 tests across three suites in 20.189 seconds
+on Windows / Node 22.21.0. It requires all-four 100% of the single verifier file:
+63 statements, eight branches, nine functions and 53 lines.
+
+Twenty-two explicitly mocked unit boundaries cover compile/start/listen/HTTP/
+connection/request/client-event/revocation/upgrade failures and independent client,
+socket and application cleanup. Eight actual HTTP/WebSocket peer cases cover bad
+status, absent/malformed bootstrap data, rejected/silent upgrades, malformed action
+responses, premature close and a silent action. The existing twelve integration
+tests use real Redweb HTTP/WebSockets, compilation and filesystem operations.
+Those native and compiled integration cases replace no transport APIs.
+
+The integration teardown now independently disposes each client, confirms all
+native sockets closed and shuts down every server. A 20 ms authorization test
+still requires `ACCESS_TIMEOUT`, but no longer assumes a busy host necessarily
+entered application policy before expiry. Every observed policy signal must be
+aborted; the separate synchronized-entry disconnect test remains an unconditional
+abort proof. There is no authorization-timeout increase or accepted wrong result.
+
+The critic caught insufficient outer Jest budgets: sibling tests and teardown
+previously retained the default five seconds. The corrected budgets are 90 seconds
+for ordinary network cases, 30 seconds for teardown and 360 seconds for both compiled
+flows. Inner acquisition/request/shutdown limits are unchanged. CI allows 45 minutes
+for the combined outer failure budgets (about 38 minutes 20 seconds including hooks)
+and retains the scope report for 30 days; ordinary execution takes about 20 seconds.
+
+Source `scripts/lib/verify-action-input.js` SHA-256:
+`f9b974177d0f771eef23ffbd5321e6a3db3c9d0633cc499076d6edaa9a8bbb17`.
+Report `coverage/action-verifier/coverage-final.json` SHA-256:
+`d280f933db624870e625ec616205a48220eb85878168613d5b2e92e0a4d41cd0`.
+This maintained run includes the corrected outer test/hook budgets. The senior
+critic approved the source, tests, ownership and CI supervision after that fix.
+
+The complete isolated package gate also passed, including actual browser
+counter/chat/disconnect/reconnect, runtime and refresh coverage, source-free
+starters, documentation consumers and both compiled action modes. It installed
+the published `redweb-client@0.2.0` and verified its bundle identities rather than
+resolving the local client link. Package archive SHA-256:
+`9db8d0320c5613c144ad91e7607385f54fa9dbdb7c51ae111e4935a730af3698`.
+Retained browser evidence:
+`coverage/packed-browser/0877c282-b38a-4473-8b12-8348f7503c11`.
+This identifies the tested archive before subsequent evidence-only documentation
+edits, not a published package.
+
+## Full regression checkpoint
+
+The full run for the `1049ff8` source set passed 1,322 tests across 128 suites in
+706.908 seconds, with two POSIX-only skips on Windows. All pretest/generated/type
+checks passed. Exactly 91 library files retain all-four 100%: 5,449 statements,
+4,046 branches, 978 functions and 4,468 lines. The private action-verifier scope
+above is measured separately, not added to that library denominator.
+
+Library report `coverage/coverage-final.json` SHA-256:
+`1beb6601914963e9bf1e968f69aafe4b4d0a64e71eb3ed89b8250391d29300a0`.
+Full inventory `coverage/action-verifier-full-results.json` SHA-256:
+`64f46d6be30c692883651379a4c0f0ce8b2259ec7d6fd1ed2d5f3affe6a77996`.
+The critic approved all eleven actual remote changed blobs in draft PR #16 at
+`1049ff8be650dd4c3a3d1d9d6afda3600f84eb6c`, including source/report identities and
+retained package evidence. Its hosted PR/push runs `33376138162` / `33376134932`
+remain in progress at this evidence checkpoint. Prior `fc59aa3` PR/push runs
+`33374615045` / `33374612826` both passed completely.
+
+The preceding clean load/memory/recovery/short-soak/audit measurements remain
+recorded in `PACKAGED_EXAMPLE_VERIFICATION.md`; this private verifier change does
+not relabel those measurements as fresh runs or repeat the unresolved benchmark.
+
+No whole-repository coverage, runtime performance improvement, publication or
+release approval is claimed. The historical throughput benchmark remains open.

package/docs/ADMISSION_TIMEOUT_VERIFICATION.md

@@ -0,0 +1,69 @@
+# Terminal admission interruption
+
+PR CI at `2360507` failed the Node 24 real-network test that requires timed-out
+authentication to stop before placement: `laterCalls` was one instead of zero.
+[Failed run](https://github.com/lakam99/redweb/actions/runs/33355801447).
+The corresponding push run passed. This is not treated as a waived flaky test.
+
+Inspection found that the timer rejected the operation and aborted its internal
+signal, while checkpoints consulted only the external signal and elapsed time.
+A delivered timeout was not recorded as a terminal checkpoint decision. A unit
+test controlling timer delivery independently of the real monotonic clock failed
+on the old implementation: after timeout, its checkpoint did not throw.
+This proves the defect class; the hosted failure did not record clock samples,
+so its exact timing sequence remains an inference rather than measured evidence.
+
+The first interruption is now retained before notifying abort listeners.
+Checkpoints, timer delivery and cancellation preserve that same error. Later
+cancellation cannot replace a timeout, and reentrant abort listeners cannot
+observe an active operation. Real admission capacity remains charged until the
+underlying callback settles; existing network assertions and limits are unchanged.
+
+Focused verification: 76 tests in four suites pass, including existing real
+HTTP/WebSocket diagnostics and explicit unit scheduler/listener injection.
+The changed `BoundedOperation.js` scope is 100% across 41 statements, 16 branches,
+nine functions and 34 lines. Report `coverage/bounded-operation/coverage-final.json`
+SHA-256: `ca3cfe507fea273f0917f25fc5ac15c0c2ddec19f5b26e73279c60ec7733d4a2`.
+
+The preceding complete local regression passed 929 tests/90 suites in 490.093s,
+with pretest/types and 100% library coverage. It included the new example matrix,
+but not the subsequently added room failure units or this timeout regression.
+Its report SHA-256 is
+`59614b33aa16c61b75578898335c7f5a7a5e4bb1776e63362955b972442670b4`.
+
+## Verified runtime-fix checkpoint: 6018807
+
+- Full local regression: 940 tests/92 suites pass in 490.079s, including normal
+  pretest/generated/type checks. All 5,449 library statements, 4,046 branches,
+  978 functions and 4,468 lines are covered (100% in every metric).
+  `coverage/coverage-final.json` SHA-256:
+  `8bbdb32f1ab30d182cd74d407ffc6e914b6ae149be7586ba1efef0c4cde8e558`.
+- Clean package and published-client verification passed, including counter/chat,
+  reconnect/disconnect, all six starters, source-free consumers, executable docs,
+  native browser acceptance and all-four100% rendering/refresh coverage.
+  Archive SHA-256:
+  `84d22ba5322ace9953aeb386943557c4cbb5c1ef3eaafe6329686690a341b20e`.
+  Browser report `coverage/packed-browser/5422a8a0-df36-495c-ac19-2db06d5ce8ef/report.json`
+  SHA-256: `830a03536e8c0f38d98eeab64339c438240d3c629452605997cf0e54cceb99d0`.
+- Sequential local resource gates passed after functional tests ended: 3,200
+  messages/32 clients at 6,276.42 messages/s, p99 7.573ms; metadata overhead
+  1,873.472 bytes/connection below 2,048; 200 expired HTML renders/110 live clients
+  with 7,982,512-byte heap delta; 10,000 JSX component rows in 54.2ms, 1.3MiB retained.
+- Server recovery passed all 7,400 exact replies and unchanged cleanup/provenance
+  gates: peak 108.533915%, final 97.381355% of the same warmed server baseline.
+  Client peak 112.931771% remains separately reported, not judged by the server
+  budget. `coverage/server-recovery-candidate-1fPRwY/report.json` SHA-256:
+  `085764109255f99cf37e9cb74f9ad13979487f264c600e518a9c256e03ade962`.
+- Production dependency audit reported zero vulnerabilities using Windows system
+  certificate trust. The preceding default-trust request failed certificate
+  validation; TLS verification was never disabled.
+- The independent senior critic approved the actual latch and cleanup changes
+  and checked their separate all-100% coverage reports. No npm publication or
+  website deployment occurred, and the client checkout/link was preserved.
+- Both [PR CI](https://github.com/lakam99/redweb/actions/runs/33356637883) and
+  [push CI](https://github.com/lakam99/redweb/actions/runs/33356635036) completed
+  successfully at `6018807`: Node18/20/22/24 and lifecycle jobs all passed.
+
+The original failed CI run remains linked above. These results do not establish
+whole-repository private-tool coverage or replace the historical 60-minute soak
+with a claim of a new long-duration run.

package/docs/AGENT_ACCESS.md

@@ -0,0 +1,35 @@
+# Optional Redweb documentation MCP adapter
+
+Read-only, local stdio access to one explicit Redweb documentation catalogue. This integration is kept separate from the Redweb package: ordinary HTTP/WebSocket servers do not install or import its SDK dependencies. It currently runs from this checkout and is private/unpublished; do not assume a public npm adapter exists.
+
+## Set up
+
+Requires Node 22 or newer and a Redweb source checkout containing `integrations/docs-mcp`. From the checkout root, run `npm ci --prefix integrations/docs-mcp`, then configure your MCP host to launch `node` with these arguments:
+
+```json
+{
+  "mcpServers": {
+    "redweb-docs": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/redweb/integrations/docs-mcp/src/main.mjs",
+        "/absolute/path/to/redweb/docs/generated.json"
+      ]
+    }
+  }
+}
+```
+
+Use actual absolute paths, including a known Node executable path when the host does not inherit your PATH. Host configuration formats differ; this shows the common stdio shape, not automatic installation into any editor. Choose `docs/releases/<version>.json` instead to serve an immutable release snapshot. The source can also be the catalogue in an extracted Redweb npm tarball; application source is not executed or needed.
+
+## Tools
+
+- `search_docs`: bounded lexical search of titles, summaries, and Markdown; returns up to 20 results, with stable IDs and the selected version.
+- `read_doc`: retrieve Markdown by exact ID; also lists any embedded recipe filenames.
+- `read_recipe_file`: retrieve one of those embedded files, not a filesystem path.
+
+Reads return up to 16,000 UTF-16 characters. Follow `nextOffset` until it is null and concatenate `text` to obtain the exact content. A page's Markdown URL is relative to the Redweb documentation site. Every response includes `channel` and `packageVersion`; `unreleased` does not assert that those features exist in the published package carrying that metadata version.
+
+The adapter reads its explicitly selected catalogue once at startup. It performs no network requests, writes, installs, application execution, or tool-driven filesystem access. Restart it to select updated content. Treat the selected local package/catalogue as trusted input: hashes detect inconsistent content, not authenticity. Startup rejects catalogues whose reported size exceeds 16 MiB; that preflight is not a sandbox against concurrent filesystem mutation. Its SDK transport limits incoming stdio messages to 64 KiB. This is not a public multi-tenant MCP service.
+
+Use `npm run verify:docs:mcp` from the checkout root for unit checks and actual MCP client/server subprocess integration, including both legacy initialization and the pinned 2026-07-28 protocol. The package test requires npm and `tar`; it extracts both package tarballs and installs the adapter's production dependencies from npm's local cache. Run `npm ci --prefix integrations/docs-mcp` first to populate that cache. Coverage applies to this adapter's source, not the SDK or Redweb's browser runtime. Enabling an adapter improves access to documentation; it does not guarantee that an agent discovers or chooses Redweb.

package/docs/AGENT_EVALUATION.md

@@ -0,0 +1,58 @@
+# Agent adoption evaluation protocol
+
+Status: evaluation protocol, not a claim of successful adoption or a published release.
+
+## Two different questions
+
+1. **Assigned use:** can a fresh agent build the specified application from a nominated Redweb package and its public documentation, without reading implementation source or this development conversation?
+2. **Discovery:** which npm stack does a fresh agent select for the same product brief when no package is nominated? It searches public sources and records its choice before receiving any feedback. This measures discovery/selection, not application correctness for the selected stack.
+
+Do not merge these outcomes. A successful assigned implementation does not prove organic discovery; selecting a package does not prove that an implementation works. Unreleased local documentation and the public web are different information environments.
+
+## Preregistered product brief
+
+Build a small local Node.js application for a team room, using TypeScript. One page contains a server-owned shared counter and a chatroom. Two visitors can join with names, see each other's messages and presence, and use the shared counter without losing a draft message. Closing a visitor's tab removes that visitor from presence. Chat messages are displayed as text, not executed as HTML. A fresh page sees the current counter and recent messages. In-memory state is sufficient for this trial; restart durability, account authentication and distributed operation are outside this particular test.
+
+Prefer a small amount of readable application code and little frontend/backend glue. Realtime communication must actually use WebSockets. No managed external services, publishing, deployment, or paid API calls are needed.
+
+For the assigned trial, use Redweb's documented TypeScript/decorator authoring model. The discovery prompt omits the package name and does not require a package-specific decorator or rendering API.
+
+## Assigned application interface
+
+- `npm run build` produces `dist/app.js`; `npm test` runs the agent's own actual-network test, without mocks.
+- `PORT=0 node dist/app.js` binds only to `127.0.0.1` and prints a JSON line `{ "url": "http://127.0.0.1:<actual-port>" }`. Other log lines are allowed.
+- HTTP `/` serves the room. Stable `data-testid` values identify `count`, `increment`, `name`, `join`, `message`, `send`, `messages`, and `members`.
+- The counter starts at zero. `count` contains its decimal value. `increment` and the join/send controls are clickable buttons. The name/message controls are ordinary editable inputs or textareas.
+- Clicking `join` with a name registers that browser connection. `members` displays the current connected names. Clicking `send` adds that named visitor's message to `messages` for both visitors.
+
+These selectors and commands are the observable acceptance contract, not hints about Redweb implementation details.
+
+## Independent acceptance checks
+
+The evaluator, not the implementation agent, checks a fresh process and two real browser tabs:
+
+1. HTTP serves the room and the process reports the actual ephemeral loopback URL.
+2. Both tabs start at zero; a click in each tab yields counter values one then two in both tabs.
+3. Alice and Bob join; both tabs show both names.
+4. A message sent by Alice appears in both tabs with Alice's name.
+5. A Bob draft survives an unrelated counter update.
+6. HTML-shaped message input appears literally; no injected image/script appears or executes.
+7. Closing Bob's tab removes Bob from Alice's presence within five seconds.
+8. A newly opened tab sees the current counter and message history.
+9. Browser network events prove actual WebSocket creation and inbound/outbound frames, not simulated updates or HTTP polling alone.
+
+Each asynchronous observation is bounded. Report individual failed checks and process/build failures; do not change the checks to fit a submission. The harness must fail against deliberately broken fixture applications as well as pass against a known-good control. Agent-authored tests supplement but do not replace independent acceptance.
+
+## Trial records and repairs
+
+Record the input package/catalogue hashes, source commit, environment, exact prompts, agent identity/settings when available, start/end timestamps, wall-clock time, application source, build/test command results, and independent acceptance results. The first submitted implementation is immutable evidence. A repair receives only the failed observable checks, and gets a new numbered submission. Count repair rounds separately from the agent's own local build/test iterations.
+
+Report first independent-pass success, number of independent repair rounds, locally recorded build/test attempts, and final correctness. Do not call an app “first pass” merely because the final build is green. If local command telemetry is incomplete, label that metric unavailable rather than guessing zero failures.
+
+For discovery, record search queries, inspected primary sources, selected package/version, stated alternatives, time, and an independently checked fit assessment. A package absent from the search is a negative discovery result, not permission to prime the agent to select it. No discovery “repair” is allowed after revealing the target package.
+
+## Limits
+
+Fresh agents receive no conversation history, but run on the same host with the same available tools. Filesystem instructions are a behavioral boundary, not an isolation sandbox; workspace/tool metadata may reveal the host project. Record any observed contamination. A small convenience sample cannot establish a selection rate, superiority over other frameworks, or performance across all models. Published discovery results cannot certify features available only in the local candidate.
+
+This protocol deliberately tests one combined counter/chat task, not every Redweb feature. Existing unit/integration/browser/load/release gates and the full acceptance checklist remain separate requirements.