AS5Bridge

Keeps your VS Code workspace in sync with a remote AS5 (AppStack5) server. Files upload when you save, download when the server version changes, and conflicts are resolved interactively — with TypeScript compiled to ES5 the way AS5 expects it.

Features

• Bidirectional sync — upload on save, download on open/tab switch, ETag-based conflict detection
• TypeScript for AS5 — compiles .ts on save to ES5 using a bundled TypeScript 6, type-checked against the whole project, with full IntelliSense for the AS5 runtime globals
• Explorer badges — see at a glance what is synced (✓), has pending changes (!), or was never uploaded (?)
• Sidebar panels — connections, open conflicts, and an activity log
• Force Pull / Force Push — overwrite a whole folder in either direction, with confirmation
• Browser login — token is captured automatically and stored in the OS keychain
• Service file navigation — jump from any .js/.ts file to the AS5 service file that includes it

Requirements

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

Getting started

1. Install

Extensions → ⋯ → Install from VSIX… and pick the .vsix file.

2. Run Setup

Command Palette (Ctrl+Shift+P / Cmd+Shift+P) → AS5B: Setup.

It creates four files in your workspace root — existing files are never overwritten:

3. Configure

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

4. Log in

Click the key icon in the status bar, or run AS5B: Login. A browser opens for authentication; the token is handed back to the extension automatically and a full sync starts.

The token is kept in the OS keychain (VS Code SecretStorage) — never in the config file and never in plain text on disk. It survives restarts; AS5B: Abmelden removes it.

Commands

Clicking the status bar item opens a context-sensitive menu with the actions that make sense right now.

How it works

Status indicators

Several backends in one workspace share a single status bar entry showing icons with counts ($(cloud) 4, $(sync~spin) 2 $(key) 1) instead of one entry per folder — four connections used to fill the whole bar. The tooltip lists every folder with its state, and clicking lets you pick one. Set as5bridge.statusBar.mode to detailed to always list them by name, or compact to always use counts.

Sync triggers

Conflicts

When local and remote both changed, you choose: Lokal aktualisieren, Remote überschreiben, or Diff anzeigen. With many conflicts at once, the "Immer …" options apply your choice to the rest of that run.

Files that fail to upload land in the Offene Konflikte panel with one-click retry, survive a restart, and are retried automatically after a login.

TypeScript support

Saving a .ts file type-checks it against the whole project (like tsc -p, so namespaces split across files resolve), emits ES5 next to the source, and uploads the .js. Compilation runs in a worker thread — the editor never blocks, and the tab shows a spinner while it works. Type errors are reported in the output channel but do not block the upload.

The bundled compiler is pinned to TypeScript 6.x: the AS5 backend only accepts ES5, and TypeScript 7 removed target: "es5" entirely. The globally installed tsc is never used, so results do not depend on the machine.

AS5 runtime declarations (as5.d.ts)

AS5 injects globals such as request, response, system, ContentBlob, XTDate, JSScript, Capability and registerRequestHandler. The extension ships documented type declarations for all of them, includes them in every compile, and copies them into your workspace so IntelliSense and hover docs work.

The file is extension-managed and updates itself when a newer version ships — put project-specific declarations in a separate .d.ts rather than editing it.

Rhino-Prüfung für handgeschriebenes JavaScript

.ts geht durch den gebündelten Compiler mit target: es5 — was dort ankommt, ist sicher. Handgeschriebenes .js wird Byte für Byte hochgeladen, und genau daraus bestehen die AS5-Servicedateien (.ROOT.js, .<name>.js). Eine Konstruktion, die die Rhino nicht parst, ist dort kein Compilerhinweis, sondern ein Dienst, der nicht mehr antwortet.

Beim Speichern einer .js wird deshalb geprüft, was die Plattform nicht versteht. Gemeldet, nicht blockiert — hochgeladen wird so oder so.

Zwei Stufen, und der Unterschied ist Beleglage, nicht Schwere:

Die zweite Stufe ist bewusst leise: nach ES5 entstanden und von dieser Rhino abgelehnt sind zwei verschiedene Aussagen, und welche zutrifft, hängt von der Version auf dem Server ab. Wer es strenger will:

{ "as5bridge.rhinoCheck.severity": "all" }

"use strict" ist kein Fund, sondern wird entfernt. Der Prolog legt die AS5-Plattform lahm, und die Antwort darauf ist immer dieselbe — also gibt es keine Rückfrage: beim Speichern verschwindet die Zeile, aus dem Upload und aus der Datei. Gilt auch für .ts, denn einen selbst geschriebenen Prolog reicht der Compiler in die erzeugte .js durch. Entfernt wird nur eine echte Direktive; var s = "use strict" bleibt unangetastet.

Der CLI (as5b push) fehlt das — der TypeScript-Parser liegt bewusst nicht im CLI-Bündel.

Gemeldet wird, wenn sich die Funde ändern — nicht bei jedem Speichern. Solange eine Zeile drin bleibt, fände die Prüfung sie sonst jedes Mal erneut, und eine Warnung, die bei jedem Speichern erscheint, wird weggeklickt.

Abschaltbar über as5bridge.rhinoCheck.enable.

Remote-Änderungen sehen, bevor sie zum Konflikt werden

Offene Dateien werden im Hintergrund darauf geprüft, ob sie auf dem Server gewandert sind. Das Ergebnis steht auf dem Tab:

Wer zusätzlich ungespeicherte Änderungen in der Datei hat, bekommt einmalig einen Hinweis mit „Diff anzeigen". Ohne das fällt eine fremde Änderung erst beim Speichern auf, als 412 — und dann steht die Entscheidung unter Zeitdruck an.

Die Prüfung nutzt if-none-match: unveränderte Dateien kosten eine leere 304-Antwort. Es wird nichts heruntergeladen, nichts überschrieben und nichts angefasst, solange ein echter Sync läuft.

{
    "as5bridge.remoteWatch.enable": true,
    "as5bridge.remoteWatch.intervalSeconds": 60
}

Formatting

AS5Bridge ships a pinned Prettier 3.9.6 — the same build the AS5 web IDE uses — and offers it as a formatter for JS, TS, JSON, CSS, LESS and HTML.

Select it once, and per-language formatter settings stop mattering:

{
    "editor.defaultFormatter": "modima.as5bridge",
    "editor.formatOnSave": true
}

xml keeps whatever formatter you have — Prettier has no XML parser.

Namespace und lokale Kopie

Die Web-IDE liest die .prettierrc aus dem Namespace, VS Code aus dem Workspace — zwei verschiedene Dateien. Da die Konfiguration üblicherweise im Namespace-Wurzelverzeichnis liegt und ein Sync-Bereich wie /api/ die Wurzel nicht umfasst, wandert sie auch nicht von selbst mit.

AS5Bridge vergleicht beide einmal pro Sitzung und meldet sich, wenn sie auseinanderlaufen — inhaltlich verglichen, Schlüsselreihenfolge und Einrückung zählen nicht. Die Namespace-Fassung lässt sich per Klick übernehmen; auf den Server geschrieben wird nie etwas. Erneut prüfen: AS5B: Prettier-Konfiguration mit Namespace abgleichen.

Deployment (Dev → Live)

Copying backend files between systems by hand is how a file ends up with the content of a different file. The deployment flow makes that mistake visible before it reaches production: nothing is written to the target until every file has been confirmed in a diff.

Configuration

"deploy": {
    "label": "Live",
    "host": "https://live-host.ecs.appstackfive.com",
    "root": "/",                            // optional, defaults to the dev root
    "compareMode": "sinceLastDeployment",   // | "folder" | "full"
    "protectedPaths": ["/api/payment/"],
    "allowDeletions": false,
    "webhook": {
        "url": [
            "https://chat.googleapis.com/v1/spaces/…",
            { "url": "https://hooks.slack.com/services/…", "notify": ["failure", "rollback"] }
        ],
        "notify": ["success", "failure", "rollback"]
    }
}

Without a deploy section the feature stays off. The target has its own login — run AS5B Deploy: Bei Live anmelden; the token is stored separately in the OS keychain.

Workflow

1. Mit Live vergleichen — lists what differs: changed, only in dev (new), only on live. Because dev and live are independent AS5 systems their ETags are not comparable, so content is compared — hence the three scopes: since last deployment (default, fast), a folder, or everything.
2. Stage the files, either from the comparison result or with AS5B Deploy: Aktuelle Datei hinzufügen. Selecting foo.ts pulls in foo.js automatically — deploying only one of them would leave live running the old compilate.
3. Nachricht setzen — appears in the journal and in the chat channel.
4. Review: each file opens as a diff live ↔ dev and must be confirmed individually. Files with warnings require an extra confirmation.
5. Deployen — a final modal lists the files, highlighting deletions and protected paths. Each write is guarded by the if-match captured during the review, so a file changed on live in the meantime aborts the deployment instead of being overwritten.

Safeguards

Journal and rollback

Every deployment is recorded under .as5bridge/deployments/ together with the target's previous content. That directory ignores itself via git and is excluded from syncing, since it holds production data.

AS5B Deploy: Letztes Deployment zurückrollen restores that state. AS5B Deploy: Historie lists past deployments and can roll back a specific one.

No atomicity. AS5 has no transaction across files. If file 7 of 10 fails, the deployment stops there and reports a partial state — it does not pretend to be all-or-nothing. A rollback is offered immediately.

Chat notification

Successful, failed and rolled-back deployments are posted to the configured channels — Google Chat, Slack, or both:

*Deployment → Live* · Markus Enderlein <m@example.com>
> Bugfix im Bestellprozess

• `/api/order/checkout.js`
• `/api/order/checkout.ts`

*🗑 Gelöscht (1):*
• `/api/order/legacy.js`

3 Dateien · 27.07.2026 14:32 · ✅ erfolgreich

webhook.url takes one URL, a list of URLs, or a list of objects when channels need different settings:

"webhook": {
    "url": "https://chat.googleapis.com/v1/spaces/…"
}

"webhook": {
    "url": [
        "https://chat.googleapis.com/v1/spaces/…",
        "https://hooks.slack.com/services/…"
    ]
}

"webhook": {
    "url": [
        { "url": "https://chat.googleapis.com/v1/spaces/…", "notify": ["success"] },
        { "url": "https://hooks.slack.com/services/…", "notify": ["failure", "rollback"] },
        { "url": "https://mattermost.intern/hooks/…", "type": "generic" }
    ]
}

The service is derived from the host — hooks.slack.com → Slack, chat.googleapis.com → Google Chat, anything else → generic, which posts the same {"text": …} body most incoming-webhook endpoints accept. type overrides the detection, which is what a relay or a proxy needs.

A channel's own notify wins over the shared one, so failures can go to the on-call channel while successes go to the team channel.

The message is identical on all services (both understand *bold*, _italic_ and `code`); only the length limit differs — Google Chat rejects anything over 4096 characters outright, so long file lists are capped with "… und N weitere" rather than silently dropped.

Every channel is posted to independently: a webhook that is unreachable is logged and ignored — it neither turns a successful deployment into a failed one nor stops the other channels. Webhook URLs are credentials and are always redacted in the log.

Command line (as5b)

The same core that drives the extension is also available as a CLI — for scripts, CI, and AI assistants that work in a terminal.

Install

Binary (nothing else required, not even Node) — from the latest release:

curl -Lo as5b https://github.com/Gevekom-ONE-GmbH/tools-as5bridge/releases/latest/download/as5b-linux-x64
chmod +x as5b && sudo mv as5b /usr/local/bin/
as5b --version

Each binary ships a .sha256 next to it. macOS marks downloads as quarantined — xattr -d com.apple.quarantine as5b once, or open it via right-click → Open. The binaries are ad-hoc signed, not notarized.

JS bundle (as5b.cjs, ~135 KB) for machines that already have Node ≥ 18 — also attached to every release:

node as5b.cjs --help

From source:

npm i -g ./extension          # or: npm link, from the extension directory
npm run build:binary          # builds a binary for the current platform
as5b --help

as5b status                              # config, login state, deployment target
as5b login [--deploy]                    # browser login (dev or target)
as5b diff api/order.js [--live]          # local file vs. dev (or the deployment target)
as5b pull [/api/]                        # download from dev
as5b push [files...]                     # upload to dev
as5b watch                               # upload on save, propagate deletions
as5b deploy compare --mode full          # differences dev ↔ live
as5b deploy plan  api/order.js           # what would happen, incl. warnings
as5b deploy run   api/order.js -m "Fix"  # deploy, with a diff review per file
as5b deploy rollback                     # undo the last deployment
as5b deploy history

Every command accepts --json and then writes a single JSON document to stdout — diagnostics go to stderr, so the output stays parseable:

as5b deploy compare --json | jq '.differences[] | select(.suspicious)'

Automation and safety

The CLI enforces the same safeguards as the editor — a diff review per file, the preflight checks, if-match on every write:

For pull/push, conflicts (both sides changed since the last sync) are asked interactively; --conflict local|remote|skip decides upfront. Without a terminal the default is skip — neither side is discarded silently. --dry-run reports what would happen without writing.

That split is deliberate: automation is possible, but a file that looks like a different file, is unsynced, or sits on a protected path does not slip through just because a script passed --yes.

Exit codes

Chaining with && has to be safe, so anything short of a clean run is non-zero:

Bad flag values are rejected rather than silently defaulted — --mode ful, --mode folder without --folder, --conflict bogus, or --id without a value (which would have rolled back the newest deployment) all stop with an error.

Authentication

The CLI cannot read the extension's tokens — VS Code's SecretStorage is only reachable from the editor. It uses, in order:

1. AS5_TOKEN / AS5_DEPLOY_TOKEN from the environment (CI, agents)
2. ~/.as5bridge/credentials.json, written with mode 600 by as5b login

Metadata files

Each synced file gets a small .as5b sidecar holding the remote ETag and a dirty flag. Setup hides them from the explorer. Reinit removes them all and re-downloads from the server without modifying anything remotely.

Deployment workflow

1. AS5B Deploy: Mit Live vergleichen — find what differs from the target
2. AS5B Deploy: Aktuelle Datei hinzufügen (or click a difference in the sidebar)
3. AS5B Deploy: Nachricht setzen — what is being shipped
4. AS5B Deploy: Review — one diff per file, each confirmed individually
5. AS5B Deploy: Deployment ausführen

Every step is a Command Palette entry; the Deployment sidebar shows the same flow with buttons. Nothing is written to the target before step 4 is complete.

Troubleshooting

"Diff gegen Dev-Server" never shows a difference. That is expected: AS5Bridge uploads on save, so the workspace and the dev server are kept identical. Use AS5B: Diff gegen Live (or as5b diff --live) to see what actually differs from production.

A file does not sync. Check that its directory is listed in directories and its extension in extensions — both must match. .service.js and other dotfiles do sync; files inside hidden directories (.cache/) never do. AS5B: Log anzeigen shows the decision for every file.

TypeScript errors in frontend files (window/document unknown, Vue redeclared). Those files are standalone browser scripts, not AS5 modules. Add their path to tscCheckExclude to compile them emit-only.

"Metadatei korrupt". The .as5b sidecar is unreadable. Delete it — the file re-syncs on the next save — or run Reinit for a clean slate.

Everything asks for a login again. The token was rejected (status bar shows $(lock)). Log in again; queued files are retried automatically.

The remote file is newer and you want to look first. AS5B: Diff gegen Remote shows both versions side by side without changing anything.

Links

• Changelog
• Contributing & build instructions
• AS5 documentation
• Issues

Licensed under the MIT License.