v1.0.1
This commit is contained in:
131
PROJECT.md
Normal file
131
PROJECT.md
Normal file
@@ -0,0 +1,131 @@
|
||||
# HPL Toolbox — Project Summary for AI
|
||||
|
||||
## What this project is
|
||||
|
||||
HPL Toolbox is an internal tool for a playable ad team. It ships as **two separate deliverables** from the same repo:
|
||||
|
||||
1. **VS Code Extension** (`src/`) — a `.vsix` that adds tool panels as webview tabs inside VS Code.
|
||||
2. **Standalone Windows App** (`standalone/`) — a Go + WebView2 desktop app that exposes the same tools through a local HTTP server rendered in a native window. It is a **real, complete, production app** — not a prototype or subset.
|
||||
|
||||
Both deliverables implement the same set of tools. New features are typically added to both.
|
||||
|
||||
---
|
||||
|
||||
## Directory structure
|
||||
|
||||
```
|
||||
HPLToolbox-Extension/
|
||||
├── src/
|
||||
│ ├── extension.ts # Extension entry point, registers commands
|
||||
│ ├── tools/ # One file per tool (VS Code webview panels)
|
||||
│ │ ├── shared.ts # Shared utilities: singletonPanel, webview styles, clipboard/open handlers
|
||||
│ │ ├── plecUpload.ts # PLEC Upload tool
|
||||
│ │ ├── applovin.ts # AppLovin Playable Preview
|
||||
│ │ ├── base64Scanner.ts # Base64 Scanner
|
||||
│ │ ├── mraidChecker.ts # MRAID Checker
|
||||
│ │ ├── mintegral.ts # Mintegral Checker
|
||||
│ │ ├── sendToMobile.ts # Send To Mobile
|
||||
│ │ ├── playworks.ts # Playworks Converter
|
||||
│ │ ├── deviceSimulator.ts# Device Simulator
|
||||
│ │ └── projectInit.ts # Initialize Project
|
||||
│ └── tools.json # Tool launcher config (name, command, icon, description)
|
||||
├── standalone/ # The Go standalone app — complete, production-grade
|
||||
│ ├── main.go # Entry point: HTTP server + WebView2 window + route registration
|
||||
│ ├── platform.go # AppConfig struct, defaultConfig(), LoadConfig/SaveConfig, OS helpers
|
||||
│ ├── settings.go # /api/settings POST endpoint; settings modal HTML
|
||||
│ ├── layout.go # Shared HTML layout, nav sidebar, CSS
|
||||
│ ├── home.go # Home page / tool launcher
|
||||
│ ├── plec.go # PLEC Upload: page HTML, pick endpoints, upload (legacy + WordPress)
|
||||
│ ├── applovin.go # AppLovin upload
|
||||
│ ├── base64.go # Base64 Scanner
|
||||
│ ├── mraid.go # MRAID Checker
|
||||
│ ├── mintegral.go # Mintegral Checker
|
||||
│ ├── mobile.go # Send To Mobile
|
||||
│ ├── playworks.go # Playworks Converter
|
||||
│ ├── device_simulator.go # Device Simulator
|
||||
│ ├── project_init.go # Initialize Project
|
||||
│ ├── changelog.go # Changelog page
|
||||
│ ├── json.go # newJSONStream helper (NDJSON streaming responses)
|
||||
│ ├── update_checker.go # Auto-update check against Gitea release API
|
||||
│ ├── single_instance.go # Single-instance lock via TCP port file
|
||||
│ └── assets/ # Embedded static assets (qrcode.min.js, mintegral preview util)
|
||||
├── scripts/
|
||||
│ ├── build.ps1 # Builds both .vsix and standalone exe into dist/
|
||||
│ └── run-standalone.ps1 # Runs the standalone app in dev mode (go run .)
|
||||
├── data/
|
||||
│ └── manifest.json # Project Init manifest (team template files list)
|
||||
├── aiAssets/ # Sample HTML files used for testing/reference
|
||||
├── package.json # Extension manifest, VS Code settings contributions, npm scripts
|
||||
├── tsconfig.json
|
||||
└── README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tools
|
||||
|
||||
| Tool | Description |
|
||||
|---|---|
|
||||
| PLEC Upload | Upload HTML playable files to internal PLEC servers. Supports two servers: Default (167.99.227.249, legacy PHP) and Backup (20.255.60.183, WordPress). Backup server uses auto-login via credentials. |
|
||||
| AppLovin Playable Preview | Upload HTML files to p.applov.in and generate QR preview links. |
|
||||
| Base64 Scanner | Scan HTML files for external or non-base64 asset references. |
|
||||
| Send To Mobile | Serve selected HTML files over LAN and display a QR code for mobile preview. |
|
||||
| MRAID Checker | Check HTML files against MRAID requirements and best practices. |
|
||||
| Mintegral Checker | Validate Mintegral playable ZIPs against PlayTurbo requirements with embedded runtime preview. |
|
||||
| Playworks Converter | Convert Playworks HTML into per-network variants. |
|
||||
| Device Simulator | Preview HTML playables inside accurate mobile device frames with notch/Dynamic Island overlays. |
|
||||
| Initialize Project | Download team template files from a shared manifest (Google Drive or direct URL). |
|
||||
|
||||
---
|
||||
|
||||
## Architecture notes
|
||||
|
||||
### VS Code Extension
|
||||
- Each tool is a singleton webview panel (`singletonPanel` in `shared.ts`).
|
||||
- The panel HTML is returned as a template string from `getHtml()` inside each tool file.
|
||||
- Communication between extension host and webview uses `panel.webview.postMessage` / `onDidReceiveMessage`.
|
||||
- Settings are read from `vscode.workspace.getConfiguration('hplToolbox.*')` and contributed in `package.json`.
|
||||
- Session-persistent UI state (e.g. last selected server) uses `context.globalState`.
|
||||
|
||||
### Standalone App
|
||||
- Go HTTP server on a random localhost port, served into a WebView2 window.
|
||||
- All pages return full HTML strings (no template files on disk).
|
||||
- Long-running operations (uploads, scans) use `newJSONStream` to stream NDJSON progress events — the browser reads these with `ReadableStream` and updates the UI incrementally.
|
||||
- Config is persisted to `%LOCALAPPDATA%\HPLToolbox\config.json` via `LoadConfig` / `SaveConfig`.
|
||||
- `localStorage` is used for lightweight UI-only state (e.g. last selected server in PLEC Upload).
|
||||
- Single-instance enforcement: on launch, tries to connect to a previous instance's port from a lock file and `POST /api/focus` to bring its window forward, then exits.
|
||||
|
||||
### PLEC Upload — dual server detail
|
||||
- **Default (legacy)**: `POST http://167.99.227.249/src/upload_HTML_Experimental.php` with `fileUpload_N` / `iterationNameUpload_N` fields. Filenames are timestamped.
|
||||
- **Backup (WordPress)**: `POST http://20.255.60.183/wp-admin/admin-ajax.php` with `action=plec_upload_files`, `nonce`, `rows` (JSON array), and `file_N` fields. Login flow: POST `/wp-login.php` → GET `/file-upload/` to extract nonce. Iteration name is used as the uploaded filename. Preview URL is constructed as `/preview?theme=calcite&n1=<original>&m1=<saved>`.
|
||||
|
||||
---
|
||||
|
||||
## Build
|
||||
|
||||
```powershell
|
||||
npm run build # builds both .vsix and standalone .exe into dist/
|
||||
npm run build -- -Extension # .vsix only
|
||||
npm run build -- -Standalone # .exe only
|
||||
npm run run-standalone # dev: go run . in standalone/
|
||||
npm run compile # tsc only
|
||||
npm run watch # tsc watch
|
||||
```
|
||||
|
||||
Requires: Node.js, TypeScript (`npm install`), Go, optionally `vsce` and `rsrc`.
|
||||
|
||||
---
|
||||
|
||||
## Key config (VS Code settings)
|
||||
|
||||
All under `hplToolbox.*`:
|
||||
|
||||
| Key | Default | Purpose |
|
||||
|---|---|---|
|
||||
| `plec.uploadUrl` | `http://167.99.227.249/src/upload_HTML_Experimental.php` | Legacy server endpoint |
|
||||
| `plec.originUrl` | `http://167.99.227.249` | Origin/Referer for legacy uploads |
|
||||
| `plec.wpUsername` | `pm` | WordPress username for backup server |
|
||||
| `plec.wpPassword` | _(set)_ | WordPress password for backup server |
|
||||
| `applovin.cookie` | _(empty)_ | `__Host-APPLOVINID` cookie for p.applov.in |
|
||||
| `deviceSimulator.devicesUrl` | Google Drive link | Remote devices.json URL |
|
||||
| `deviceSimulator.languagesUrl` | Google Drive link | Remote languages.json URL |
|
||||
Reference in New Issue
Block a user