AS5Bridge

A VS Code extension that keeps your local workspace files in real-time sync with a remote AS5 (AppStack5) server via HTTP. Files are uploaded automatically when you save, downloaded when the remote version changes, and conflicts are resolved interactively.

Features

• Bidirectional sync — uploads on save, downloads remote changes when you open or switch to a file
• ETag-based version control — detects conflicts and lets you choose: update local, overwrite remote, or show diff
• In-memory sync tree — caches the remote file state in RAM; tab switches to known-current files require no HTTP round-trip
• TypeScript compilation — compiles .ts files on save using your project's tsconfig.json and uploads the resulting .js
• Service file navigation — CodeLens button and context menu command to jump from any .js/.ts file to the AS5 service file that includes it
• Read-only protection — synced files are locked for editing until you log in, preventing accidental changes
• Browser-based login — OAuth flow opens automatically when your token expires; no manual token handling
• File decorations — Explorer shows sync state directly on each file: ✓ synced, ! dirty (unsynced changes), ? in scope but never synced
• Sidebar panels — connections overview, dirty files list, and activity log in the activity bar
• Dirty files tracking — files that failed to sync are listed with one-click retry; automatically retried after login
• Gitignore-style exclusion — flexible ignore patterns to skip directories or file types
• Force Pull / Force Push — overwrite an entire folder in either direction after explicit confirmation
• Batched delete confirmation — deleting a folder or many files produces one prompt, not one per file
• Pause / Resume — temporarily stop auto-sync without losing your config
• Workspace setup — Setup command creates config, tsconfig.json, and .vscode/settings.json in one step

Requirements

• VS Code 1.82 or later
• Network access to your AS5 server

Getting Started

1. Install the extension

In VS Code: Extensions → ⋯ → Install from VSIX… and select the .vsix file.

2. Run Setup

Open the Command Palette (Ctrl+Shift+P) and run AS5B: Setup.

This creates four files in your workspace root (none are overwritten if they already exist):

3. Configure

Edit the generated .as5bridge-config.json:

{
    "host": "http://your-as5-host",
    "root": "/",
    "directories": ["/api/", "/varlibs/", "/web/"],
    "extensions": ["js", "ts", "html", "css", "less", "json", ""],
    "ignore": ["**/data/"],
    "maxParallelRequest": 20
}

4. Log in

Click the key icon in the status bar or run AS5B: Login from the Command Palette. A browser window opens for Google OAuth. After authenticating, the token is transferred automatically to the extension — no copy-paste required. The browser shows a confirmation page and can be closed. A full sync starts immediately.

Note: The token is never written to disk. It lives only in memory for the duration of the VS Code session.

File Decorations

AS5Bridge adds badges to files directly in the VS Code Explorer:

Decorations update automatically after every commit, download, config change, and login.

Status Bar Icons

Click the status bar item for a context-sensitive quick-action menu: login/setup (when needed), sync all, sync current file, pause/resume, force pull/push, open log.

Commands

Sync Behaviour

Automatic triggers

Conflict resolution

When a version conflict is detected you are prompted to choose:

• Lokal aktualisieren — download the remote version and discard local changes
• Remote überschreiben — force-push your local version to the server
• Diff anzeigen — open VS Code's built-in side-by-side diff viewer

After a 401 / token expiry

• The status bar switches to $(lock) and a login prompt appears
• All files that failed to commit are tracked in the dirty files panel
• After a successful login, files without a server copy are automatically retried

Service File Navigation

AS5 service files (files named .servicename.js) declare which source files they include. AS5Bridge scans your workspace for these files and:

• Shows a CodeLens button above the first line of any .js/.ts file that is referenced by a service file
• Adds AS5B: Zum Service-File springen to the right-click context menu

TypeScript Support

When you save a .ts file, AS5Bridge automatically:

1. Finds the nearest tsconfig.json by walking up the directory tree
2. Type-checks against the whole project (all files of the tsconfig, like tsc -p) — namespaces split across multiple files resolve correctly. Subsequent saves are incremental
3. Compiles in-process using the TypeScript compiler bundled with the extension (pinned to 6.x — the last major version that supports target: "es5", which the AS5 backend requires; TypeScript 7 removed ES5 output entirely). The globally installed tsc is never used
4. Writes the resulting .js next to the source file (only the saved file is emitted)
5. Uploads the .js to the server

Type errors are logged as warnings but do not block the upload — the compiled .js is still emitted.

AS5 runtime type declarations (as5.d.ts)

The AS5 server provides a set of globals to every service script at runtime — request, response, system, ContentBlob, XTDate, JSScript, Capability, registerRequestHandler, include, makePersistentClass and more. The extension bundles ambient type declarations for all of them:

• Compilation always includes as5.d.ts automatically — references to AS5 globals type-check without errors.
• Setup copies as5.d.ts into the workspace root so VS Code's own IntelliSense (hover docs, completion, signature help) knows the AS5 API too. If it's missing in a connected TS workspace, the extension offers to create it; the command AS5B: AS5-Typdefinitionen (as5.d.ts) anlegen/aktualisieren does the same on demand.
• Auto-update: the file carries a version marker (@as5bridge-dts-version) in its first line. When a newer extension ships an updated as5.d.ts, the workspace copy is updated automatically on activation. The file is extension-managed — put project-specific declarations into a separate .d.ts instead of editing it.

All declarations carry JSDoc documentation, so hovering system.createLease or ContentBlob.generateRsaKeyPair in the editor shows parameter docs inline.

The Setup command creates a tsconfig.json pre-configured for AS5 targets if one does not already exist:

{
    "compilerOptions": {
        "module": "commonjs",
        "target": "es5",
        "strict": false,
        "skipLibCheck": true
    }
}

Metadata Files

AS5Bridge stores a small .as5b sidecar file next to each synced file (e.g. main.js.as5b). It contains the remote ETag and a dirty flag. These files are hidden by default via the .vscode/settings.json created during Setup.

To remove all local sync metadata and start fresh, run AS5B: Lokale Sync-Dateien entfernen (Reinit). This deletes all .as5b files locally but does not modify the server.

Building from Source

# Install dependencies
cd extension && npm install

# Compile TypeScript (one-shot)
npm run vscode:prepublish

# Compile TypeScript (watch mode)
npm run compile

# Package as .vsix (output goes to dist/)
npm run package

Release Notes

2.1.0

Features

• Force Pull / Force Push — overwrite an entire folder in either direction (Command Palette + status bar menu), with a modal confirmation
• Batched delete confirmation — deleting a folder or several files at once produces a single prompt instead of one per file; known children of a deleted folder are included
• Context-sensitive status bar menu — now offers login, setup, sync current file, and force pull/push depending on state
• Bundled TypeScript compiler — .ts files are compiled in-process with a bundled TypeScript 6.x (ES5 support guaranteed); no dependency on a globally installed tsc
• Visible compile results (#2) — full type-check on save; diagnostics (file, line, message) go to the AS5Bridge output channel, and errors raise a notification with a "Log anzeigen" button. The type-check runs against the whole project (like tsc -p), so namespaces split across files resolve correctly; only the saved file is emitted and reported. Subsequent saves reuse the compiled program (incremental, fast)
• Compile spinner — while a .ts file compiles, its editor tab shows an animated spinner badge and the status bar a progress indicator. Compilation runs in a worker thread, so the UI never blocks — even on large projects
• AS5 runtime type declarations (as5.d.ts) — documented ambient types for all AS5 globals (request, system, ContentBlob, XTDate, …); always included in compilation, copied into the workspace by Setup for IntelliSense
• Content-Type on upload — PUT requests now send the correct MIME type

Fixes

• Setup could not create tsconfig.json (#1) — the bundled template files were resolved against a wrong path; template resolution is fixed and falls back to built-in defaults so setup always succeeds
• Saves during a running full sync are no longer silently dropped (download echoes are detected via content hashes instead)
• Per-file compile debounce — "Save All" over multiple .ts files now compiles every file, not just the last one
• Remote DELETE is conditional (if-match) — a file changed remotely in the meantime is no longer deleted blindly (412 → explicit prompt)
• Remote paths are URL-encoded — file names with spaces, umlauts, #, ? work correctly
• Dirty files survive a VS Code restart — persisted .as5b dirty flags are restored into the "Offene Konflikte" panel at startup
• Fixed a temp-file race between concurrent .as5b metadata writes
• .git/node_modules watcher filter is segment-exact — files like release.git.js are no longer skipped
• Hidden directories (.foo/) are excluded consistently at any depth; hidden FILES stay in scope (AS5 service files like .service.js are dotfiles and must sync). Sync behaviour and file decorations can no longer disagree
• Directory prefix matching is segment-exact (/api/ no longer matches /apifoo/); extensionless matching checks the basename (folders containing dots work)
• Automatic retry with backoff for uploads and deletes on 429/502/503 and network errors (previously only downloads retried)
• Directory listings with 1000+ entries produce an explicit truncation warning instead of silently missing files

Internal

• Migrated from the deprecated request package to native fetch (requires VS Code ≥ 1.82)
• Unit tests (mocha) + GitHub Actions CI
• .vscodeignore — sources, tests, and source maps are no longer packaged

2.0.2

• Automatic login — token is passed directly to the extension via OAuth callback; no manual copy-paste required. Browser shows a styled confirmation page after login. Falls back to manual input for older backends
• root config parameter — new optional field for a remote path prefix; your workspace root maps to host + root (e.g. "/api/project/"). Host URLs with a path are normalised automatically and the path is merged into root
• Token security — auth token moved from URL query string to Authorization: Bearer header; no longer appears in server logs, proxy logs, or the VS Code output channel
• ETag guard — files stay dirty instead of writing undefined as ETag when the server returns no ETag header after a successful PUT
• Atomic metadata writes — .as5b sidecar files are written via a temp file + rename to prevent corruption on crash
• Schema validation — corrupted .as5b files (missing or non-string version) are detected on read and reported with a warning
• markDirty() fix — files without a .as5b sidecar are now correctly tracked in the dirty files panel
• Workspace path match fix — getControllerForFile() no longer matches partial paths (e.g. /proj no longer matches /project)
• Request timeout — all HTTP requests time out after 30 s instead of hanging indefinitely
• runningCmds encapsulation — counter is only modified through incRunning() / decRunning(); watchdog timeout raised from 60 s to 120 s and no longer kills the request queue
• syncTree improvements — capped at 5 000 entries (LRU eviction); stale entries invalidated on network error
• ServiceFileLens cache — 30 s TTL cache prevents repeated filesystem scans on every code lens update
• TypeScript compilation security — exec() replaced with execFile() to avoid shell injection
• Token redaction in logs — Bearer tokens are redacted before writing to the output channel
• ActivityProvider memory fix — event listener is now properly disposed when the provider is released

2.0.1

• File decorations — Explorer shows ✓ (synced), ! (dirty / unsynced changes), ? (in scope but never synced) badges directly on files
• In-memory sync tree — remote file versions are cached in RAM; tab-switch checks skip HTTP requests when the cached version matches local, reducing network load significantly
• Setup command extended — now also creates tsconfig.json from a built-in template and writes recommended exclusions to .vscode/settings.json
• Config reload triggers re-check — adding a new extension type to the config immediately commits matching open files (no extra save needed)
• Synchronize current file fixed — for files never previously synced (no .as5b), the command now commits the local file directly
• Fix: open-file handler — files were never checked on open due to a guard that always short-circuited; now correctly synced when opened
• Fix: single-file sync during full sync — Synchronize current file no longer stalls when a full sync is running in the background
• Fix: 401 retry — files that fail to commit due to an expired token are tracked and automatically retried after a successful login

2.0.0

• Browser-based OAuth login — token captured automatically after Google OAuth
• TypeScript per-file compilation — .ts → compile with nearest tsconfig.json → upload .js
• Service file CodeLens — in-editor button to jump to the including service file
• Read-only protection — synced files locked until authenticated; released after login
• Sidebar panels — Verbindungen, Offene Konflikte, Letzte Aktivität
• Dirty files panel — lists sync failures with one-click retry
• Activity log — records every upload, download, and delete
• Conflict resolution UX — prompts for local update, remote overwrite, or diff
• Reinit command — clears all local metadata and re-downloads from server
• Retry logic — exponential backoff for network errors and rate limits (429)

1.2.9

• maxParallelRequest config option (default 20)
• Delete .as5b sidecar when the remote resource is deleted
• Improved binary file handling