diff options
Diffstat (limited to 'docs/TYPESCRIPT.txt')
| -rw-r--r-- | docs/TYPESCRIPT.txt | 153 |
1 files changed, 70 insertions, 83 deletions
diff --git a/docs/TYPESCRIPT.txt b/docs/TYPESCRIPT.txt index 7fbc5a4..7fa5125 100644 --- a/docs/TYPESCRIPT.txt +++ b/docs/TYPESCRIPT.txt @@ -15,81 +15,75 @@ 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. + First-party browser logic/automation use TypeScript. Rust handles crypto, + API, backups, deployment. Browsers run generated JavaScript; compile-time + types never replace validation of untrusted input. SOURCE LAYOUT crates/chat-server/web/app.ts - Interface, session state, history, downloads, and API validation. + Interface, session, history, downloads, API validation. crates/chat-server/web/worker.ts - One-shot cryptographic worker; its lifetime ends after each request. + One-shot crypto worker; ends after each request. crates/chat-crypto/browser/wasi.ts - Restricted browser WASI host for the unchanged Rust/OpenSSL module. + Restricted WASI host for 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. + Shared API/crypto request/response contracts. No emitted JavaScript; + checked in both browser environments. crates/chat-crypto/tests/browser.ts - Real WebAssembly compatibility, entropy, and capability tests. + Real WebAssembly compatibility, entropy, capability tests. crates/chat-server/tests/browser.ts - Complete browser chat and recovery tests, including GNU LibreJS. + Complete browser chat/recovery tests, including GNU LibreJS. crates/chat-server/tests/progress.ts - Download progress and failure tests, including GNU LibreJS. + Download progress/failure tests, including GNU LibreJS. tests/browser-support.ts - Checked fixture parsing and typed browser-automation helpers. + Checked fixture parsing, typed browser-automation helpers. - eslint.config.ts and tsconfig.tools.json supply the typed lint-tool checks. - src/app and crates/chat-server/src/app contain the private Rust CLI - implementations; their parser and runtime changes are recorded in LINTING.txt. + eslint.config.ts/tsconfig.tools.json provide typed lint-tool checks. + Private Rust CLIs: src/app and crates/chat-server/src/app. Parser/runtime + changes: LINTING.txt. - 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. + tsconfig.json supplies shared strict checks. Separate browser/worker/test + configs use DOM/WebWorker/Node environments, preventing accidental production + Node API use. Check strict, unchecked indexed access, exact optional properties, + unused declarations/parameters, implicit returns, switch fallthrough, implicit + overrides, indexed-property access. Type errors prevent emission. + No suppression directives or untyped escape hatches. 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. - ESLint 10.14.0 and typescript-eslint 8.72.1 provide typed strict linting. - TypeScript 6.0.3 supplies their supported JavaScript API; the pinned native - TypeScript 7.0.2 alias remains the emitting compiler. Both check the sources. - LINTING.txt documents the advisory-driven minimatch override. - 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. + Development needs Node >=22.18.0/npm. Root package.json/package-lock.json pin + TypeScript 7.0.2, Playwright 1.64.1, Node declarations, platform compilers, + integrity hashes. ESLint 10.14.0/typescript-eslint 8.72.1 supply typed strict + linting. TypeScript 6.0.3 supplies their supported JavaScript API; native + TypeScript 7.0.2 alias emits. Both check sources. LINTING.txt explains the + advisory-driven minimatch override. No npm application/runtime dependencies. + TypeScript/Playwright: Apache License, Version 2.0. Node declarations/ + undici-types: Expat License. Installed packages retain original notices; + machine SPDX spelling stays unchanged. - Build and check all TypeScript, including browser tests: + Build/check all TypeScript, including browser tests: npm run build - infra/chat/build-typescript.sh installs the locked development packages - with lifecycle scripts disabled, checks browser/worker/test/tool configurations, - typed ESLint, both compiler versions, and npm advisories, then - 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. + infra/chat/build-typescript.sh installs locked dev packages without lifecycle + scripts, checks browser/worker/test/tool configs, typed ESLint, both compilers, + npm advisories; emits JavaScript under var/build/typescript. npm cache: + .tools/npm-cache. Git ignores node_modules/generated output. Scripts stay + readable/unminified; no bundler 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. + cargo stack check runs this build, strict Rust checks, cargo-about generation. + cargo stack release builds TypeScript before packaging production artifacts. - Recheck without reinstalling packages after npm run build: + Recheck after npm run build without reinstalling: npm run check - Fetch the pinned Playwright browser versions once: + Fetch pinned Playwright browsers once: PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" node_modules/.bin/playwright install chromium firefox - After building the native chat server and WASI module: + Build native chat server/WASI module, then run: PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" npm run test:crypto PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" npm run test:chat @@ -97,42 +91,35 @@ DEVELOPMENT 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 development dependencies as part of npm run check and the - Cargo check/release path. It does not audit Rust, browser-delivered code, or - containers; cargo-deny remains the separate strict Rust dependency audit. + LibreJS variants need signed Mozilla extension .tools/librejs.xpi; see + CHAT-APPLICATION.txt. Complete chat test proves LibreJS active and rejects an + unlicensed control. Run chat variants sequentially; they share default port. + npm audit checks dev dependencies in npm run check/Cargo check/release; + it does not audit Rust, delivered browser code, or containers. cargo-deny + remains the separate strict Rust dependency audit. 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. + Generated app.js/worker.js/wasi.mjs retain public URLs, AGPL headers, + recognized @license/@license-end markers. JavaScript license table links + each file to complete corresponding TypeScript/Rust source archive. + Classic scripts/importScripts preserve LibreJS compatibility. No runtime + module loader or third-party browser scripts added. + + Local native-server tests serve var/build/typescript. Release packages files + into bin/chat/web and bin/chat/wasi.mjs; containers serve packaged files. + Copy HTML/CSS explicitly; never substitute TypeScript for executable JS. + /SOURCE.tar.gz contains TypeScript, shared declarations, every compiler config, + npm lock, tests/build scripts, Cargo-vendored dependencies, verified OpenSSL + archive. Node/npm/TypeScript are general-purpose development tools pinned and + documented here. Exclude installed copies/downloaded browsers. + + Source exports/releases/backups carry root npm manifests/TypeScript configs. + Activation/restored prebuilt images need no destination Node/npm/TypeScript/ + Rust. Preserve single private root .env and persistent data. Source archive + excludes .env, credentials, runtime DBs, exports, .git, node_modules, build/cache + directories. Root .env.example remains public; no extra environment file. + + Test generated JavaScript after every compiler upgrade. Static types cannot + guarantee privacy, security, or LibreJS recognition. Existing runtime/Rust + still enforce browser storage restrictions, protocol validation, algorithms. |