APEXlang support for pi

pi-apexlang is a pi package for Oracle APEX application development with APEXlang. It combines two resources:

• Oracle's public apexlang Agent Skill, vendored unchanged at a pinned upstream commit.
• A small pi extension that runs the packaged APEXlang CLI with the user's project as its working directory, keeps runtime context stable for the session, and exposes a bounded apexlang tool.

This is an independent integration and is not an Oracle product.

APEX versions

Package 0.5.0 vendors Oracle's complete versioned skill tree at commit 014cdb29f12dfa6a689bbe8a80ee1c5f0bf15be1, checked on 2026-10-21.

The tool resolves mmdVersion from .apex/apexlang.json, matching major.minor (including values such as 26.2.0+3479). Optional apex_version must agree. Unknown versions default to 26.1; unsupported or conflicting versions stop before execution. Oracle has no 26.2 generation runtime in this snapshot, so the older generation/property-query/GUI-import actions reject 26.2 apps. Read the 26.2 router and only its inventory and examples.

To check a 26.2 app, set SQLCL_BIN to the absolute SQLcl executable path or provide sqlcl_bin in the tool input:

{"action":"sqlcl_validate","app_path":"applications/my-app","apex_version":"26.2","sqlcl_bin":"/absolute/path/to/sqlcl/bin/sql"}

This runs Oracle's matching compile helper with /nolog on a temporary copy. It preserves all app files, including 26.2 generated-artifacts and translations. Success requires exit zero, exactly one explicit validation-success marker, and no hard errors. Reports go to logs/sqlcl-validate.json and .log; this local compiler check never grants import authority. The upstream deploy skill is included for explicitly authorized deployment workflows; the Pi GUI import flow remains 26.1 only. Bash is required for the upstream compile helper.

Documentation · Документація

• English documentation: setup, architecture, tool reference, and maintenance.
• Українська документація: початок роботи, архітектура, довідник інструмента та супровід.
• Infographics / Інфографіка: English · Українська.

Install

Try the local checkout without installing it:

pi -e .

Install this Git repository for the current user:

pi install git:github.com/avhrst/pi-apex

Or install it only for the current project:

pi install git:github.com/avhrst/pi-apex -l

After an npm release, the equivalent command is:

pi install npm:pi-apexlang

Pi packages execute with the user's system permissions. Review extension and skill sources before installation.

Use

Pi discovers the skill automatically when a task concerns APEXlang. Force it for a particular request with /skill:apexlang:

/skill:apexlang Create a dashboard page from the verified schema metadata in metadata/tables.json. Check the APEXlang code and do not import it.

Useful prompts include:

/skill:apexlang Probe this workspace and tell me which APEX app is safe to edit.

/skill:apexlang Add an interactive report to the orders app using the existing table metadata. Validate locally and show me the compiler-truth evidence.

/skill:apexlang Check applications/service-ops against connection apex_dev and APEX workspace SERVICE_OPS_DEV. Do not import it.

The registered apexlang tool supports the actions below. Except for the version-neutral workspace probe and sqlcl_validate, these use the 26.1 generation runtime:

local_validate preserves Oracle's complete validator and report semantics. The extension accelerates its repeated block and nesting queries in a process-local cache; the vendored Oracle skill remains unchanged and no checks are skipped.

The model cannot request import as a standalone action. Oracle's skill defaults to checking code; only after authoritative live validation passes does the extension offer a separate GUI choice. Selecting Check and import APEXlang code requires an explicit target mode:

• Update existing proceeds only when Oracle resolves one existing remote application.
• Create new first runs Oracle's target resolver without import authority. Only after it proves the alias is absent does Pi ask for a second confirmation and rerun validation plus import together.

Every post-validation choice is abort-aware and bounded to five minutes. Without a confirmed GUI response—or when the request is aborted or times out—the tool stops after checking and reports import as a follow-up. Silence is never treated as import authorization.

When refreshing a full APEXlang export, run one SQLcl export with explicit replacement semantics:

apex export -applicationid <id> -exptype APEXLANG -split -dir <absolute-parent-directory> -force

-dir names the parent directory; SQLcl creates the application-alias folder below it. The -force flag removes and recreates that export folder, so a repeat export produces one current snapshot instead of collision copies such as application_1.apx and p00005_1.apx. Because this replaces the complete local export, preserve or import any local-only work before refreshing it.

SQLcl and ORDS compatibility advisory

Oracle documents minimum APEXlang prerequisites, but does not publish an exact ORDS-to-SQLcl patch certification matrix. The extension therefore keeps this mapping advisory and records whether a row is Oracle-confirmed or an extension diagnostic recommendation:

The complete machine-readable table, source URLs, thresholds, and the direct diagnostic-build download are in extensions/apexlang/ords-sqlcl-compatibility.json. The exact build is a known diagnostic baseline, not a universal pin, and SQLcl 26.2 is not categorically blocked.

When a validation result contains at least 50 structured findings, the extension appends the table and recommends checking:

• local sql -version;
• the app's .apex/apexlang.json mmdVersion;
• the server APEX release and ORDS version with its administrator.

For local and compiler-truth text reports, the mass-error signal additionally requires at least five distinct .apx files, which avoids treating one noisy file as an environment-wide mismatch. An explicitly unsupported MMD version also produces the compatibility advice. The advice never changes validation status, relaxes an import gate, or claims that the application is valid.

ORDS 26.1.1 introduced APEXlang support, APEX 26.1 requires ORDS 26.1.1 or later, and Oracle's SQLcl prerequisites set the SQLcl minimum at 26.1. SQLcl 26.1.2 added full APEXlang support.

All app paths must remain inside the active Pi workspace. The adapter rejects traversal, app-tree symlinks, and multiply linked files on mutating vocabulary fixes; verifies live workspace input against deployments/default.json; and terminates the whole spawned process tree when a run is cancelled or times out.

Requirements

Offline routing, templates, generation, and most local checks need Node.js 22.19 or newer. The bundled Python validators also require Python 3.

Oracle documents these requirements for live APEXlang work:

• For the generation/live GUI workflow: Oracle APEX 26.1 with APEXlang support.
• For 26.2 authoring/compilation: its versioned skills and SQLcl compiler metadata supporting the app mmdVersion; no database connection is required by sqlcl_validate.
• ORDS 26.1.1 or newer.
• SQLcl 26.1.2 or newer, as required by the bundled Oracle skill, selected with the compatibility advisory above.
• Java 17 or Java 21 for SQLcl.
• A saved SQLcl connection name and its corresponding APEX workspace name.
• A local APEX app or authoritative schema, model, API, or table metadata.

Do not pass database passwords or connection strings to the extension. Live operations accept only a saved db_connection_name and require the matching workspace_name.

Package layout

extensions/apexlang/index.ts  pi tool and lifecycle integration
extensions/lib/               argument-safe APEXlang process adapter
skills/apexlang/               unmodified Oracle APEXlang skill snapshot
scripts/                       provenance, sync, and smoke checks
test/                          adapter contract tests

Pi progressively discloses the skill: it initially sees only the skill name and description, then reads SKILL.md and Oracle's compact routing catalogs before loading task-specific references and templates. The entire versioned documentation tree is not injected into the model context.

Develop and verify

npm install
npm run check
npm run verify:package

To update the Oracle snapshot and record a new pinned commit:

npm run sync:oracle -- --ref main
npm run check

Review upstream changes before committing a refreshed snapshot. The sync script replaces only skills/apexlang, refreshes the Oracle license, and updates UPSTREAM.json.

Provenance and license

Package 0.5.0 includes Oracle's versioned 26.1/26.2 skill tree. The 26.1 generation skill retains release 2026.09.21. See the bundled Oracle release notes.

The vendored skill comes from oracle/skills/apex/apexlang at commit 014cdb29f12dfa6a689bbe8a80ee1c5f0bf15be1. See UPSTREAM.json and THIRD_PARTY_NOTICES.md.

This package is distributed under the Universal Permissive License 1.0. See LICENSE.