| name | xstream-dev-constraints |
| description | Use this skill before writing or reviewing any Flutter/Dart, Go FFI, or build-script code in the Xstream repo. It enforces non-negotiable product semantics, architecture rules, coding conventions, and App Store compliance constraints that apply to every change in this project. Always read this before suggesting API designs, UI copy, or implementation approaches. |
Xstream Development Constraints
Authoritative constraint set for every code change in this repository.
Read before implementing, reviewing, or suggesting any code, UI copy, or documentation.
1. Product Semantics (Non-negotiable)
Xstream is a legal System VPN / Secure Network Tunnel for macOS App Store distribution.
1.1 Approved Vocabulary
Use only these terms in UI copy, docs, code comments, and variable names:
| ✅ Use | ❌ Never use |
|---|
| Secure Tunnel | bypass / circumvent / break through |
| System VPN | any country or region name |
| Packet Tunnel | censorship / blocking / restriction |
| Encrypted Network | proxy (as a primary feature term) |
| Network Acceleration | VPN workaround / alternative path |
| Network Reliability | — |
| Privacy Protection | — |
| System-level Networking | — |
1.2 Architecture Constraints
- System-wide networking must only use NEPacketTunnelProvider (Packet Tunnel).
- DNS (including DoT) is treated as part of the secure tunnel — never a workaround.
- Prohibited: user-space TUN hacks, TUN + SOCKS forwarding, sudo routing, proxy env vars.
2. Flutter / Dart Coding Rules
2.1 State Management
- Global state lives in
lib/utils/global_config.dart (GlobalState, ValueNotifier).
- Never manipulate service objects directly from the view layer.
- Use
ValueListenableBuilder to react to state changes.
2.2 Localization
- All UI-facing strings must use
context.l10n.get('key').
- Adding a new key? Add both
en and zh translations in lib/l10n/app_localizations.dart in the same commit.
- Never hardcode Chinese or English text in widget code.
2.3 Logging
- Use
addAppLog(...) for application-level logs.
- Never use
print(...) in production code paths.
- No sensitive data (passwords, tokens, UUIDs) in logs.
2.4 Async & Error Handling
- Always
await async calls and wrap in try/catch.
- Surface errors to the user via
SnackBar or Dialog — never swallow silently.
2.5 Screen / AppBar Embedding Rule
- Screens embedded inside
MainPage (IndexedStack) must not render their own AppBar.
- The outer
MainPage provides the breadcrumb AppBar for all embedded pages.
- Screens that can be pushed via
Navigator.push independently must render their own AppBar.
- Use a constructor parameter (e.g.
breadcrumbItems) to distinguish the two cases.
2.6 Native Interaction
- Prefer service-layer methods (
VpnConfigService, NativeBridge) over raw FFI in view code.
- Do not handle file paths, permissions, or FFI details in screen widgets.
2.7 Lint & Format
- All Dart changes must pass
flutter analyze with zero new issues.
- Format with
dart format . before committing.
- Local
// ignore suppressions must include a reason comment.
3. Go FFI Rules
- Every exported function must return a result string or an explicit error code — never panics.
- Pointers created via
C.CString / C.malloc must have a corresponding FreeCString (Go side). The Flutter caller must free after use.
- Platform-specific logic →
bridge_<platform>.go. Shared exported functions → bridge.go only.
- macOS system networking is handled by the Swift
PacketTunnel extension, not Go code.
4. Build & Version Rules
4.1 Version Source of Truth
- Version is defined only in
pubspec.yaml (format: MAJOR.MINOR.PATCH+BUILD).
- Before an Xcode Archive, run:
make sync-macos-config
This regenerates macos/Flutter/ephemeral/Flutter-Generated.xcconfig so Xcode picks up the correct MARKETING_VERSION and CURRENT_PROJECT_VERSION.
4.2 Makefile Targets (canonical names)
| Goal | Command |
|---|
| macOS ARM64 release + DMG | make build-macos-arm64 |
| macOS x64 release + DMG | make build-macos-x64 |
| Sync Xcode config | make sync-macos-config |
| iOS release IPA | make build-ios-ipa |
| Windows x64 | make build-windows-x64 |
| Linux x64 | make build-linux-x64 |
| Clean | make clean |
4.3 PR Checklist
5. Resources & Templates
- New static assets →
assets/ + register in pubspec.yaml.
- Modifying
lib/templates/ → sync services/vpn_config_service.dart in the same commit.
- Changing default config / example nodes → update
docs/user-manual.md.
When to Call This Skill
Call before:
- Writing any new screen, widget, or service
- Proposing UI copy or localization keys
- Touching build scripts, Makefile, or Xcode config
- Reviewing a PR that touches core VPN logic or App Store metadata
