Architecture

Runtime Flow

1. pier <name> <cmd...> wraps portless and records <name>.localhost -> cwd
2. CLI ensures the bridge process is running
3. Extension content script activates only on localhost-style pages
4. Content script opens WebSocket /terminal with token and page context
5. Bridge resolves the page hostname using the workspace registry
6. Bridge creates or reuses shell session (node-pty with pipe fallback)
7. xterm.js renders terminal output in-page

Repository Structure

• packages/shared: shared constants, settings normalization, and WebSocket protocol helpers
• packages/cli-core: CLI commands, config store, workspace routing registry
• packages/bridge-core: bridge HTTP/WebSocket server and shell session management
• packages/extension-src: extension source and static assets
• extension/: generated unpacked extension output
• cli/, server/, and bin/: JS shims loading compiled dist output

Extension Build Pipeline

pnpm run build:extension bundles the shared runtime, content script, options UI, copies static extension assets, and removes stale vendored JS.

Packaging Model

• Published package is a single npm package: @malviyahimanshu/pier
• Internal packages are implementation details
• prepack runs build and checks so published tarballs include generated extension output and compiled dist files