docs: run_app, commands/testkit, waybetter release and waybetter/build
This commit is contained in:
parent
6eb1dd496a
commit
af1b240179
1 changed files with 52 additions and 8 deletions
60
README.md
60
README.md
|
|
@ -50,8 +50,10 @@ npm create waybetter app -- --site kick.com # a whole app: Tauri 2 + waybetter
|
||||||
|
|
||||||
`create-waybetter` (in `packages/create-waybetter`) asks for what it needs in a terminal, and
|
`create-waybetter` (in `packages/create-waybetter`) asks for what it needs in a terminal, and
|
||||||
takes every answer as a flag (`--help`). The app skeleton is this README in code: the native
|
takes every answer as a flag (`--help`). The app skeleton is this README in code: the native
|
||||||
`SiteSpec`, the page `SiteAdapter`, the three capability files, a shell that reports the tab
|
`SiteSpec`, the page `SiteAdapter`, the app on `waybetter_host::app` (its config, site hooks and
|
||||||
rectangle (`tabs_sync`), the plugin store and one site-only command, with presets for
|
its own commands), the three capability files and a `tests/security.rs` on `waybetter_host::testkit`,
|
||||||
|
a shell that reports the tab rectangle (`tabs_sync`), the plugin store, one site-only command, the
|
||||||
|
runtime bundled with `waybetter/build` and a `waybetter.release.json` for `waybetter release`, with presets for
|
||||||
youtube.com, kick.com and twitch.tv and every site selector marked as a placeholder. Its tests
|
youtube.com, kick.com and twitch.tv and every site selector marked as a placeholder. Its tests
|
||||||
generate each kind into a temp folder and check it against the real contracts: plugin headers with
|
generate each kind into a temp folder and check it against the real contracts: plugin headers with
|
||||||
`plugins::parse_meta`, plugin code against `createCorePluginApi`'s members, themes against
|
`plugins::parse_meta`, plugin code against `createCorePluginApi`'s members, themes against
|
||||||
|
|
@ -87,6 +89,10 @@ crates/waybetter-host/ Rust: security policy, profiles, plugin store, hotfi
|
||||||
src/store/ install links, download allow-list, signed multi-app store catalog, staging
|
src/store/ install links, download allow-list, signed multi-app store catalog, staging
|
||||||
and installs; downloads with feature "net" (docs/STORE.md)
|
and installs; downloads with feature "net" (docs/STORE.md)
|
||||||
src/host.rs (feature "tauri") webview helpers, shell events, system menu
|
src/host.rs (feature "tauri") webview helpers, shell events, system menu
|
||||||
|
src/app.rs (feature "app") the whole app around a site: run_app / App, AppConfig,
|
||||||
|
SiteHooks, the window, shell and tab webviews, the generic commands
|
||||||
|
src/commands.rs the commands the host serves and who may call them; manifest() for build.rs
|
||||||
|
src/testkit.rs capability/caller-check assertions for an app's tests/security.rs
|
||||||
packages/runtime/src/ page runtime core (TypeScript, no dependencies)
|
packages/runtime/src/ page runtime core (TypeScript, no dependencies)
|
||||||
site.ts SiteAdapter (the page half of the adapter) + configureRuntime
|
site.ts SiteAdapter (the page half of the adapter) + configureRuntime
|
||||||
domHub.ts netHub.ts one MutationObserver/frame, one fetch/XHR hook per page
|
domHub.ts netHub.ts one MutationObserver/frame, one fetch/XHR hook per page
|
||||||
|
|
@ -112,7 +118,8 @@ packages/shell/src/ shell core (TypeScript, no dependencies)
|
||||||
installController.ts the install screen's state machine (links, drops, store items, confirm)
|
installController.ts the install screen's state machine (links, drops, store items, confirm)
|
||||||
InstallDialog.tsx StoreView.tsx store.css the install screen and the Store view (React peer, --wb-* tokens)
|
InstallDialog.tsx StoreView.tsx store.css the install screen and the Store view (React peer, --wb-* tokens)
|
||||||
packages/waybetter/ the published npm package (runtime + shell as ESM + .d.ts, theme.schema.json,
|
packages/waybetter/ the published npm package (runtime + shell as ESM + .d.ts, theme.schema.json,
|
||||||
store-catalog.schema.json, the `waybetter store build|sign|verify` command)
|
store-catalog.schema.json, the `waybetter store build|sign|verify` and
|
||||||
|
`waybetter release windows|macos` commands, `waybetter/build`)
|
||||||
docs/STORE.md the Store: shared catalog format, signing and keys, tooling, trust model, how to add it
|
docs/STORE.md the Store: shared catalog format, signing and keys, tooling, trust model, how to add it
|
||||||
packages/create-waybetter/ `npm create waybetter`: plugin, theme and app scaffolds (no dependencies)
|
packages/create-waybetter/ `npm create waybetter`: plugin, theme and app scaffolds (no dependencies)
|
||||||
```
|
```
|
||||||
|
|
@ -186,7 +193,7 @@ The security model is the same for every app and must stay keyed by webview labe
|
||||||
|
|
||||||
| webview | may call |
|
| webview | may call |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
| `shell` (local assets only) | app, settings, vault, tab management (`tabs_sync`, `tab_navigate`, `tab_action`, ...) |
|
| `shell` (local assets only) | app, settings, vault, and the host's `commands::SHELL` (`tabs_sync`, `tab_navigate`, `tab_action`, `shell_raise`, `profiles_*`, `i18n_*`, ...) |
|
||||||
| `tab-*` (any site) | only tab chrome about itself: `tab_report`, `tab_shortcut`, `tab_link_drag` |
|
| `tab-*` (any site) | only tab chrome about itself: `tab_report`, `tab_shortcut`, `tab_link_drag` |
|
||||||
| `tab-*` on the exact site origin | the app's short, reviewed list of site-only commands |
|
| `tab-*` on the exact site origin | the app's short, reviewed list of site-only commands |
|
||||||
| other local webviews (`popover-*`, ...) | their own narrow capability |
|
| other local webviews (`popover-*`, ...) | their own narrow capability |
|
||||||
|
|
@ -208,8 +215,32 @@ caller's label, the webview's own URL (never the page's claim), payload bounds.
|
||||||
about itself; the account it reports is recorded only for its own profile, only while it is on the
|
about itself; the account it reports is recorded only for its own profile, only while it is on the
|
||||||
site, and a shell save can never change it (`ProfileSettings::keep_accounts_from`).
|
site, and a shell save can never change it (`ProfileSettings::keep_accounts_from`).
|
||||||
|
|
||||||
|
`waybetter_host::testkit` checks this in an app's own tests: `Capabilities::from_dir` reads every
|
||||||
|
capability file, `assert_host_commands` keeps the host's commands shell-only / tab-only,
|
||||||
|
`assert_shell_only` / `assert_tab_only` do the same for the app's, `assert_no_plugin_apis` refuses
|
||||||
|
Tauri plugin JS APIs, and `assert_guarded` / `assert_host_guards` check that each command's first
|
||||||
|
statement checks its caller.
|
||||||
|
|
||||||
## What the host gives an app
|
## What the host gives an app
|
||||||
|
|
||||||
|
- `app` (feature `app`): the whole app. `App::new(AppConfig, hooks).setup(..).run(context,
|
||||||
|
handler)` (or `run_app`) registers single-instance, deep-link (opt-in), window-state, opener,
|
||||||
|
updater (opt-in), process, notification and dialog; makes the app-data folder (0700 on Unix),
|
||||||
|
loads the profiles and the language, runs the app's setup, then builds the window (frameless
|
||||||
|
with the shell's titlebar, or the OS frame), restores its geometry (lost geometry reset),
|
||||||
|
routes helper-window closes (Windows), follows window resizes natively and adds the shell
|
||||||
|
webview (transparent: it can rise above the tabs; macOS needs the `macos-private-api` feature).
|
||||||
|
It serves `commands::SHELL` (`tabs_sync`, `tab_navigate`, `tab_action`, `open_external_url`,
|
||||||
|
`shell_focus`, `shell_raise`, `window_system_menu`, `profiles_get`/`profiles_set`,
|
||||||
|
`i18n_get`/`i18n_set`) and `commands::TAB` (`tab_shortcut`, `tab_link_drag`), each checking its
|
||||||
|
caller first, and dispatches every other command to the app's handler. Tab webviews get their
|
||||||
|
profile's data folder, the app's document-start scripts, navigation/pop-up/load/title/download
|
||||||
|
handling, stills and memory targets; `SiteHooks` is where the app says what only it knows (page
|
||||||
|
scripts, legacy domains, link routing, per-tab state, what a finished site page gets). Helpers:
|
||||||
|
`profiles`, `tab_profile`, `account_seen`, `tr`/`trf`, `i18n_page_script`, `notify`,
|
||||||
|
`open_external`.
|
||||||
|
- `commands`: the host's command list and `manifest(&[..])` for the app's `build.rs`.
|
||||||
|
- `testkit`: see the capabilities section.
|
||||||
- `policy`: `SHELL_LABEL`, `tab_id`, `require_local`, `require_site_tab`, `clamp_tab_rect` (tabs never
|
- `policy`: `SHELL_LABEL`, `tab_id`, `require_local`, `require_site_tab`, `clamp_tab_rect` (tabs never
|
||||||
cover the titlebar or, while restored, the resize band).
|
cover the titlebar or, while restored, the resize band).
|
||||||
- `profiles`: `ProfileSettings` (validated, default profile required, profiles with open tabs cannot be
|
- `profiles`: `ProfileSettings` (validated, default profile required, profiles with open tabs cannot be
|
||||||
|
|
@ -247,15 +278,28 @@ site, and a shell save can never change it (`ProfileSettings::keep_accounts_from
|
||||||
`read_json`/`write_json`, `remove_profile_dirs`, `prune_profile_dirs`, `migrate_identifier`,
|
`read_json`/`write_json`, `remove_profile_dirs`, `prune_profile_dirs`, `migrate_identifier`,
|
||||||
`system_menu`.
|
`system_menu`.
|
||||||
|
|
||||||
The app keeps its own `#[tauri::command]` wrappers, so IPC command names, the build-time command
|
The app keeps its own `#[tauri::command]` wrappers for everything else, and its capability files;
|
||||||
manifest and the capability files stay in the app.
|
its `build.rs` lists its commands through `commands::manifest`, which adds the host's.
|
||||||
|
|
||||||
|
The npm package adds the app-side tooling:
|
||||||
|
|
||||||
|
- `waybetter/build`: `buildRuntime({ entry, outfile, catalog, prefixes, ... })` bundles a page
|
||||||
|
runtime into one IIFE with the app's esbuild (`?inline` CSS as text, other CSS dropped, only the
|
||||||
|
runtime's own catalog prefixes compiled in).
|
||||||
|
- `waybetter release windows|macos`: signed native releases and the update manifest from the
|
||||||
|
app's `waybetter.release.json` (product and file names, key folder, CDN and API URLs, an optional
|
||||||
|
manifest validator). Windows: the signed NSIS build, the installer and `.sig` in
|
||||||
|
`<outDir>/upload`, `latest.json` (other platforms of the version kept); macOS: signs a universal
|
||||||
|
build's updater bundle and adds both darwin platforms. It never uploads: it prints the steps.
|
||||||
|
The key is read only into the build's environment or handed to the Tauri signer by path.
|
||||||
|
|
||||||
## Consuming it
|
## Consuming it
|
||||||
|
|
||||||
wayBetter for X adds this repository as a git submodule at `waybetter/` and consumes it from source:
|
wayBetter for X adds this repository as a git submodule at `waybetter/` and consumes it from source:
|
||||||
|
|
||||||
- Rust: a path dependency, `waybetter-host = { path = "../../../waybetter/crates/waybetter-host" }`,
|
- Rust: a path dependency, `waybetter-host = { path = "../../../waybetter/crates/waybetter-host" }`,
|
||||||
with `features = ["tauri", "net"]` enabled by the app's desktop feature.
|
with `features = ["app", "net", "macos-private-api"]` enabled by the app's desktop feature (and
|
||||||
|
as a build-dependency for `commands::manifest`).
|
||||||
- TypeScript: relative imports of `waybetter/packages/*/src/*.ts` from a few adapter modules. The
|
- TypeScript: relative imports of `waybetter/packages/*/src/*.ts` from a few adapter modules. The
|
||||||
packages are not Bun workspace members of the app on purpose: the app's server CI clones without
|
packages are not Bun workspace members of the app on purpose: the app's server CI clones without
|
||||||
submodules and runs `bun i`, which fails when a declared workspace package is missing; and Node's
|
submodules and runs `bun i`, which fails when a declared workspace package is missing; and Node's
|
||||||
|
|
@ -273,7 +317,7 @@ bun run test:rust
|
||||||
bun run test:create # scaffolds into temp dirs; its cargo check of an app is ~1 min cold
|
bun run test:create # scaffolds into temp dirs; its cargo check of an app is ~1 min cold
|
||||||
# (WAYBETTER_SKIP_CARGO_CHECK=1 skips it; needs the local crate cache)
|
# (WAYBETTER_SKIP_CARGO_CHECK=1 skips it; needs the local crate cache)
|
||||||
bun run check # typecheck + build:packages + test
|
bun run check # typecheck + build:packages + test
|
||||||
bun run check:tauri # cargo check with the tauri feature (slow: builds Tauri)
|
bun run check:tauri # cargo check with the app feature (slow: builds Tauri and its plugins)
|
||||||
bun run build # typecheck + cargo build
|
bun run build # typecheck + cargo build
|
||||||
bun run pack:check # npm pack --dry-run of waybetter and create-waybetter
|
bun run pack:check # npm pack --dry-run of waybetter and create-waybetter
|
||||||
```
|
```
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue