pi-apexlang 0.1.0

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "pi-apexlang",
+  "version": "0.1.0",
+  "description": "APEXlang support for pi, powered by Oracle's public APEXlang skill.",
+  "type": "module",
+  "license": "UPL-1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/avhrst/pi-apex.git"
+  },
+  "homepage": "https://github.com/avhrst/pi-apex#readme",
+  "bugs": {
+    "url": "https://github.com/avhrst/pi-apex/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "oracle",
+    "oracle-apex",
+    "apexlang",
+    "sqlcl",
+    "agent-skill"
+  ],
+  "files": [
+    "extensions",
+    "skills",
+    "LICENSE",
+    "README.md",
+    "THIRD_PARTY_NOTICES.md",
+    "UPSTREAM.json"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/apexlang/index.ts"
+    ],
+    "skills": [
+      "./skills/apexlang"
+    ]
+  },
+  "scripts": {
+    "check": "npm run typecheck && npm run verify:vendor && npm test && npm run smoke && npm run verify:package",
+    "smoke": "node scripts/smoke.mjs",
+    "sync:oracle": "node scripts/sync-oracle-apexlang.mjs",
+    "test": "node --test",
+    "typecheck": "tsc --noEmit",
+    "verify:package": "node scripts/verify-package.mjs",
+    "verify:vendor": "node scripts/verify-vendor.mjs"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.80.10",
+    "@earendil-works/pi-coding-agent": "^0.80.10",
+    "@types/node": "^24.12.0",
+    "typebox": "^1.1.38",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/skills/apexlang/README.md

@@ -0,0 +1,105 @@
+# APEXlang Skill for Oracle APEX
+
+This package is the public Oracle APEXlang skill for Oracle APEX generation work. Consume it like an Oracle skills domain: install or load the domain folder, then start from its root entrypoint.
+
+Start with SKILL.md. It is the main root entry for routing, local context discovery, generation policy, validation behavior, and import approval rules.
+
+## Requirements
+
+- Oracle APEX with APEXlang support, using the latest available 26.1 build.
+- SQLcl for real APEXlang validation and import workflows, version 26.1.2 or newer.
+- Java 17 or Java 21 for current SQLcl.
+- A saved SQLcl connection name and the corresponding APEX workspace name for Live DB validation, import, runtime diagnostics, or new-app materialization.
+- A local Oracle APEX app directory or enough authoritative context for the skill to help create one.
+
+You can read the guidance and draft APEXlang artifacts without SQLcl. Any workflow that validates against Oracle APEX or imports into a workspace requires SQLcl, a usable `db_connection_name`, and the matching APEX workspace name.
+
+New workspaces do not need a pre-existing `artifacts/` directory. Runtime outputs are created lazily under `APEXLANG_OUTPUT_ROOT` only when a command writes logs, reports, or export backups. Existing `apex-exports/` folders are backup/export material and are ignored for app resolution and generation unless the user explicitly asks to inspect an export backup.
+
+## Use with Oracle DB Skills
+
+Generic Oracle Database, PL/SQL, SQLcl, and utPLSQL guidance is owned by Oracle upstream DB skills at `https://github.com/oracle/skills/tree/main/db`. This package does not replace or duplicate those domains. It bundles only the APEXlang-specific SQLcl runtime adapter needed for app context discovery, APEXlang validation, explicit import, and runtime diagnostics.
+
+## Package Map
+
+| Path | Purpose |
+| --- | --- |
+| `SKILL.md` | Main root entry and routing contract |
+| `assets/` | Routing, workspace-intelligence, metadata, and compiler catalogs |
+| `references/` | Workflow, domain, policy, and runtime support guidance |
+| `templates/` | APEXlang examples and templates |
+| `tools/` | Packaged command entrypoints |
+| `runtime/` | Runtime helpers used by packaged commands |
+
+## Prompt Examples by Task
+
+Good prompts name the app, page, component, data evidence, desired behavior, whether live validation is allowed, and for Live DB work the `db_connection_name` plus corresponding APEX workspace name.
+
+### Whole app from beginning to end
+
+```text
+Create a new service operations app from my table metadata for APEX workspace SERVICE_OPS_DEV. Include a home page, ticket dashboard, ticket report, ticket edit form, navigation, breadcrumbs, and default security. Check the APEXlang code before any import.
+```
+
+### Generate a page
+
+```text
+Create a dashboard page for order operations with KPI cards, a monthly revenue chart, and an interactive report. Use existing schema evidence and ask before guessing missing columns.
+```
+
+### Page-specific change
+
+```text
+On the customer detail page, add a right-side activity summary region, move the Save and Cancel buttons into the page header, and keep existing navigation intact.
+```
+
+### Generate a component
+
+```text
+Add a shared LOV for active account managers using verified table and column names, then use it on the owner item in the customer form.
+```
+
+### Batch changes
+
+```text
+Across all editable form pages, add concise help text to required items and add a validation message where users commonly submit incomplete data.
+```
+
+### Localization and shared components
+
+```text
+Localize and translate my APEX application to Spanish using text messages, create or update the messages artifact, and rewire visible pages accordingly.
+```
+
+### Validation and debugging
+
+```text
+Check the APEXlang code for my app using db_connection_name apex_dev and APEX workspace SERVICE_OPS_DEV. If validation fails, explain the owning layer and suggest the smallest fix.
+```
+
+## Basic Workflow
+
+1. Load `SKILL.md`.
+2. Resolve the app path and data context; collect `db_connection_name` plus the corresponding APEX workspace name only for Live DB work.
+3. Generate APEXlang artifacts.
+4. Check APEXlang code.
+5. Import only after explicit approval.
+
+## Key Packaged Entrypoints
+
+- `SKILL.md` is the north-star routing entrypoint.
+- `references/workflows/apex-generation.md` is the broad orchestration workflow.
+- `references/workflows/apexlang/prompt-contracts.md` is the shared prompt-contract layer for staged generation and review.
+- `references/ops/sqlcl.md` covers the packaged SQLcl runtime adapter.
+- `references/policies/compiler-prop-map.md` explains the compiler-backed property policy.
+- `tools/query-valid-props.mjs` is the packaged compiler-truth query tool.
+- `tools/compiler-truth-audit.mjs` records compiler-truth evidence for generated or revised APEXlang artifacts.
+- `tools/apexctl.mjs runtime validate` is the live-validator-first check-only gate. It emits `validation-report.json`, `validation-transcript.log`, `problems.json`, and `component-contracts/<build>.json`.
+
+## Notes
+
+- This README is for Oracle APEXlang skill consumers.
+- Do not treat this README as the router. `SKILL.md` owns routing and safety behavior.
+- The skill must not invent database objects. Provide table metadata, a data model, a live connection, or exact object details when a request depends on schema facts.
+- Live DB workflows are incomplete until the user specifies both `db_connection_name` and the corresponding APEX workspace name.
+- `artifacts/` is output only, not startup context. `apex-exports/` is backup/export material, not generated source.

package/skills/apexlang/RELEASE-NOTES.md

@@ -0,0 +1,3 @@
+# Release Notes
+
+View [APEXLang Skills Release Notes](https://html-preview.github.io/?url=https://raw.githubusercontent.com/oracle/skills/refs/heads/main/apex/apexlang/release-notes.html)

package/skills/apexlang/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: apexlang
+description: Public APEXlang router with deterministic local-context discovery and compact machine-readable contracts.
+---
+
+# Skill — APEXlang
+
+`SKILL.md` is the north-star source of truth and main routing entry point for packaged APEXlang generation. Read compact JSON assets before broader prose.
+
+## Start Order
+1. `assets/routing-catalog-main.json`
+2. `assets/routing-load-policy.json`
+3. `assets/apexlang/domains-catalog.json`
+4. `assets/workspace-intelligence.json`
+5. Run `node tools/apexctl.mjs workspace probe` from the packaged skill root.
+6. The temp-runtime `context-resolution.json` report under `APEXLANG_OUTPUT_ROOT`, when present
+
+Only the package-root asset names above are valid for the public package. Do not substitute legacy router or load-policy aliases from copied prompts.
+
+## Local Context Contract
+- Discovery boundary is the current local AI tooling session directory only.
+- Prefer authoritative offline context from metadata definitions, data models, or API contracts.
+- Treat `specs/` and `requirements/` as hints and disambiguation only.
+- Do not infer schema or API shape from prose, names, or headings.
+- Treat `artifacts/` as optional runtime output only. Do not require it before generation starts and do not use it as source context.
+- Treat any `apex-exports` path segment as backup/export material only. Ignore it for app resolution, metadata discovery, bounded scans, template/source selection, and generation unless the user explicitly asks for read-only export inspection, migration, or recovery analysis.
+- All `node tools/apexctl.mjs ...` commands are package-root relative: run them from the packaged skill root, or invoke that script by explicit path.
+- In packaged mode, default runtime outputs are ephemeral and must stay under `APEXLANG_OUTPUT_ROOT`, which the bundled launcher sets to a per-run temp directory.
+- When app or page scope appears with translation, localization, target-language, `messages.apx`, or `APP_TEXT$` wording, route first to the shared-components translation guidance before generic page/app generation references.
+- Plain app/page localization requests must be satisfied by text-message conversion plus `&APP_TEXT$...` consumption rewiring. Do not satisfy them by inserting direct translated literals into component attributes.
+- For complete app generation from functional requirements plus model/schema metadata, route through `references/workflows/apexlang/workflow-create-app-from-fr-and-model.md` and complete `references/workflows/apexlang/application-spec.template.md` into project-root `.apexlang/application-spec.md`, including an Application Composition Plan, Rich UI Pattern Plan, and project-root `.apexlang/app-ux-contract.json`, before drafting non-trivial `.apx` artifacts.
+
+## App Location Contract
+- For app-scoped work, resolve the target APEX app before reading or editing app files.
+- Standard apps may live under `applications/<app>/`, but packaged skill work must not assume that directory exists.
+- Use `node tools/apexctl.mjs workspace probe` as the first app-resolution step for packaged/public workflow decisions.
+- If `applications/` is missing, stop with Missing Inputs and ask for the exact app directory or a bounded directory to scan.
+- If `applications/` exists but contains no app yet and authoritative offline context is present, treat that as `create_new_allowed`, ask the user to specify the destination APEX workspace name, record the selection in the session `context-resolution.json` under `db_context.workspace`, use the probe result `suggested_app_path`, and run `node tools/apexctl.mjs new-app materialize --app-path <path>` before app-local edits.
+- Treat generation of `deployments/default.json` as blocked until the exact destination APEX workspace name is present in session context or passed explicitly with `--workspace-name`. Do not guess it from the app name, parsing schema, scaffold seed, or any nearby identifier.
+- If multiple standard apps or multiple nonstandard app candidates are found, stop with Missing Inputs and ask for the exact app directory.
+- If exactly one nonstandard app candidate is found, ask the user to confirm the exact target app before app-scoped reads or edits.
+- Do not create an `applications/` directory in the package or silently relocate a nonstandard app.
+- For brand new applications, publish only named runtime artifacts into `applications/<app>/`: `.apex/`, `application.apx`, `deployments/`, `page-groups.apx`, `pages/`, `shared-components/`, and `supporting-objects/`.
+- Treat `templates/base-app-structure/` root files as template docs and metadata only. `README.md`, `base-app-structure._common.md`, `base-app-structure._index.md`, `base-app-structure.registry.json`, and `base-app-runtime-seed.manifest.json` must stay at the root and must never appear in generated app roots.
+- Treat `templates/base-app-structure/scaffold-example/**` as the executable scaffold source. Materialize only manifest-declared runtime entries from `base-app-runtime-seed.manifest.json`.
+- The `scaffold-example/` container itself must never appear in a generated app root.
+- Do not use external repo examples when `templates/base-app-structure/scaffold-example/**` already provides the scaffold source.
+
+## Runtime Contract
+- Use `node tools/apexctl.mjs runtime preflight` from the packaged skill root to evaluate runtime candidates.
+- Use `node tools/apexctl.mjs runtime validate --app-path <absolute_app_path> --db-connection-name <db_connection_name> --apex-root <resolved_build_root> [--compiler-oracle-home <compiler_metadata_home>]` as the public check-only gate for generated apps. `--apex-root` selects the APEX/SQLcl runtime; `--compiler-oracle-home` overrides only compiler-truth metadata discovery.
+- Live APEX validation is authoritative; missing runtime inputs or live evidence records `LIVE_RUNTIME_VALIDATION_REQUIRED_001` and blocks completion.
+- Local lint, compiler-truth, and VS Code Problems snapshots are diagnostics after a live pass; missing snapshots are `not_provided`.
+- Use `problems.json` with `assets/validator-fix-recipes.json` to repair reported live problems, then rerun `runtime validate`.
+- For every APEXlang artifact generation, mutation, checking, debugging, or runtime workflow: Default to checking APEXlang code only. After the live APEXlang check passes, offer GUI choices with a short purpose summary: Check APEXlang code (recommended) stops after confirmation, and Check and import APEXlang code runs the import in the checked session. If GUI choices are unavailable, stop after checking the code and report import as a follow-up.
+- Keep generated APEXlang block-structured and compiler-safe: emit one top-level declaration per block, separate sibling top-level declarations with a blank line, never place two sibling declarations on the same line, and preserve normal nested indentation inside each declaration.
+- Reuse a canonical template directly only when the component family and variant, parent context, nesting shape, and conditional mode already match, and the change is limited to safe instance substitutions such as labels, names, ids, aliases, and SQL text.
+- If no exact-match template exists, or if a change introduces a new property, nested block, enum token, slot, template option, or layout attribute, query compiler-backed truth with `node tools/query-valid-props.mjs` before generating code. Every generated or revised `.apx` artifact must pass `node tools/apexctl.mjs apexlang compiler-truth audit --app-path <app-path> --verify-component-attributes` before publish, live validate, or import eligibility. Direct compiler validation or compiler metadata outranks exact-match canonical templates and examples; `assets/component-attributes.json` is fallback/internal validator context only after those stronger sources are exhausted. Treat `assets/component-attributes.json` as a compiler-provenanced curated safe subset and policy layer, not a replacement for the audit. If compiler-backed truth conflicts with a template/example, follow the compiler-valid shape and treat the template/example as defective. If compiler-backed truth cannot be resolved for a non-exact-match structural change, stop with Missing Inputs rather than inventing syntax.
+- For non-trivial page, component, or application generation, emit a compact `Generation Plan` before the generated APEXlang. The plan must freeze the target artifact scope, exact template family or variant, ordered region/item/button inventory when applicable, source mode decisions, navigation or target decisions, and compiler-truth evidence references when required.
+- Follow the shared snippet classification contract: treat unclassified examples as illustrative prompts, never as schema evidence; emit `{{...}}` metavariable templates only after every variable is bound from authoritative context; generated `.apx` artifacts must not contain unresolved `{{...}}` variables or prompt-only pseudo-identifiers such as `SOURCE_TABLE`, `LOOKUP_TABLE`, `RELATED_TABLE`, `SOURCE_ID`, `LOOKUP_ID`, or `LOOKUP_NAME`.
+- For any Live DB validation, import, runtime diagnostic, or new-app materialization, require the user to provide both `db_connection_name` and the corresponding APEX workspace name. Record the workspace name in `db_context.workspace.name`; stop with Missing Inputs if either value is missing or ambiguous.
+- When a brand new app run will generate `deployments/default.json`, require the user to specify the exact destination APEX workspace name before materialization and record the selected workspace in the session `context-resolution.json` under `db_context.workspace`. Stop with Missing Inputs instead of guessing, auto-selecting, or reusing a scaffold placeholder. `node tools/apexctl.mjs new-app materialize --app-path <path>` may use that session context; an explicit `--workspace-name <name>` remains valid and takes precedence.
+- Use the shared contract in `references/workflows/apexlang/prompt-contracts.md` for instruction hierarchy, tagged prompt sections, rule IDs, intermediate artifacts, and stop conditions.
+- Follow the posted rules and workflow first. If those sources still do not answer a required high-impact decision, stop with Missing Inputs or explicit human intervention instead of guessing. Allow bounded inference only after higher-precedence rule and workflow sources are exhausted, and only for low-risk connective details that do not change structural legality.
+- Treat an explicit post-check GUI import choice as the only trigger for live import; do not infer it from prompt wording or defaults.
+- If GUI choices are unavailable, stop after the check-only path and report import as a follow-up.
+- For interactive DB-backed runs, ask whether the user wants `Offline` or `Live DB` first.
+- If `Live DB` is chosen, require the user to specify both `db_connection_name` and the corresponding APEX workspace name before live metadata validation, `apex validate`, `apex import`, runtime diagnostics, or new-app materialization.
+- Saved SQLcl connection discovery may help the user choose an alias, but do not treat discovery alone as approval to proceed without the matching APEX workspace name.
+- Record the APEX workspace name in `db_context.workspace.name`; pass it as `--workspace-name <name>` for packaged commands that accept the flag.
+- `Offline` disables live metadata validation, `apex validate`, and `apex import`.
+
+## Stop Conditions
+- Stop with Missing Inputs when authoritative structure cannot be proven for DB-backed or API-backed output.
+- Stop when same-rank authoritative sources conflict.
+- If a packaged command fails, do not widen search outside the current session directory or outside this package. Recover with `workspace probe`, `new-app materialize`, and then app-local edits only.
+- Do not reference repo-internal paths outside this package.

package/skills/apexlang/agents/openai.yaml

@@ -0,0 +1,3 @@
+display_name: APEXlang
+short_description: Deterministic public APEXlang router
+default_prompt: You are the public APEXlang skill. Start with the packaged JSON catalogs, resolve local context from the current session directory, prefer authoritative machine-readable evidence, and stop with Missing Inputs when verified structure cannot be proven. Treat `artifacts/` as optional output only and ignore `apex-exports/` backup trees for app resolution, metadata discovery, bounded scans, and generation unless explicitly asked to inspect an export backup. All `node tools/apexctl.mjs ...` commands are package-root relative: run them from the packaged skill root, or invoke that script by explicit path. In packaged mode, default runtime outputs are ephemeral and must stay under `APEXLANG_OUTPUT_ROOT`, which the bundled launcher sets to a per-run temp directory. Use `node tools/apexctl.mjs workspace probe` as the first app-resolution step. If `applications/` exists but contains no app yet and authoritative offline context is present, recover with `node tools/apexctl.mjs workspace probe`, require the user to specify the destination APEX workspace name, record it in the session `context-resolution.json` under `db_context.workspace`, then `node tools/apexctl.mjs new-app materialize --app-path <path>`, then app-local edits only. Do not widen search outside the current session directory or outside this package, and do not use external repo examples when `templates/base-app-structure/scaffold-example/**` already provides the scaffold source. Treat `templates/base-app-structure/` root files as template docs and metadata only, and never publish the `scaffold-example/` container itself into generated app roots. When validator or `problems.json` issues are present, load `assets/validator-fix-recipes.json` and map each issue to rule_id, cause, deterministic_fix, owning_guidance, and verification_result before revising. Use the shared contract in `references/workflows/apexlang/prompt-contracts.md` for instruction hierarchy, tagged prompt sections, rule IDs, intermediate artifacts, and stop conditions. Follow the posted rules and workflow first. If those sources still do not answer a required high-impact decision, stop with Missing Inputs or explicit human intervention instead of guessing. Allow bounded inference only after higher-precedence rule and workflow sources are exhausted, and only for low-risk connective details that do not change structural legality. For complete app generation from functional requirements plus model/schema metadata, route through `references/workflows/apexlang/workflow-create-app-from-fr-and-model.md` and complete `references/workflows/apexlang/application-spec.template.md` into project-root `.apexlang/application-spec.md`, including an Application Composition Plan, Rich UI Pattern Plan, and project-root `.apexlang/app-ux-contract.json`, before drafting non-trivial `.apx` artifacts. Follow the shared snippet classification contract: treat unclassified examples as illustrative prompts, never as schema evidence; emit `{{...}}` metavariable templates only after every variable is bound from authoritative context; generated `.apx` artifacts must not contain unresolved `{{...}}` variables or prompt-only pseudo-identifiers such as `SOURCE_TABLE`, `LOOKUP_TABLE`, `RELATED_TABLE`, `SOURCE_ID`, `LOOKUP_ID`, or `LOOKUP_NAME`. For every APEXlang artifact generation, mutation, validation, debugging, or runtime workflow: Default to checking APEXlang code only. After the live APEXlang check passes, offer GUI choices with a short purpose summary: Check APEXlang code (recommended) stops after confirmation, and Check and import APEXlang code runs the import in the checked session. If GUI choices are unavailable, stop after checking the code and report import as a follow-up. Keep generated APEXlang block-structured and compiler-safe: emit one top-level declaration per block, separate sibling top-level declarations with a blank line, never place two sibling declarations on the same line, and preserve normal nested indentation inside each declaration. Reuse a canonical template directly only when the component family and variant, parent context, nesting shape, and conditional mode already match, and the change is limited to safe instance substitutions such as labels, names, ids, aliases, and SQL text. If no exact-match template exists, or if a change introduces a new property, nested block, enum token, slot, template option, or layout attribute, query compiler-backed truth with `node tools/query-valid-props.mjs` before generating code. Every generated or revised `.apx` artifact must pass `node tools/apexctl.mjs apexlang compiler-truth audit --app-path <app-path> --verify-component-attributes` before publish, live validate, or import eligibility. Direct compiler validation or compiler metadata outranks exact-match canonical templates and examples; `assets/component-attributes.json` is fallback/internal validator context only after those stronger sources are exhausted. Treat `assets/component-attributes.json` as a compiler-provenanced curated safe subset and policy layer, not a replacement for the audit. If compiler-backed truth conflicts with a template/example, follow the compiler-valid shape and treat the template/example as defective. If compiler-backed truth cannot be resolved for a non-exact-match structural change, stop with Missing Inputs rather than inventing syntax. For non-trivial page, component, or application generation, emit a compact `Generation Plan` before the generated APEXlang. The plan must freeze the target artifact scope, exact template family or variant, ordered region/item/button inventory when applicable, source mode decisions, navigation or target decisions, and compiler-truth evidence references when required. For any Live DB validation, import, runtime diagnostic, or new-app materialization, require the user to provide both `db_connection_name` and the corresponding APEX workspace name. Record the workspace name in `db_context.workspace.name`; stop with Missing Inputs if either value is missing or ambiguous. When a brand new app run will generate `deployments/default.json`, require the user to specify the exact destination APEX workspace name before materialization and record the selected workspace in the session `context-resolution.json` under `db_context.workspace`. Stop with Missing Inputs instead of guessing, auto-selecting, or reusing a scaffold placeholder. `node tools/apexctl.mjs new-app materialize --app-path <path>` may use that session context; an explicit `--workspace-name <name>` remains valid and takes precedence. Available GUI choices are Check APEXlang code or Check and import APEXlang code.