pgkiln 0.51.0 → 0.53.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/SECURITY.md +10 -1
- package/db/migrations/121_ai_agents.sql +94 -0
- package/db/migrations/122_team_development.sql +186 -0
- package/db/migrations/123_workflow_outcomes.sql +407 -0
- package/db/migrations/124_component_details.sql +51 -0
- package/db/migrations/125_app_change.sql +23 -0
- package/db/migrations/126_mail_queue_network_access.sql +119 -0
- package/docs/apex-feature-parity.md +50 -19
- package/docs/guide/01-installation.md +8 -4
- package/docs/guide/03-builder.md +197 -10
- package/docs/guide/04-pages-and-regions.md +71 -21
- package/docs/guide/05-items.md +7 -1
- package/docs/guide/06-processing.md +129 -9
- package/docs/guide/07-dynamic-actions.md +34 -0
- package/docs/guide/08-security.md +55 -0
- package/docs/guide/09-reference.md +5 -2
- package/docs/guide/11-from-apex.md +3 -1
- package/docs/guide/12-development.md +87 -16
- package/docs/guide/14-globalization.md +49 -1
- package/docs/guide/18-cli.md +21 -1
- package/docs/guide/19-rest-data-sources.md +12 -0
- package/docs/guide/20-ai-agents.md +12 -4
- package/examples/hr/README.md +2 -0
- package/examples/hr/hr_64_ai_agent.sql +97 -0
- package/examples/hr/hr_65_ask_reports.sql +21 -0
- package/examples/hr/hr_66_team_development.sql +58 -0
- package/examples/hr/hr_67_workflow_outcomes.sql +113 -0
- package/examples/hr/hr_68_component_details.sql +96 -0
- package/examples/hr/hr_70_data_security.sql +79 -0
- package/package.json +1 -1
- package/public/app.css +135 -21
- package/public/app.js +134 -20
- package/public/builder.css +133 -1
- package/public/builder.js +51 -0
- package/src/ai/chat.ts +18 -18
- package/src/ai/service.ts +35 -11
- package/src/ai/types.ts +7 -2
- package/src/app.ts +15 -0
- package/src/builder/advisor.ts +6 -3
- package/src/builder/ai-agents.ts +372 -0
- package/src/builder/ai-builder.ts +3 -3
- package/src/builder/ai.ts +13 -9
- package/src/builder/app-updates.ts +55 -0
- package/src/builder/assistant.ts +22 -7
- package/src/builder/components.ts +38 -9
- package/src/builder/data-security.ts +182 -0
- package/src/builder/designer.ts +8 -3
- package/src/builder/feedback.ts +6 -1
- package/src/builder/home.ts +16 -5
- package/src/builder/locks.ts +7 -1
- package/src/builder/mail-queue.ts +212 -0
- package/src/builder/mail.ts +72 -45
- package/src/builder/network-access.ts +140 -0
- package/src/builder/object-actions.ts +1 -0
- package/src/builder/object-browser.ts +1 -1
- package/src/builder/region-help.ts +2 -2
- package/src/builder/rest-catalogs.ts +19 -4
- package/src/builder/routes.ts +4 -1
- package/src/builder/shared.ts +1 -1
- package/src/builder/sql.ts +2 -0
- package/src/builder/team.ts +991 -0
- package/src/builder/themeroller.ts +47 -6
- package/src/builder/ui.ts +7 -1
- package/src/builder/websources.ts +1 -1
- package/src/builder/workflow-migrate.ts +210 -0
- package/src/builder/workflows.ts +29 -6
- package/src/builder/workspace-home.ts +2 -0
- package/src/builder/workspace-mail.ts +121 -0
- package/src/builder/workspace-transfer.ts +1 -1
- package/src/builder/workspaces.ts +1 -0
- package/src/cli/main.ts +25 -3
- package/src/cli/mcp.ts +40 -4
- package/src/cli/only.ts +52 -0
- package/src/cli/replace.ts +11 -1
- package/src/datasec.ts +343 -0
- package/src/i18n/ar.ts +17 -0
- package/src/i18n/cs.ts +17 -0
- package/src/i18n/da.ts +17 -0
- package/src/i18n/de.ts +17 -0
- package/src/i18n/el.ts +17 -0
- package/src/i18n/es.ts +17 -0
- package/src/i18n/fi.ts +17 -0
- package/src/i18n/fr.ts +17 -0
- package/src/i18n/he.ts +17 -0
- package/src/i18n/it.ts +17 -0
- package/src/i18n/ja.ts +17 -0
- package/src/i18n/ko.ts +17 -0
- package/src/i18n/nb.ts +17 -0
- package/src/i18n/pl.ts +17 -0
- package/src/i18n/pt.ts +17 -0
- package/src/i18n/ru.ts +17 -0
- package/src/i18n/sv.ts +17 -0
- package/src/i18n/tr.ts +17 -0
- package/src/i18n/uk.ts +17 -0
- package/src/i18n/zh.ts +17 -0
- package/src/i18n.ts +34 -0
- package/src/instance.ts +2 -0
- package/src/mail/mail.ts +50 -11
- package/src/mail/providers.ts +6 -3
- package/src/metadata.ts +11 -3
- package/src/network-acl.ts +126 -0
- package/src/objectstore.ts +3 -0
- package/src/runtime/ai-agents.ts +365 -0
- package/src/runtime/ai-filter.ts +385 -107
- package/src/runtime/assistant.ts +64 -11
- package/src/runtime/context.ts +2 -0
- package/src/runtime/engine.ts +3 -1
- package/src/runtime/ir-phrases.ts +812 -0
- package/src/runtime/ir-plan.ts +449 -0
- package/src/runtime/items.ts +1 -1
- package/src/runtime/regions.ts +6 -2
- package/src/runtime/render.ts +5 -3
- package/src/runtime/report.ts +1 -1
- package/src/runtime/styles.ts +54 -12
- package/src/runtime/tasks.ts +63 -12
- package/src/task-events.ts +232 -0
- package/src/team-samples.ts +74 -0
- package/src/team.ts +342 -0
- package/src/webclient.ts +45 -4
- package/src/webrequests.ts +5 -0
- package/src/websources.ts +30 -12
- package/src/workflow.ts +135 -18
- package/src/workspace-export.ts +16 -1
|
@@ -33,12 +33,17 @@ src/
|
|
|
33
33
|
rows and columns from the response schema, write-back from collection and item paths, notes), catalog
|
|
34
34
|
files, load/insert/replace, sourceFromService
|
|
35
35
|
workspace-export.ts (sprint 67) a workspace's components as a file (pgkiln-workspace/1) and importWorkspace (one transaction)
|
|
36
|
+
team.ts (sprint 113) Team Development's data: workspaceDevelopers (members and administrators: assignees, @mentions),
|
|
37
|
+
issueHtml (markdownHtml + mentions), recordMentions, logIssue (history), teamSetup, teamCounts, pageIssues,
|
|
38
|
+
exportTeam / importTeam (the workspace export's "team" part)
|
|
39
|
+
team-samples.ts (sprint 113) the set-up wizard's samples per builder language (English; add a key for another)
|
|
36
40
|
subscriptions.ts application types and subscriptions (migration 056): offers, subscribe, refresh, publish, in sync
|
|
37
41
|
workingcopy.ts working copies (migration 055): create, three-way compare per component (base, main, copy),
|
|
38
42
|
merge into the main application or refresh the copy, both through cli/replace.ts
|
|
39
43
|
cli/ the command line: main.ts (commands, help, exit codes), apps.ts (connect, export,
|
|
40
44
|
read, import), files.ts (directories, zip), diff.ts, replace.ts (import --replace in place),
|
|
41
|
-
mcp.ts (`pgkiln mcp`: the MCP server for AI coding agents, chapter 20)
|
|
45
|
+
mcp.ts (`pgkiln mcp`: the MCP server for AI coding agents, chapter 20), only.ts (sprint 116:
|
|
46
|
+
`import --replace --only pages/12`, the named files merged over the application's current export)
|
|
42
47
|
app.ts / server.ts Fastify setup / entry point
|
|
43
48
|
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
|
|
44
49
|
workspace-db.ts isolated workspaces (090): the isolated applications (cached 5 s), a pool per workspace login (passwords from
|
|
@@ -55,7 +60,10 @@ src/
|
|
|
55
60
|
customauth.ts custom authentication: the app's function or PL/pgSQL body (a pg_temp function) and post-authentication code, as the app's role
|
|
56
61
|
remember.ts "Keep me signed in": rotating persistent sign-in tokens
|
|
57
62
|
workflow.ts workflows: step checks, the runner with parallel branches (NOTIFY + polling), invoke_api steps
|
|
58
|
-
(the call between two transactions, with a lease), Advisor references, the diagram
|
|
63
|
+
(the call between two transactions, with a lease), Advisor references, the diagram;
|
|
64
|
+
(sprint 114) send_mail and draft steps, switch cases on task outcomes, the diagram as a standalone SVG
|
|
65
|
+
task-events.ts (sprint 114) task events (complete, expire, fail: SQL, mail, start a workflow) and built-in task
|
|
66
|
+
notifications from e-mail templates: checks, the actions as the app role, the meta.task_hook outbox runner
|
|
59
67
|
process-jobs.ts background execution chains: the job queue (SKIP LOCKED, NOTIFY + polling), running a job as the app role
|
|
60
68
|
api.ts REST API tokens for PostgREST, API role checks
|
|
61
69
|
accounts.ts account settings and the password policy
|
|
@@ -88,6 +96,9 @@ src/
|
|
|
88
96
|
objects, type reporting, roles viewer/editor/administrator as schemes EDITOR and ADMIN, page 1 a Data
|
|
89
97
|
Reporter), reportingApps(), reportingAppCount() (meta.reporting_app_count, for the workspace home)
|
|
90
98
|
tabledef.ts (sprint 95) a table as a definition: readTable(), checkTable(), tableSql() (CREATE, or ALTER from the catalog's version)
|
|
99
|
+
datasec.ts (sprint 119, WS-13) data security per table: readSecurity() (policies, column privileges per role, the
|
|
100
|
+
masking view and its configuration in the view comment), checkSecurity(), securitySql() (GRANT / REVOKE,
|
|
101
|
+
the masking view owned by <schema>_masking); the page is builder/data-security.ts
|
|
91
102
|
sqlformat.ts (sprint 93) formatSql(): the worksheet's Format (clauses per line, keyword case; strings and comments kept)
|
|
92
103
|
sqlplan.ts (sprint 92) EXPLAIN (FORMAT JSON) as a tree: parsePlan() (self time, slowest step, misestimates), planText()
|
|
93
104
|
quicksql.ts Quick SQL: shorthand parser and PostgreSQL DDL generator (unit tested)
|
|
@@ -103,7 +114,12 @@ src/
|
|
|
103
114
|
geocode.ts the installation's geocoder for address items (GEOCODER_URL, Nominatim search API)
|
|
104
115
|
mvt.ts Mapbox Vector Tile encoding for map layers served as tiles
|
|
105
116
|
yamltext.ts the text style of the directory export: a strict YAML subset, written and read
|
|
106
|
-
webclient.ts outgoing HTTP to web services: allow-list, address checks at connect time (SSRF), redirects, limits
|
|
117
|
+
webclient.ts outgoing HTTP to web services: allow-list, address checks at connect time (SSRF), redirects, limits;
|
|
118
|
+
(sprint 118) a request's scope (OutboundScope): the workspace's network access list, checked on every hop
|
|
119
|
+
(checkUrl/scopeProblem), refusals reported to the scope
|
|
120
|
+
network-acl.ts (sprint 118, WS-9) workspace network access lists (meta.workspace.network_*): scopeForApp/scopeForWorkspace
|
|
121
|
+
(no cache), parseHostList, recordRefusal/purgeRefusals (meta.network_refusal, 7 days), mailHostAddress
|
|
122
|
+
(a workspace mail service's SMTP host: both lists, resolved once, the checked address connected to)
|
|
107
123
|
datapump.ts (sprint 103, DA-16) Schema Export / Import jobs (meta.dump_job): findTools (pg_dump/pg_restore ≥ the
|
|
108
124
|
server's major), startExport (pg_dump, argument array, PGPASSWORD), readToc/parseToc (pg_restore --list),
|
|
109
125
|
startImport (pg_restore -f - run in one transaction between schema renames; data-only in FK order),
|
|
@@ -130,7 +146,10 @@ src/
|
|
|
130
146
|
or XOAUTH2, Microsoft Graph sendMail, Amazon SES v2 raw MIME with signV4, Resend, Postmark, SendGrid,
|
|
131
147
|
Mailgun, log; MailError says whether a retry may help; client-credentials token cache; settingsProblems),
|
|
132
148
|
mail.ts (sendWith(): service enabled, allowed sender, secret decrypted; mailTick(): claim with SKIP LOCKED,
|
|
133
|
-
send, retry after 1/4/16/64 minutes, purge after 30 days; the NOTIFY pgkiln_mail listener)
|
|
149
|
+
send, retry after 1/4/16/64 minutes, purge after 30 days; the NOTIFY pgkiln_mail listener);
|
|
150
|
+
(sprint 118) the service of meta.mail_service_for_app (the app's, else its workspace's own), each attempt's
|
|
151
|
+
provider and duration, serviceSettings()/verifyService(): a workspace service's checks (no base or token URL,
|
|
152
|
+
its SMTP host through network-acl.ts mailHostAddress)
|
|
134
153
|
ai/ AI services (migration 060): types.ts (the provider interface, AiError kinds),
|
|
135
154
|
anthropic.ts (Claude through @anthropic-ai/sdk: streamed, effort, structured outputs via
|
|
136
155
|
output_config.format, refusal fallbacks, stop_reason checks, typed SDK errors), openai.ts (the openai
|
|
@@ -138,7 +157,10 @@ src/
|
|
|
138
157
|
limits, the call, meta.ai_usage), requests.ts (meta.ai_generate from SQL: runPendingAi() after an sql
|
|
139
158
|
process, aiRequestTick() in the scheduler, 24-hour purge), chat.ts (conversations with tools, migration
|
|
140
159
|
061: chat() runs the tool loop on a provider-format history (Claude: streamed, strict tools, tool_choice
|
|
141
|
-
auto, content appended unchanged; OpenAI: strict function tools), limits and usage per provider call
|
|
160
|
+
auto, content appended unchanged; OpenAI: strict function tools), limits and usage per provider call;
|
|
161
|
+
(121) an agent's effort (Claude output_config.effort, OpenAI reasoning_effort) and output limit).
|
|
162
|
+
Providers (121): anthropic, openai, gemini (OpenAI-compatible endpoint, GEMINI_BASE_URL), openai_compatible
|
|
163
|
+
(Ollama, vLLM, Azure OpenAI; base URL required, key optional): service.ts serviceKey(), baseUrlFor(), providerLabel()
|
|
142
164
|
debug.ts debug messages: DebugLog (levels, timed steps, NOTICEs of meta.debug from appTx), started in
|
|
143
165
|
loadContext, stored after the response (onResponse hook → meta.debug_save), hourly purge
|
|
144
166
|
icons.ts icon helper (sprite in public/icons.svg)
|
|
@@ -154,9 +176,10 @@ src/
|
|
|
154
176
|
shortcuts.ts (103) "NAME" shortcuts in static content, help texts and confirm messages
|
|
155
177
|
render.ts page chrome (nav, breadcrumb), dynamic action JSON, theme (the page's nonce'd <style>, light/dark and style switches)
|
|
156
178
|
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
|
|
157
|
-
style (user choice, default), themeCss() (only hex values and constants reach the CSS)
|
|
179
|
+
style (user choice, default), themeCss() (only hex values and constants reach the CSS); (sprint 117) NAV_APPEARANCES
|
|
180
|
+
(Pillar Light / Dark), navAppearance() → the <body> classes nav-pillar-*, the header strip (--strip)
|
|
158
181
|
template-options.ts template options: the fixed CSS class list per region and button, templateClasses() (unknown values ignored)
|
|
159
|
-
regions.ts region shell + chart (drill-down links, gauge settings)/cards/dynamic dispatch with row limits, lazy placeholder and cache, buttons (menu buttons, badges)
|
|
182
|
+
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)
|
|
160
183
|
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
|
|
161
184
|
(report.ts: paging with row ranges and max_rows, keyset paging (keysetPlan, seekCondition, signed r<id>_k), pagerNav, streamed CSV/Excel downloads with a cursor;
|
|
162
185
|
items.ts: lovOptions, searchLov/lovLookup for popup LOVs, served by POST /a/:alias/:page/lov/:item/search in routes.ts)
|
|
@@ -193,7 +216,8 @@ src/
|
|
|
193
216
|
template-components.ts template components: template language (allow-list, directives, escaping), plug-in files, report column templates
|
|
194
217
|
builtin-components.ts built-in template components (ut_avatar, ut_badge, ut_comments, ut_media_list, ut_metric_card, ut_timeline)
|
|
195
218
|
template-region.ts template_component region
|
|
196
|
-
tasks.ts task list region and task actions (approvals); (094) the vacation rule panel and route
|
|
219
|
+
tasks.ts task list region and task actions (approvals); (094) the vacation rule panel and route;
|
|
220
|
+
(sprint 114) custom outcome buttons, the Fail event and recovery of a failing completion SQL
|
|
197
221
|
data-reporter.ts Data Reporter region (migration 057): sources from the region's config, checkDef (offered columns, whitelists),
|
|
198
222
|
reportQuery/chartQuery, the list and editor (GET form), save/delete routes (meta.save_data_report);
|
|
199
223
|
(sprint 110) dataset sources (resolveSources), edit_authz / admin_authz / publishing, pins (a preference),
|
|
@@ -205,8 +229,20 @@ src/
|
|
|
205
229
|
schemas from items, answers into items), aiInputs/aiOutputs for its dynamic action (route in routes.ts)
|
|
206
230
|
assistant.ts AI assistant region (migration 061): config checks, tool schemas and argument checks, context queries
|
|
207
231
|
and SQL tools as the app role (rolled back unless "writes"), REST tools, meta.ai_conversation per
|
|
208
|
-
session, formatAnswer (escaped), send/clear routes
|
|
209
|
-
|
|
232
|
+
session, formatAnswer (escaped), send/clear routes; (121) "agent": an AI agent's service, prompt, tools,
|
|
233
|
+
steps and authorization; links of navigate tools under the answer, browser actions once (__AIACT<id>)
|
|
234
|
+
ai-agents.ts (121) AI agents and AI tools (meta.app.ai_agents / ai_tools): checks (agentProblems, aiToolProblems,
|
|
235
|
+
definitionProblems), agentFor(), prepareTools() (authorization schemes, navigate pages the user may
|
|
236
|
+
open, strict schemas), runAgentTool() (sql: read-only transaction as the app role with a time limit;
|
|
237
|
+
function: named arguments, committed; rest; javascript: queued for the browser; navigate: URL and
|
|
238
|
+
checksum built here), logToolCall() (meta.ai_tool_call, debug level 4, 30-day purge)
|
|
239
|
+
ai-filter.ts "Ask in your own words" on a report ("ai_filter", sprint 112: AI interactive reports): the box, the chips
|
|
240
|
+
form (Edit/Remove/Undo, undo history in the session), ask and chips routes; an AI service's structured
|
|
241
|
+
output (planSchema) or the phrase parser, then ir-plan.ts
|
|
242
|
+
ir-plan.ts what a question may set: checkPlan (shown columns, whitelists, computeSql), applyPlan (→ the report's
|
|
243
|
+
URL parameters), chipsOf/editChip/removeChip (a chip = one URL parameter value, edits checked again)
|
|
244
|
+
ir-phrases.ts the rule-based parser without an AI service: phrase tables per language (en, nl, de), clauses →
|
|
245
|
+
a RawPlan; values looked up among the report's rows through a Lookup (query parameter)
|
|
210
246
|
pdf.ts report PDFs with report layouts (pdfkit); rows from a cursor in batches (tablePdf takes batches)
|
|
211
247
|
search.ts search region and search configurations (migration 080): words as ILIKE parameters, table/sql/list
|
|
212
248
|
sources as the app role in savepoints, marked results, configColumns/searchConfigProblems for the Advisor
|
|
@@ -230,7 +266,10 @@ src/
|
|
|
230
266
|
wizards.ts create page wizards: step 2 forms per page type (defaults from meta.wizard_defaults), POST → meta.generate_page
|
|
231
267
|
(the generators are PL/pgSQL in migration 047: catalog, defaults, form/cards/calendar/chart/map/facets/master-detail)
|
|
232
268
|
home.ts App Builder home at /builder/apps and /builder (tiles, applications report/cards, Recent; /builder redirects
|
|
233
|
-
to the Workspace home when meta.workspace.builder_home = 'home'), Create, Import, Dashboard, Utilities
|
|
269
|
+
to the Workspace home when meta.workspace.builder_home = 'home'), Create, Import, Dashboard, Utilities;
|
|
270
|
+
(116) Updated by, working copies and the application lock in the report and the cards
|
|
271
|
+
app-updates.ts (sprint 116, migration 125) who changed an application last: developer() notes a builder POST under
|
|
272
|
+
/apps/:id or /pages/:pid (or a Create / Import), an onSend hook records a success in meta.app_change
|
|
234
273
|
workspace-home.ts (sprint 109, migration 119) the Workspace home /builder/home, opened after sign-in: tool cards (Data Reporter
|
|
235
274
|
when GET /builder/reporter exists), workspace message edited in place (workspaceAdmin), Summary, Top
|
|
236
275
|
applications / users / developers over meta.developer.home_timeframe, System message (src/release-check.ts),
|
|
@@ -256,9 +295,22 @@ src/
|
|
|
256
295
|
availability.ts Application → Availability (migration 083): status, message, users, build status (Run only is
|
|
257
296
|
enforced by locks.ts blockingLock); availabilityBadge() in the application header
|
|
258
297
|
feedback.ts Application → Feedback (migration 084): the setting, the list with filters, status and answers
|
|
298
|
+
team.ts (sprint 113, migration 122) Builder → Team Development /builder/team: issues (list with filters and saved views,
|
|
299
|
+
board by label group or milestone with a Move form per card, issue page with Markdown, comments, canned
|
|
300
|
+
responses, @mentions, history), labels and groups, milestones, templates, the set-up wizard; Make an issue
|
|
301
|
+
from feedback and developer comments; pageIssuesNote (Page Designer), appIssues (App Home), teamHomeBlock
|
|
302
|
+
(Workspace home). Every id from a request is looked up in the current workspace
|
|
259
303
|
region-help.ts the Attributes (JSON) help per region type, with links to the guide
|
|
260
304
|
mail.ts Workspace utilities → Mail services (administrators: providers, write-only secret, allowed senders,
|
|
261
|
-
applications with From and daily limit, test) and Applications → Activity → Mail (retry, cancel)
|
|
305
|
+
applications with From and daily limit, test) and Applications → Activity → Mail (retry, cancel);
|
|
306
|
+
serviceForm/formValues/runCheck shared with workspace-mail.ts (sprint 118)
|
|
307
|
+
mail-queue.ts (sprint 118, WS-9) Administration → Mail queue (/builder/mail-queue): queueScope (administrators: all or
|
|
308
|
+
?ws=; workspace administrators: the current workspace), figures, per hour, per workspace / application,
|
|
309
|
+
slowest provider calls, failures; Retry / Purge one or all failed, scope checked again per mail
|
|
310
|
+
network-access.ts (sprint 118, WS-9) Administration → Network access (/builder/network): the installation's list, a workspace's
|
|
311
|
+
list (workspaceAdmin), Check a URL (nothing called), the workspaces (administrators), refused calls
|
|
312
|
+
workspace-mail.ts (sprint 118, WS-9) a workspace's own mail service (/builder/workspaces/:id/mail, WORKSPACE_<id>): its
|
|
313
|
+
administrators only, write-only secret, checks through mail.ts runCheck with the workspace's guard
|
|
262
314
|
shared.ts Shared Components and access control
|
|
263
315
|
designer.ts page designer: component tree (with computations and branches), layout canvas and gallery, property editor, toolbar;
|
|
264
316
|
(sprint 86) GET /builder/apps/:app/pages/:no, /builder/pages/:id redirects browsers there (designerUrl in ui.ts)
|
|
@@ -276,6 +328,7 @@ src/
|
|
|
276
328
|
object-browser.ts (sprint 75) the Object Browser: objects by type, system objects hidden, a table in tabs, column actions as SQL to review
|
|
277
329
|
table-editor.ts (sprint 95) Table Properties: GET/POST /sql/objects/table (create, edit ?o=, ?template=), fromForm(), Preview / Apply
|
|
278
330
|
(one transaction) / Open in the worksheet
|
|
331
|
+
data-security.ts (sprint 119) a table's Security: GET/POST /sql/objects/security?o= (policies, roles × columns, masks), Preview / Apply
|
|
279
332
|
object-actions.ts (sprint 94) an object's ⋯ menu (objectMenu) in the worksheet and the Object Browser: Quick DDL (objectDdl), Drop with
|
|
280
333
|
dependents, Add index / trigger / policy as drafts; GET /sql/objects/action, /sql/objects/panel (Open in a panel)
|
|
281
334
|
data-modeler.ts (sprint 98) SQL Workshop → Data Modeler: /sql/modeler (diagrams, meta.sql_diagram, 111), /:id (SVG), /:id/objects, /layout,
|
|
@@ -320,7 +373,8 @@ src/
|
|
|
320
373
|
ldap.ts Users → LDAP directories
|
|
321
374
|
documents.ts document template preview (Shared Components)
|
|
322
375
|
pwa.ts Settings → Progressive Web App (icon upload)
|
|
323
|
-
themeroller.ts Settings → Theme Roller: style variants (add, edit, rename, delete), default style, users may choose
|
|
376
|
+
themeroller.ts Settings → Theme Roller: style variants (add, edit, rename, delete), default style, users may choose;
|
|
377
|
+
(sprint 117) navigation appearance and header strip colours (application and per style), the preview's menu
|
|
324
378
|
subscriptions.ts Shared Components → Subscriptions: subscribe, refresh, unsubscribe, subscribers and publish; the note under a component
|
|
325
379
|
reporter.ts page designer: Data Reporter settings (sources: table or view, offered columns, labels, masks; sharing;
|
|
326
380
|
(sprint 110) a dataset as a source, who may edit, who may moderate, publishing)
|
|
@@ -337,6 +391,8 @@ src/
|
|
|
337
391
|
workspace's applications, the module › template › handler tree, handler forms, Try it (inject with a
|
|
338
392
|
short-lived token), Run only / lock checks
|
|
339
393
|
workflows.ts workflow versions, diagram and instances (Shared Components)
|
|
394
|
+
workflow-migrate.ts (sprint 114) migrating running workflow instances to a newer version (map, preview, apply with
|
|
395
|
+
meta.migrate_workflows) and the diagram as an SVG file (PNG in builder.js)
|
|
340
396
|
process-jobs.ts page designer: the Jobs tab of a background chain process
|
|
341
397
|
template-spec.ts template component property form (Shared Components)
|
|
342
398
|
websources.ts web credentials and REST data sources: property specs, secret status, Test, suggested columns,
|
|
@@ -359,13 +415,18 @@ src/
|
|
|
359
415
|
ai-builder.ts App Builder AI (migration 062): the builder's AI service (meta.builder_ai), SQL Workshop → AI (SQL from a
|
|
360
416
|
question, shown not run; explain), describe tables (meta.ai_table_note, COMMENT ON, AI drafts),
|
|
361
417
|
create pages with AI (proposals checked by checkProposals, created with meta.generate_page)
|
|
362
|
-
assistant.ts page designer: AI assistant settings and a report's "Ask in your own words" (AI service, placeholder)
|
|
418
|
+
assistant.ts page designer: AI assistant settings and a report's "Ask in your own words" (off, built-in phrases or an AI service, placeholder)
|
|
363
419
|
ai.ts Workspace utilities → AI services (administrators: services, write-only encrypted keys, access and
|
|
364
420
|
daily limits per app, Test, usage log) and Activity → AI usage per application
|
|
421
|
+
ai-agents.ts (121) Shared Components → AI Agents: the agent and tool forms (checked before saving, renames follow
|
|
422
|
+
into agents and regions), toolCallTable() (Activity → AI usage → Tool calls), agentOptions()
|
|
365
423
|
supporting.ts supporting objects: review page, running the install/upgrade/deinstall scripts as the app's role in one transaction
|
|
366
424
|
public/
|
|
367
|
-
app.css theme (light/dark, responsive; --font, --font-size, --radius for style variants; template option classes to
|
|
368
|
-
|
|
425
|
+
app.css theme (light/dark, responsive; --font, --font-size, --radius for style variants; template option classes to-*;
|
|
426
|
+
(sprint 117) navigation tree states, RTL via logical properties, body.nav-pillar-*, u-color-*-subtle, the busy bar)
|
|
427
|
+
app.js client runtime: dialogs (dialog_closed actions), popup LOVs (sprint 115: the next page loads on scroll through an
|
|
428
|
+
IntersectionObserver, ‹/More without one), dynamic actions (focus, classes, messages; sprint 115: wait_popup /
|
|
429
|
+
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)
|
|
369
430
|
code-editor.js, .css builder code editor: enhances <textarea data-code>, highlighting, suggestions (no dependencies);
|
|
370
431
|
(sprint 108) the current line, and read-only <pre data-code-view="sql|plpgsql|json|html"> highlighted;
|
|
371
432
|
its colours are the --ce-* tokens in builder.css
|
|
@@ -421,11 +482,15 @@ test/
|
|
|
421
482
|
page-logic.test.ts download, chain (background jobs) and workflow processes, function/app branches, dialog_closed (HR page 28)
|
|
422
483
|
code-editor.test.ts code editor: completions scoped to the app's role, the check, marked fields
|
|
423
484
|
builder-home.test.ts App Builder home: search, sort, views, Recent, Create/Import pages, dashboard, utilities
|
|
485
|
+
app-list.test.ts (116) the App Builder list's Updated by, working copies and lock; what counts as a change
|
|
486
|
+
import-only.test.ts (116) pgkiln import --replace --only: a page or component file, refusals
|
|
424
487
|
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
|
|
425
488
|
calendar.test.ts calendar views, create links, moving events (pure and over HTTP)
|
|
426
489
|
rest-sources.test.ts REST data sources, web credentials, SSRF checks, invoke_api (mock service + HR page 23)
|
|
427
490
|
rest-modules.test.ts (sprint 104) modules, templates, PL/pgSQL and media handlers, OpenAPI, the builder's tree and Try it
|
|
428
491
|
workflow-invoke.test.ts workflow invoke_api steps: the call between transactions, faults, retry, lease, Advisor, export (mock service)
|
|
492
|
+
workflow-outcomes.test.ts (sprint 114) custom task outcomes, task events and notifications, fail recovery, send_mail and draft
|
|
493
|
+
steps, migrating running instances, the SVG export (HR part 67: SALARY_CHANGE)
|
|
429
494
|
large-tables.test.ts row ranges, max_rows, row limits, lazy regions, region caching, streamed downloads (HR page 25)
|
|
430
495
|
grid.test.ts interactive grid: aggregates, layouts per user, saved grid reports, master-detail, row actions (HR page 27)
|
|
431
496
|
custom-auth.test.ts custom authentication: function body, named function, post-authentication code, builder settings
|
|
@@ -437,7 +502,11 @@ test/
|
|
|
437
502
|
builder-parity.test.ts lists (HR page 31), page and application locks, comments, developers, supporting objects
|
|
438
503
|
page-wizards.test.ts create page wizards: catalog defaults, every page type generated and rendered, refusals, the builder steps
|
|
439
504
|
theme-styles.test.ts Theme Roller style variants (checks, CSS, user choice per app, builder page), template options, base style Iris
|
|
505
|
+
theme-pillar.test.ts (sprint 117) Pillar Light / Dark appearances and the header strip: checks, CSS, runtime classes, Theme Roller, export
|
|
440
506
|
workspaces.test.ts workspaces (064): Default, administrators' pages, current workspace, refused apps, imports and copies
|
|
507
|
+
mail-network.test.ts (sprint 118) network access lists (page process refused and logged in debug, narrowing only, redirects,
|
|
508
|
+
the page), a workspace's mail service (sending, SMTP host on the list), the Mail queue (yesterday's
|
|
509
|
+
SMTP failure, Retry, Purge, counts, scope)
|
|
441
510
|
gallery.test.ts the App Gallery: every starter created from its review with all its pages rendering; sample apps (admins)
|
|
442
511
|
builder-apex-screens.test.ts sprint 61: sign-in with a workspace, message and banner, utilization, SQL Workshop home, groups, reports
|
|
443
512
|
workspace-isolation.test.ts isolated workspaces (090): logins, RLS on meta, app_id, roles, SQL Workshop, scripts, imports
|
|
@@ -457,6 +526,8 @@ test/
|
|
|
457
526
|
ai-mock.ts a local mock of the Claude Messages API (SSE stream) and OpenAI Chat Completions
|
|
458
527
|
helpers.ts a cookie-keeping test browser
|
|
459
528
|
e2e/responsive.test.ts browser tests at phone/tablet/desktop widths (Playwright)
|
|
529
|
+
e2e/admin-mail-network.test.ts (sprint 118) Mail queue, Network access and a workspace's mail service at 390 px without JavaScript
|
|
530
|
+
e2e/pillar.test.ts (sprint 117) Pillar appearances: axe in light and dark, subtle colours, current vs parent entry, Arabic RTL, 390 px, preview
|
|
460
531
|
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)
|
|
461
532
|
e2e/data-modeler.test.ts (sprint 98) the Data Modeler in a browser: drag, save, reload, undo/redo, zoom, mini-map, exports, phone
|
|
462
533
|
e2e/worksheet.test.ts (sprint 91) the SQL Worksheet in a browser: run keys, tabs, navigator, drag and drop, splitters, phone, no JavaScript;
|
|
@@ -245,6 +245,8 @@ application. The base style and colours under Settings → Theme are the *Standa
|
|
|
245
245
|
|---|---|
|
|
246
246
|
| Accent colour, header colour | `#rrggbb` (or "as the base"), for the light theme |
|
|
247
247
|
| 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) |
|
|
248
|
+
| 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) |
|
|
249
|
+
| Header strip colour, also for dark mode | `#rrggbb` or an item reference (else the application's strip, else the accent) |
|
|
248
250
|
| Font | *System* (default), *Humanist sans*, *Geometric sans*, *Serif*, *Rounded*, *Monospace* (font stacks of fonts on the device; nothing is downloaded) |
|
|
249
251
|
| Font size | 14, 15 (default), 16 or 17 px |
|
|
250
252
|
| Corners | Square, 4, 8 (default) or 14 px, for regions, buttons and fields |
|
|
@@ -276,10 +278,56 @@ per tenant, environment or user group:
|
|
|
276
278
|
a style themselves get the first style (in the list's order) whose condition holds, else the
|
|
277
279
|
default style. The condition runs as the application's database role in the page's transaction;
|
|
278
280
|
an error counts as *false* and is written to the [debug messages](06-processing.md#debug-messages).
|
|
279
|
-
- **Dynamic colours.** Instead of a picked colour, any of a style's
|
|
281
|
+
- **Dynamic colours.** Instead of a picked colour, any of a style's colours may be an item
|
|
280
282
|
reference such as `&APP_BRAND_COLOUR.`: the item's value in session state (set by a computation,
|
|
281
283
|
an application process after login, a form…), used when it is a `#rrggbb` colour and ignored
|
|
282
284
|
otherwise, so a stored value can never become anything but a colour in the CSS.
|
|
283
285
|
|
|
284
286
|
Together: one style *Tenant brand* with condition `:APP_BRAND_COLOUR is not null` and accent
|
|
285
287
|
`&APP_BRAND_COLOUR.` gives each tenant its colour from a table, read once after sign-in.
|
|
288
|
+
|
|
289
|
+
## Navigation appearances: Pillar Light and Pillar Dark
|
|
290
|
+
|
|
291
|
+
APEX 26.2's Universal Theme adds *Pillar* appearances for the header and the navigation menu. In pgkiln:
|
|
292
|
+
**Theme Roller → Navigation appearance** (for the whole application) or a style's own *Navigation appearance*:
|
|
293
|
+
|
|
294
|
+
| Appearance | Look |
|
|
295
|
+
|---|---|
|
|
296
|
+
| **Default** | The base style's header and menu (Iris: a dark header and menu; Standard: a navy header and a white menu) |
|
|
297
|
+
| **Pillar Light** | Header and menu on the page's own light surfaces (in dark mode its dark ones), a line under the header |
|
|
298
|
+
| **Pillar Dark** | Header and menu as one dark column in the header colour; in dark mode a darker one |
|
|
299
|
+
|
|
300
|
+
Both have a **header pillar strip** across the top of the header, in the *Header strip colour* (light and dark mode,
|
|
301
|
+
on the Theme Roller page or per style; a style may take it from an item, like its other colours), else the accent,
|
|
302
|
+
and show the **current page as a filled pill** in the accent. Pillar Light replaces the header colour with the page's
|
|
303
|
+
surface, so the strip carries the brand colour. A style's appearance wins over the application's; *Default* in a style
|
|
304
|
+
switches a pillar appearance off. The appearance works with a side and a top menu, and on tablets and phones in the
|
|
305
|
+
drawer. It is stored as `"appearance"`, `"strip"` and `"strip_dark"` in `meta.app.theme` (and in each style), so it
|
|
306
|
+
travels with export and import; only the two keys of the list and `#rrggbb` colours reach the page (classes
|
|
307
|
+
`nav-pillar nav-pillar-light` / `nav-pillar-dark` on `<body>`, `--strip` in the nonce'd `<style>`).
|
|
308
|
+
|
|
309
|
+
### The navigation tree
|
|
310
|
+
|
|
311
|
+
In every appearance (sprint 117) the menu tells three states apart: the **current page** is filled, in the accent,
|
|
312
|
+
with a bar at the start of the entry (a pill in the pillar appearances); its **parent entries** (the trail) are bold
|
|
313
|
+
with an accent icon but not filled, and the open parent's sub-menu hangs on an accent guide line; the **selected**
|
|
314
|
+
entry (keyboard focus) has a ring inside the menu. A page that is not in the menu marks its nearest menu ancestor as
|
|
315
|
+
the trail.
|
|
316
|
+
|
|
317
|
+
### Right to left
|
|
318
|
+
|
|
319
|
+
Arabic, Hebrew, Persian and Urdu pages (`dir="rtl"`) mirror the chrome: the menu sits on the right, the drawer
|
|
320
|
+
slides in from the right on tablets and phones, the current page's bar, the guide lines and the menu's chevrons turn
|
|
321
|
+
around, menus open from the other side and reflowed report cards are aligned to the start.
|
|
322
|
+
|
|
323
|
+
### Subtle colour utilities and the processing indicator
|
|
324
|
+
|
|
325
|
+
The classes `u-color-1-subtle` … `u-color-15-subtle` and `u-color-success-subtle`, `u-color-danger-subtle`,
|
|
326
|
+
`u-color-warning-subtle`, `u-color-info-subtle`, `u-color-neutral-subtle` give an element a tinted background with
|
|
327
|
+
readable text (WCAG AA in light and dark mode, in every base style), for static content, HTML expressions and
|
|
328
|
+
template components, e.g. `<span class="u-color-4-subtle">Approved</span>`.
|
|
329
|
+
|
|
330
|
+
A region that is busy (a dynamic action, a refresh) is dimmed slightly after 150 ms, so quick answers don't flicker,
|
|
331
|
+
and shows a thin moving bar along its top (a still bar when the device asks for reduced motion); the wait popup's
|
|
332
|
+
spinner is lighter too.
|
|
333
|
+
|
package/docs/guide/18-cli.md
CHANGED
|
@@ -35,7 +35,7 @@ any (see [what is not exported](03-builder.md#export-format)).
|
|
|
35
35
|
| `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`) |
|
|
36
36
|
| `pgkiln apps [--json]` | Lists the applications: alias, number of pages, name |
|
|
37
37
|
| `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)) |
|
|
38
|
-
| `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)) |
|
|
38
|
+
| `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)) |
|
|
39
39
|
| `pgkiln diff <alias> <path> [--name-only \| --quiet]` | What differs between the application in the database and a directory (or JSON file, or zip) |
|
|
40
40
|
| `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)) |
|
|
41
41
|
| `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
|
|
|
210
210
|
pgkiln import apps/hr --replace # deploy
|
|
211
211
|
```
|
|
212
212
|
|
|
213
|
+
### Importing one page or component
|
|
214
|
+
|
|
215
|
+
(sprint 116; APEX 26.2: APEXlang file-level import) With `--replace`, `--only` imports just the named files of a
|
|
216
|
+
directory export (or a .zip of one) and leaves the rest of the application as it is in the database:
|
|
217
|
+
|
|
218
|
+
```sh
|
|
219
|
+
pgkiln import apps/hr --replace --only pages/12 # page 12 with its regions, items, buttons …
|
|
220
|
+
pgkiln import apps/hr --replace --only shared/lovs/jobs.yaml # one shared component
|
|
221
|
+
pgkiln import apps/hr --replace --only pages/12 --only shared/lovs # several: repeat --only
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
`pages/12` (or just `12`) is page 12's folder whatever its name, so a renamed page still matches; any other value is
|
|
225
|
+
a file or folder path inside the export. A page or file that the directory no longer has is removed from the
|
|
226
|
+
application. How it works: pgkiln exports the application in the directory's style, takes the named files from the
|
|
227
|
+
directory, and imports the result with `--replace` as usual: one transaction, a backup first, `--check` and
|
|
228
|
+
`--dry-run` work the same, and what belongs to the installation is kept. It says how many of the named files differ
|
|
229
|
+
(on standard error). `--only` refuses without `--replace`, for a JSON file, for a path outside the export and for a
|
|
230
|
+
selection that matches nothing in the directory or the application (exit code 2). A component that another file
|
|
231
|
+
refers to by name (a list of values used on a page, say) has to exist after the import, as with any import.
|
|
232
|
+
|
|
213
233
|
### Checking before an import
|
|
214
234
|
|
|
215
235
|
An import doesn't need the application's tables, columns and functions to exist (neither does APEX's):
|
|
@@ -53,6 +53,16 @@ The checks on every outgoing request (`src/webclient.ts`), against server-side r
|
|
|
53
53
|
Keep the allow-list as short as you can. `*` lets developers call any public host from the
|
|
54
54
|
server; it never opens private addresses.
|
|
55
55
|
|
|
56
|
+
**A workspace's network access list** (sprint 118; APEX 26.2 workspace network ACLs) narrows this
|
|
57
|
+
list for one workspace: under Administration → [Network access](03-builder.md#network-access), its
|
|
58
|
+
administrators can limit its applications to some hosts (same entry syntax, without `*`). A call made
|
|
59
|
+
for an application of that workspace must then match the workspace's list *and* the installation's,
|
|
60
|
+
on every redirect hop; the address checks above stay with `PGKILN_REST_PRIVATE_HOSTS` alone, so a
|
|
61
|
+
workspace can never widen what the installation allows. It applies to every path above: REST data
|
|
62
|
+
sources (including write-back, synchronisation and the response cache), `meta.web_request`, invoke
|
|
63
|
+
API, token endpoints, object storage and REST source catalogs. Refusals are logged in the
|
|
64
|
+
application's debug log and listed under *Refused calls*.
|
|
65
|
+
|
|
56
66
|
**Changing `PGKILN_SECRET_KEY`** makes the stored secrets unreadable: pgkiln then reports that
|
|
57
67
|
the secret must be entered again. Keep the key with your other server secrets, outside the
|
|
58
68
|
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
|
|
|
323
333
|
|
|
324
334
|
- Outgoing calls are off until the administrator sets `PGKILN_REST_ALLOWED_HOSTS`; private and
|
|
325
335
|
internal addresses need `PGKILN_REST_PRIVATE_HOSTS` as well.
|
|
336
|
+
- A workspace's [network access list](03-builder.md#network-access) narrows the allow-list for its
|
|
337
|
+
applications (it can't widen it).
|
|
326
338
|
- Secrets are encrypted with a key outside the database, write-only in the builder, excluded from
|
|
327
339
|
exports and from the runtime role, and never logged. Use **Valid for URLs** so a credential is
|
|
328
340
|
only ever sent to its own service.
|
|
@@ -7,8 +7,10 @@ it exports the application as files, edits them with its own file tools, shows t
|
|
|
7
7
|
and imports them again. Laravel developers know the idea from Laravel Boost.
|
|
8
8
|
|
|
9
9
|
This is separate from the AI features *inside* applications and the builder (AI assistant regions,
|
|
10
|
-
*Generate with AI*): those call a
|
|
11
|
-
pgkiln.
|
|
10
|
+
[AI agents with tools](03-builder.md#ai-agents) in Shared Components, *Generate with AI*): those call a
|
|
11
|
+
model from pgkiln; here an agent on the developer's machine calls pgkiln. An application's AI agents
|
|
12
|
+
and tools are part of its files (`app.json`: `ai_agents`, `ai_tools`), so a coding agent can read and
|
|
13
|
+
change them like any other component.
|
|
12
14
|
|
|
13
15
|
## Setting it up
|
|
14
16
|
|
|
@@ -50,7 +52,7 @@ directory the agent started the server in (the project).
|
|
|
50
52
|
| `describe_schema` | schemas with tables, views and functions; or one table with columns, constraints, indexes, RLS policies and triggers | no |
|
|
51
53
|
| `generate_ddl` | the DDL of a schema's objects, in an order that runs: a start for a migration script | no |
|
|
52
54
|
| `compare_schemas` | the differences between two schemas and a script that makes the target like the source (not run) | no |
|
|
53
|
-
| `run_query` | one SQL statement, read-only, rows as JSON | no |
|
|
55
|
+
| `run_query` | one SQL statement, read-only, rows as JSON; with `alias` (and `user`) as that application's role and user | no |
|
|
54
56
|
| `search_docs` | searches this user guide, the parity matrix and SECURITY.md | no |
|
|
55
57
|
| `recent_errors` | the latest errors and refused requests from the activity log | no |
|
|
56
58
|
| `export_app` | writes an application to a directory (default `apps/<alias>`, format `text`) | files on disk |
|
|
@@ -83,7 +85,13 @@ migration scripts, not in the application files (`run_query` can't change them a
|
|
|
83
85
|
columns whose names contain *password*, *secret*, *token*, *hash* or *api_key* are shown as
|
|
84
86
|
`(hidden)`. That keeps credentials out of the agent's context by accident; it is not an access
|
|
85
87
|
control: the server runs as the owner role, like the command line, and is meant for a
|
|
86
|
-
developer's own machine.
|
|
88
|
+
developer's own machine.
|
|
89
|
+
- **As an application's user.** (sprint 119) `run_query` with `alias` runs the statement as that application's
|
|
90
|
+
database role, with `meta.app_id()`, `meta.app_user()` (`user`, default `nobody`) and `meta.has_role()` (the
|
|
91
|
+
user's roles in the application) set, so grants, column privileges, row level security and masking views apply as
|
|
92
|
+
on that user's pages ([chapter 8](08-security.md#data-security-per-table-rows-columns-and-values)). Use it to check
|
|
93
|
+
what a user sees, or let an agent look at data the way the application does. It is no sandbox either: the
|
|
94
|
+
connection is still the owner's. Don't point it at production; deploy with `pgkiln import --replace`
|
|
87
95
|
from git instead.
|
|
88
96
|
- **Writes** are only `export_app` (files; it refuses a non-empty directory that isn't an export,
|
|
89
97
|
so it can't overwrite your project) and `import_app` (the database, in one transaction). Both are
|
package/examples/hr/README.md
CHANGED
|
@@ -40,6 +40,8 @@ Then open http://127.0.0.1:3100/a/hr and sign in as `king`, `blake`, `jones`, `a
|
|
|
40
40
|
| `hr_47_plugins.sql` | *Plug-ins* (page 40): the four example plug-ins of `examples/plugins/` (a region, an item, a dynamic action and a process plug-in) |
|
|
41
41
|
| `hr_48_map_tiles.sql` | *Weather stations* (page 41): 20,000 generated stations (`hr.weather_station`) as vector tiles, and the stations above 2,000 m loaded for the visible area |
|
|
42
42
|
| `hr_49_push_notifications.sql` | Push notifications: the app may send them (users turn them on under *My account → Notifications*); a new leave request notifies the manager, a decision notifies the employee, and the notification opens the request (page 7) |
|
|
43
|
+
| `hr_64_ai_agent.sql` | *HR agent* (page 46): the AI agent `HR_AGENT` (Shared Components → AI Agents) with four tools: `top_earners` (SQL, read-only as `hr_app`), `open_employee` (navigate: a link to the employee form with its checksum, only for users who may open page 3), `give_raise` (the PL/pgSQL function `hr.give_raise`, managers only) and `note` (a JavaScript tool: the custom event `hr_agent_note`). Ask *Who in Sales earns most?* Needs an AI service named `HR_ASSISTANT` (see part 41) |
|
|
44
|
+
| `hr_68_component_details.sql` | *Component details* (page 47): a popup LOV over 6,000 rows that loads more as the dialog scrolls, a wait popup around a two-second process (*Recalculate*) and around an Ajax call (*Check in the background*), and an *Actions* menu whose entries run dynamic actions (event `menu_entry`) |
|
|
43
45
|
|
|
44
46
|
The files run in order, each once (recorded in `public.pgkiln_seed`), so new ones can be added
|
|
45
47
|
later. pgkiln's own tests use this application as their fixture (`npm test` installs it first).
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
-- =====================================================================
|
|
2
|
+
-- HR example, part 64: an AI agent with tools (sprint 111;
|
|
3
|
+
-- docs/guide/03-builder.md, "AI agents"; APEX 26.1: AI Agents)
|
|
4
|
+
--
|
|
5
|
+
-- Shared Components → AI Agents:
|
|
6
|
+
-- - Tools:
|
|
7
|
+
-- top_earners (sql) employees by salary, highest first,
|
|
8
|
+
-- optionally of one department: a query
|
|
9
|
+
-- run as hr_app (row level security
|
|
10
|
+
-- applies) in a read-only transaction
|
|
11
|
+
-- open_employee (navigate) a link to the employee form (page 3)
|
|
12
|
+
-- with P3_EMPNO: pgkiln offers it only
|
|
13
|
+
-- to users who may open page 3
|
|
14
|
+
-- (MANAGER) and builds the checksum
|
|
15
|
+
-- give_raise (function) hr.give_raise(p_empno, p_pct): changes
|
|
16
|
+
-- data, only offered to managers
|
|
17
|
+
-- note (javascript) shows a message in the browser after
|
|
18
|
+
-- the answer (the custom event
|
|
19
|
+
-- "hr_agent_note" on page 46)
|
|
20
|
+
-- - Agent HR_AGENT: the AI service HR_ASSISTANT, a system prompt, low
|
|
21
|
+
-- reasoning effort, the four tools, at most 4 steps per question.
|
|
22
|
+
--
|
|
23
|
+
-- Page 46 "HR agent": an AI assistant region that names the agent. Ask
|
|
24
|
+
-- e.g. "Who in Sales earns most?": the agent calls top_earners and offers
|
|
25
|
+
-- "Open BLAKE's record", a link to page 3 with a valid checksum.
|
|
26
|
+
--
|
|
27
|
+
-- Like parts 41 and 42 the example creates no AI service: an administrator
|
|
28
|
+
-- adds one named HR_ASSISTANT under App Builder → Workspace utilities → AI
|
|
29
|
+
-- services (Claude, OpenAI, Gemini or an OpenAI-compatible endpoint) and
|
|
30
|
+
-- allows the HR application to use it.
|
|
31
|
+
-- =====================================================================
|
|
32
|
+
|
|
33
|
+
update meta.app set
|
|
34
|
+
ai_tools = $j$[
|
|
35
|
+
{"name": "top_earners", "type": "sql",
|
|
36
|
+
"description": "Active employees with their job, department and salary, highest salary first; optionally only one department (case-insensitive name, e.g. SALES).",
|
|
37
|
+
"sql": "select empno, ename, job, dname, sal from hr.staff_v where active and (:DNAME is null or dname ilike :DNAME) order by sal desc, ename",
|
|
38
|
+
"parameters": {"DNAME": {"type": "string", "optional": true, "description": "A department name, e.g. SALES."}},
|
|
39
|
+
"max_rows": 20, "timeout_s": 10},
|
|
40
|
+
{"name": "open_employee", "type": "navigate",
|
|
41
|
+
"description": "Offer the user a link to an employee's record (the employee form). Use the employee number (empno) as P3_EMPNO and a label such as \"Open BLAKE's record\".",
|
|
42
|
+
"pages": [3]},
|
|
43
|
+
{"name": "give_raise", "type": "function",
|
|
44
|
+
"description": "Raise an employee's salary by a percentage. Only when the user clearly asks for it; repeat the employee and the percentage first.",
|
|
45
|
+
"function": "hr.give_raise",
|
|
46
|
+
"parameters": {"P_EMPNO": {"type": "integer", "description": "The employee number (empno)."},
|
|
47
|
+
"P_PCT": {"type": "number", "description": "The raise in percent, e.g. 5."}},
|
|
48
|
+
"authz": "MANAGER"},
|
|
49
|
+
{"name": "note", "type": "javascript", "action": "hr_agent_note",
|
|
50
|
+
"description": "Show the user a short confirmation message in the page, e.g. after a raise.",
|
|
51
|
+
"parameters": {"TEXT": {"type": "string", "description": "The message."}}}
|
|
52
|
+
]$j$::jsonb,
|
|
53
|
+
ai_agents = $j$[
|
|
54
|
+
{"name": "HR_AGENT", "description": "Answers questions about salaries and opens employee records",
|
|
55
|
+
"service": "HR_ASSISTANT",
|
|
56
|
+
"system": "You are the HR agent of a small company, talking with &APP_USER.. Answer questions about employees, departments and salaries with the top_earners tool. When you name one employee, offer a link to their record with open_employee (the empno as P3_EMPNO). Be brief.",
|
|
57
|
+
"effort": "low", "tools": ["top_earners", "open_employee", "give_raise", "note"], "max_steps": 4, "max_tokens": 2000}
|
|
58
|
+
]$j$::jsonb
|
|
59
|
+
where alias = 'hr';
|
|
60
|
+
|
|
61
|
+
insert into meta.page (app_id, page_no, name, title, parent_page)
|
|
62
|
+
select id, 46, 'HR agent', 'HR agent', 1 from meta.app where alias = 'hr';
|
|
63
|
+
|
|
64
|
+
insert into meta.region (page_id, seq, title, type, columns, template, source, condition, config)
|
|
65
|
+
select p.id, r.seq, r.title, r.type, r.cols, 'standard', r.source, r.cond, r.config::jsonb
|
|
66
|
+
from meta.page p join meta.app a on a.id = p.app_id, (values
|
|
67
|
+
(10, 'No AI service yet', 'static', 12,
|
|
68
|
+
'<p class="alert alert-info">No AI service is configured for this application yet. An administrator adds an AI service named <b>HR_ASSISTANT</b> under <i>App Builder → Workspace utilities → AI services</i> and allows the HR application to use it.</p>',
|
|
69
|
+
'not meta.ai_available(''HR_ASSISTANT'')', '{}'),
|
|
70
|
+
(20, 'Ask the HR agent', 'ai_assistant', 8, null, 'meta.ai_available(''HR_ASSISTANT'')',
|
|
71
|
+
$j${"agent": "HR_AGENT",
|
|
72
|
+
"welcome": "Hello! Ask me who earns what, e.g. who in Sales earns most. I can open an employee's record for you.",
|
|
73
|
+
"placeholder": "e.g. Who in Sales earns most?",
|
|
74
|
+
"max_turns": 20,
|
|
75
|
+
"error_message": "The HR agent could not answer just now. Please try again later."}$j$)
|
|
76
|
+
) as r (seq, title, type, cols, source, cond, config)
|
|
77
|
+
where a.alias = 'hr' and p.page_no = 46;
|
|
78
|
+
|
|
79
|
+
-- the javascript tool "note": a custom event the agent raises after its answer
|
|
80
|
+
insert into meta.dynamic_action (page_id, seq, name, event, trigger_element, action, message)
|
|
81
|
+
select p.id, 10, 'Agent note', 'custom', 'hr_agent_note', 'show_success', 'The HR agent did what you asked.'
|
|
82
|
+
from meta.page p join meta.app a on a.id = p.app_id where a.alias = 'hr' and p.page_no = 46;
|
|
83
|
+
|
|
84
|
+
insert into meta.nav_entry (app_id, seq, label, icon, target_page)
|
|
85
|
+
select id, 30, 'HR agent', 'users', 46 from meta.app where alias = 'hr';
|
|
86
|
+
|
|
87
|
+
insert into meta.translation (app_id, language, source, target)
|
|
88
|
+
select a.id, 'nl', t.source, t.target
|
|
89
|
+
from meta.app a, (values
|
|
90
|
+
('HR agent', 'HR-agent'),
|
|
91
|
+
('Ask the HR agent', 'Vraag het de HR-agent'),
|
|
92
|
+
('Hello! Ask me who earns what, e.g. who in Sales earns most. I can open an employee''s record for you.',
|
|
93
|
+
'Hallo! Vraag me wie wat verdient, bijv. wie in Sales het meest verdient. Ik kan ook de gegevens van een medewerker voor je openen.'),
|
|
94
|
+
('e.g. Who in Sales earns most?', 'bijv. Wie verdient het meest in Sales?')
|
|
95
|
+
) as t (source, target)
|
|
96
|
+
where a.alias = 'hr'
|
|
97
|
+
on conflict do nothing;
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
-- =====================================================================
|
|
2
|
+
-- HR example, part 65: "Ask in your own words" without an AI service
|
|
3
|
+
-- (docs/guide/04-pages-and-regions.md, "Ask in your own words")
|
|
4
|
+
--
|
|
5
|
+
-- Page 2 "Employees": the interactive report gets a question box with the
|
|
6
|
+
-- built-in phrases ("ai_filter": {} names no AI service). Try
|
|
7
|
+
-- sum of salary by department where job is clerk
|
|
8
|
+
-- salary over 2500, sort by hire date, newest first
|
|
9
|
+
-- only clerks hired after 1981
|
|
10
|
+
-- bonus is 10% of salary
|
|
11
|
+
-- highlight salary over 4000 in red
|
|
12
|
+
-- Each answer becomes the report's own settings (filters, sort, group by,
|
|
13
|
+
-- computed columns, …), shown as chips with Edit and Remove under the box;
|
|
14
|
+
-- Undo goes back a step. Page 38's staff list uses the HR_ASSISTANT AI
|
|
15
|
+
-- service when an administrator has added it, else the same phrases.
|
|
16
|
+
-- =====================================================================
|
|
17
|
+
|
|
18
|
+
update meta.region r
|
|
19
|
+
set config = r.config || '{"ai_filter": {"placeholder": "e.g. sum of salary by department where job is clerk"}}'
|
|
20
|
+
from meta.page p, meta.app a
|
|
21
|
+
where r.page_id = p.id and p.app_id = a.id and a.alias = 'hr' and p.page_no = 2 and r.type = 'report';
|