@nanobpm/urban-pr-review-codefirst 0.1.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 ADDED
@@ -0,0 +1,141 @@
1
+ # urban-pr-review-codefirst
2
+
3
+ The **code-first** expression of [urban-pr-review](../urban-pr-review): a durable,
4
+ multi-round loop that drives a GitHub PR to convergence against an automated
5
+ reviewer, escalating to a human when the reviewer is stuck or a round cap is hit.
6
+
7
+ The model-first app draws this loop in `convergence-loop.bpmn`. Here the same loop
8
+ is written with the `@nanobpm/workflow` declarative surface (`defineFlow`, ADR
9
+ 0044/0045). The SDK derives the executable BPMN (with DI), the job types, and the
10
+ message names — no diagram, no task-type wiring, no correlation plumbing.
11
+
12
+ **Feature parity with the model-first app.** This app persists to the same SQLite
13
+ schema and serves the same schema-driven web frontend as
14
+ [urban-pr-review](../urban-pr-review) — the two run identically. The only
15
+ difference is *how* the loop and its record steps are expressed: model-first draws
16
+ them (`convergence-loop.bpmn` + `workers/*/worker.ts`), code-first writes them
17
+ (`workflows/convergence-loop.ts`, with the record steps hosted in-process). See
18
+ [Persistence](#persistence) and [Frontend](#frontend) below.
19
+
20
+ ## The flow
21
+
22
+ `workflows/convergence-loop.ts`:
23
+
24
+ ```
25
+ loop:
26
+ review-round (EXTERNAL agent — a coding-agent harness)
27
+ switch status:
28
+ converged -> persist-converged; break
29
+ addressed -> if round >= maxRounds:
30
+ persist-escalation-maxrounds (fall through)
31
+ else:
32
+ persist-round (round+1); wait-review; continue
33
+ default -> persist-escalation (fall through)
34
+ wait-answer (both escalation paths park here for a human)
35
+ ```
36
+
37
+ - **`review-round`** is a `w.task` — an **external** worker. Point a coding-agent
38
+ harness at the job type `convergence-loop:review-round` (e.g. `c8ctl nano hire`).
39
+ The app never hosts or names it; it only owns the durable orchestration around it.
40
+ - **`persist-*`** and **`persist-converged`** are `w.run` — app-hosted handlers.
41
+ `persist-round` returns `{ round: round + 1 }`; that return value (not an
42
+ ioMapping) is the loop's only state mutation.
43
+ - **`wait-review`** / **`wait-answer`** are `w.signal` — real, engine-visible catch
44
+ events correlated on `prKey`. Both resume at the loop head (`review-round`):
45
+ `wait-review` via an explicit `continue`, `wait-answer` via the loop's natural
46
+ repeat. The two escalation branches converge on the single trailing
47
+ `wait-answer` (step names must be unique, so the signal is not repeated). This
48
+ durable wait is the surface a Temporal-style code-first API cannot draw.
49
+
50
+ Because every step declares a typed `envelope()` contract, this flow can be
51
+ **ejected to model-first** without losing its I/O shapes — they are lifted into
52
+ the generated BPMN as `nano:shape` + `io.nanobpm.dataEnvelope` properties.
53
+
54
+ ## Derived names
55
+
56
+ | Step | Derived job type / message |
57
+ | --- | --- |
58
+ | `review-round` (external) | `convergence-loop:review-round` |
59
+ | `persist-round` | `convergence-loop:persist-round` |
60
+ | `persist-escalation` | `convergence-loop:persist-escalation` |
61
+ | `persist-escalation-maxrounds` | `convergence-loop:persist-escalation-maxrounds` |
62
+ | `persist-converged` | `convergence-loop:persist-converged` |
63
+ | `wait-review` (signal) | `convergence-loop:wait-review` |
64
+ | `wait-answer` (signal) | `convergence-loop:wait-answer` |
65
+
66
+ ## Run it
67
+
68
+ Requires a running Nano gateway (default `http://localhost:8080`; override with
69
+ `NANOBPMN_BASE_URL`).
70
+
71
+ ```sh
72
+ # The one service: applies DB migrations, deploys the flow, hosts the app-owned
73
+ # w.run record steps, AND serves the web frontend + review-ready poller.
74
+ deno task start # → http://localhost:3000
75
+ ```
76
+
77
+ `deno task start` now does everything: it applies the `db/migrations/` on boot
78
+ (creating `app.db`), deploys the flow, hosts the `persist-*` handlers, serves the
79
+ schema-driven page runtime at `http://localhost:3000`, and runs the review-ready
80
+ poller. Submit and answer PRs directly from the web UI, or drive the same actions
81
+ from the CLI:
82
+
83
+ ```sh
84
+ # submit a PR (parks after review-round at wait-review or wait-answer)
85
+ deno task submit https://github.com/owner/repo/pull/42 5 # 5 = maxRounds
86
+
87
+ # nudge a re-review (resumes an instance parked at wait-review)
88
+ deno task review-ready owner/repo#42
89
+
90
+ # answer an escalation (resumes an instance parked at wait-answer)
91
+ deno task answer owner/repo#42 "merge as-is"
92
+
93
+ # wipe all persisted PRs/rounds/escalations (drops + re-migrates app.db)
94
+ deno task purge
95
+ ```
96
+
97
+ The reviewer itself is not started by `deno task start` — it is the external
98
+ `convergence-loop:review-round` job. Host it with a coding-agent harness so the
99
+ automated review is fully decoupled from the durable orchestration.
100
+
101
+ Environment overrides: `PR_REVIEW_PORT` (default `3000`), `NANOBPMN_BASE_URL`
102
+ (gateway), `NANO_APP_DB_URL` (default `file:./app.db`), `NANO_PR_POLL_MS`
103
+ (poller interval, default `60000`), `NANO_PR_MAX_ROUNDS` (default `10`),
104
+ `GITHUB_TOKEN` (enables the poller — without it the poller idles and re-reviews
105
+ come only from the CLI/UI).
106
+
107
+ ## Persistence
108
+
109
+ Parity with the model-first app: the same three-table SQLite schema
110
+ (`pull_requests`, `rounds`, `escalations`), the same `db/migrations/*.sql`, and
111
+ the same generated typed data facade (`nano-generated/domain.ts`, exposing
112
+ `db.pull_requests` / `db.rounds` / `db.escalations`). The `nano.app.json` manifest
113
+ declares the `app` sqlite datasource (`${NANO_APP_DB_URL:-file:./app.db}`) and the
114
+ migrations directory.
115
+
116
+ The record steps that write these rows are the code-first counterpart of the
117
+ model-first `workers/{persist-round,persist-escalation,finalize}` — but instead of
118
+ standalone `defineWorker`s, they are the `w.run` handlers in
119
+ `workflows/convergence-loop.ts`, hosted **in-process** by the `@nanobpm/workflow`
120
+ `Worker` that `deno task start` runs. The datasource is opened lazily and memoised
121
+ on first persist, so the thin CLI scripts (`submit`/`answer`/`review-ready`) can
122
+ import the flow to start/signal instances without ever opening the DB — only the
123
+ worker host does.
124
+
125
+ ## Frontend
126
+
127
+ The same schema-driven page runtime as the model-first app (`pages/home.page.json`
128
+ + the `nano-generated/app-pages.ts` engine), served by `main.ts` at
129
+ `http://localhost:3000`. It lists active + historical PRs, submits new ones, and
130
+ answers or cancels runs inline. Because both apps commit the identical page schema
131
+ and generated runtime, the UI is byte-for-byte the same; `main.ts` supplies the
132
+ code-first action bindings (`start` → `wf.start`, escalation `message` →
133
+ `wf.signal wait-answer`, `cancel` → gateway cancellation) behind it.
134
+
135
+ ## Link it into your Nano projects
136
+
137
+ This is a standalone Deno project. Import it by reference (ADR 0041) so the
138
+ console reads it live from this directory:
139
+
140
+ - In the console **Projects → Import by reference**, point at this folder, or
141
+ - drop a `urban-pr-review-codefirst.project-ref.json` in your projects root.
@@ -0,0 +1,69 @@
1
+ {
2
+ "$schema": "https://unpkg.com/@camunda/zeebe-element-templates-json-schema@0.44.0/resources/schema.json",
3
+ "id": "io.nanobpm.urban.pr-review-round-codefirst",
4
+ "name": "PR Review Round (agent, code-first)",
5
+ "description": "One decoupled review round serviced by an external agent (e.g. a Copilot instance via `c8ctl nano work`). The agent reads the latest review, addresses it, pushes, re-requests review, and returns a structured status. Mirrors the model-first template, bound to the code-first derived job type.",
6
+ "appliesTo": ["bpmn:Task"],
7
+ "elementType": { "value": "bpmn:ServiceTask" },
8
+ "properties": [
9
+ {
10
+ "type": "Hidden",
11
+ "value": "convergence-loop:review-round",
12
+ "binding": { "type": "zeebe:taskDefinition:type" }
13
+ },
14
+ {
15
+ "label": "Input data-envelope type",
16
+ "type": "Hidden",
17
+ "value": "ReviewRoundIn",
18
+ "binding": { "type": "zeebe:property", "name": "io.nanobpm.dataEnvelope.in" }
19
+ },
20
+ {
21
+ "label": "Output data-envelope type",
22
+ "type": "Hidden",
23
+ "value": "ReviewRoundOut",
24
+ "binding": { "type": "zeebe:property", "name": "io.nanobpm.dataEnvelope.out" }
25
+ },
26
+ {
27
+ "label": "PR URL",
28
+ "type": "String",
29
+ "feel": "optional",
30
+ "value": "=prUrl",
31
+ "binding": { "type": "zeebe:input", "name": "prUrl" }
32
+ },
33
+ {
34
+ "label": "Repo (owner/name)",
35
+ "type": "String",
36
+ "feel": "optional",
37
+ "value": "=repo",
38
+ "binding": { "type": "zeebe:input", "name": "repo" }
39
+ },
40
+ {
41
+ "label": "PR number",
42
+ "type": "String",
43
+ "feel": "optional",
44
+ "value": "=prNumber",
45
+ "binding": { "type": "zeebe:input", "name": "prNumber" }
46
+ },
47
+ {
48
+ "label": "Round",
49
+ "type": "String",
50
+ "feel": "optional",
51
+ "value": "=round",
52
+ "binding": { "type": "zeebe:input", "name": "round" }
53
+ },
54
+ {
55
+ "label": "Prompt (instructions)",
56
+ "type": "String",
57
+ "feel": "optional",
58
+ "value": "=prompt",
59
+ "binding": { "type": "zeebe:input", "name": "prompt" }
60
+ },
61
+ {
62
+ "label": "Answer (on escalation resume)",
63
+ "type": "String",
64
+ "feel": "optional",
65
+ "value": "=answer",
66
+ "binding": { "type": "zeebe:input", "name": "answer" }
67
+ }
68
+ ]
69
+ }
@@ -0,0 +1,46 @@
1
+ -- urban-pr-review schema (SPEC §7). One row per PR under convergence, its rounds,
2
+ -- and any escalations raised mid-convergence.
3
+
4
+ CREATE TABLE IF NOT EXISTS pull_requests (
5
+ pr_key TEXT PRIMARY KEY, -- "<owner>/<repo>#<number>"
6
+ repo TEXT NOT NULL, -- "<owner>/<repo>"
7
+ number INTEGER NOT NULL,
8
+ url TEXT NOT NULL,
9
+ title TEXT, -- fetched from GitHub (optional)
10
+ status TEXT NOT NULL, -- converging | waiting_review | escalated | converged | abandoned
11
+ current_round INTEGER NOT NULL DEFAULT 0,
12
+ process_key TEXT, -- engine process-instance key
13
+ waiting_since TEXT, -- ISO ts we began waiting for a review (poller cursor)
14
+ last_review_id INTEGER, -- last GitHub review id we reacted to
15
+ outcome TEXT, -- final summary
16
+ created_at TEXT NOT NULL,
17
+ updated_at TEXT NOT NULL,
18
+ converged_at TEXT
19
+ );
20
+
21
+ CREATE TABLE IF NOT EXISTS rounds (
22
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
23
+ pr_key TEXT NOT NULL REFERENCES pull_requests(pr_key),
24
+ round_no INTEGER NOT NULL,
25
+ status TEXT, -- converged | addressed | needs_input | blocked
26
+ summary TEXT,
27
+ started_at TEXT NOT NULL,
28
+ ended_at TEXT
29
+ );
30
+
31
+ CREATE TABLE IF NOT EXISTS escalations (
32
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
33
+ pr_key TEXT NOT NULL REFERENCES pull_requests(pr_key),
34
+ round_no INTEGER NOT NULL,
35
+ kind TEXT NOT NULL, -- question | blocker
36
+ question TEXT NOT NULL,
37
+ answer TEXT,
38
+ status TEXT NOT NULL, -- open | answered
39
+ asked_at TEXT NOT NULL,
40
+ answered_at TEXT
41
+ );
42
+
43
+ CREATE INDEX IF NOT EXISTS idx_pr_status ON pull_requests(status);
44
+ CREATE INDEX IF NOT EXISTS idx_rounds_pr ON rounds(pr_key);
45
+ CREATE INDEX IF NOT EXISTS idx_esc_pr ON escalations(pr_key);
46
+ CREATE INDEX IF NOT EXISTS idx_esc_open ON escalations(pr_key, status);
@@ -0,0 +1,7 @@
1
+ -- Auditability: keep the agent's full transcript (the harness's byte-capped
2
+ -- stdout capture, surfaced on the io.nanobpm.agentResult envelope) alongside the
3
+ -- round it produced and any escalation it raised, so a human can see exactly what
4
+ -- the agent did without re-running it.
5
+
6
+ ALTER TABLE rounds ADD COLUMN transcript TEXT;
7
+ ALTER TABLE escalations ADD COLUMN transcript TEXT;
@@ -0,0 +1,8 @@
1
+ -- Denormalise the currently-open escalation onto the PR row so the generic page
2
+ -- runtime (ADR 0042) can bind a conditional "answer" form to it without a join:
3
+ -- the form is shown when `open_escalation_id` is set and prints
4
+ -- `open_escalation_question`. The persist-escalation worker sets these when it
5
+ -- opens an escalation, and answering (or finalising) clears them.
6
+
7
+ ALTER TABLE pull_requests ADD COLUMN open_escalation_id INTEGER;
8
+ ALTER TABLE pull_requests ADD COLUMN open_escalation_question TEXT;
package/deno.json ADDED
@@ -0,0 +1,22 @@
1
+ {
2
+ "compilerOptions": {
3
+ "lib": ["deno.window", "deno.ns", "esnext", "dom"]
4
+ },
5
+ "lint": {
6
+ "exclude": [".deno-cache/", "nano-generated/"]
7
+ },
8
+ "imports": {
9
+ "@nanobpm/workflow": "npm:@nanobpm/workflow@^0.3.0",
10
+ "@nanobpm/domain": "./nano-generated/domain.ts",
11
+ "@nanobpm/data": "./nano-generated/data-sdk.ts",
12
+ "@nanobpm/app": "./nano-generated/app-pages.ts",
13
+ "bpmn-auto-layout": "npm:bpmn-auto-layout@^2.0.0-alpha.2"
14
+ },
15
+ "tasks": {
16
+ "start": "deno run --allow-net --allow-read --allow-write --allow-env --allow-run=deno main.ts",
17
+ "purge": "deno run --allow-read --allow-write --allow-env --allow-run=deno scripts/purge-db.ts",
18
+ "submit": "deno run --allow-net --allow-read --allow-env scripts/submit.ts",
19
+ "review-ready": "deno run --allow-net --allow-read --allow-env scripts/review-ready.ts",
20
+ "answer": "deno run --allow-net --allow-read --allow-env scripts/answer.ts"
21
+ }
22
+ }
package/deno.lock ADDED
@@ -0,0 +1,77 @@
1
+ {
2
+ "version": "5",
3
+ "specifiers": {
4
+ "npm:@nanobpm/workflow@0.3": "0.3.0_bpmn-auto-layout@2.0.0-alpha.2",
5
+ "npm:@types/node@22": "22.20.1",
6
+ "npm:bpmn-auto-layout@^2.0.0-alpha.2": "2.0.0-alpha.2"
7
+ },
8
+ "npm": {
9
+ "@nanobpm/workflow@0.3.0_bpmn-auto-layout@2.0.0-alpha.2": {
10
+ "integrity": "sha512-idZuikc0JQE3Lw85WPQoM6z3KXhVZQo7xGPo/5ubLzWmMFxMBZMLuCbUrEgKXOKhsu3DiXqJP52HOqPK1KDVhg==",
11
+ "dependencies": [
12
+ "bpmn-auto-layout"
13
+ ],
14
+ "optionalPeers": [
15
+ "bpmn-auto-layout"
16
+ ]
17
+ },
18
+ "@types/node@22.20.1": {
19
+ "integrity": "sha512-EANqOCF9QFyra+4pfxUcX9STKJpCLjMbObVzljIJomAWSnuSIEAvyzEU53GaajbXJEgdh0iEcPL+DGvpUd4k1Q==",
20
+ "dependencies": [
21
+ "undici-types"
22
+ ]
23
+ },
24
+ "bpmn-auto-layout@2.0.0-alpha.2": {
25
+ "integrity": "sha512-Xg8BoRMijfECgWljIlE44hbGDAuF0BkjJuLfd5o3oOx1ileL06EJQhlgO040xFIegfjxq91dVFAoxCL17wo53A==",
26
+ "dependencies": [
27
+ "bpmn-moddle",
28
+ "min-dash"
29
+ ],
30
+ "bin": true
31
+ },
32
+ "bpmn-moddle@10.1.0": {
33
+ "integrity": "sha512-k9Vl97hiFwlr4bJTQ5+pZp21bmrQwil5jnMQ30wF8vney2/WnIcJmWwYzRTAKFVoViTGowtDfbO5rGEF4viO0w==",
34
+ "dependencies": [
35
+ "min-dash",
36
+ "moddle",
37
+ "moddle-xml"
38
+ ]
39
+ },
40
+ "min-dash@5.1.0": {
41
+ "integrity": "sha512-HAvN6XzmCQj+js43G9sJRRw8kj/7DvoxN7qhoIN9Xo5ZN1NMljtpyKs/NunXmw0QSWwlgZzNv6tLeEa4xaZ0tg=="
42
+ },
43
+ "moddle-xml@12.1.0_moddle@8.2.1": {
44
+ "integrity": "sha512-+m50j9/MFGhvWbLJoKSSjQj3uv7SYm2w5i2lfv6goWarlWW1Nd0A31NYUXmKuWnEZ8Mm/bH1RZYtuf4x8ptY7g==",
45
+ "dependencies": [
46
+ "min-dash",
47
+ "moddle",
48
+ "saxen"
49
+ ]
50
+ },
51
+ "moddle@8.2.1": {
52
+ "integrity": "sha512-20qzO/ZpMGO9j9gdQgXk9bfGxb9wA3JKnGth/21YZKODLrZE4RW/uVMIL5pTskYm34Z61DucBEPkq93qByNsBQ==",
53
+ "dependencies": [
54
+ "min-dash"
55
+ ]
56
+ },
57
+ "saxen@11.1.1": {
58
+ "integrity": "sha512-J4BkmJFaM7VgE7pgkFGsNEcqqM3h7+Mz80vfLWFhx7uNOCOXIu6LLjQHYWNejdst3pf/3JUaBIG9+pkk1umlow=="
59
+ },
60
+ "undici-types@6.21.0": {
61
+ "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ=="
62
+ }
63
+ },
64
+ "workspace": {
65
+ "dependencies": [
66
+ "npm:@nanobpm/workflow@0.3",
67
+ "npm:bpmn-auto-layout@^2.0.0-alpha.2"
68
+ ],
69
+ "packageJson": {
70
+ "dependencies": [
71
+ "npm:@nanobpm/workflow@0.3",
72
+ "npm:@types/node@22",
73
+ "npm:bpmn-auto-layout@^2.0.0-alpha.2"
74
+ ]
75
+ }
76
+ }
77
+ }