pgkiln 0.0.0-stage → 0.31.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,12 @@
+pgkiln
+Copyright 2026 Vargar
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+Oracle and Oracle APEX are registered trademarks of Oracle and/or its
+affiliates. This project is not affiliated with, endorsed by, or sponsored
+by Oracle.
+
+Third-party components shipped with pgkiln keep their own licences: Leaflet
+(BSD-2-Clause) for map regions and Lucide icons (ISC, https://lucide.dev/license),
+served from their npm packages.

package/README.md

@@ -1,3 +1,240 @@
-# Temporary Holding Version
+# pgkiln
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/pgkiln/pgkiln/actions/workflows/ci.yml/badge.svg)](https://github.com/pgkiln/pgkiln/actions/workflows/ci.yml)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Website](https://img.shields.io/badge/website-pgkiln.vargar.eu-c2410c.svg)](https://pgkiln.vargar.eu)
+
+**[Website](https://pgkiln.vargar.eu)** · **[Documentation](https://pgkiln.vargar.eu/docs/)** ·
+**[Tutorial](https://pgkiln.vargar.eu/docs/tutorial)** · **[Coming from Oracle APEX](https://pgkiln.vargar.eu/docs/from-apex)** ·
+**[Roadmap](ROADMAP.md)**
+
+A low-code, SQL-driven application builder for PostgreSQL, modeled on
+Oracle APEX. Applications are **data**: pages, regions, items, buttons,
+dynamic actions, validations and processes are rows in the `meta` schema. A
+runtime turns those rows into web pages, and the builder is an editor for
+them.
+
+> pgkiln is an independent open source project and is not affiliated with Oracle. Oracle and APEX are trademarks of Oracle.
+
+<p align="center">
+  <img src="docs/images/builder-page-designer.png" alt="The page designer: component tree, layout and property editor" width="100%">
+</p>
+
+## Screenshots
+
+Everything below is the HR example application (`npm run example:hr`) and the builder. The
+screenshots are made by `npm run screenshots`.
+
+| | |
+|---|---|
+| ![Dashboard with metric cards and charts](docs/images/app-dashboard.png) | ![Interactive report with search and filters](docs/images/app-interactive-report.png) |
+| **Dashboard**: metric cards and charts, all of it SQL | **Interactive report**: search, filters, sort, download |
+| ![Faceted search with suggested filters](docs/images/app-faceted-search.png) | ![Map and cards regions](docs/images/app-cards-map.png) |
+| **Smart filters and faceted search** | **Map and cards** regions on the same table |
+| ![Charts in dark mode](docs/images/app-charts-dark.png) | ![Calendar region](docs/images/app-calendar.png) |
+| **Charts**, in dark mode | **Calendar** of leave requests |
+| ![App Builder home](docs/images/builder-home.png) | ![SQL Workshop object browser](docs/images/builder-object-browser.png) |
+| **App Builder** home | **SQL Workshop**: object browser with RLS and grants |
+
+<p align="center">
+  <img src="docs/images/app-phone.png" alt="The dashboard on a phone" width="260"><br>
+  <em>Responsive on phones and tablets, and installable as a Progressive Web App</em>
+</p>
+
+## Quick start
+
+With Docker (no Node.js needed):
+
+```bash
+mkdir pgkiln && cd pgkiln
+curl -fsSLO https://raw.githubusercontent.com/pgkiln/pgkiln/main/deploy/compose.yaml
+curl -fsSL -o .env https://raw.githubusercontent.com/pgkiln/pgkiln/main/deploy/.env.example   # fill in the four secrets
+docker compose up -d   # http://127.0.0.1:3100/builder (admin / the password from .env)
+```
+
+Or from the source, for developing:
+
+```bash
+npm install
+cp .env.example .env
+npm run setup        # Postgres 17 on localhost:5434 + the pgkiln schema (migrations)
+npm run dev          # http://127.0.0.1:3100/builder (admin / admin)
+```
+
+Then build an application on your own tables: *Create application* in the builder generates
+report and form pages from a table, and everything else (regions, items, processes, security,
+translations, documents, approvals) is added in the page designer and Shared Components. The
+[tutorial](docs/guide/10-tutorial.md) walks through one.
+
+### The example application
+
+pgkiln itself contains no application. The repository ships an example built on it, **HR**
+(`examples/hr/`): employees and departments, leave requests with approvals, a dashboard, a REST API,
+translations, documents, automations and row level security, all of it ordinary pgkiln metadata
+and PostgreSQL code, the way you would build your own.
+
+```bash
+npm run example:hr   # http://127.0.0.1:3100/a/hr
+```
+
+Users (password = username): `king` is admin and manager (the president), `blake` and `jones` are
+managers, `allen` and `scott` are employees, and `demo` is an admin who is not an employee. Sign
+in as different users to see authorization schemes and row level security at work.
+
+### Developing pgkiln
+
+```bash
+npm test             # unit + security regression tests (installs the HR example as their fixture)
+npm run test:e2e     # browser tests on phone/tablet/desktop (npx playwright install chromium first)
+```
+
+`npm run db:reset` recreates the database (pgkiln only). Schema changes go in a new
+`db/migrations/NNN_*.sql` file; `npm run db:migrate` applies pending ones.
+
+## Working with AI coding agents
+
+pgkiln ships an **MCP server** (`pgkiln mcp`), so Claude Code, Cursor and other agents can find an
+application, read and explain its pages, look at the tables and RLS policies behind them, search
+this documentation, and change the application: export it as files (one YAML file per component,
+SQL inline), edit them, show the diff, and import them again in one transaction. In a checkout,
+`.mcp.json` starts it for Claude Code; for your own project:
+
+```bash
+claude mcp add pgkiln -- /path/to/pgkiln/bin/pgkiln.js mcp
+```
+
+Then ask things like *"explain what happens when I press Save on page 3 of hr"* or *"add a hire
+date column to the employee report and show me the diff"*. Queries it runs are read-only. See
+[AI coding agents](docs/guide/20-ai-agents.md).
+
+Without an agent, the same export and import is on the command line (`pgkiln export hr --format text`,
+`pgkiln diff`, `pgkiln import --replace`, see [the CLI](docs/guide/18-cli.md)) and in the builder
+(*Export* / *Import*).
+
+## Documentation
+
+What's next: [ROADMAP.md](ROADMAP.md).
+
+
+The **[user guide](docs/README.md)** explains how everything works: installation and
+configuration, concepts, the builder, every region and item type, processing, dynamic actions,
+security, the SQL reference, a step-by-step tutorial, a guide for Oracle APEX developers, and
+developing pgkiln itself.
+
+## What's in the box
+
+For a full comparison with Oracle APEX 26.1, including what's missing, see
+**[docs/apex-feature-parity.md](docs/apex-feature-parity.md)**.
+
+**Runtime (Universal Theme-style UI, responsive on phone, tablet and desktop)**
+- Side or top navigation (a drawer on tablets and phones), breadcrumbs, user menu, dark mode, theme colours
+- 12-column region grid; region templates *standard*, *plain*, *collapsible*
+- Regions:
+  - **Interactive report**: search, column filters, sort, rows per page, CSV download, reflow on phones
+  - **Interactive grid**: inline edit, add and delete rows
+  - **Form**: automatic row fetch and DML, in a page or a **modal dialog**
+  - **Charts**: bar, column, line, area and donut
+  - **Cards and metric cards**, **calendar**, **faceted search**
+  - **Static and dynamic content**
+- **Items**: text, textarea, number, date, datetime, select, popup LOV (searchable), radio, checkbox, switch, checkbox group, multi-select, email, phone, URL, colour, display, hidden, password. Lists of values come from SQL, `STATIC:` or shared lists; items can be required or read-only (by condition), and select lists can cascade.
+- **Dynamic actions**:
+  - Client-side: show, hide, enable, disable, alert, submit
+  - Server-side: set value from SQL, execute SQL, refresh a region, refresh an item
+- Validations, processes (form DML, grid DML, any SQL/PL/pgSQL), branches, application items and processes
+
+**Builder**
+- App Builder home, app dashboard, and create page wizards from any table: *Report and form*, *Interactive grid*, *Form*, *Cards*, *Calendar*, *Chart*, *Map*, *Faceted search* and *Master detail*, with defaults from the catalog
+- A **page designer** with a component tree and a grouped property editor
+- **Shared components**: navigation menu, authorization schemes, lists of values, application items and processes, users
+- Settings with theme and a security checklist, and an **activity monitor**
+- **SQL Workshop**: SQL commands, plus an object browser with RLS policies and grants
+- Export and import of apps as JSON, and developer accounts
+- A `pgkiln` command line: migrations, export/import, and apps as one file per component for git
+  (diff, update in place)
+- An MCP server for AI coding agents (`pgkiln mcp`): read, explain, change, diff and import applications
+
+**Security** is covered in [SECURITY.md](SECURITY.md): least-privilege runtime role, per-app database roles, authorization schemes, checksummed URLs and grid rows, CSRF protection, login throttling, a strict CSP, and 28 security regression tests.
+
+## PL/pgSQL examples in the HR example application
+
+The example ([`examples/hr/hr.sql`](examples/hr/hr.sql)) keeps its business rules in
+the database and calls them from the app:
+
+| Where in the app | Database object | Shows |
+|---|---|---|
+| Leave requests → *Submit request* | `hr.request_leave()` | Validation in PL/pgSQL (dates, overlaps, a 25-day balance). `raise exception … using column = 'end_date'` puts the message on the matching form field. |
+| Leave request → *Approve* / *Reject* | `hr.decide_leave()` | Authorization in the database: a recursive CTE checks the management chain (`hr.is_manager_of`). |
+| Manager's dashboard, employee's dashboard | `hr.notify_leave_requested()`, `hr.notify_leave_decided()` | Triggers creating notifications for *other* users (SECURITY DEFINER past RLS) |
+| Employee form → *Give 10% raise* | `hr.give_raise()` | Role check via `meta.has_role()`; the returned salary is written back into the item |
+| Employee form, salary field | trigger `hr.check_salary()` | A BEFORE trigger rule whose error appears on the Salary field |
+| Employee form, *Job* | `hr.suggest_salary()` | Dynamic action: set a value from SQL as you type |
+| Leave form, dates | `hr.business_days()` | Dynamic action computing working days live |
+| Administration → Audit trail | trigger `hr.audit()` | A generic jsonb-diff audit trail recording the **application user** |
+| Leave requests, notifications, audit | RLS policies | Each user sees only their own and their team's rows |
+| Sign in | after-login application process | Maps the app user to an employee (`AI_EMPNO`, `AI_ENAME`) |
+
+## How it works
+
+```
+Browser ── HTML + /static/app.js (dialogs, dynamic actions; no inline JS)
+   │
+Runtime (Fastify, server-rendered)            Builder (/builder)
+   │ per request: BEGIN                          │ owner connection
+   │   set pgkiln.app_user / app_id / session    │ edits meta.* rows
+   │   SET LOCAL ROLE <app db_role>              │ SQL Workshop
+   │   authorization → visibility → render/process
+   │ COMMIT
+   │ connects as pgkiln_runtime (least privilege)
+Postgres
+   meta.*        app definitions, sessions (hashed tokens), activity log
+   your schemas  tables, PL/pgSQL, RLS policies
+```
+
+### Bind variables
+
+`:NAME` in developer SQL is replaced by the item's value as an **escaped,
+untyped string literal**. Postgres then resolves the literal's type from its
+context, the way Oracle converts types implicitly. APEX patterns like
+`where :P2_DEPTNO is null or deptno = :P2_DEPTNO` therefore work. With `$1`
+parameters they fail with *could not determine data type of parameter*.
+Empty strings are `NULL`, as in APEX. The scanner skips literals,
+identifiers, comments, dollar quotes and `::` casts (see `test/binds.test.ts`).
+Inside functions and `DO` blocks, use `meta.v('P1_X')`.
+
+### SQL API for developers
+
+| Function | Purpose |
+|---|---|
+| `meta.app_user()` | Signed-in application user (`nobody` when anonymous) |
+| `meta.has_role('admin')` | Role check; use it in RLS policies |
+| `meta.v('P1_ITEM')` | Session state value |
+| `meta.page_url(3, '{"P3_ID": 7}')` | Link with a valid checksum |
+| `meta.generate_crud('app', 'schema.table', 2, 3)` | The page wizard |
+| `meta.generate_page('app', 'calendar', 'schema.table', 4)` | The other page wizards (form, cards, calendar, chart, map, facets, master_detail) |
+| `meta.export_app('alias')` / `meta.import_app(json)` | Deployment (or `pgkiln export` / `pgkiln import`, [chapter 18](docs/guide/18-cli.md)) |
+
+## Project layout
+
+```
+db/migrations/     pgkiln: versioned schema (metadata repository, roles, SQL API)
+examples/hr/       an example application built on pgkiln (not part of it): schema, PL/pgSQL, RLS, app definition
+src/runtime/       context, authz, items, report, grid, charts, calendar, facets, regions, render, engine, routes
+src/builder/       builder UI; components.ts is the spec the property editor is generated from
+src/security.ts    checksums, headers, password policy
+src/cli/           the `pgkiln` command line (bin/pgkiln.js; docs/guide/18-cli.md)
+public/            theme (CSS), app.js, icon sprite
+test/              bind scanner unit tests, security regression tests, e2e/ browser tests
+```
+
+## Roadmap
+
+See the prioritised roadmap at the end of [docs/apex-feature-parity.md](docs/apex-feature-parity.md#roadmap-proposed-priority).
+
+## Contributing
+
+Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md), and report
+vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
+
+## License
+
+Copyright 2026 Vargar. Licensed under the [Apache License, Version 2.0](LICENSE).