diff --git a/AGENTS.md b/AGENTS.md deleted file mode 120000 index 42061c01a1..0000000000 --- a/AGENTS.md +++ /dev/null @@ -1 +0,0 @@ -README.md \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..7964aa76d0 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,58 @@ +# Welcome to the Outline Monorepo! + +This document provides a guide for AI and human agents working with the Outline codebase. + +## Repository Structure + +The Outline monorepo is organized into three main components: + +* `/client`: The Outline Client application, available on all major platforms. See [`client/AGENTS.md`](client/AGENTS.md). +* `/server_manager`: A graphical application to create and manage Outline Servers. See [`server_manager/AGENTS.md`](server_manager/AGENTS.md). +* `/infrastructure`: The build system and shared TypeScript utilities. See [`infrastructure/AGENTS.md`](infrastructure/AGENTS.md). + +## The `npm run action` Command + +The primary entry point for all development tasks is `npm run action `, which resolves to `.action.sh` or `.action.mjs` files in the repo. Run `npm run action list` to see all available actions. Pass flags after `--`: + +```sh +npm run action client/src/cordova/setup macos -- --buildMode=release +``` + +### Common Actions + +* `npm run action list`: Lists all available actions. +* `npm run action client/web/start`: Starts a dev server for the shared web UI. +* `npm run action server_manager/www/start`: Starts a dev server for the Manager UI. +* `npm run action /test`: Runs tests (e.g. `npm run action client/web/test`). +* `npm run action /build`: Builds a component (e.g. `npm run action client/electron/build linux`). + +### Other useful commands + +* `npm run reset`: Clean and reinstall all dependencies (fixes most build issues). +* `npm run storybook`: Launch the Storybook UI component explorer. +* `npm run lint:gts`: Lint TypeScript (pass filepaths on macOS; works on all files on Linux). + +## Code Style + +* **TypeScript**: Follows [Google's TypeScript style](https://google.github.io/styleguide/tsguide.html), enforced by [`gts`](https://github.com/google/gts). Run `npm run lint:gts` to check and `npm run format:all` to auto-fix (Linux only for whole codebase; pass specific filepaths on macOS). +* **Go**: Follows standard Go style. Use `gofmt` and `go vet`. + +## Requirements + +| Component | Version | +|-----------|---------| +| Node.js | 22 — run `nvm use` if you have nvm | +| Go | 1.22+ | + +Platform-specific requirements (Android SDK, Xcode, zig for cross-compilation) are documented in the relevant subdirectory AGENTS.md files. + +## Common Concepts + +* **Access Keys**: Credentials used by Outline clients to connect to an Outline server. Generated by the Outline Manager. +* **Shadowbox**: The core proxy component of Outline, responsible for handling network traffic. +* **Outline Client**: The end-user application for connecting to the internet through an Outline server. +* **Server Manager**: The application used to create and manage Outline servers on cloud providers. +* **Electron**: Framework used to build the desktop versions of the Outline Client and Server Manager. +* **Cordova**: Framework used to build the mobile (iOS/Android) and macOS versions of the Outline Client. +* **Lit**: The UI framework for web components. All new components use Lit. The client has fully migrated; the server_manager still has legacy Polymer components in its app shell being migrated. +* **OutlineAction**: A custom build script (`.action.sh` or `.action.mjs`) that defines a task runnable via `npm run action`. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000000..47dc3e3d86 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/README.md b/README.md index a0799dffed..705626ba0c 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,8 @@ Outline makes it easy for anyone to create a VPN server, allowing you to share a Interested in **contributing to Outline?** See our [Contributing Guide](CONTRIBUTING.md) for more information. +See [AGENTS.md](./AGENTS.md) for AI agent and developer guidance. + You can also **join the Outline Community** by signing up for the [IFF Mattermost](https://wiki.digitalrights.community/index.php?title=IFF_Mattermost)! For customer support and to **contact us directly**, go to https://support.getoutline.org. diff --git a/client/AGENTS.md b/client/AGENTS.md deleted file mode 120000 index 42061c01a1..0000000000 --- a/client/AGENTS.md +++ /dev/null @@ -1 +0,0 @@ -README.md \ No newline at end of file diff --git a/client/AGENTS.md b/client/AGENTS.md new file mode 100644 index 0000000000..d34113844d --- /dev/null +++ b/client/AGENTS.md @@ -0,0 +1,71 @@ +# Outline Client Logo  Outline Client + +This document provides a guide for AI and human agents working on the Outline Client. + +## Directory Structure + +The `/client` directory contains the source code for all Outline client applications. Here's a breakdown of the key subdirectories: + +* `/electron`: Contains the Electron-specific code for the desktop client, including the main process, preload scripts, and build configurations. +* `/go`: Contains shared Go source code that is used across platforms for networking and other functionality that cannot be done on the browser. +* `/src/cordova`: Contains the Cordova-specific code for the mobile (iOS and Android) and macOS (via Mac Catalyst) clients. +* `/src/www`: Contains the shared web-based UI components, built with TypeScript. This code is used by both the Electron and Cordova applications. + +## Key Technologies + +* **Electron**: Used to build the desktop client for Windows and Linux. +* **Cordova**: Used to build the clients for macOS, iOS, Android. +* **[Lit](https://lit.dev/)**: The UI framework for all web components in the client. +* **TypeScript**: Used for all web-based code. +* **Go**: Used to implement the networking and other shared code. + +## Building and Running the Client + +The `npm run action` command is used to build and run the client applications. + +### Shared Web App Development + +If you are making changes to the shared web app and do not need to test platform-specific functionality, you can test in a desktop browser by running: + +```sh +npm run action client/web/start +``` + +The app logic is located in `src/www/app`. UI components are located in `src/www/ui_components`. To work on an individual UI element, use Storybook: + +```sh +npm run storybook +``` + +### Electron Client + +* **Build (Linux)**: `npm run action client/electron/build linux` +* **Build (Windows)**: `npm run action client/electron/build windows` + +### Cordova Clients + +* **Build (Android)**: `npm run action client/src/cordova/build android` +* **Build (iOS)**: `npm run action client/src/cordova/build ios` +* **Build (macOS)**: `npm run action client/src/cordova/build macos` + +### Configuration Flags + +Certain actions take configuration flags. Since they are run through `npm`, you must use the `--` separator to pass them to the underlying process. For example: + +```sh +SENTRY_DSN= npm run action client/src/cordova/setup macos -- --buildMode=release --versionName= +``` + +## Testing the Client + +* **Web Components**: `npm run action client/web/test` +* **Go Backend**: `go test -race -bench=. -benchtime=100ms ./client/...` +* **OutlineAppleLib (macOS)**: `npm run action client/src/cordova/test macos` +* **OutlineAppleLib (iOS)**: `npm run action client/src/cordova/test ios` + +## Additional Resources + +* [Life of a Packet](/docs/life_of_a_packet.md): Learn how the Outline Client works. +* [Developing for Apple (macOS and iOS)](src/cordova/apple) +* [Developing for Android](src/cordova/android) +* [Developing for Electron (Windows and Linux)](electron) diff --git a/infrastructure/AGENTS.md b/infrastructure/AGENTS.md new file mode 100644 index 0000000000..7334893c83 --- /dev/null +++ b/infrastructure/AGENTS.md @@ -0,0 +1,39 @@ +# Outline Infrastructure + +This document provides a guide for AI agents working with the Outline infrastructure. + +## Directory Structure + +The `/infrastructure` directory contains the build system, deployment scripts, and other application-independent code for the Outline project. + +* `/build`: Contains the core scripts for the `npm run action` command. +* `*.ts`: Various TypeScript files providing utility functions for the build system and applications, similar to third-party dependencies. + +## The `npm run action` Build System + +The `npm run action` command is the heart of the Outline build system. It is implemented as a set of Node.js scripts in the `/infrastructure/build` directory. The main entry point is `run_action.mjs`, which parses the command-line arguments and executes the corresponding action script. + +### Creating a New Action + +To create a new action, you need to create a new `.mjs` file in the appropriate directory that matches the `*.action.mjs` naming convention (e.g., `server_manager/www/my_action.action.mjs`). This file should export a default function that will be executed when the action is run. + +The function will be passed an `options` object containing the command-line arguments. You can use the utility functions in `/infrastructure` to perform common tasks like spawning processes, downloading files, and creating reload servers. + +### Example Action + +```javascript +// server_manager/www/my_action.action.mjs +import { spawnStream } from '../../infrastructure/build/spawn_stream.mjs'; + +export default async function(options) { + await spawnStream('echo', ['Hello, World!']); +} +``` + +This action can be run with the command `npm run action server_manager/www/my_action`. + +## Testing the Infrastructure + +The infrastructure code can be tested by running the following command: + +`npm run action infrastructure/test` diff --git a/server_manager/AGENTS.md b/server_manager/AGENTS.md deleted file mode 120000 index 42061c01a1..0000000000 --- a/server_manager/AGENTS.md +++ /dev/null @@ -1 +0,0 @@ -README.md \ No newline at end of file diff --git a/server_manager/AGENTS.md b/server_manager/AGENTS.md new file mode 100644 index 0000000000..16e8b32c3f --- /dev/null +++ b/server_manager/AGENTS.md @@ -0,0 +1,72 @@ +# Outline Server Manager + +This document provides a guide for AI and human agents working on the Outline Server Manager. + +## Directory Structure + +The `/server_manager` directory contains the source code for the Outline Server Manager, which is available as a web-based application and an Electron desktop application. + +* `/www`: Contains the web application that serves as the main UI for the Server Manager. +* `/electron`: Houses the Electron-specific code for the desktop version of the Server Manager. +* `/cloud`: Includes the APIs for interacting with cloud providers like DigitalOcean and Google Cloud Platform. +* `/install_scripts`: Contains the shell scripts used to install and configure Outline servers on various cloud providers. + +## Key Technologies + +* **Lit**: The primary UI framework for the Server Manager's web-based components. New components use Lit. +* **Polymer**: Still used in legacy app shell components (`/www/ui_components/`). Being migrated to Lit. +* **Electron**: Used to build the desktop version of the Server Manager. +* **TypeScript**: Used for all web-based code. +* **Shadowbox**: The core proxy component of Outline, which is managed by the Server Manager. + +## Prerequisites + +Ensure you have installed Node.js and have run `npm ci` in the root directory. + +## Building and Running the Server Manager + +The `npm run action` command is used to build and run the Server Manager. + +### Web Application + +* **Build**: `npm run action server_manager/www/build` +* **Run for development**: `npm run action server_manager/www/start` + +### Electron Application + +* **Build**: `npm run action server_manager/electron/build ${PLATFORM}` +* **Run**: `npm run action server_manager/electron/start ${PLATFORM}` +* **Run with development build**: `BUILD_ENV=development npm run action server_manager/electron/start ${PLATFORM}` + +Where `${PLATFORM}` is one of `linux`, `macos`, `windows`. If omitted, it assumes the host platform. + +### Packaging + +To build the app binary: + +``` +npm run action server_manager/electron/package ${PLATFORM} -- --buildMode=[debug,release] +``` + +The per-platform standalone apps will be at `output/build/server_manager/electron/static/dist`: + +- **Windows**: `.exe` — only generated if [wine](https://www.winehq.org/download) is installed. +- **Linux**: `.AppImage` +- **macOS**: `.dmg` and `.zip` (both required for auto-update). You may need to run `security unlock-keychain login.keychain` so electron-builder has access to your certificates. + +## Debugging + +You can run an existing binary in debug mode by setting `OUTLINE_DEBUG=true`. This will enable the Developer menu on the application window. + +## Error Reporting + +To enable error reporting through [Sentry](https://sentry.io/) for local builds, run: + +```bash +export SENTRY_DSN=[Sentry DSN URL] +npm run action server_manager/electron/start ${PLATFORM} +``` + +## Testing the Server Manager + +* **Web Application**: `npm run action server_manager/test` diff --git a/server_manager/README.md b/server_manager/README.md index f9ef817365..34aa221c20 100644 --- a/server_manager/README.md +++ b/server_manager/README.md @@ -85,6 +85,12 @@ The per-platform standalone apps will be at `output/build/server_manager/electro > NOTE: If you are building for macOS, you may need to run `security unlock-keychain login.keychain` so electron-builder has access to your certificates. +## Testing + +``` +npm run action server_manager/test +``` + ## Error reporting To enable error reporting through [Sentry](https://sentry.io/) for local builds, run: