pgkiln 0.52.0 → 0.53.0

package/docs/guide/09-reference.md

@@ -81,7 +81,9 @@ select meta.web_request_source('EXCHANGE', '{"currency": "EUR"}');
   must be on `PGKILN_REST_ALLOWED_HOSTS` (unset: no calls), private and loopback addresses are refused
   when the connection is made unless the host is in `PGKILN_REST_PRIVATE_HOSTS`, redirects (at most 3)
   go through the same checks, the response is cut off at `PGKILN_REST_MAX_BYTES` (default 5 MB) and
-  the time limit is 1–60 seconds.
+  the time limit is 1–60 seconds. A workspace's [network access list](03-builder.md#network-access)
+  (sprint 118) narrows the hosts for its applications: a refused request ends with `status` `error`
+  and the reason in `message`, and is logged (debug log, Refused calls).
 - **Web credentials** are named, never passed: `p_credential => 'NAME'` signs the request with a
   credential of the current application (basic, bearer, header, OAuth2), and only for the URLs it is
   valid for. The secret is decrypted by the server for the request only and is never stored with it

package/docs/guide/11-from-apex.md

@@ -65,6 +65,7 @@ What's missing is listed in the [feature parity matrix](../apex-feature-parity.m
 | Automatic Time Zone | Settings → Globalization → Time zone and Automatic time zone; My account → Time zone ([chapter 14](14-globalization.md#time-zones)) |
 | Universal Theme's default style (26.1: *Iris*) | Base style *Iris* (the default for new applications), *Lavender* or *Standard* ([chapter 14](14-globalization.md#base-styles-iris-lavender-and-standard)) |
 | Theme styles, *Enable End Users to Choose Theme Style* | Theme style (automatic/light/dark) and *Users may choose light or dark*; Theme Roller style variants with *Users may choose a style* ([chapter 14](14-globalization.md#style-variants-theme-roller)) |
+| Universal Theme 26.2: *Pillar Light* / *Pillar Dark*, Theme Roller's *Header Pillar Strip*, `u-color-*-subtle` | Theme Roller → *Navigation appearance* and *Header strip colour* (per application or style), the same utility classes ([chapter 14](14-globalization.md#navigation-appearances-pillar-light-and-pillar-dark)) |
 | Template Options (regions, buttons) | *Template options* in the Page Designer: CSS classes from a fixed list ([chapter 4](04-pages-and-regions.md#template-options)) |
 | ORDS | Not needed to serve apps; REST APIs with PostgREST, see [below](#ords-and-postgrest) |
 | Export `f123.sql` / APEXlang | `meta.export_app('alias')` (JSON) |

package/docs/guide/12-development.md

@@ -42,7 +42,8 @@ src/
                            merge into the main application or refresh the copy, both through cli/replace.ts
   cli/                     the command line: main.ts (commands, help, exit codes), apps.ts (connect, export,
                            read, import), files.ts (directories, zip), diff.ts, replace.ts (import --replace in place),
-                           mcp.ts (`pgkiln mcp`: the MCP server for AI coding agents, chapter 20)
+                           mcp.ts (`pgkiln mcp`: the MCP server for AI coding agents, chapter 20), only.ts (sprint 116:
+                           `import --replace --only pages/12`, the named files merged over the application's current export)
   app.ts / server.ts       Fastify setup / entry point
   db.ts                    the owner and shared runtime pools, `runtime` (the current scope's: runtimeScope), appTx() (SET LOCAL ROLE + pgkiln.* settings, NOTICEs to the debug log), savepoints
   workspace-db.ts          isolated workspaces (090): the isolated applications (cached 5 s), a pool per workspace login (passwords from
@@ -95,6 +96,9 @@ src/
                            objects, type reporting, roles viewer/editor/administrator as schemes EDITOR and ADMIN, page 1 a Data
                            Reporter), reportingApps(), reportingAppCount() (meta.reporting_app_count, for the workspace home)
   tabledef.ts              (sprint 95) a table as a definition: readTable(), checkTable(), tableSql() (CREATE, or ALTER from the catalog's version)
+  datasec.ts               (sprint 119, WS-13) data security per table: readSecurity() (policies, column privileges per role, the
+                           masking view and its configuration in the view comment), checkSecurity(), securitySql() (GRANT / REVOKE,
+                           the masking view owned by <schema>_masking); the page is builder/data-security.ts
   sqlformat.ts             (sprint 93) formatSql(): the worksheet's Format (clauses per line, keyword case; strings and comments kept)
   sqlplan.ts               (sprint 92) EXPLAIN (FORMAT JSON) as a tree: parsePlan() (self time, slowest step, misestimates), planText()
   quicksql.ts              Quick SQL: shorthand parser and PostgreSQL DDL generator (unit tested)
@@ -110,7 +114,12 @@ src/
   geocode.ts               the installation's geocoder for address items (GEOCODER_URL, Nominatim search API)
   mvt.ts                   Mapbox Vector Tile encoding for map layers served as tiles
   yamltext.ts              the text style of the directory export: a strict YAML subset, written and read
-  webclient.ts             outgoing HTTP to web services: allow-list, address checks at connect time (SSRF), redirects, limits
+  webclient.ts             outgoing HTTP to web services: allow-list, address checks at connect time (SSRF), redirects, limits;
+                           (sprint 118) a request's scope (OutboundScope): the workspace's network access list, checked on every hop
+                           (checkUrl/scopeProblem), refusals reported to the scope
+  network-acl.ts           (sprint 118, WS-9) workspace network access lists (meta.workspace.network_*): scopeForApp/scopeForWorkspace
+                           (no cache), parseHostList, recordRefusal/purgeRefusals (meta.network_refusal, 7 days), mailHostAddress
+                           (a workspace mail service's SMTP host: both lists, resolved once, the checked address connected to)
   datapump.ts              (sprint 103, DA-16) Schema Export / Import jobs (meta.dump_job): findTools (pg_dump/pg_restore ≥ the
                            server's major), startExport (pg_dump, argument array, PGPASSWORD), readToc/parseToc (pg_restore --list),
                            startImport (pg_restore -f - run in one transaction between schema renames; data-only in FK order),
@@ -137,7 +146,10 @@ src/
                            or XOAUTH2, Microsoft Graph sendMail, Amazon SES v2 raw MIME with signV4, Resend, Postmark, SendGrid,
                            Mailgun, log; MailError says whether a retry may help; client-credentials token cache; settingsProblems),
                            mail.ts (sendWith(): service enabled, allowed sender, secret decrypted; mailTick(): claim with SKIP LOCKED,
-                           send, retry after 1/4/16/64 minutes, purge after 30 days; the NOTIFY pgkiln_mail listener)
+                           send, retry after 1/4/16/64 minutes, purge after 30 days; the NOTIFY pgkiln_mail listener);
+                           (sprint 118) the service of meta.mail_service_for_app (the app's, else its workspace's own), each attempt's
+                           provider and duration, serviceSettings()/verifyService(): a workspace service's checks (no base or token URL,
+                           its SMTP host through network-acl.ts mailHostAddress)
   ai/                      AI services (migration 060): types.ts (the provider interface, AiError kinds),
                            anthropic.ts (Claude through @anthropic-ai/sdk: streamed, effort, structured outputs via
                            output_config.format, refusal fallbacks, stop_reason checks, typed SDK errors), openai.ts (the openai
@@ -164,7 +176,8 @@ src/
     shortcuts.ts           (103) "NAME" shortcuts in static content, help texts and confirm messages
     render.ts              page chrome (nav, breadcrumb), dynamic action JSON, theme (the page's nonce'd <style>, light/dark and style switches)
     styles.ts              base styles (BASE_STYLES: Iris, Lavender, Standard; baseStyleOf → html data-style), Theme Roller style variants: fixed lists (fonts, sizes, corners), parseStyle/appStyles checks, the request's
-                           style (user choice, default), themeCss() (only hex values and constants reach the CSS)
+                           style (user choice, default), themeCss() (only hex values and constants reach the CSS); (sprint 117) NAV_APPEARANCES
+                           (Pillar Light / Dark), navAppearance() → the <body> classes nav-pillar-*, the header strip (--strip)
     template-options.ts    template options: the fixed CSS class list per region and button, templateClasses() (unknown values ignored)
     regions.ts             region shell + chart (drill-down links, gauge settings)/cards/dynamic dispatch with row limits, lazy placeholder and cache, buttons (menu buttons, badges; (124) menu entries {action} → data-menu-entry for menu_entry dynamic actions)
     report.ts, report-views.ts (group by, pivot, chart), compute.ts (computed column expressions), grid.ts (aggregates, row actions, Actions menu, single row view, layoutFromForm), grid-layout.ts (column layouts: clean, arrange, per user), master-detail.ts (signed master row selection, details), facets.ts (facetChart: a facet's counts as a chart, sprint 65), items.ts
@@ -253,7 +266,10 @@ src/
     wizards.ts             create page wizards: step 2 forms per page type (defaults from meta.wizard_defaults), POST → meta.generate_page
                            (the generators are PL/pgSQL in migration 047: catalog, defaults, form/cards/calendar/chart/map/facets/master-detail)
     home.ts                App Builder home at /builder/apps and /builder (tiles, applications report/cards, Recent; /builder redirects
-                           to the Workspace home when meta.workspace.builder_home = 'home'), Create, Import, Dashboard, Utilities
+                           to the Workspace home when meta.workspace.builder_home = 'home'), Create, Import, Dashboard, Utilities;
+                           (116) Updated by, working copies and the application lock in the report and the cards
+    app-updates.ts         (sprint 116, migration 125) who changed an application last: developer() notes a builder POST under
+                           /apps/:id or /pages/:pid (or a Create / Import), an onSend hook records a success in meta.app_change
     workspace-home.ts      (sprint 109, migration 119) the Workspace home /builder/home, opened after sign-in: tool cards (Data Reporter
                            when GET /builder/reporter exists), workspace message edited in place (workspaceAdmin), Summary, Top
                            applications / users / developers over meta.developer.home_timeframe, System message (src/release-check.ts),
@@ -286,7 +302,15 @@ src/
                            (Workspace home). Every id from a request is looked up in the current workspace
     region-help.ts         the Attributes (JSON) help per region type, with links to the guide
     mail.ts                Workspace utilities → Mail services (administrators: providers, write-only secret, allowed senders,
-                           applications with From and daily limit, test) and Applications → Activity → Mail (retry, cancel)
+                           applications with From and daily limit, test) and Applications → Activity → Mail (retry, cancel);
+                           serviceForm/formValues/runCheck shared with workspace-mail.ts (sprint 118)
+    mail-queue.ts          (sprint 118, WS-9) Administration → Mail queue (/builder/mail-queue): queueScope (administrators: all or
+                           ?ws=; workspace administrators: the current workspace), figures, per hour, per workspace / application,
+                           slowest provider calls, failures; Retry / Purge one or all failed, scope checked again per mail
+    network-access.ts      (sprint 118, WS-9) Administration → Network access (/builder/network): the installation's list, a workspace's
+                           list (workspaceAdmin), Check a URL (nothing called), the workspaces (administrators), refused calls
+    workspace-mail.ts      (sprint 118, WS-9) a workspace's own mail service (/builder/workspaces/:id/mail, WORKSPACE_<id>): its
+                           administrators only, write-only secret, checks through mail.ts runCheck with the workspace's guard
     shared.ts              Shared Components and access control
     designer.ts            page designer: component tree (with computations and branches), layout canvas and gallery, property editor, toolbar;
                            (sprint 86) GET /builder/apps/:app/pages/:no, /builder/pages/:id redirects browsers there (designerUrl in ui.ts)
@@ -304,6 +328,7 @@ src/
     object-browser.ts      (sprint 75) the Object Browser: objects by type, system objects hidden, a table in tabs, column actions as SQL to review
     table-editor.ts        (sprint 95) Table Properties: GET/POST /sql/objects/table (create, edit ?o=, ?template=), fromForm(), Preview / Apply
                            (one transaction) / Open in the worksheet
+    data-security.ts       (sprint 119) a table's Security: GET/POST /sql/objects/security?o= (policies, roles × columns, masks), Preview / Apply
     object-actions.ts      (sprint 94) an object's ⋯ menu (objectMenu) in the worksheet and the Object Browser: Quick DDL (objectDdl), Drop with
                            dependents, Add index / trigger / policy as drafts; GET /sql/objects/action, /sql/objects/panel (Open in a panel)
     data-modeler.ts        (sprint 98) SQL Workshop → Data Modeler: /sql/modeler (diagrams, meta.sql_diagram, 111), /:id (SVG), /:id/objects, /layout,
@@ -348,7 +373,8 @@ src/
     ldap.ts                Users → LDAP directories
     documents.ts           document template preview (Shared Components)
     pwa.ts                 Settings → Progressive Web App (icon upload)
-    themeroller.ts         Settings → Theme Roller: style variants (add, edit, rename, delete), default style, users may choose
+    themeroller.ts         Settings → Theme Roller: style variants (add, edit, rename, delete), default style, users may choose;
+                           (sprint 117) navigation appearance and header strip colours (application and per style), the preview's menu
     subscriptions.ts       Shared Components → Subscriptions: subscribe, refresh, unsubscribe, subscribers and publish; the note under a component
     reporter.ts            page designer: Data Reporter settings (sources: table or view, offered columns, labels, masks; sharing;
                            (sprint 110) a dataset as a source, who may edit, who may moderate, publishing)
@@ -396,7 +422,8 @@ src/
                            into agents and regions), toolCallTable() (Activity → AI usage → Tool calls), agentOptions()
     supporting.ts          supporting objects: review page, running the install/upgrade/deinstall scripts as the app's role in one transaction
 public/
-  app.css                  theme (light/dark, responsive; --font, --font-size, --radius for style variants; template option classes to-*)
+  app.css                  theme (light/dark, responsive; --font, --font-size, --radius for style variants; template option classes to-*;
+                           (sprint 117) navigation tree states, RTL via logical properties, body.nav-pillar-*, u-color-*-subtle, the busy bar)
   app.js                   client runtime: dialogs (dialog_closed actions), popup LOVs (sprint 115: the next page loads on scroll through an
                            IntersectionObserver, ‹/More without one), dynamic actions (focus, classes, messages; sprint 115: wait_popup /
                            remove_wait_popup as a modal <dialog class="wait-popup">, pgkiln.waitPopup(), the menu_entry event), grids (add/duplicate rows, master-detail refresh, move/resize columns, copy/paste of cell ranges), menus, lazy regions, maps (Leaflet layers, marker clusters, heat layer, layer legend, area/distance filter) (no inline JS)
@@ -455,6 +482,8 @@ test/
   page-logic.test.ts       download, chain (background jobs) and workflow processes, function/app branches, dialog_closed (HR page 28)
   code-editor.test.ts      code editor: completions scoped to the app's role, the check, marked fields
   builder-home.test.ts     App Builder home: search, sort, views, Recent, Create/Import pages, dashboard, utilities
+  app-list.test.ts         (116) the App Builder list's Updated by, working copies and lock; what counts as a change
+  import-only.test.ts      (116) pgkiln import --replace --only: a page or component file, refusals
   charts.test.ts           chart markup per kind (geometry as classes), gauges, Gantt time axis and dependencies, pyramid, polar, range, box plot, stock, drill-down links
   calendar.test.ts         calendar views, create links, moving events (pure and over HTTP)
   rest-sources.test.ts     REST data sources, web credentials, SSRF checks, invoke_api (mock service + HR page 23)
@@ -473,7 +502,11 @@ test/
   builder-parity.test.ts   lists (HR page 31), page and application locks, comments, developers, supporting objects
   page-wizards.test.ts     create page wizards: catalog defaults, every page type generated and rendered, refusals, the builder steps
   theme-styles.test.ts     Theme Roller style variants (checks, CSS, user choice per app, builder page), template options, base style Iris
+  theme-pillar.test.ts     (sprint 117) Pillar Light / Dark appearances and the header strip: checks, CSS, runtime classes, Theme Roller, export
   workspaces.test.ts       workspaces (064): Default, administrators' pages, current workspace, refused apps, imports and copies
+  mail-network.test.ts     (sprint 118) network access lists (page process refused and logged in debug, narrowing only, redirects,
+                           the page), a workspace's mail service (sending, SMTP host on the list), the Mail queue (yesterday's
+                           SMTP failure, Retry, Purge, counts, scope)
   gallery.test.ts          the App Gallery: every starter created from its review with all its pages rendering; sample apps (admins)
   builder-apex-screens.test.ts sprint 61: sign-in with a workspace, message and banner, utilization, SQL Workshop home, groups, reports
   workspace-isolation.test.ts isolated workspaces (090): logins, RLS on meta, app_id, roles, SQL Workshop, scripts, imports
@@ -493,6 +526,8 @@ test/
   ai-mock.ts               a local mock of the Claude Messages API (SSE stream) and OpenAI Chat Completions
   helpers.ts               a cookie-keeping test browser
   e2e/responsive.test.ts   browser tests at phone/tablet/desktop widths (Playwright)
+  e2e/admin-mail-network.test.ts (sprint 118) Mail queue, Network access and a workspace's mail service at 390 px without JavaScript
+  e2e/pillar.test.ts       (sprint 117) Pillar appearances: axe in light and dark, subtle colours, current vs parent entry, Arabic RTL, 390 px, preview
   e2e/code-editor.test.ts  the code editor in a browser: highlighting, keys, suggestions, touch, screen readers, syntax colours at AA in both themes (sprint 108)
   e2e/data-modeler.test.ts (sprint 98) the Data Modeler in a browser: drag, save, reload, undo/redo, zoom, mini-map, exports, phone
   e2e/worksheet.test.ts    (sprint 91) the SQL Worksheet in a browser: run keys, tabs, navigator, drag and drop, splitters, phone, no JavaScript;

package/docs/guide/14-globalization.md

@@ -245,6 +245,8 @@ application. The base style and colours under Settings → Theme are the *Standa
 |---|---|
 | Accent colour, header colour | `#rrggbb` (or "as the base"), for the light theme |
 | Accent and header colour in dark mode | `#rrggbb` (or the base style's dark palette), for the dark theme; choose light colours (text on the accent is dark there) |
+| Navigation appearance | *As the application*, *Default* (the base style's header and menu), *Pillar Light* or *Pillar Dark*, see [below](#navigation-appearances-pillar-light-and-pillar-dark) |
+| Header strip colour, also for dark mode | `#rrggbb` or an item reference (else the application's strip, else the accent) |
 | Font | *System* (default), *Humanist sans*, *Geometric sans*, *Serif*, *Rounded*, *Monospace* (font stacks of fonts on the device; nothing is downloaded) |
 | Font size | 14, 15 (default), 16 or 17 px |
 | Corners | Square, 4, 8 (default) or 14 px, for regions, buttons and fields |
@@ -276,10 +278,56 @@ per tenant, environment or user group:
   a style themselves get the first style (in the list's order) whose condition holds, else the
   default style. The condition runs as the application's database role in the page's transaction;
   an error counts as *false* and is written to the [debug messages](06-processing.md#debug-messages).
-- **Dynamic colours.** Instead of a picked colour, any of a style's four colours may be an item
+- **Dynamic colours.** Instead of a picked colour, any of a style's colours may be an item
   reference such as `&APP_BRAND_COLOUR.`: the item's value in session state (set by a computation,
   an application process after login, a form…), used when it is a `#rrggbb` colour and ignored
   otherwise, so a stored value can never become anything but a colour in the CSS.
 
 Together: one style *Tenant brand* with condition `:APP_BRAND_COLOUR is not null` and accent
 `&APP_BRAND_COLOUR.` gives each tenant its colour from a table, read once after sign-in.
+
+## Navigation appearances: Pillar Light and Pillar Dark
+
+APEX 26.2's Universal Theme adds *Pillar* appearances for the header and the navigation menu. In pgkiln:
+**Theme Roller → Navigation appearance** (for the whole application) or a style's own *Navigation appearance*:
+
+| Appearance | Look |
+|---|---|
+| **Default** | The base style's header and menu (Iris: a dark header and menu; Standard: a navy header and a white menu) |
+| **Pillar Light** | Header and menu on the page's own light surfaces (in dark mode its dark ones), a line under the header |
+| **Pillar Dark** | Header and menu as one dark column in the header colour; in dark mode a darker one |
+
+Both have a **header pillar strip** across the top of the header, in the *Header strip colour* (light and dark mode,
+on the Theme Roller page or per style; a style may take it from an item, like its other colours), else the accent,
+and show the **current page as a filled pill** in the accent. Pillar Light replaces the header colour with the page's
+surface, so the strip carries the brand colour. A style's appearance wins over the application's; *Default* in a style
+switches a pillar appearance off. The appearance works with a side and a top menu, and on tablets and phones in the
+drawer. It is stored as `"appearance"`, `"strip"` and `"strip_dark"` in `meta.app.theme` (and in each style), so it
+travels with export and import; only the two keys of the list and `#rrggbb` colours reach the page (classes
+`nav-pillar nav-pillar-light` / `nav-pillar-dark` on `<body>`, `--strip` in the nonce'd `<style>`).
+
+### The navigation tree
+
+In every appearance (sprint 117) the menu tells three states apart: the **current page** is filled, in the accent,
+with a bar at the start of the entry (a pill in the pillar appearances); its **parent entries** (the trail) are bold
+with an accent icon but not filled, and the open parent's sub-menu hangs on an accent guide line; the **selected**
+entry (keyboard focus) has a ring inside the menu. A page that is not in the menu marks its nearest menu ancestor as
+the trail.
+
+### Right to left
+
+Arabic, Hebrew, Persian and Urdu pages (`dir="rtl"`) mirror the chrome: the menu sits on the right, the drawer
+slides in from the right on tablets and phones, the current page's bar, the guide lines and the menu's chevrons turn
+around, menus open from the other side and reflowed report cards are aligned to the start.
+
+### Subtle colour utilities and the processing indicator
+
+The classes `u-color-1-subtle` … `u-color-15-subtle` and `u-color-success-subtle`, `u-color-danger-subtle`,
+`u-color-warning-subtle`, `u-color-info-subtle`, `u-color-neutral-subtle` give an element a tinted background with
+readable text (WCAG AA in light and dark mode, in every base style), for static content, HTML expressions and
+template components, e.g. `<span class="u-color-4-subtle">Approved</span>`.
+
+A region that is busy (a dynamic action, a refresh) is dimmed slightly after 150 ms, so quick answers don't flicker,
+and shows a thin moving bar along its top (a still bar when the device asks for reduced motion); the wait popup's
+spinner is lighter too.
+

package/docs/guide/18-cli.md

@@ -35,7 +35,7 @@ any (see [what is not exported](03-builder.md#export-format)).
 | `pgkiln migrate [--example <name>]` | Applies the migrations that were not applied yet, then optionally `examples/<name>/` (same as `npm run db:migrate` / `npm run example:hr`; `--root` and `--seed` as in `scripts/migrate.ts`) |
 | `pgkiln apps [--json]` | Lists the applications: alias, number of pages, name |
 | `pgkiln export <alias> [--format json\|dir\|text] [--out <path>]` | `json` (default): the `pgkiln/2` document with sorted keys, to `--out` or standard output. `dir`: a directory (default `./<alias>`), see below. `text`: the same directory in YAML with the code inline ([text files](#text-files-apexlang)) |
-| `pgkiln import <path> [--alias <alias>] [--replace] [--check [--force] \| --dry-run]` | Imports a JSON export, an application directory or a `.zip` of one. `--alias` gives the copy another alias. `--replace` updates the application with that alias in place (after a [backup](03-builder.md#backups)). `--check` checks the application before it commits, `--dry-run` only checks ([below](#checking-before-an-import)) |
+| `pgkiln import <path> [--alias <alias>] [--replace [--only <file>]…] [--check [--force] \| --dry-run]` | Imports a JSON export, an application directory or a `.zip` of one. `--alias` gives the copy another alias. `--replace` updates the application with that alias in place (after a [backup](03-builder.md#backups)); with `--only pages/12` (repeatable) only that page or component file ([below](#importing-one-page-or-component)). `--check` checks the application before it commits, `--dry-run` only checks ([below](#checking-before-an-import)) |
 | `pgkiln diff <alias> <path> [--name-only \| --quiet]` | What differs between the application in the database and a directory (or JSON file, or zip) |
 | `pgkiln ddl <schema> [--no-comments] [--no-grants] [--out <file>]` | The DDL of a schema's objects, in an order that runs (as SQL Workshop → DDL, [chapter 3](03-builder.md#sql-workshop)) |
 | `pgkiln compare <source> <target> [--script]` | Compares two schemas: `+` only in the source, `-` only in the target, `~` different; exit code 1 when they differ. `--script` writes the script that makes the target like the source (drops commented out); nothing is run |
@@ -210,6 +210,26 @@ pgkiln diff hr apps/hr                           # on the target: what would cha
 pgkiln import apps/hr --replace                  # deploy
 ```
 
+### Importing one page or component
+
+(sprint 116; APEX 26.2: APEXlang file-level import) With `--replace`, `--only` imports just the named files of a
+directory export (or a .zip of one) and leaves the rest of the application as it is in the database:
+
+```sh
+pgkiln import apps/hr --replace --only pages/12                 # page 12 with its regions, items, buttons …
+pgkiln import apps/hr --replace --only shared/lovs/jobs.yaml    # one shared component
+pgkiln import apps/hr --replace --only pages/12 --only shared/lovs   # several: repeat --only
+```
+
+`pages/12` (or just `12`) is page 12's folder whatever its name, so a renamed page still matches; any other value is
+a file or folder path inside the export. A page or file that the directory no longer has is removed from the
+application. How it works: pgkiln exports the application in the directory's style, takes the named files from the
+directory, and imports the result with `--replace` as usual: one transaction, a backup first, `--check` and
+`--dry-run` work the same, and what belongs to the installation is kept. It says how many of the named files differ
+(on standard error). `--only` refuses without `--replace`, for a JSON file, for a path outside the export and for a
+selection that matches nothing in the directory or the application (exit code 2). A component that another file
+refers to by name (a list of values used on a page, say) has to exist after the import, as with any import.
+
 ### Checking before an import
 
 An import doesn't need the application's tables, columns and functions to exist (neither does APEX's):

package/docs/guide/19-rest-data-sources.md

@@ -53,6 +53,16 @@ The checks on every outgoing request (`src/webclient.ts`), against server-side r
 Keep the allow-list as short as you can. `*` lets developers call any public host from the
 server; it never opens private addresses.
 
+**A workspace's network access list** (sprint 118; APEX 26.2 workspace network ACLs) narrows this
+list for one workspace: under Administration → [Network access](03-builder.md#network-access), its
+administrators can limit its applications to some hosts (same entry syntax, without `*`). A call made
+for an application of that workspace must then match the workspace's list *and* the installation's,
+on every redirect hop; the address checks above stay with `PGKILN_REST_PRIVATE_HOSTS` alone, so a
+workspace can never widen what the installation allows. It applies to every path above: REST data
+sources (including write-back, synchronisation and the response cache), `meta.web_request`, invoke
+API, token endpoints, object storage and REST source catalogs. Refusals are logged in the
+application's debug log and listed under *Refused calls*.
+
 **Changing `PGKILN_SECRET_KEY`** makes the stored secrets unreadable: pgkiln then reports that
 the secret must be entered again. Keep the key with your other server secrets, outside the
 database: a database dump alone does not reveal the secrets.
@@ -323,6 +333,8 @@ values, processes and workflow steps refer to sources and credentials by name, s
 
 - Outgoing calls are off until the administrator sets `PGKILN_REST_ALLOWED_HOSTS`; private and
   internal addresses need `PGKILN_REST_PRIVATE_HOSTS` as well.
+- A workspace's [network access list](03-builder.md#network-access) narrows the allow-list for its
+  applications (it can't widen it).
 - Secrets are encrypted with a key outside the database, write-only in the builder, excluded from
   exports and from the runtime role, and never logged. Use **Valid for URLs** so a credential is
   only ever sent to its own service.

package/docs/guide/20-ai-agents.md

@@ -52,7 +52,7 @@ directory the agent started the server in (the project).
 | `describe_schema` | schemas with tables, views and functions; or one table with columns, constraints, indexes, RLS policies and triggers | no |
 | `generate_ddl` | the DDL of a schema's objects, in an order that runs: a start for a migration script | no |
 | `compare_schemas` | the differences between two schemas and a script that makes the target like the source (not run) | no |
-| `run_query` | one SQL statement, read-only, rows as JSON | no |
+| `run_query` | one SQL statement, read-only, rows as JSON; with `alias` (and `user`) as that application's role and user | no |
 | `search_docs` | searches this user guide, the parity matrix and SECURITY.md | no |
 | `recent_errors` | the latest errors and refused requests from the activity log | no |
 | `export_app` | writes an application to a directory (default `apps/<alias>`, format `text`) | files on disk |
@@ -85,7 +85,13 @@ migration scripts, not in the application files (`run_query` can't change them a
   columns whose names contain *password*, *secret*, *token*, *hash* or *api_key* are shown as
   `(hidden)`. That keeps credentials out of the agent's context by accident; it is not an access
   control: the server runs as the owner role, like the command line, and is meant for a
-  developer's own machine. Don't point it at production; deploy with `pgkiln import --replace`
+  developer's own machine.
+- **As an application's user.** (sprint 119) `run_query` with `alias` runs the statement as that application's
+  database role, with `meta.app_id()`, `meta.app_user()` (`user`, default `nobody`) and `meta.has_role()` (the
+  user's roles in the application) set, so grants, column privileges, row level security and masking views apply as
+  on that user's pages ([chapter 8](08-security.md#data-security-per-table-rows-columns-and-values)). Use it to check
+  what a user sees, or let an agent look at data the way the application does. It is no sandbox either: the
+  connection is still the owner's. Don't point it at production; deploy with `pgkiln import --replace`
   from git instead.
 - **Writes** are only `export_app` (files; it refuses a non-empty directory that isn't an export,
   so it can't overwrite your project) and `import_app` (the database, in one transaction). Both are

package/examples/hr/hr_70_data_security.sql

@@ -0,0 +1,79 @@
+-- =====================================================================
+-- HR example, part 70: data security per table (sprint 119, WS-13;
+-- docs/guide/08-security.md "Data security per table")
+--
+-- hr.emp_masked, the masking view that SQL Workshop › hr.emp › Security
+-- writes when sal and comm are masked (empty) for everyone but the
+-- application role manager. It runs as hr_masking, so row level security
+-- on hr.emp would still apply inside it. hr_app keeps SELECT on hr.emp
+-- because the other pages read it: the Security page warns that the mask
+-- holds only where the view is read.
+--
+-- Page 48 "Salaries (masked)": a report on the view. Signed in as KING
+-- (manager) it shows salaries; as ALLEN (no manager role) they are empty.
+-- =====================================================================
+
+do $role$ begin
+  if not exists (select from pg_roles where rolname = 'hr_masking') then
+    create role hr_masking nologin;
+  end if;
+end $role$;
+grant hr_masking to current_user;
+grant usage on schema hr to hr_masking;
+grant select on hr.emp to hr_masking;
+grant hr_app to hr_masking;
+
+create view hr.emp_masked with (security_barrier) as
+select t.empno,
+       t.ename,
+       t.job,
+       t.mgr,
+       t.hiredate,
+       case when (select meta.has_role('manager')) then t.sal end as sal,
+       case when (select meta.has_role('manager')) then t.comm end as comm,
+       t.deptno,
+       t.active,
+       t.username,
+       t.photo,
+       t.photo_name,
+       t.photo_mime,
+       t.work_location
+  from hr.emp t;
+alter view hr.emp_masked owner to hr_masking;
+comment on view hr.emp_masked is 'pgkiln masking view of emp: {"table":"emp","roles":["manager"],"cols":{"comm":{"mask":"null","see":["manager"],"others":false},"sal":{"mask":"null","see":["manager"],"others":false}}}';
+grant select on hr.emp_masked to hr_app;
+
+do $check$ begin
+  if exists (select from pg_roles r where r.rolname = 'hr_masking'
+              and (r.rolsuper or r.rolbypassrls or pg_has_role(r.oid, (select relowner from pg_class where oid = 'hr.emp'::regclass), 'USAGE'))) then
+    raise exception 'the masking role hr_masking would bypass row level security on hr.emp';
+  end if;
+end $check$;
+
+insert into meta.page (app_id, page_no, name, title, parent_page)
+select id, 48, 'Salaries (masked)', 'Salaries (masked)', 1 from meta.app where alias = 'hr';
+
+insert into meta.region (page_id, seq, title, type, columns, template, source, config)
+select p.id, r.seq, r.title, r.type, 12, 'standard', r.source, r.config::jsonb
+  from meta.page p join meta.app a on a.id = p.app_id, (values
+  (10, 'Salaries (masked)', 'static',
+   '<p>This report reads <code>hr.emp_masked</code>: salary and commission are only shown to the role <b>manager</b>. Open SQL Workshop › hr.emp › Security to change who sees what.</p>', '{}'),
+  (20, 'Employees', 'report',
+   'select ename, job, sal, comm from hr.emp_masked where active order by ename',
+   '{"page_size": 15, "headings": {"ename": "Name", "job": "Job", "sal": "Salary", "comm": "Commission"}}')
+  ) as r (seq, title, type, source, config)
+ where a.alias = 'hr' and p.page_no = 48;
+
+insert into meta.nav_entry (app_id, seq, label, icon, target_page)
+select id, 35, 'Salaries (masked)', 'shield', 48 from meta.app where alias = 'hr';
+
+insert into meta.translation (app_id, language, source, target)
+select a.id, 'nl', t.source, t.target
+  from meta.app a, (values
+  ('Salaries (masked)', 'Salarissen (gemaskeerd)'),
+  ('Employees', 'Medewerkers'),
+  ('Salary', 'Salaris'),
+  ('Commission', 'Commissie')
+  ) as t(source, target)
+ where a.alias = 'hr'
+on conflict do nothing;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgkiln",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "Open source low-code, SQL-driven application builder for PostgreSQL, inspired by Oracle APEX",
   "keywords": [
     "postgresql",