pi-apexlang 0.1.0

package/skills/apexlang/templates/shared-components/app-computations.md

@@ -0,0 +1,141 @@
+---
+templateId: app-computations
+componentType: app-computations
+version: 1.0
+---
+
+# Purpose
+
+The app computations component defines application-level computations that set values for application items during application processing points.
+
+---
+
+# Generation Rules (MANDATORY)
+
+**Important**
+
+If the item referenced is not found in the application, then DO NOT create the computation and stop this process!
+
+1. Create the app computation id.
+2. Render exactly one `computation {}` strategy per app computation.
+3. All updates should be made to the app-computations.apx file found under an application's /shared-components directory.
+4. `security {}` is optional. All other values documented as required must be present.
+
+---
+
+# Variable Contract
+
+## Required Variables
+
+- appComputation
+  - Type: text
+  - The app computation id; lowercase with dashes, no spaces
+
+- itemName
+  - Type: text
+  - Target application item name
+  - Should be a valid item defined within an application under one of the following:
+    - /shared-components/app-items.md
+    - /pages/*
+
+- execution.sequence
+  - Type: number
+  - Sequence order for execution
+
+- execution.point
+  - Type: enum
+  - Valid values:
+    - afterAuthentication
+    - beforeHeader (default)
+    - afterHeader
+    - afterRegions
+    - beforeRegions
+    - afterSubmit
+    - beforeFooter
+    - afterFooter
+
+- error.errorMessage
+  - Type: text
+  - Message shown when computation evaluation fails
+
+- computation
+  - Type: object
+  - Exactly one strategy must be selected from the list below:
+    - staticValue
+      - `computation.staticValue` (required)
+    - expression
+      - `computation.type: expression` (required)
+      - `computation.plsqlExpression` (required)
+    - item
+      - `computation.type: item` (required)
+      - `computation.itemName` (required)
+    - functionBody
+      - `computation.type: functionBody` (required)
+      - `computation.plsqlFunctionBody` (required; fenced `plsql` block)
+    - sqlQuerySingleValue
+      - `computation.type: sqlQuerySingleValue` (required)
+      - `computation.sqlQuery` (required; fenced `sql` block)
+    - sqlQueryMultipleValues
+      - `computation.type: sqlQueryMultipleValues` (required)
+      - `computation.sqlQuery` (required; fenced `sql` block)
+
+## Optional Variables
+
+- security.authorizationScheme
+  - Type: reference
+  - Authorization scheme reference (for example `@administration-rights`)
+  - If omitted, omit the entire `security {}` block
+
+---
+
+# Conditional Rendering Rules
+
+- `security {}` is optional and rendered only when `security.authorizationScheme` is provided.
+- Do not render more than one computation strategy in the same `computation {}` block.
+- For `staticValue`, do not render `computation.type`.
+- For all non-static strategies, render `computation.type` and its required companion attribute.
+
+---
+
+# Output Template - Static Value
+```
+appComputation {{appComputation}} (
+    itemName: {{itemName}}
+    execution {
+        sequence: {{execution.sequence}}
+        point: {{execution.point}}
+    }
+    computation {
+        staticValue: {{computation.staticValue}}
+    }
+    error {
+        errorMessage: {{error.errorMessage}}
+    }
+    security {
+        authorizationScheme: {{security.authorizationScheme}}
+    }
+)
+```
+
+---
+
+# Output Template - Non-Static
+```
+appComputation {{appComputation}} (
+    itemName: {{itemName}}
+    execution {
+        sequence: {{execution.sequence}}
+        point: {{execution.point}}
+    }
+    computation {
+        type: {{computation.type}}
+        {{computation.attribute}}: {{computation.value}}
+    }
+    error {
+        errorMessage: {{error.errorMessage}}
+    }
+    security {
+        authorizationScheme: {{security.authorizationScheme}}
+    }
+)
+```

package/skills/apexlang/templates/shared-components/app-items.md

@@ -0,0 +1,77 @@
+---
+templateId: app-items
+componentType: app-items
+version: 1.0
+---
+
+# Purpose
+
+The app items component defines application-level or global application items used across pages and shared logic.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Create the app item id.
+2. Use only supported security attributes from this template.
+3. All updates should be made to the app-items.apx file found under an application's /shared-components directory.
+
+---
+
+# Variable Contract
+
+## Required Variables
+
+- appItem
+  - Type: text
+  - The app item id; uppercase with underscores, no spaces
+
+## Optional Variables
+
+- scope
+  - Scope of the app item
+  - Valid values:
+    - global
+  - If omitted, item is application-scoped
+
+- security.sessionStateProtection
+  - Session state protection mode
+  - Valid values:
+    - checksumRequiredAppLevel
+    - checksumRequiredSessionLevel
+    - checksumRequiredUserLevel
+    - unrestricted
+
+- security.escapeSpecialChars
+  - Boolean flag for output escaping
+  - Use only when explicitly required (for example, unrestricted no-escape variants)
+
+---
+
+# Conditional Rendering Rules
+
+- If `scope` is not provided, omit `scope`.
+- If `security.sessionStateProtection` is not provided, omit the entire `security {}` block unless another security attribute is present.
+- If `security.escapeSpecialChars` is not provided, omit `escapeSpecialChars`.
+- If `security.escapeSpecialChars` is provided, render it inside `security {}`.
+
+---
+
+# Output Template - Minimal
+```
+appItem {{appItem}} (
+)
+```
+
+---
+
+# Output Template - Full
+```
+appItem {{appItem}} (
+    scope: {{scope}}
+    security {
+        sessionStateProtection: {{security.sessionStateProtection}}
+        escapeSpecialChars: {{security.escapeSpecialChars}}
+    }
+)
+```

package/skills/apexlang/templates/shared-components/app-processes/app-processes._common.md

@@ -0,0 +1,122 @@
+---
+templateId: app-processes.common
+componentType: appProcess
+version: 1.0
+imports:
+  - app-processes.before-header.md
+  - app-processes.after-header.md
+  - app-processes.before-regions.md
+  - app-processes.after-regions.md
+  - app-processes.after-footer.md
+  - app-processes.after-submit.md
+  - app-processes.processing.md
+  - app-processes.after-authentication.md
+  - app-processes.ajax-callback.md
+  - app-processes.new-session.md
+description: Canonical contract and guardrails for application processes.
+---
+
+# Purpose
+
+Standardize application process generation with an executeCode-only contract, deterministic execution points, and server-side condition rules.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Emit APEXlang DSL only; no markdown commentary inside output.
+2. Always declare `execution.point` using supported enum values: `beforeHeader`, `afterHeader`, `beforeRegions`, `afterRegions`, `afterFooter`, `afterSubmit`, `processing`, `afterAuthentication`, `ajaxCallback`, `newSession`.
+3. `appProcess` MUST use `type: executeCode` only.
+4. `appProcess` MUST NOT use the `invokeApi` process type.
+5. If packaged logic is required, call packages in `source.plsqlCode` using named notation.
+6. Server-side conditions must use types catalogued in `references/policies/memory-bank/20-data/apex.logic.md`; include only the attributes required for the chosen type.
+7. Honor build options and authorization schemes; omit blocks entirely when variables are null.
+8. Place new processes in `applications/<app>/shared-components/app-processes.apx`.
+
+---
+
+# Variable Contract
+
+| Name | Required | Type | Notes |
+|------|----------|------|-------|
+| staticId | yes | string | Lowercase, hyphenated identifier (e.g., `process-on-load`). |
+| name | yes | string | Builder label describing purpose. |
+| type | yes | literal | `executeCode` only for appProcess. |
+| source.plsqlCode | yes | plsql | Required for appProcess; must follow named-notation guardrail. |
+| execution.sequence | yes | number | Execution order; default to 10 if unspecified. |
+| execution.point | yes | enum | See Rule 2. |
+| error.errorMessage | optional | string | Provide friendly message; omit block if null. |
+| error.displayLocation | optional | enum | `inlineInNotification`, `onErrorPage`. |
+| serverSideCondition.type | optional | enum | `rowsReturned`, `noRowsReturned`, `expression`, `functionBody`, `always`, `never`. |
+| serverSideCondition.sqlQuery | conditional | sql | Required when type is `rowsReturned`/`noRowsReturned`. |
+| serverSideCondition.plsqlExpression | conditional | plsql | Required when type is `expression`. |
+| serverSideCondition.plsqlFunctionBody | conditional | plsql | Required when type is `functionBody`. |
+| security.authorizationScheme | optional | string | Reference shared authorization aliases (`@administration-rights`, etc.). |
+| config.buildOption | optional | string | Build option reference (`@commented-out`, `!@commented-out`). |
+| comments.comments | optional | string | Descriptive notes for maintainers. |
+
+---
+
+# Conditional Rendering Rules
+
+- Always render `type: executeCode` for appProcess.
+- Always render `source { plsqlCode: ```plsql ... ``` }` for appProcess.
+- Do not render `invoke {}` in appProcess templates.
+- Include `serverSideCondition {}` only when `serverSideCondition.type` is supplied.
+- Add `security { authorizationScheme: @alias }` only when authorization is set.
+- Add `config { buildOption: <value> }` only when build option differs from default.
+- Include `comments {}` when descriptive text exists; omit otherwise.
+
+---
+
+# Output Template — Full
+```
+appProcess {{staticId}} (
+    name: {{name}}
+    type: executeCode
+    source {
+        plsqlCode:
+            ```plsql
+            {{source.plsqlCode}}
+            ```
+    }
+    execution {
+        sequence: {{execution.sequence}}
+        point: {{execution.point}}
+    }
+    error {
+        errorMessage: {{error.errorMessage}}
+        displayLocation: {{error.displayLocation}}
+    }
+    serverSideCondition {
+        type: {{serverSideCondition.type}}
+        sqlQuery:
+            ```sql
+            {{serverSideCondition.sqlQuery}}
+            ```
+        plsqlExpression: {{serverSideCondition.plsqlExpression}}
+        plsqlFunctionBody:
+            ```plsql
+            {{serverSideCondition.plsqlFunctionBody}}
+            ```
+    }
+    security {
+        authorizationScheme: {{security.authorizationScheme}}
+    }
+    config {
+        buildOption: {{config.buildOption}}
+    }
+    comments {
+        comments: {{comments.comments}}
+    }
+)
+```
+
+---
+
+# Guardrails Reminder
+
+- Follow Named Notation for all PL/SQL calls (see `references/policies/memory-bank/00-guard/ai.guard.md`).
+- Do not invent execution points; use documented enums only.
+- Keep app-process logic concise and deterministic.
+- Ensure server-side condition SQL never references session state without bind variable notation (`:Pxx_ITEM`).

package/skills/apexlang/templates/shared-components/app-processes/app-processes._index.md

@@ -0,0 +1,18 @@
+---
+templateId: app-processes.index
+componentType: template
+version: 1.0
+imports:
+  - app-processes._common.md
+description: Routing entrypoint for app-processes templates.
+---
+
+# Purpose
+
+Primary routing entrypoint for `app-processes` templates.
+
+# Load Order
+
+1. Load this file.
+2. Load `app-processes._common.md`.
+3. Load one scenario template in this folder.

package/skills/apexlang/templates/shared-components/app-processes/app-processes.after-authentication.md

@@ -0,0 +1,61 @@
+---
+templateId: app-processes.after-authentication
+componentType: appProcess
+version: 1.0
+imports:
+  - app-processes._common.md
+description: Application process that runs immediately after authentication completes.
+---
+
+# Purpose
+
+Execute logic once a user successfully authenticates but before navigation proceeds.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Use `execution.point: afterAuthentication`.
+2. `appProcess` must use `type: executeCode`.
+3. Keep logic idempotent; authentication can run multiple times per session.
+
+---
+
+# Recommended Use Cases
+
+- Persist user preferences or consent acknowledgments.
+- Route administrators to oversight dashboards.
+- Log authentication metadata to audit tables.
+
+---
+
+# Output Template — Execute Code Example
+```
+appProcess {{staticId}} (
+    name: {{name}}
+    type: executeCode
+    source {
+        plsqlCode:
+            ```plsql
+            app_process_api.after_authentication_hook(
+                p_app_user => :APP_USER
+            );
+            ```
+    }
+    execution {
+        sequence: {{execution.sequence}}
+        point: afterAuthentication
+    }
+    serverSideCondition {
+        type: {{serverSideCondition.type}}
+    }
+)
+```
+
+---
+
+# Guardrails
+
+- Avoid referencing page items; rely on session and authentication context.
+- Handle failures gracefully; prefer logging over blocking login without user messaging.
+- Remove optional blocks when variables are not supplied.

package/skills/apexlang/templates/shared-components/app-processes/app-processes.after-footer.md

@@ -0,0 +1,61 @@
+---
+templateId: app-processes.after-footer
+componentType: appProcess
+version: 1.0
+imports:
+  - app-processes._common.md
+description: Application process that executes after the page footer renders.
+---
+
+# Purpose
+
+Handle post-render tasks such as asynchronous logging, clean-up, or notification dispatch once the full page has rendered.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Use `execution.point: afterFooter`.
+2. `appProcess` must use `type: executeCode`.
+3. Defer expensive work to background jobs or scheduled processes when possible.
+
+---
+
+# Recommended Use Cases
+
+- Queue analytics or telemetry updates that should occur after rendering.
+- Finalize temporary resources (e.g., purge collections created earlier).
+- Trigger external webhooks announcing completed page load.
+
+---
+
+# Output Template — Execute Code Example
+```
+appProcess {{staticId}} (
+    name: {{name}}
+    type: executeCode
+    source {
+        plsqlCode:
+            ```plsql
+            app_process_api.finalize_page_render(
+                p_page_id => :APP_PAGE_ID
+            );
+            ```
+    }
+    execution {
+        sequence: {{execution.sequence}}
+        point: afterFooter
+    }
+    error {
+        errorMessage: {{error.errorMessage}}
+    }
+)
+```
+
+---
+
+# Guardrails
+
+- Keep logic non-blocking; if failures occur, log via centralized error handler.
+- Remove optional blocks when values are not provided.
+- Respect build options to toggle diagnostics in non-production environments.

package/skills/apexlang/templates/shared-components/app-processes/app-processes.after-header.md

@@ -0,0 +1,66 @@
+---
+templateId: app-processes.after-header
+componentType: appProcess
+version: 1.0
+imports:
+  - app-processes._common.md
+description: Application process that fires immediately after the page header renders and before body regions load.
+---
+
+# Purpose
+
+Perform lightweight logic that depends on header initialization (for example, session messages, breadcrumbs) but must execute before regions render.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Use `execution.point: afterHeader`.
+2. If using `executeCode`, ensure PL/SQL is idempotent and leverages named notation.
+3. Do not modify items rendered within body regions—limit to global context or session settings.
+
+---
+
+# Recommended Use Cases
+
+- Broadcast global alerts or notifications before regions load.
+- Set context items used by dynamic actions or shared components.
+- Trigger logging or analytics hooks after header setup completes.
+
+---
+
+# Output Template — Execute Code Example
+```
+appProcess {{staticId}} (
+    name: {{name}}
+    type: executeCode
+    source {
+        plsqlCode:
+            ```plsql
+            app_process_api.log_page_entry(
+                p_page_id => :APP_PAGE_ID,
+                p_user    => :APP_USER
+            );
+            ```
+    }
+    execution {
+        sequence: {{execution.sequence}}
+        point: afterHeader
+    }
+    serverSideCondition {
+        type: {{serverSideCondition.type}}
+    }
+    comments {
+        comments: {{comments.comments}}
+    }
+)
+```
+
+---
+
+# Guardrails
+
+- Keep PL/SQL logic concise (< 50 lines); refactor into `app_process_api` when growing.
+- Avoid DML unless wrapped in packaged APIs with error handling.
+- Remove `serverSideCondition {}` when unused.
+

package/skills/apexlang/templates/shared-components/app-processes/app-processes.after-regions.md

@@ -0,0 +1,66 @@
+---
+templateId: app-processes.after-regions
+componentType: appProcess
+version: 1.0
+imports:
+  - app-processes._common.md
+description: Application process that fires after all body regions render but before the footer.
+---
+
+# Purpose
+
+Run wrap-up tasks that depend on region data (for example, aggregating results, staging notifications) prior to footer rendering.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Use `execution.point: afterRegions`.
+2. Avoid heavy DML; prefer enqueueing jobs or calling packaged APIs for asynchronous work.
+3. Only reference session state items populated by regions earlier in the rendering cycle.
+
+---
+
+# Recommended Use Cases
+
+- Queue background processes once regions finish presenting data.
+- Evaluate region-computed flags before displaying footer messages.
+- Persist analytics events capturing region interaction context.
+
+---
+
+# Output Template — Execute Code Example
+```
+appProcess {{staticId}} (
+    name: {{name}}
+    type: executeCode
+    source {
+        plsqlCode:
+            ```plsql
+            app_process_api.enqueue_refresh(
+                p_page_id => :APP_PAGE_ID,
+                p_user    => :APP_USER
+            );
+            ```
+    }
+    execution {
+        sequence: {{execution.sequence}}
+        point: afterRegions
+    }
+    serverSideCondition {
+        type: {{serverSideCondition.type}}
+    }
+    config {
+        buildOption: {{config.buildOption}}
+    }
+)
+```
+
+---
+
+# Guardrails
+
+- Ensure PL/SQL calls use named notation.
+- Remove optional blocks when variables are not supplied.
+- If asynchronous behavior is required, document completion handling for downstream regions.
+

package/skills/apexlang/templates/shared-components/app-processes/app-processes.after-submit.md

@@ -0,0 +1,65 @@
+---
+templateId: app-processes.after-submit
+componentType: appProcess
+version: 1.0
+imports:
+  - app-processes._common.md
+description: Application process that runs after page submission but before computations and validations.
+---
+
+# Purpose
+
+Execute immediate logic triggered by page submission prior to computation/validation phases.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Use `execution.point: afterSubmit`.
+2. `appProcess` must use `type: executeCode`.
+3. Keep package calls in named-notation PL/SQL and handle exceptions with friendly messages.
+
+---
+
+# Recommended Use Cases
+
+- Branch or reroute users based on submitted values.
+- Run centralized hooks before validation or computation phases.
+- Initialize session state used during validation or computation steps.
+
+---
+
+# Output Template — Execute Code Example
+```
+appProcess {{staticId}} (
+    name: {{name}}
+    type: executeCode
+    source {
+        plsqlCode:
+            ```plsql
+            app_process_api.on_after_submit(
+                p_request => :REQUEST
+            );
+            ```
+    }
+    execution {
+        sequence: {{execution.sequence}}
+        point: afterSubmit
+    }
+    error {
+        errorMessage: {{error.errorMessage}}
+        displayLocation: {{error.displayLocation}}
+    }
+    serverSideCondition {
+        type: {{serverSideCondition.type}}
+    }
+)
+```
+
+---
+
+# Guardrails
+
+- Ensure prerequisite items are submitted; otherwise, explicitly set them before execution.
+- Omit optional blocks when variables are not provided.
+- Keep business logic consolidated in shared packages for reuse.