Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions apps/issue-tracker/0.3.0/ui.js

Large diffs are not rendered by default.

15 changes: 11 additions & 4 deletions integrations/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -344,13 +344,14 @@ a drive app whose rows are a shared class (`event-v1`, `issue-v1`,
that class. On such a table it can offer "Sync this table to <provider>".
Calendar 0.3.0 does this for Google Calendar
([`calendar/README.md`](calendar/README.md#syncing-a-table-the-app-didnt-make)),
and issue-tracker 0.3.0 for GitHub
([`issue-tracker/README.md`](issue-tracker/README.md#syncing-a-table-the-app-didnt-make)),
and timesheets 0.6.0 for Clockify, with that table's observation log under
its binding
([`timesheets/README.md`](timesheets/README.md#syncing-a-table-the-app-didnt-make));
issue-tracker can follow the same pattern. What the pinned
host (`a12b74a`) allows, read from `server/src/plugins/app_row_grant.rs`,
([`timesheets/README.md`](timesheets/README.md#syncing-a-table-the-app-didnt-make)).
What the pinned host (`a12b74a`) allows, read from `server/src/plugins/app_row_grant.rs`,
`server/src/handlers/app_write.rs` and the page's `AppPage/hostStore.ts`,
and checked by the calendar e2e:
and checked by the calendar and issue-tracker e2es:

| Write | Allowed |
| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand Down Expand Up @@ -394,6 +395,12 @@ The pattern, as calendar implements it:
is paused and offer to allow editing again; don't fail on the first
write. A provider deletion can't delete the row: offer "keep as local"
and tell the person to delete the row in the table.
7. **List everything the app writes on rows.** The grant checks every
property a row write sends, not only the provider's. Issue-tracker's
Bridge sets Atomic's `localId` on each row it imports (so a create a
reload interrupted is found again, not made twice), so issue-tracker
0.3.0 lists `localId` in `row-extras` too. A property under another app,
or on the never-list (`parent`, `isA`, rights, `classtype`), can't be one.

What this does not give, at the pin: edits made while the app is closed are
found only on its next open (the app can't read `/changes` or receive
Expand Down
10 changes: 5 additions & 5 deletions integrations/catalog.json
Original file line number Diff line number Diff line change
Expand Up @@ -368,15 +368,15 @@
"https://atomicdata.dev/properties/name": "GitHub issues",
"https://atomicdata.dev/properties/emoji": "🐙",
"https://atomicdata.dev/properties/description": "A drive app that keeps one GitHub repository's issues on a board, two-way, with every change to GitHub reviewed before it is sent.",
"https://atomicdata.dev/integrations/properties/capabilities": "Imports one repository's issues and comments into the app's table, shown as a board (Todo, Doing, Blocked, Done) or a list, with search and a label filter. The rows are of the shared Issue class (issue-v1: title, task/v1 status and body), so other views of that class can read them. Title, description (Markdown), status and comments sync both ways; Doing and Blocked are the atomic:doing and atomic:blocked labels on GitHub. A change bound for GitHub waits in Review and send until you approve exactly that change. A field changed on both sides pauses sync until you pick a side. An issue gone from GitHub can be kept here only or removed from the board.",
"https://atomicdata.dev/integrations/properties/capabilities": "Imports one repository's issues and comments into the app's table, shown as a board (Todo, Doing, Blocked, Done) or a list, with search and a label filter. The rows are of the shared Issue class (issue-v1: title, task/v1 status and body), so other views of that class can read them. Title, description (Markdown), status and comments sync both ways; Doing and Blocked are the atomic:doing and atomic:blocked labels on GitHub. A change bound for GitHub waits in Review and send until you approve exactly that change. A field changed on both sides pauses sync until you pick a side. An issue gone from GitHub can be kept here only or removed from the board. Added as a view of another Issue table, it offers Sync this table to GitHub: once you allow it to edit that table's rows (the host's Allow editing, which then also covers the GitHub issue number, source, sync baseline and import key the app keeps on each row), it imports one repository into that table and syncs it the same way; the repository choice and sync state are kept under the app, and the table's own rows stay local until you publish them.",
"https://atomicdata.dev/integrations/properties/events": "Install from Drive apps, connect GitHub through the host's consent bar and choose a repository. It syncs when opened, on Sync now and after each edit made in the app; nothing runs while the app is closed.",
"https://atomicdata.dev/integrations/properties/limitation": "One repository per app, synced with the app's own table only: offered on another Issue table, it shows a notice and syncs nothing. A row added to the table outside the app stays local until you choose Publish to GitHub on it. A status other than exactly one of Todo, Doing, Blocked and Done is shown as it is and not synced. Labels and assignees are shown read-only; milestones and pull requests are not synced, and deletions are never sent to GitHub. One syncing view per app is assumed: two tabs or devices are not guarded. A new issue or comment whose send got no answer is never sent twice: you link it to the issue it became on GitHub, or send it again once GitHub shows no match. Waits for the stable ontology domain. Mock-tested only: not yet verified against live GitHub or the real integration proxy.",
"https://atomicdata.dev/integrations/properties/limitation": "One repository per table: the app's own table, and each other Issue table it was asked to sync. On a table that isn't the app's own, rows are never deleted (Allow editing doesn't cover it, so Remove from board isn't offered there), the table itself is never written, and syncing pauses when the grant is taken back. A row added to the table outside the app stays local until you choose Publish to GitHub on it. A status other than exactly one of Todo, Doing, Blocked and Done is shown as it is and not synced. Labels and assignees are shown read-only; milestones and pull requests are not synced, and deletions are never sent to GitHub. One syncing view per app is assumed: two tabs or devices are not guarded. A new issue or comment whose send got no answer is never sent twice: you link it to the issue it became on GitHub, or send it again once GitHub shows no match. Waits for the stable ontology domain. Mock-tested only: not yet verified against live GitHub or the real integration proxy.",
"https://atomicdata.dev/integrations/properties/keywords": "github issues board kanban tracker two-way review drive app devonian",
"https://atomicdata.dev/integrations/properties/version": "0.2.0",
"https://atomicdata.dev/integrations/properties/version": "0.3.0",
"https://atomicdata.dev/integrations/properties/app-row-name": "Issue",
"https://atomicdata.dev/integrations/properties/app-row-name-plural": "Issues",
"https://atomicdata.dev/integrations/properties/app-module": "https://ontola.github.io/atomic-plugins/apps/issue-tracker/0.2.0/ui.js",
"https://atomicdata.dev/integrations/properties/app-module-integrity": "sha384-Oy8HoxJRzRTf+5CIJJrWPEDdnFx/HrS+tq7OsA8vJAWfQclMxNPGGvKHRYXSutel"
"https://atomicdata.dev/integrations/properties/app-module": "https://ontola.github.io/atomic-plugins/apps/issue-tracker/0.3.0/ui.js",
"https://atomicdata.dev/integrations/properties/app-module-integrity": "sha384-V1/cSNb1t/cfotBhNY423Jx+7992gxY5Yvw4HRxTc5IFXpKBwMbaAisdn5CB9oqR"
},
{
"https://atomicdata.dev/properties/localId": "open-cloud-mesh",
Expand Down
94 changes: 79 additions & 15 deletions integrations/issue-tracker/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,11 +148,13 @@ integration proxy (#46).
## Drive app (`app/`)

An iframe drive app, the same shape as `pets/app/` and `notion/app/`: one
ES module (`app/build.mjs` -> `dist/ui.js`, minified, 154,931 bytes for
0.2.0) whose `view({ root, store })` runs in the host's null-origin frame. It
ES module (`app/build.mjs` -> `dist/ui.js`, minified, 160,628 bytes for
0.3.0) whose `view({ root, store })` runs in the host's null-origin frame. It
hosts the Devonian bridge from `devonian/github-issues/` for **one repository
per app install**, two-way for issue title, body (Markdown),
Todo/Doing/Blocked/Done status and comments.
per table**: the app's own table, and each other Issue table it was asked
to sync (since 0.3.0, see [Syncing a table the app didn't
make](#syncing-a-table-the-app-didnt-make)), two-way for issue title, body
(Markdown), Todo/Doing/Blocked/Done status and comments.

**Flow.** The first screen offers GitHub Issues (Jira and Todoist are shown
as not available). "Connect" asks the host for a connection
Expand Down Expand Up @@ -194,7 +196,10 @@ its published GitHub Pages subject:
issue number, GitHub source (JSON: url, author, labels, assignees,
timestamps) and GitHub sync baseline (JSON: the title, body and status the
app last agreed with GitHub). They are declared as the App's `row-extras`
(atomic-server #1849). A comment's Message carries its own baseline;
(atomic-server #1849), and so is Atomic's `localId` (since 0.3.0), which
the Bridge sets on each row it imports so that a create a reload
interrupted is found again instead of made twice. A comment's Message
carries its own baseline;
- one Message per comment (`about` its row) in a "GitHub comments" folder
under the app;
- one sync resource holding the bound repository and the sync state as JSON
Expand All @@ -203,13 +208,13 @@ its published GitHub Pages subject:
preferences.

**The shared class.** On first open the app adds `issue-v1` to its App's
`renders` (so the host's "+ Add view" offers it on any table of that class)
and sets its own table's `classtype` to `issue-v1`, through the frame store
(#177 spike S2; a catalog Install cannot do this yet, #177 H2). The table is
then an ordinary `issue-v1` table that other views of the class can read.
Opened as a view on an Issue table it did not make, the app shows a notice
and writes nothing: syncing an existing table ("Sync this table to GitHub",
#177 item 14) is not built.
`renders` (so the host's "+ Add view" offers it on any table of that class),
lists its row extras in `row-extras`, and sets its own table's `classtype`
to `issue-v1`, through the frame store (#177 spike S2; a catalog Install
cannot do this yet, #177 H2). Since 0.3.0 that happens on the first open
itself, before a repository is chosen; 0.2.0 did it only once one was. The
table is then an ordinary `issue-v1` table that other views of the class can
read.

**Baselines on the rows (#177 decision 7).** The Bridge still keeps a
baseline per record in memory. At each checkpoint, a baseline that differs
Expand Down Expand Up @@ -412,6 +417,55 @@ folder as a sandbox package. `syncables` is not used: the Bridge's GitHub
port already pages GitHub, and bundling the GitHub OpenAPI document for
syncables would only add size.

### Syncing a table the app didn't make

Since 0.3.0 (#177 §6.2 item 14), on the pattern calendar 0.3.0 set for
Google Calendar (#272). Opened as a view on an Issue table it did not make,
the app shows that the table isn't synced and offers **Sync this table to
GitHub**. Nothing is written before that is pressed. Pressing it:

1. makes sure the App declares its row extras (number, source, baseline and
`localId`), then compares `store.rowAccess()`'s `extras` with them. When
there is no grant, or it doesn't cover them (for example "Allow editing"
chosen in Add view before the app ever declared its extras), it calls
`store.requestRowAccess()`, and the host shows its own "Allow editing" /
"Not now" bar. "Not now" leaves the table unsynced and says why;
2. makes a **binding** under the App: a resource of the app's sync class
with `synced-table` (a new app Property, an `atomicURL`, the table's
subject) and `localId` `github-issues:sync <table>`, so AtomicServer keeps
one per table. The app finds it with `store.query` on `synced-table` and
accepts only one whose parent is the App;
3. goes on as on the app's own table: connect (if needed), choose the
repository, import. The repository, the sync state and a "GitHub
comments" folder for that table's comments are kept on and under the
binding. "Not now" on those two screens removes a binding that has no
repository yet.

From then on it is the same sync as on the app's own table: compare on
open and on "Sync now", every change bound for GitHub held for review, the
same conflict rules, the baselines and issue numbers on the rows. Rows that
were in the table before stay local until "Publish to GitHub" on each
(#177 Q6). What differs from the app's own table:

- the table itself is never written: no rename after the repository, no
`classtype` change. A row grant never covers the table;
- rows are never deleted: a grant doesn't cover `destroy`, so for an issue
gone from GitHub only "Keep here only" is offered, and the banner says to
delete the row in the table;
- the grant is checked on every open, before every pass and before every
edit made in the app. Once it lapses (the view removed, the person who
gave it loses write access, the app's key changes, or someone revokes it
in the tab's menu), the app says syncing is paused and offers "Allow
editing again"; it sends nothing to GitHub and writes nothing meanwhile.
A row write the host refuses mid-pass for that reason shows the same
pause;
- the binding keeps its repository for good, like the app's own sync
resource: the table can't switch repositories.

Not verified: what an uninstall does with a binding; two tabs syncing the
same table (not guarded, as on the app's own table). Edits made in the
table while the app is closed are found only on its next open (#177 H6).

## Mock data for user testing

The mock proxy's github-issues fixture has a second, opt-in scenario for
Expand Down Expand Up @@ -483,12 +537,22 @@ local until "Publish to GitHub", its reviewed create, and moving it to
Blocked, which adds `atomic:blocked` on GitHub; then Disconnect GitHub and
connecting again through the host's "Use existing connection" with no
reload, after which the app syncs by itself (the unit tests also cover the
repository-picker case). The e2e reads `issue-v1` from its published GitHub
repository-picker case). A second e2e test (0.3.0) makes an `issue-v1`
table by hand with one row, adds GitHub issues to it as a Read-only view,
presses "Sync this table to GitHub", allows editing in the host's bar,
connects, imports a repository of its own (seeded through the mock's
`createIssue` driver), checks the rows, the untouched table and the binding
under the App, and sends a status edit made in the table after review. The
e2e reads `issue-v1` from its published GitHub
Pages subject, so it needs network access to `ontola.github.io`; its
`beforeAll` checks Pages serves the class first
(`node ontology-kit/served.mjs classes/issue-v1`). The 0.1.x in-place
rewrite, a status shown as it is and the "other table" notice are unit-tested
only (`app/controller.test.ts`).
rewrite and a status shown as it is are unit-tested only
(`app/controller.test.ts`), and so are, for another table
(`app/syncTable.test.ts`, against a fake host that enforces the pinned
row-grant scope): "Not now" in the host's bar, a grant from before the
extras were declared, Publish to GitHub, reopening, a revoked grant and
"Allow editing again", "Not now" before a repository, and no row deletion.

These check `adapter.ts`'s pagination, PR exclusion and mapping, the generic
event-to-JavaScript starter (`automation.test.ts`), the Todoist projection, and
Expand Down
13 changes: 8 additions & 5 deletions integrations/issue-tracker/app/build.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,17 @@ describe('GitHub issues drive-app bundle', async () => {
expect(Object.keys(mod)).toEqual(['view']);
expect(typeof mod.view).toBe('function');
// Stored as a string property on a resource; keep an eye on the size.
// Measured 154,931 bytes (151.3 KiB) on 2026-10-01 for 0.2.0, with the
// JS and the embedded stylesheets minified: the shared issue-v1 class,
// the bundled ontology-kit terms and resolver, Blocked, Publish to
// GitHub and baselines on the rows (#177 item 6). Earlier: 137,315 bytes
// Measured 160,628 bytes (156.9 KiB) on 2026-10-02 for 0.3.0, with the
// JS and the embedded stylesheets minified: 0.2.0 plus "Sync this table
// to GitHub" on another issue-v1 table (#177 item 14: the row grant,
// the binding under the App and its setup copy). Earlier: 154,931 bytes
// on 2026-10-01 for 0.2.0 (the shared issue-v1 class, the bundled
// ontology-kit terms and resolver, Blocked, Publish to GitHub and
// baselines on the rows, #177 item 6); 137,315 bytes
// on 2026-10-01 after resolving uncertain creates (#156); 125,472 bytes
// on 2026-09-24 for the designed board/list/detail UI (#89). The limit is
// the latest plus 10%, rounded up to the next KiB.
expect(bytes).toBeLessThan(167 * 1024);
expect(bytes).toBeLessThan(173 * 1024);
});

it('has no storage or network access of its own', () => {
Expand Down
7 changes: 5 additions & 2 deletions integrations/issue-tracker/app/controller.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ import {
DESCRIPTION,
IS_A,
ISSUE_V1,
LOCAL_ID,
NAME,
PARENT,
PROPERTIES,
Expand Down Expand Up @@ -542,6 +543,8 @@ group(
property(store, 'github-issue-number'),
property(store, 'github-source'),
property(store, 'github-sync-baseline'),
// The Bridge's create-recovery key on imported rows (since 0.3.0).
LOCAL_ID,
]);
expect(store.resources.get(TABLE)![CLASSTYPE]).toBe(ISSUE_V1);
// Idempotent: a second open writes neither again.
Expand Down Expand Up @@ -672,14 +675,14 @@ group(
]);
});

it('only shows a notice on an Issue table it did not make', async () => {
it('writes nothing on an Issue table it did not make before it is asked to sync it', async () => {
const store = fakeStore({ table: 'did:ad:someone-elses-table' });
store.resources.set('did:ad:someone-elses-table', {
[PARENT]: 'did:ad:drive',
[CLASSTYPE]: ISSUE_V1,
});
const state = await createController(store).start();
expect(state.kind).toBe('other-table');
expect(state).toEqual({ kind: 'other-table', canSync: true });
expect(store.writes).toEqual([]);
});
},
Expand Down
Loading
Loading