diff options
Diffstat (limited to 'docs/TYPESCRIPT.txt')
| -rw-r--r-- | docs/TYPESCRIPT.txt | 128 |
1 files changed, 128 insertions, 0 deletions
diff --git a/docs/TYPESCRIPT.txt b/docs/TYPESCRIPT.txt new file mode 100644 index 0000000..d50ea95 --- /dev/null +++ b/docs/TYPESCRIPT.txt @@ -0,0 +1,128 @@ +Copyright (C) 2026 Doan Luu Duc Tai <doan@luuduct.ai> + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU Affero General Public License as +published by the Free Software Foundation, either version 3 of the +License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU Affero General Public License for more details. + +You should have received a copy of the GNU Affero General Public License +along with this program. If not, see <https://www.gnu.org/licenses/>. + +TYPESCRIPT BROWSER TOOLCHAIN + + All first-party browser logic and browser automation are TypeScript. + Rust still implements cryptography, the API, backups, and deployment. + Browsers execute JavaScript generated by TypeScript; TypeScript adds + compile-time checks and does not replace validation of untrusted input. + +SOURCE LAYOUT + + crates/chat-server/web/app.ts + Interface, session state, history, downloads, and API validation. + crates/chat-server/web/worker.ts + One-shot cryptographic worker; its lifetime ends after each request. + crates/chat-crypto/browser/wasi.ts + Restricted browser WASI host for the unchanged Rust/OpenSSL module. + crates/chat-crypto/browser/protocol.d.ts + Shared API and cryptographic request/response contracts. Declarations + emit no JavaScript and are checked for both browser environments. + crates/chat-crypto/tests/browser.ts + Real WebAssembly compatibility, entropy, and capability tests. + crates/chat-server/tests/browser.ts + Complete browser chat and recovery tests, including GNU LibreJS. + crates/chat-server/tests/progress.ts + Download progress and failure tests, including GNU LibreJS. + tests/browser-support.ts + Checked fixture parsing and typed browser-automation helpers. + + tsconfig.json supplies shared strict checks. The browser, worker, and + test configurations use separate DOM, WebWorker, and Node environments. + Production browser builds cannot accidentally rely on Node APIs. + strict, unchecked indexed access, exact optional properties, unused + declarations/parameters, implicit returns, switch fallthrough, implicit + overrides, and indexed-property access are checked. Type errors prevent + emission. No suppression directives or untyped escape hatches are used. + +DEVELOPMENT + + Install Node >=22.18.0 and npm on the development machine. Root package.json + and package-lock.json pin TypeScript 7.0.2, Playwright 1.64.1, Node type + declarations, platform compiler packages, and their integrity hashes. + There are no npm application/runtime dependencies. TypeScript and + Playwright use the Apache License, Version 2.0; Node declarations and + undici-types use the Expat License. Original notices remain in the + installed packages. SPDX identifiers retain their required spelling. + + Build and check all TypeScript, including browser tests: + + npm run build + + infra/chat/build-typescript.sh installs the locked development packages + with lifecycle scripts disabled, checks all three configurations, and + emits JavaScript under var/build/typescript. The npm cache stays under + .tools/npm-cache. node_modules and generated outputs are ignored by Git. + Generated scripts are readable and unminified; no bundler is needed. + + cargo stack check includes this build, then the strict Rust checks and + cargo-about license generation. cargo stack release builds TypeScript + before packaging the complete production release. + + Check without installing packages or emitting output after npm run build: + + npm run check + + Fetch the pinned Playwright browser versions once: + + PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" node_modules/.bin/playwright install chromium firefox + + After building the native chat server and WASI module: + + PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" npm run test:crypto + PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" npm run test:chat + PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" npm run test:progress + CHAT_LIBREJS=1 PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" npm run test:chat + CHAT_LIBREJS=1 PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" npm run test:progress + + LibreJS variants require the signed Mozilla extension at + .tools/librejs.xpi as documented in CHAT-APPLICATION.txt. The complete + chat test proves LibreJS is active and rejects an unlicensed control. + Run chat variants sequentially because they share the default test port. + npm audit checks the development dependency lock separately from + cargo-deny; it does not audit Rust, browser-delivered code, or containers. + +RELEASES, SOURCE, AND LIBREJS + + Generated app.js, worker.js, and wasi.mjs keep their existing public URLs. + They preserve the AGPL headers and recognized @license/@license-end + markers. The JavaScript license table links each generated file to its + complete corresponding TypeScript and Rust source archive. Classic scripts + and importScripts remain in use for LibreJS compatibility; the migration + introduces no runtime module loader or third-party browser scripts. + + Local native-server tests serve generated files from var/build/typescript. + The release packages those files into bin/chat/web and bin/chat/wasi.mjs. + Containers serve the packaged files. HTML and CSS are copied explicitly, + so TypeScript source files are not substituted for executable JavaScript. + /SOURCE.tar.gz includes TypeScript, shared declarations, all compiler + configurations, the npm lock, tests and build scripts, together with the + existing Cargo-vendored dependencies and verified OpenSSL source archive. + Node/npm/TypeScript are general-purpose development tools, documented and + pinned here; their installed copies and downloaded browsers are excluded. + + Source exports, releases, and backups carry the root npm manifests and + TypeScript configurations. Release activation and restored prebuilt images + need no Node, npm, TypeScript, or Rust installation on the destination. + They retain the single private root .env and existing persistent data. + The source archive excludes that .env, credentials, runtime databases, + exports, .git, node_modules, and build/cache directories. The root + .env.example remains public. No additional environment file is introduced. + + Test the actual generated JavaScript after any compiler upgrade. Static + types cannot guarantee privacy, security, or LibreJS recognition. Browser + storage restrictions, protocol validation, and algorithm choices continue + to be enforced by the existing runtime and Rust implementation. |