pi-apexlang 0.1.0

package/LICENSE

@@ -0,0 +1,35 @@
+Copyright (c) 2025 Oracle and/or its affiliates.
+
+The Universal Permissive License (UPL), Version 1.0
+
+Subject to the condition set forth below, permission is hereby granted to any
+person obtaining a copy of this software, associated documentation and/or data
+(collectively the "Software"), free of charge and under any and all copyright
+rights in the Software, and any and all patent rights owned or freely
+licensable by each licensor hereunder covering either (i) the unmodified
+Software as contributed to or provided by such licensor, or (ii) the Larger
+Works (as defined below), to deal in both
+
+(a) the Software, and
+(b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+one is included with the Software (each a "Larger Work" to which the Software
+is contributed by such licensors),
+
+without restriction, including without limitation the rights to copy, create
+derivative works of, display, perform, and distribute the Software and make,
+use, sell, offer for sale, import, export, have made, and have sold the
+Software and the Larger Work(s), and to sublicense the foregoing rights on
+either these or other terms.
+
+This license is subject to the following condition:
+The above copyright notice and either this complete permission notice or at
+a minimum a reference to the UPL must be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# 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.
+
+## Install
+
+Try the local checkout without installing it:
+
+```bash
+pi -e .
+```
+
+Install this Git repository for the current user:
+
+```bash
+pi install git:github.com/avhrst/pi-apex
+```
+
+Or install it only for the current project:
+
+```bash
+pi install git:github.com/avhrst/pi-apex -l
+```
+
+After an npm release, the equivalent command is:
+
+```bash
+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`:
+
+```text
+/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:
+
+```text
+/skill:apexlang Probe this workspace and tell me which APEX app is safe to edit.
+```
+
+```text
+/skill:apexlang Add an interactive report to the orders app using the existing table metadata. Validate locally and show me the compiler-truth evidence.
+```
+
+```text
+/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:
+
+| Action | Effect |
+| --- | --- |
+| `workspace_probe` | Finds bounded local context and candidate APEX apps. |
+| `new_app_materialize` | Creates Oracle's base app scaffold after UI confirmation. |
+| `local_validate` | Runs local APEXlang and vocabulary checks. |
+| `compiler_truth_audit` | Verifies generated component structure against compiler metadata. |
+| `query_valid_props` | Queries legal properties for an APEXlang component. |
+| `runtime_preflight` | Resolves and checks the local SQLcl/APEX runtime. |
+| `runtime_doctor` | Diagnoses runtime configuration. |
+| `runtime_validate` | Runs Oracle's live check gate, then offers an interactive check-only or same-session validate-and-import choice. |
+
+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.
+
+Without GUI support, the tool always stops after checking and reports import
+as a follow-up.
+
+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:
+
+- Oracle APEX with APEXlang support, using the latest available 26.1 build.
+- SQLcl 26.1.2 or newer.
+- 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
+
+```text
+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 700+ file
+documentation tree is not injected into the model context.
+
+## Develop and verify
+
+```bash
+npm install
+npm run check
+npm run verify:package
+```
+
+To update the Oracle snapshot and record a new pinned commit:
+
+```bash
+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
+
+The vendored skill comes from
+[`oracle/skills/apex/apexlang`](https://github.com/oracle/skills/tree/30e30dbcbf5f92f3564bc85f8fd59d32736adcd6/apex/apexlang)
+at commit `30e30dbcbf5f92f3564bc85f8fd59d32736adcd6`. See
+[`UPSTREAM.json`](UPSTREAM.json) and
+[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
+
+This package is distributed under the Universal Permissive License 1.0. See
+[`LICENSE`](LICENSE).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,15 @@
+# Third-party notices
+
+## Oracle APEXlang skill
+
+`skills/apexlang` is an unmodified snapshot of
+[`oracle/skills/apex/apexlang`](https://github.com/oracle/skills/tree/30e30dbcbf5f92f3564bc85f8fd59d32736adcd6/apex/apexlang)
+at commit `30e30dbcbf5f92f3564bc85f8fd59d32736adcd6`.
+
+Copyright (c) 2025 Oracle and/or its affiliates.
+
+The snapshot is distributed under the Universal Permissive License 1.0. See
+[`LICENSE`](LICENSE).
+
+Oracle and Oracle APEX are trademarks of Oracle and/or its affiliates. This
+project is an independent integration and is not endorsed by Oracle.

package/UPSTREAM.json

@@ -0,0 +1,8 @@
+{
+  "repository": "https://github.com/oracle/skills.git",
+  "commit": "30e30dbcbf5f92f3564bc85f8fd59d32736adcd6",
+  "source_path": "apex/apexlang",
+  "vendored_path": "skills/apexlang",
+  "content_sha256": "413de83cf898dce3d3752469d9ebc5fbd57ebff6805e6224ad82420b74230494",
+  "license": "UPL-1.0"
+}

package/extensions/apexlang/index.ts

@@ -0,0 +1,426 @@
+import { rm, mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+  APEXLANG_ACTIONS,
+  runApexlang,
+  runApexlangCreateNewProof,
+  runApexlangImport,
+  type ApexlangAction,
+  type ApexlangInput,
+  type ApexlangRunResult
+} from "../lib/apexlang-cli.mjs";
+
+const MAX_TOOL_OUTPUT = 80_000;
+const COMMAND_TIMEOUT_MS = 10 * 60 * 1000;
+const CHECK_ONLY_CHOICE = "Check APEXlang code (recommended) — stop after the successful live check";
+const IMPORT_CHOICE = "Check and import APEXlang code — revalidate and import in one SQLcl session";
+const UPDATE_EXISTING_CHOICE = "Update an existing app — require one proven remote target";
+const CREATE_NEW_CHOICE = "Create a new app — require proof that the alias is absent";
+
+function trimOutput(value: string, outputRoot?: string): string {
+  if (value.length <= MAX_TOOL_OUTPUT) return value;
+  const location = outputRoot ? ` at ${outputRoot}` : "";
+  return `${value.slice(0, MAX_TOOL_OUTPUT)}\n\n[output truncated; full reports are in APEXLANG_OUTPUT_ROOT${location}]`;
+}
+
+function actionWritesProject(params: ApexlangInput): boolean {
+  return params.action === "new_app_materialize" ||
+    (params.action === "local_validate" && params.fix_vocab === true);
+}
+
+function confirmationMessage(params: ApexlangInput): string {
+  if (params.action === "new_app_materialize") {
+    return `Materialize a new APEXlang app at ${params.app_path ?? "the requested path"}?`;
+  }
+  return `Apply vocabulary fixes inside ${params.app_path ?? "the requested app"}?`;
+}
+
+function parsePayload(result: ApexlangRunResult): Record<string, unknown> | undefined {
+  try {
+    return JSON.parse(result.stdout) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+function liveValidationPassed(result: ApexlangRunResult): boolean {
+  if (!result.ok) return false;
+  const payload = parsePayload(result);
+  const validationSources = payload?.validation_sources as
+    | { live_validator?: { status?: string } }
+    | undefined;
+  return (payload?.live_check_status === "pass" || payload?.validation_status === "pass") &&
+    validationSources?.live_validator?.status === "pass";
+}
+
+function liveImportPassed(result: ApexlangRunResult): boolean {
+  if (!result.ok) return false;
+  const payload = parsePayload(result);
+  return payload?.validate_status === "pass" &&
+    payload?.import_status === "pass" &&
+    payload?.runtime_gate_status === "pass";
+}
+
+function createNewTargetProved(result: ApexlangRunResult): boolean {
+  const payload = parsePayload(result);
+  return !result.ok &&
+    payload?.target_resolution_mode === "create-new" &&
+    payload?.target_resolution_status === "not_found_in_workspace" &&
+    payload?.create_new_confirmation_required === true &&
+    payload?.import_status === "blocked" &&
+    payload?.failure_class === "create_new_confirmation_required";
+}
+
+function processOutput(result: ApexlangRunResult): string {
+  const streams = result.ok ? [result.stdout, result.stderr] : [result.stderr, result.stdout];
+  return trimOutput(streams.filter(Boolean).join("\n").trim(), result.outputRoot);
+}
+
+function failureOutput(result: ApexlangRunResult, fallback: string): string {
+  const output = processOutput(result) || fallback;
+  return `${output}\n\nAPEXlang reports: ${result.outputRoot}`;
+}
+
+type ApexlangDependencies = {
+  run: typeof runApexlang;
+  runCreateNewProof: typeof runApexlangCreateNewProof;
+  runImport: typeof runApexlangImport;
+  outputRoot: typeof getOutputRoot;
+};
+
+export function createApexlangTool(overrides: Partial<ApexlangDependencies> = {}) {
+  const dependencies: ApexlangDependencies = {
+    run: runApexlang,
+    runCreateNewProof: runApexlangCreateNewProof,
+    runImport: runApexlangImport,
+    outputRoot: getOutputRoot,
+    ...overrides
+  };
+
+  return defineTool({
+  name: "apexlang",
+  label: "APEXlang",
+  description:
+    "Run the vendored Oracle APEXlang workspace probe, local checks, compiler-truth queries, runtime diagnostics, live validation, or confirmed new-app scaffolding. After a live check passes, import is available only through a separate interactive choice.",
+  promptSnippet: "Probe, scaffold, and check Oracle APEXlang applications",
+  promptGuidelines: [
+    "Load the apexlang skill before using the apexlang tool and follow its routing and Missing Inputs rules.",
+    "Use apexlang workspace_probe before app-scoped APEXlang work.",
+    "Use apexlang runtime_validate only after the user provides both db_connection_name and the matching APEX workspace_name; import requires the tool's separate post-check GUI choice."
+  ],
+  executionMode: "sequential",
+  parameters: Type.Object({
+    action: StringEnum(APEXLANG_ACTIONS, {
+      description: "The bounded APEXlang operation to run."
+    }),
+    app_path: Type.Optional(
+      Type.String({
+        description: "APEX application directory contained within the current pi workspace."
+      })
+    ),
+    db_connection_name: Type.Optional(
+      Type.String({
+        description:
+          "Saved SQLcl connection name. Required with workspace_name for live checks, runtime diagnostics, and new-app materialization. Never pass credentials or a connect string."
+      })
+    ),
+    workspace_name: Type.Optional(
+      Type.String({ description: "APEX workspace name corresponding to db_connection_name." })
+    ),
+    execution_mode: Type.Optional(StringEnum(["auto", "build-root", "path"] as const)),
+    apex_root: Type.Optional(
+      Type.String({ description: "Optional APEX/SQLcl runtime root used by live validation." })
+    ),
+    compiler_oracle_home: Type.Optional(
+      Type.String({ description: "Optional Oracle home or compiler metadata location." })
+    ),
+    component: Type.Optional(
+      Type.String({ description: "Semantic component name for query_valid_props." })
+    ),
+    component_type_id: Type.Optional(
+      Type.String({ description: "Exact compiler component type ID for query_valid_props." })
+    ),
+    template_component: Type.Optional(
+      Type.String({ description: "Universal Theme template component for query_valid_props." })
+    ),
+    parent: Type.Optional(Type.String({ description: "Optional parent component filter." })),
+    group: Type.Optional(Type.String({ description: "Optional property group filter." })),
+    when: Type.Optional(
+      Type.Array(Type.String(), {
+        description: "Compiler assumptions such as identification.type=NATIVE_IR.",
+        maxItems: 20
+      })
+    ),
+    list: Type.Optional(Type.Boolean({ description: "List matching compiler component types." })),
+    supporting_objects: Type.Optional(
+      Type.Boolean({ description: "Include supporting objects in runtime preflight/doctor." })
+    ),
+    fix_vocab: Type.Optional(
+      Type.Boolean({ description: "Apply local vocabulary fixes after interactive confirmation." })
+    )
+  }),
+
+  async execute(_toolCallId, params, signal, onUpdate, ctx) {
+    const input = params as ApexlangInput;
+    if (actionWritesProject(input)) {
+      if (!ctx.hasUI) {
+        throw new Error("This APEXlang action changes project files and requires interactive confirmation.");
+      }
+      const confirmed = await ctx.ui.confirm("Confirm APEXlang project change", confirmationMessage(input));
+      if (!confirmed) {
+        return {
+          content: [{ type: "text", text: "APEXlang project change cancelled." }],
+          details: { action: input.action, cancelled: true }
+        };
+      }
+    }
+
+    onUpdate?.({
+      content: [{ type: "text", text: `Running APEXlang ${input.action}…` }],
+      details: { action: input.action }
+    });
+
+    const outputRoot = await dependencies.outputRoot();
+    const runOptions = {
+      cwd: ctx.cwd,
+      outputRoot,
+      ...(signal ? { signal } : {}),
+      timeoutMs: COMMAND_TIMEOUT_MS
+    };
+    const result = await dependencies.run(input, runOptions);
+    const output = processOutput(result);
+    if (!result.ok) {
+      throw new Error(
+        failureOutput(result, `APEXlang ${input.action} failed with exit code ${result.code}.`)
+      );
+    }
+
+    if (input.action === "runtime_validate") {
+      if (!liveValidationPassed(result)) {
+        throw new Error(
+          failureOutput(
+            result,
+            "APEXlang runtime validation did not produce authoritative live pass evidence."
+          )
+        );
+      }
+
+      if (!ctx.hasUI) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${output}\n\nLive validation passed. Import was not run because GUI choices are unavailable; importing remains an explicit interactive follow-up.`
+            }
+          ],
+          details: {
+            action: input.action,
+            exitCode: result.code,
+            outputRoot: result.outputRoot,
+            liveValidationPassed: true,
+            imported: false
+          }
+        };
+      }
+
+      const choice = await ctx.ui.select("APEXlang live check passed. Choose the next step:", [
+        CHECK_ONLY_CHOICE,
+        IMPORT_CHOICE
+      ]);
+      if (choice !== CHECK_ONLY_CHOICE && choice !== IMPORT_CHOICE) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${output}\n\nLive validation passed. The post-check choice was cancelled; import was not run.`
+            }
+          ],
+          details: {
+            action: input.action,
+            exitCode: result.code,
+            outputRoot: result.outputRoot,
+            liveValidationPassed: true,
+            imported: false,
+            postCheckChoice: "cancelled"
+          }
+        };
+      }
+      if (choice === IMPORT_CHOICE) {
+        const targetChoice = await ctx.ui.select("Choose the explicitly intended import target:", [
+          UPDATE_EXISTING_CHOICE,
+          CREATE_NEW_CHOICE
+        ]);
+        if (targetChoice !== UPDATE_EXISTING_CHOICE && targetChoice !== CREATE_NEW_CHOICE) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `${output}\n\nLive validation passed. Import was cancelled before choosing a target mode.`
+              }
+            ],
+            details: {
+              action: input.action,
+              exitCode: result.code,
+              outputRoot: result.outputRoot,
+              liveValidationPassed: true,
+              imported: false
+            }
+          };
+        }
+
+        const targetResolutionMode = targetChoice === CREATE_NEW_CHOICE
+          ? "create-new"
+          : "update-existing";
+        let createNewConfirmed = false;
+        if (targetResolutionMode === "create-new") {
+          onUpdate?.({
+            content: [
+              {
+                type: "text",
+                text: "Resolving the selected workspace to prove that the new app alias is absent…"
+              }
+            ],
+            details: { action: input.action, targetResolutionMode, provingTarget: true }
+          });
+          const proofResult = await dependencies.runCreateNewProof(input, runOptions);
+          if (!createNewTargetProved(proofResult)) {
+            throw new Error(
+              failureOutput(
+                proofResult,
+                "Oracle did not prove that the create-new target is absent from the selected workspace."
+              )
+            );
+          }
+          const proofPayload = parsePayload(proofResult);
+          const provenAlias = String(proofPayload?.source_application_alias ?? "the app alias");
+          const provenWorkspace = String(
+            proofPayload?.lookup_scope_workspace_name ?? input.workspace_name ?? "the selected workspace"
+          );
+          createNewConfirmed = await ctx.ui.confirm(
+            "Confirm new APEX application",
+            `Oracle proved that ${provenAlias} is absent from ${provenWorkspace}. Create it by rerunning validation and import together?`
+          );
+          if (!createNewConfirmed) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `${output}\n\nLive validation passed. Create-new import was cancelled.`
+                }
+              ],
+              details: {
+                action: input.action,
+                exitCode: result.code,
+                outputRoot: result.outputRoot,
+                liveValidationPassed: true,
+                imported: false
+              }
+            };
+          }
+        }
+
+        onUpdate?.({
+          content: [{ type: "text", text: "Revalidating and importing APEXlang in one SQLcl session…" }],
+          details: { action: input.action, importApproved: true, targetResolutionMode }
+        });
+        const importResult = await dependencies.runImport(input, runOptions, {
+          targetResolutionMode,
+          createNewConfirmed
+        });
+        const importOutput = processOutput(importResult);
+        if (!liveImportPassed(importResult)) {
+          throw new Error(
+            failureOutput(
+              importResult,
+              "APEXlang validate-and-import did not produce authoritative import pass evidence."
+            )
+          );
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: trimOutput(
+                `Import completed: validate_status=pass, import_status=pass, runtime_gate_status=pass, target_resolution_mode=${targetResolutionMode}.\n\nApproved same-session validate and import:\n${importOutput}\n\nInitial live check:\n${output}`,
+                importResult.outputRoot
+              )
+            }
+          ],
+          details: {
+            action: input.action,
+            exitCode: importResult.code,
+            outputRoot: importResult.outputRoot,
+            liveValidationPassed: true,
+            imported: true,
+            postCheckChoice: IMPORT_CHOICE,
+            targetResolutionMode
+          }
+        };
+      }
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: output || `APEXlang ${input.action} completed with exit code ${result.code}.`
+        }
+      ],
+      details: {
+        action: input.action,
+        exitCode: result.code,
+        outputRoot: result.outputRoot,
+        preludeCount: result.preludeResults.length,
+        ...(input.action === "runtime_validate"
+          ? {
+              liveValidationPassed: true,
+              imported: false,
+              postCheckChoice: CHECK_ONLY_CHOICE
+            }
+          : {})
+      }
+    };
+  }
+  });
+}
+
+const apexlangTool = createApexlangTool();
+
+let outputRootPromise: Promise<string> | undefined;
+
+function getOutputRoot(): Promise<string> {
+  outputRootPromise ??= mkdtemp(join(tmpdir(), "pi-apexlang-"));
+  return outputRootPromise;
+}
+
+async function cleanOutputRoot(): Promise<void> {
+  if (!outputRootPromise) return;
+  const outputRoot = await outputRootPromise;
+  outputRootPromise = undefined;
+  await rm(outputRoot, { recursive: true, force: true });
+}
+
+export default function apexlangExtension(pi: ExtensionAPI) {
+  pi.registerTool(apexlangTool);
+  pi.on("session_shutdown", async () => {
+    await cleanOutputRoot();
+  });
+}
+
+export {
+  APEXLANG_ACTIONS,
+  CHECK_ONLY_CHOICE,
+  IMPORT_CHOICE,
+  CREATE_NEW_CHOICE,
+  UPDATE_EXISTING_CHOICE,
+  actionWritesProject,
+  confirmationMessage,
+  createNewTargetProved,
+  liveImportPassed,
+  liveValidationPassed
+};
+export type { ApexlangAction };