airpuls RIC SDK — VS Code extension

Create and manage airpuls Near-RT RIC xApp projects from inside VS Code. The extension is a front end for the airpuls-sdk CLI (the airpuls-sdk-cli Python distribution): every lifecycle operation runs the CLI, so behavior, validation, and remote effects are identical to the terminal workflow.

Features

• New xApp from an empty window — the airpuls activity-bar view and the Explorer's empty state offer New xApp: a short prompt flow (name, description, deployment name, sinks, image, then the RIC) that runs airpuls-sdk xapp new and opens the generated project. Prompts show their default as a hint and start empty; an empty answer takes the default. The RIC question lists the registered RICs (registry default first) plus None — connect later, and offers Add RIC… when nothing is registered; no endpoint is ever typed — the CLI reads it from the RIC's own listener, creates the project connected to that RIC with its credentials fetched, and points the generated Redis sink at the RIC's Redis. After scaffolding, the extension offers to provision .venv and install the project dependencies (xapp venv); the Python extension detects .venv as the project interpreter. The same offer appears when a scaffolded project is opened without a .venv — the state of a fresh clone, since the scaffold gitignores the environment. No CLI on the machine is needed to start: a Python with its venv module is enough, and the project's .venv is then created first with the CLI installed into it, after telling you so.
• Sidebar panel — the airpuls activity-bar container stacks three views beside the editor, so the panel never occupies an editor tab and coding continues while it is open:
  • Status — SDK installation (CLI, version, settings file), xApp identity (deployment name, endpoint, languages, schema type/version, sinks), and — for a tls:// project — the credential files under certs/ with per-file copy actions. Right-clicking the sinks row offers Add Sink…: pick a RIC and the flow probes that installation for the sink destinations it serves — its Redis, its InfluxDB — then writes the chosen one, endpoint and credentials included, into xapp.yml. The user never types a destination; the installation is the source of truth. Pending from the CLI: the probe document's sinks list and xapp add sink's discovery options.
  • Doctor — airpuls-sdk doctor as one node per environment check with a pass/warn/fail icon, the detail inline, and the remedial hint in the tooltip. Runs automatically the first time the view is revealed; the title-bar icon reruns it. The view stays empty without an xApp project in the window — the checks describe a project's environment.
  • Deploy Targets — one node per registered RIC with the current xApp's deployment presence, and per target the staged xApp IPC transport (tls or plaintext) as the first child, the deployment's licence state right after it (the checkout's own verify-license.sh: offline checks plus online validation against the licence server it configures), the deployment stack's compose services with a run-state light (green up, red down; omitted when the checkout defines no compose stack), and the current xApp's credential files generated on the host. Probed through ric probe on reveal and via the title-bar icon — every probe reads the target afresh, since the RIC configuration may change. Inline deploy / credentials / undeploy icons and registry actions in the context menu. The xApp's credential files and the credentials icon appear only under the RIC the project's endpoint points at — a certificate authenticates to the RIC that signed it and to no other; every other RIC offers Connect xApp Here instead.
• Lifecycle actions as view-title icons — new xApp, run, test, and deploy sit as icons in the Status view's title bar; build, validate, provision environment, build image, run in container, show deploy template, undeploy, and the credential actions are in its … overflow menu and the command palette. Run and Run in Container check the project first — endpoint, transport, TLS material, sink credentials, an instance already running — and, when something is missing, list the findings with a button per fix and "Run Anyway". For an instance of the xApp already running the fix is "Stop the running instance and run", which launches with --replace; "Run Anyway" is not offered then, since no launch gets past a running instance. Run in Container runs the project's image the way the deployment launcher does, asking first whether to run it as built or build it first; Generate Credentials asks whether the deployment's sink credentials come along into the project's gitignored .airpuls/sinks.env (development environments only) or the TLS material alone. Deploy first checks the configuration (see below), then always asks how the launcher's image reaches the host: build it and push it to the registry its reference names (the default), copy the built image over SSH for a host that cannot reach the registry, or upload the entry alone for a configuration-only redeploy. Interactive verbs run in an integrated terminal so streamed output, confirmation prompts, and the CLI's SSH password fallback work unchanged; quick verbs run captured and report as notifications with a transcript in the airpuls output channel.
• Configuration parameters kept in step with the schema — the management system builds the xApp's configuration form from xapp.schema.json, so every parameter the xApp's code registers (add_param) or xapp.yml sets must be declared there, with the type and required flag the code registers; xapp deploy refuses the project otherwise. The extension helps keep the three in step:
  • Editor highlighting — each parameter out of step is marked at the line that registers or sets it (at the top of the file when the CLI names no line): an error where xapp.yml sets a key the schema does not declare (the file is then invalid), a warning where only the code disagrees with the schema. The check is xapp validate, run in the background when the window opens, when xapp.yml, xapp.schema.json or a Python, C or Go source of the project is saved, and after every command the extension runs; it shows no notifications, and a CLI that cannot run it leaves the editor unmarked and a line in the airpuls output channel.
  • Quick fix — each mark offers Declare xapp.… in xapp.schema.json or Change xapp.… in xapp.schema.json to match the code, which runs xapp add config-param and updates both files. A parameter the code requires without giving a value asks for one first, checked against its type: an int is digits with an optional sign, a float a finite number, a bool true or false, a string anything but blank. The Status view's readiness rows for these parameters run the same fix when clicked; Run lists them but offers no button for them, since they concern the deploy.
  • Check before deploy — Deploy runs xapp validate before asking anything else. When the configuration does not match, the deploy is refused in a dialog listing each parameter: Fix and Deploy declares them all, checks again and deploys once the configuration matches; Fix declares them without deploying. A problem no declaration solves — a wrong value in xapp.yml — leaves only Open xapp.yml, and so does a round of fixes that changed nothing.
  • Before the check and before any fix runs, the project's unsaved edits to xapp.yml, xapp.schema.json and its sources are saved: the CLI reads and writes the files on disk.
  • Declared but never registered — a setting added with xapp add config-param that no add_param call in the code registers shows up in the configuration form, but the SDK does not read a value set for it: xapp.… is declared in xapp.schema.json, but the xApp's code never registers it with add_param — the SDK does not read a value set for it. Settings declared by hand are not checked, since an xApp may read those with its own parser. It is marked with a warning at the xapp.yml key that sets it, or at its declaration in xapp.schema.json, and never blocks a deploy: the CLI cannot see a registration the code builds at run time. Its quick fix, Show the code that registers xapp.…, opens the registration and read code in a read-only tab named after the parameter (xapp.… — code.py) — in Python, unless the project has only C or Go — and copies the registration call to the clipboard, naming the parameter. The Status view's readiness row for it does the same when clicked.

Development use only

The Deploy Targets workflow — deploy, undeploy, credentials, and the probes — moves keys and certificates between this machine and the RIC host over SSH, and the copy actions place certificate and key material on the clipboard. That handling is acceptable in a development lab and nowhere else: never register a production RIC as a deploy target. A dialog states this before the first deploy target is registered; the acknowledgment is remembered, so it appears once.

Requirements

• Python with the airpuls-sdk-cli distribution installed (pip install airpuls-sdk-cli) — provides the airpuls-sdk CLI. It installs wherever Python runs; Linux and macOS are its supported platforms, and on Windows the deployment actions need an SSH key the host already trusts. The CLI must speak the global --json flag; a release without it is reported with an upgrade hint.
• The airpuls-ric-sdk runtime (pip install airpuls-ric-sdk, Linux x86_64) only for commands that execute an xApp — Run and the tests that import it. On other hosts, open the project in the Dev Container the scaffolding generates.
• OpenSSH client tools for deploy, undeploy, credentials, and the deployment probes.
• Docker for xapp build --docker-image and for every deploy that ships an image: the default mode builds the launcher's image and pushes it, which also needs docker login against the registry the image reference names. Only the entry-only mode runs without Docker.

airpuls-sdk doctor (the Doctor tab) reports all of the above.

Settings

• airpuls.cliPath — path to the airpuls-sdk executable. Empty resolves it from PATH, then ~/.local/bin.
• airpuls.configFile — CLI settings file override, exported as AIRPULS_SDK_CONFIG to every CLI invocation. Empty uses the CLI's per-user default.
• airpuls.cliDistribution — what pip install receives when New xApp provisions a project's .venv with the CLI because none is installed: a distribution name with an optional version, or a wheel path. Default airpuls-sdk-cli.

CLI output contract

Every captured invocation runs the CLI's machine-readable channel: the global --json flag makes an invocation write exactly one JSON document to stdout — {"schema": 1, "ok": …, "command": …, "data": …, "warnings": […]} plus an error block on failure — and never prompt. The extension parses only these documents (schema 1); no rendered output is ever interpreted. Facts come from --version, config show (the RIC registry and settings-file path), xapp info (project identity), doctor (environment checks), ric probe (per-target reachability, staged transport, generated credentials, deployed entries), xapp check (readiness findings, each fix with its argv and value_missing, each finding's snippets: code per language that resolves it, and its param: the configuration parameter it is about), xapp validate, the xapp add config-param result (the declared parameter's path, replaced for a changed declaration, and registered — whether the code registers it yet), and the xapp new result. xapp validate reports the configuration parameters out of step with the schema in undeclared_params and mismatched_params — also when validation fails — one record each: path, type, default, required, where it was found (file relative to the project, 1-based line, where), the argv of the xapp add config-param command that fixes it, and value_missing when that command still needs --default VALUE --required; an undeclared record adds in_manifest (xapp.yml sets it, so the schema refuses the file), a mismatched one declared_type and declared_required. unexplained_violations lists the violations left once every in_manifest parameter is declared: a failed validation is fixed by declarations only when it is present and empty. unregistered_params lists the parameters xapp add config-param declared that no add_param call registers — path, type, default, required, file (xapp.yml when it sets the key, else xapp.schema.json), line, where, and code, the registration and read code per language; they never fail validation. A CLI whose documents carry none of these marks nothing, lets a passing validation deploy, and offers no fix for a failing one. The filesystem contributes only what the CLI does not report: locating the enclosing xapp.yml and the presence of credential files under certs/. The extension opens no remote connections of its own — every remote fact arrives through the CLI, which probes in SSH batch mode without prompting. Interactive verbs run the CLI in text mode inside the integrated terminal, where its rendering and prompts are the interface.

Development

npm install
npm run compile      # tsc → out/
npm test             # node --test (pure parser modules)

Launch the extension with F5 (Run Extension) from VS Code, or build a VSIX with npm run package.

This project is self-contained: no references into the enclosing repository, movable to its own repository as-is. Its only coupling to the SDK is the airpuls-sdk command-line contract.