Skip to content

Commit f016b4f

Browse files
clausprueferclauspruefer
authored
Merge pull request #1 from WEBcodeX1/copilot/build-x0-application
feat: build x0 github2stackfield application
2 parents ce1aa75 + 4699278 commit f016b4f

23 files changed

Lines changed: 2296 additions & 0 deletions

‎AI-prompt.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
Build an x0 application using the x0 framework from https://github.com/WEBcodeX1/x0,
2+
The backend in Python should use the https://github.com/clauspruefer/python-micro-esb project
3+
The CSS styling is done with the x0 contained Bootstrap default theme and should look modern.
4+
The browser-frontend consists of 3 x0 screens / 3 menu entries:
5+
1. Screen1 "User Credentials": contains 2 groups of formfields (x0 object of type `sysObjectFormfieldList`): group a) GitHub API User/Token credentials group b) Stackfield API User/Token Credentials
6+
1.1. On each formfield group there must be a button "verify user credentials" to test if the API authentication is working
7+
2. Screen2 "Issue / Task Mapping": contains the mapping between GitHub Issues and Stackfield Tasks
8+
2.1. On top there should be 1 formfield / search input and a search execution button (x0 object of type `sysObjectFormfieldList`)
9+
2.2. Under the search must be a list (x0 object of type `sysObjectList` containing the search results
10+
2.3. The search result list from 2.2. contains a x0 object of type `sysObjContextMenu` with one entry "Connect Stackfield Task"
11+
2.4. On button click from 2.1 the relevant python-micro-esb backend service must be called and the given result list from 2.2 must be filled with the result data from the backend service
12+
3. Screen3 "Connect Stackfield Task"
13+
3.1. Contains detailed GitHub Task properties from GitHub API webservice result (encapsulated from python-micro-esb backend), e.g. 3 or four formfields describing the task properties from API result
14+
3.2. On right click of screen 2 object result display list single row, the GitHub task properties fields of Screen3 will be updated from the row data
15+
3.3. Also there should be relevant Stackfield properties where to map the Stackfield Task (Stackfield room or similar, please find the best possible fields from the API to map)
16+
3.4. At the bottom there must be 1 button (x0 object type `sysObjButton`), on click a NEW STACKFIELD TASK will be generated from the relevant GitHub Issue/Task data from Screen3 formfield data.

‎README.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# github2stackfield
2+
3+
**github2stackfield** is an x0 web application that bridges **GitHub Issues** with **Stackfield Tasks**.
4+
It lets you search GitHub issues, inspect their details, and create corresponding Stackfield tasks — all from a clean, Bootstrap-styled browser frontend.
5+
6+
---
7+
8+
## Architecture
9+
10+
| Layer | Technology |
11+
|---|---|
12+
| Browser frontend | [x0 JavaScript framework](https://github.com/WEBcodeX1/x0) with Bootstrap default theme |
13+
| Backend services | Python WSGI scripts via [python-micro-esb](https://github.com/clauspruefer/python-micro-esb) |
14+
| Database | PostgreSQL (shared x0 instance) |
15+
| Deployment | Apache2 + mod_wsgi (Docker or bare-metal) |
16+
17+
---
18+
19+
## Screens
20+
21+
### Screen 1 — User Credentials
22+
Configure and verify API access for both platforms.
23+
24+
- **GitHub API Credentials** — enter your GitHub username and Personal Access Token.
25+
Click *Verify GitHub Credentials* to validate and store them.
26+
- **Stackfield API Credentials** — enter your Stackfield e-mail and API token.
27+
Click *Verify Stackfield Credentials* to validate and store them.
28+
29+
### Screen 2 — Issue / Task Mapping
30+
Search GitHub issues and select one to map to Stackfield.
31+
32+
1. Enter the target repository (`owner/repository`) and an optional search term.
33+
2. Click **Search Issues** — results populate the issue list below.
34+
3. Right-click any row and select **Connect Stackfield Task** to navigate to Screen 3.
35+
36+
### Screen 3 — Connect Stackfield Task
37+
Review the selected GitHub issue and create a Stackfield task.
38+
39+
- **GitHub Issue Properties** — read-only fields: issue number, state, title, URL.
40+
- **Stackfield Task Mapping** — editable fields pre-populated from the issue:
41+
- *Stackfield Room ID* — the target Stackfield room / channel identifier.
42+
- *Task Title* — editable, defaults to the GitHub issue title.
43+
- *Description* — editable, defaults to the GitHub issue body.
44+
- *Priority* — Low / Medium / High / Urgent.
45+
- Click **Create New Stackfield Task** — a new task is created in Stackfield via the REST API.
46+
47+
---
48+
49+
## Prerequisites
50+
51+
| Requirement | Notes |
52+
|---|---|
53+
| Docker Engine | With Compose V2 (`docker compose`) |
54+
| GitHub Personal Access Token | Needs `repo` scope for private repos, `public_repo` for public |
55+
| Stackfield API token | See Stackfield workspace settings → Integrations → API |
56+
57+
---
58+
59+
## Docker (quick start)
60+
61+
The application uses the official x0 container images:
62+
63+
- **`ghcr.io/webcodex1/x0-app`** — Apache2 + mod_wsgi web application server with the x0 JavaScript framework pre-installed ([packages page](https://github.com/WEBcodeX1/x0/pkgs/container/x0-app))
64+
- **`ghcr.io/webcodex1/x0-db`** — PostgreSQL 16 database with the x0 schema pre-installed ([packages page](https://github.com/WEBcodeX1/x0/pkgs/container/x0-db))
65+
66+
Both custom images are built automatically on `docker compose up --build`:
67+
68+
- `docker/Dockerfile` extends `ghcr.io/webcodex1/x0-app` and copies all static files, Python WSGI scripts, and the Apache2 config snippet into the image.
69+
- `docker/Dockerfile.db` extends `ghcr.io/webcodex1/x0-db` and runs the github2stackfield SQL init scripts (`database/0*.sql`) against the x0 database on first start.
70+
71+
```bash
72+
cd docker
73+
docker compose up --build
74+
```
75+
76+
Then open [http://localhost:8080/?appid=github2sf](http://localhost:8080/?appid=github2sf).
77+
78+
No further manual configuration is required.
79+
80+
---
81+
82+
## Project structure
83+
84+
```
85+
github2stackfield/
86+
├── static/
87+
│ ├── menu.json # x0 navigation menu definition
88+
│ ├── object.json # x0 UI objects (formfields, lists, buttons …)
89+
│ └── skeleton.json # x0 screen layout
90+
├── python/
91+
│ ├── service_implementation.py # GitHubService + StackfieldService ClassHandlers
92+
│ ├── user_routing.py # python-micro-esb ServiceRouter routing functions
93+
│ ├── VerifyGitHubCredentials.py # WSGI – verify GitHub credentials
94+
│ ├── VerifyStackfieldCredentials.py # WSGI – verify Stackfield credentials
95+
│ ├── SearchGitHubIssues.py # WSGI – search issues, populate list
96+
│ ├── GetGitHubIssueDetails.py # WSGI – fetch issue details for Screen 3
97+
│ ├── CreateStackfieldTask.py # WSGI – create Stackfield task
98+
│ ├── POSTData.py # x0 POST body reader helper
99+
│ └── StdoutLogger.py # logging helper
100+
├── database/
101+
│ ├── 01-create-schema.sql # github2sf schema + tables
102+
│ ├── 02-insert-config.sql # x0 app configuration rows
103+
│ └── 03-insert-text.sql # UI text / i18n entries
104+
├── docker/
105+
│ ├── Dockerfile # extends x0-app, bakes in static/ python/ apache2.conf
106+
│ ├── Dockerfile.db # extends x0-db, auto-inits github2sf schema on startup
107+
│ ├── docker-compose.yml
108+
│ ├── db-init.sh # startup script used by Dockerfile.db
109+
│ └── apache2.conf
110+
└── README.md
111+
```
112+
113+
---
114+
115+
## python-micro-esb integration
116+
117+
The backend services are built on the [python-micro-esb](https://github.com/clauspruefer/python-micro-esb) framework:
118+
119+
- **`service_implementation.py`** — contains `GitHubService` and `StackfieldService`, both subclassing `microesb.ClassHandler`. Each class exposes service methods (`verify`, `search_issues`, `get_issue_details`, `create_task`).
120+
- **`user_routing.py`** — routing functions consumed by `ServiceRouter.send()`. Each function instantiates the appropriate service class, calls the relevant method, and returns the result.
121+
- **WSGI scripts** — thin wrappers that read the x0 POST payload, call `ServiceRouter.send()`, and return JSON to the x0 frontend.
122+
123+
---
124+
125+
## Stackfield API notes
126+
127+
Stackfield's REST API is available at `https://www.stackfield.com/api/v1/`.
128+
Key endpoints used:
129+
130+
| Endpoint | Purpose |
131+
|---|---|
132+
| `GET /v1/user` | Verify credentials |
133+
| `POST /v1/rooms/{room_id}/tasks` | Create a new task |
134+
135+
The **Room ID** can be found in Stackfield under *Room settings → General → Room ID* or via the URL slug.
136+
137+
---
138+
139+
## License
140+
141+
See [LICENSE](LICENSE).

‎database/01-create-schema.sql‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
-- ]*[ ------------------------------------------------------------------ ]*[
2+
-- . github2stackfield - Database Schema .
3+
-- ]*[ ------------------------------------------------------------------ ]*[
4+
-- . .
5+
-- . Run against an existing x0 PostgreSQL database. .
6+
-- . The x0 framework must be set up first (see x0 repository). .
7+
-- . .
8+
-- ]*[ ------------------------------------------------------------------ ]*[
9+
10+
-- Application schema
11+
CREATE SCHEMA IF NOT EXISTS github2sf;
12+
13+
-- ---------------------------------------------------------------------------
14+
-- API Credentials storage
15+
-- ---------------------------------------------------------------------------
16+
CREATE TABLE IF NOT EXISTS github2sf.credentials (
17+
credential_type VARCHAR(20) NOT NULL,
18+
username_or_email TEXT NOT NULL,
19+
api_token TEXT NOT NULL,
20+
updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
21+
CONSTRAINT pk_credentials PRIMARY KEY (credential_type)
22+
);
23+
24+
COMMENT ON TABLE github2sf.credentials IS
25+
'Stores GitHub and Stackfield API credentials (one row per credential_type).';
26+
27+
-- ---------------------------------------------------------------------------
28+
-- Application configuration key-value store
29+
-- ---------------------------------------------------------------------------
30+
CREATE TABLE IF NOT EXISTS github2sf.app_config (
31+
config_key VARCHAR(100) NOT NULL,
32+
value TEXT,
33+
updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
34+
CONSTRAINT pk_app_config PRIMARY KEY (config_key)
35+
);
36+
37+
COMMENT ON TABLE github2sf.app_config IS
38+
'Key-value store for github2stackfield application runtime configuration.';
39+
40+
-- ---------------------------------------------------------------------------
41+
-- Issue / Task mapping log
42+
-- ---------------------------------------------------------------------------
43+
CREATE TABLE IF NOT EXISTS github2sf.issue_task_mapping (
44+
id SERIAL NOT NULL,
45+
github_repo TEXT NOT NULL,
46+
github_issue_number INTEGER NOT NULL,
47+
github_issue_title TEXT,
48+
stackfield_room_id TEXT NOT NULL,
49+
stackfield_task_id TEXT,
50+
stackfield_task_url TEXT,
51+
created_at TIMESTAMP NOT NULL DEFAULT NOW(),
52+
CONSTRAINT pk_issue_task_mapping PRIMARY KEY (id)
53+
);
54+
55+
CREATE INDEX IF NOT EXISTS idx_issue_task_mapping_repo_issue
56+
ON github2sf.issue_task_mapping (github_repo, github_issue_number);
57+
58+
COMMENT ON TABLE github2sf.issue_task_mapping IS
59+
'Audit log of all GitHub issue → Stackfield task mappings created by the app.';

‎database/02-insert-config.sql‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
-- ]*[ ------------------------------------------------------------------ ]*[
2+
-- . github2stackfield - x0 Application Configuration .
3+
-- ]*[ ------------------------------------------------------------------ ]*[
4+
-- . .
5+
-- . Insert the x0 system.config rows for the github2stackfield app. .
6+
-- . Adjust app_id value if your x0 setup uses a different identifier. .
7+
-- . .
8+
-- ]*[ ------------------------------------------------------------------ ]*[
9+
10+
-- Remove any previously inserted config for this app
11+
DELETE FROM system.config WHERE app_id = 'github2sf';
12+
13+
INSERT INTO system.config (app_id, config_group, "value") VALUES
14+
('github2sf', 'index_title', 'GitHub ↔ Stackfield Connector'),
15+
('github2sf', 'debug_level', '0'),
16+
('github2sf', 'display_language', 'en'),
17+
('github2sf', 'default_screen', 'Screen1'),
18+
('github2sf', 'parent_window_url', 'null'),
19+
('github2sf', 'subdir', '/static/github2sf'),
20+
('github2sf', 'config_file_menu', 'menu.json'),
21+
('github2sf', 'config_file_object', 'object.json'),
22+
('github2sf', 'config_file_skeleton','skeleton.json');

0 commit comments

Comments
 (0)