gcf-board 0.9.1 → 0.11.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 +112 -106
- package/dist/server/app.js +71 -12
- package/dist/server/atomic.js +24 -0
- package/dist/server/events.js +8 -9
- package/dist/server/files.js +30 -1
- package/dist/server/runs.js +293 -54
- package/dist/server/talks.js +3 -0
- package/dist/server/themes.js +75 -0
- package/dist/shared/board.js +8 -0
- package/dist/web/assets/index-9AdVt1Kf.js +39 -0
- package/dist/web/assets/index-xG2PuBXE.css +1 -0
- package/dist/web/index.html +2 -2
- package/node_modules/gcf-session/lib/activity.js +12 -4
- package/node_modules/gcf-session/lib/chat.js +2 -0
- package/node_modules/gcf-session/lib/thread.js +9 -6
- package/node_modules/gcf-session/package.json +1 -1
- package/node_modules/gcf-session/types/index.d.ts +4 -0
- package/package.json +2 -1
- package/dist/web/assets/index-UzVgbCWq.css +0 -1
- package/dist/web/assets/index-m10Wkvhe.js +0 -39
package/README.md
CHANGED
|
@@ -1,106 +1,112 @@
|
|
|
1
|
-
# gcf-board
|
|
2
|
-
|
|
3
|
-
A local web board for game projects on [GCF](../gcf-aif-ext): the items by status, the phase, WIP, the inbox, the playtest session, what was accepted and what was killed — and buttons that run the same `ai-factory gcf` commands an operator runs in a console. The board is a view: it stores nothing, and without it the work goes on in the console unchanged (Methodology §11).
|
|
4
|
-
|
|
5
|
-
## Requirements
|
|
6
|
-
|
|
7
|
-
- Node.js ≥ 22.18
|
|
8
|
-
- [`ai-factory`](https://www.npmjs.com/package/ai-factory) installed globally, and in each project [`gcf-aif-ext`](../gcf-aif-ext) ≥ 0.10 (`gcf board --json` with `schema: 3`: the columns, the moves, the item's fields, the blocks and the Help terms come from it as data)
|
|
9
|
-
- for runs: [`gcf-harness-aif-ext`](../gcf-harness-aif-ext) ≥ 0.11 (every board run opens its chat: `--chat`, `gcf-harness chat`; it waits the project's answer time) and Claude Code (`claude -p`); ≥ 0.12 to wait for the usage limit's reset and for queued runs (`--wait-limit`)
|
|
10
|
-
- for the project chat: `gcf-aif-ext` ≥ 0.12 (`domain.chat`, `agent.rules`) and Claude Code
|
|
11
|
-
- for
|
|
12
|
-
- gcf-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
gcf-board
|
|
20
|
-
gcf-board
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
- **
|
|
40
|
-
- **
|
|
41
|
-
- **
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
- a card
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
- **
|
|
55
|
-
- **
|
|
56
|
-
- **
|
|
57
|
-
- **
|
|
58
|
-
- **
|
|
59
|
-
- **
|
|
60
|
-
- **
|
|
61
|
-
- **
|
|
62
|
-
- **
|
|
63
|
-
- **
|
|
64
|
-
- **
|
|
65
|
-
- **
|
|
66
|
-
- **
|
|
67
|
-
- **
|
|
68
|
-
- **
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
The
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
-
|
|
81
|
-
-
|
|
82
|
-
-
|
|
83
|
-
- A
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
1
|
+
# gcf-board
|
|
2
|
+
|
|
3
|
+
A local web board for game projects on [GCF](../gcf-aif-ext): the items by status, the phase, WIP, the inbox, the playtest session, what was accepted and what was killed — and buttons that run the same `ai-factory gcf` commands an operator runs in a console. The board is a view: it stores nothing, and without it the work goes on in the console unchanged (Methodology §11).
|
|
4
|
+
|
|
5
|
+
## Requirements
|
|
6
|
+
|
|
7
|
+
- Node.js ≥ 22.18
|
|
8
|
+
- [`ai-factory`](https://www.npmjs.com/package/ai-factory) installed globally, and in each project [`gcf-aif-ext`](../gcf-aif-ext) ≥ 0.10 (`gcf board --json` with `schema: 3`: the columns, the moves, the item's fields, the blocks and the Help terms come from it as data)
|
|
9
|
+
- for runs: [`gcf-harness-aif-ext`](../gcf-harness-aif-ext) ≥ 0.11 (every board run opens its chat: `--chat`, `gcf-harness chat`; it waits the project's answer time) and Claude Code (`claude -p`); ≥ 0.12 to wait for the usage limit's reset and for queued runs (`--wait-limit`)
|
|
10
|
+
- for the project chat: `gcf-aif-ext` ≥ 0.12 (`domain.chat`, `agent.rules`) and Claude Code
|
|
11
|
+
- for 0.11: `gcf-aif-ext` ≥ 0.12.1 for **waiting for me** and the human columns of Command (an older core marks no column `human`: they stay empty); ≥ 0.15 names a session mark's life (`domain.session_ttl_min`; older: 120 minutes)
|
|
12
|
+
- for 0.10: `gcf-aif-ext` ≥ 0.14 for an item's attachments and the project's model and effort; `gcf-harness-aif-ext` ≥ 0.14 for the run gate's refusal before the click (an older one: the click is gated, as before)
|
|
13
|
+
- for board v2 (0.9): `gcf-aif-ext` ≥ 0.13 for an item's History, `needs`, the design units, filters and lanes; `gcf-harness-aif-ext` ≥ 0.13 for past runs and a run's model and effort. On older ones these hide or say which version they need
|
|
14
|
+
- gcf-board 0.2 needs `gcf-aif-ext` ≥ 0.7 (priority, questions, session marks, `run_mode`)
|
|
15
|
+
|
|
16
|
+
## Run
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm i -g gcf-board
|
|
20
|
+
gcf-board # http://127.0.0.1:4317
|
|
21
|
+
gcf-board --port 4400
|
|
22
|
+
gcf-board --version # the installed version
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
It opens the board in your browser (the URL with the token, `http://127.0.0.1:4317/?t=<token>`, is printed too; `--no-open` skips the browser). Started again while it runs, it just opens the running board. Add a project by its folder (one that has `gcf/`) under **Projects**.
|
|
26
|
+
|
|
27
|
+
**Desktop shortcut**: run once
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
gcf-board shortcut # or: gcf-board shortcut --port 4400
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
It puts **GCF Board** on the desktop (Windows: a shortcut whose server console starts minimized; macOS: `GCF Board.command`; Linux: an application entry). Double-click it: the board starts and opens, or opens if it already runs. Run the command again after moving Node.js.
|
|
34
|
+
|
|
35
|
+
## What it does
|
|
36
|
+
|
|
37
|
+
The board knows no domain by name: the project's board read gives its columns, moves with their forms, item fields, blocks and Help terms (`domain`, Board-PRD decision 16). The page follows design B (`docs/design/mockup`): a left nav with the project switcher (add a project, take one off the board), the screens **Command**, **Board**, **Chat**, **Inbox**, **Runs**, **Playtest**, **Ended**, **Agent**, **Settings** and **Metrics** (a domain without a block has no screen for it, a project without a harness no Runs and no Metrics), and a header with the phase, the runs, the limit wait, the quota, WIP, the release, **waiting for me**, **+ item** and **?**. The project and the screen are in the URL hash. On a phone a bottom bar holds Command, Board, Chat, Inbox and More. When the server is gone, the page says so and reconnects by itself. For a GCF project:
|
|
38
|
+
|
|
39
|
+
- **Command**: **waiting for me**, what only the operator moves on (Board-PRD §1.3), by group: failed run reports and a paused queue, a card waiting in a chat (a permission is answered right there, **Always** naming the rule it saves), D1 questions, the items to play and judge, to decide, to unblock (the columns the domain marks `human`), and a `paused: limit` item to resume. Beside it **Live**: the runs going on with their plan progress, **Follow** and **Stop**, the console runs and sessions, **Run next**, the queue, the run reports, and what the board did by itself.
|
|
40
|
+
- **Board**: columns ready, running, blocked, awaiting-verdict, awaiting-decision, unplayed, parked. A card shows the type, the gate, the plan progress (`2/5`), the severity, `verified`, the model, **needs N** and **needed by N**. A running card shows when its run log was last written (`active 12 s ago`), and `quiet 6 min` when the log has been silent for 5 minutes or more. A run's end report gives each item's cost when the agent reported it. Pointing at a card (or focusing it from the keyboard) lights up the cards it needs and the cards that need it, each saying how, and dims the rest. The toolbar (board 0.9.0, core 0.13.0) searches ids and titles, keeps **waiting for me**, filters by the fields the domain marks `filter` (GCF: type, gate, severity, system, milestone; several values at once, each a chip to take off) and lays the board out in lanes by a field it marks `group` (system, parent, milestone): an item with two systems stands in both lanes, one with none in **none**, a parent lane is named by the feature's title. The mouse drags the board sideways from its empty space; the wheel over a column with no scroll of its own pans it.
|
|
41
|
+
- **An item**: its file, its plan and its run log as it grows, its fields, and the moves the core offers for it (`items[].moves`, Methodology §4.1): run, verdict, decide, block, unblock, drop, close, submit, depends. Each move's form comes from the core; the core still checks the rest itself, and the board shows its answer. **Dependencies**: what it needs that has not ended in history (an item with its column, a design unit with its TBDs or the questions that block it, a graveyard line, an unknown id) and the items that need it, each a link; **Edit…** opens the picker of the board's items and design units (search by id and title, or type an id), and Save sends the `depends` move's adds and removes. **History** (core 0.13.0): its moves newest first, when, which, who (a run, your session, you; unknown on a commit older than the framework's marks), the commit and its subject; then its runs, as on the Runs screen. **Related**: its feature's other children, and the graveyard lines tagged with its system ("did we kill this before?"). An item that ended opens from **Ended** with its History.
|
|
42
|
+
- **Runs** (harness 0.13.0): what runs now with the run's model and effort, its last log lines, **Whole log** and **Stop**; the queue with what each item will run on; the past runs of the harness's run log, newest first, 50 at a time: start, end, mode, cost, and per item its result word, the reason word for word, cost, tokens, turns, handoffs, a broken step and what it ran on. **log** opens the part of the item's log that run wrote, **chat** that run's chat. Every start the operator asks for (Run selected, Run next, a drop on running, this screen) asks first with a model and effort picker for that run only (**default: each item's own**); the drawer's Run is one click. An older harness shows the active runs only, and the dialog has no pickers. The API: `GET /api/p/<project>/runs/past?limit=` (`gcf-harness runs --json`; 404 without a harness that keeps them), `GET …/item/<id>/history` (`{id, moves, runs}`), `GET …/log/<id>?from=&to=` (a past run's part, once: `{text, cut}`, at most its last 2 MB; without `from` and `to` the log as it grows), `POST …/run` with `model` and `effort`, `POST …/inbox/<entry>/draft` (`{thread, created}`).
|
|
43
|
+
- **Drag**:
|
|
44
|
+
- a ready card into **running** starts its run;
|
|
45
|
+
- a blocked or parked card into **ready** unblocks it;
|
|
46
|
+
- a card onto **graveyard** drops it.
|
|
47
|
+
|
|
48
|
+
Every other move is a button.
|
|
49
|
+
- **Run**: **run** on an item, or select ready cards and **Run selected**. It starts `ai-factory gcf-harness run <ids> --json` in the project's run mode:
|
|
50
|
+
- `run_mode: worktree`: one worktree and one agent session per item, all at once, then the integrator;
|
|
51
|
+
- `run_mode: main`: one item at a time in the project folder. A run asked for meanwhile waits in the board's **queue**; **remove from queue** takes it out.
|
|
52
|
+
|
|
53
|
+
A run asks first: it spends the subscription. **Stop** on a running item ends its session; the item stays ready and its work is kept. **Stop** during the wait for the usage limit's reset leaves the item **paused: limit** with its reset, and the queue goes on. A queued main run that the next one would repeat (the harness did not start, or another run works the checkout) pauses the queue: the header shows **queue paused — resume**; fix the cause, then resume. A card marked **interrupted** had a run that stopped (a timeout, a stop, a crash, the usage limit): **resume** continues its agent session with all its context, **start fresh** drops it. After the usage limit the run itself waits for the reset and goes on in the same session (harness 0.12): the card reads **limit: resumes HH:MM**, and **Stop** ends the wait. A run that could not wait (the week's limit, an unknown reset) ends **paused: limit** and pauses the main queue; **resume** on the header goes on after the reset. When a run ends, a report card lists each item's result and stays until closed, across page reloads. **What the board did by itself** lists its automatic acts with their times: a usage limit, a context handoff, the queue paused, resumed or started. A run confirmation names what each interrupted item picks up. The header shows the usage limit as the last run read it, from the newest `.gcf-session/runs/quota.json` of the board's projects: `quota 19% left · resets 03:00`, the window with the least left, every window in its tooltip; `quota ?` before any reading, or once every window has reset since. The queue, its pause, the reports and that list live in the board home too (`~/.gcf/queue.json`, board 0.10): a board started again goes on with them. It first takes in its runs; then a queue not paused, with no main run going, goes on (`queue-restored` in the list); a run that died while the board was down (a restart of the machine) pauses it, and a limit's pause shows its reset time. Two boards on one home both go on with the same queue: start one. A run itself outlives the board: closing it or Ctrl+C in its console leaves the run going, and the board started again shows it running, then its report (a run in flight keeps its record in `~/.gcf/runs/`).
|
|
54
|
+
- **Who runs it** (core 0.7.13): a running card tells a console run and **your session** (a `gcf claim` mark) from the board's own run; a session offers **release mark** instead of **stop**. A ready card whose dependencies are not built yet shows **waits for <dep>**; the drawer shows when an item began to wait (`since_at`).
|
|
55
|
+
- **Run next N independent**: the framework's gate picks the ready items that can run together now, by priority, and the board runs them after asking.
|
|
56
|
+
- **Priority**: drop a ready card on another to put it before; the column's ranks are committed (`gcf prioritize`).
|
|
57
|
+
- **Questions**: each D1 shows its question and proposed answer; **Answer** writes yours into its record (`gcf question answer`), and the next agent on its units puts it in place.
|
|
58
|
+
- **New item**: `gcf item new … --commit`, its form from the core: a bug asks its severity, a release its version and channel. The item's `model` and `effort` go to its run.
|
|
59
|
+
- **Help** (**?**): the domain's terms, columns, moves and field values with what each means, and the words of runs, under one filter.
|
|
60
|
+
- **Settings**: the keys of `gcf/config.yml` and the agents' language (`language.ui`, `language.artifacts` of `.ai-factory/config.yaml`), by the core's groups, each a `gcf config set` commit.
|
|
61
|
+
- **Theme** (board 0.11.0, Board-PRD decision 26): Settings, "Board · this browser": **Dark (built-in)** or a theme file of `~/.gcf/themes/<id>.json` — `{"gcf_theme": 1, "name", "scheme": "light" | "dark", "tokens": {…}}`, the colour tokens of `web/tokens.css` without `--gcf-` over the built-in dark (a template: docs/design/theme-sample.json). Each browser keeps its own choice; a file that cannot be read is listed with its reason, and the page falls back to dark when the chosen one is gone. Reload the page after changing a file. `GET /api/themes` lists the files.
|
|
62
|
+
- **Agent**: the deny groups to tick, the rules the ticked groups add, the operator's own deny rules (add, remove) and the allow rules of `agent.allow`, apart; the context limits, read only.
|
|
63
|
+
- **An item's chat** (its drawer's **Chat** tab; harness 0.11.1, core 0.11.1): every run the board starts keeps its agent sessions open; the project's `chat:` settings (Settings: `chat.ask`, `chat.answer_timeout_min`) say what the agent asks and how long a question waits. The tab shows the run's chat, then the item's own thread of the project chat: the talk, question cards (picks, several questions, **Submit**), the run's milestones, its sessions, the limit wait, the context share. A message goes where the server puts it: the live run (its limit wait too), else the item's thread, and the line under the box says where it went. `GET /api/p/<project>/chat/<id>` follows the item's chat from its start, in raw chunks of JSON lines (the page splits them). `POST` there sends `{type: 'say', text, images?, attach?}`, `{type: 'interrupt'}` or `{type: 'answer', request_id, answers}` through `gcf-harness chat`; with no live run a message goes to the item's thread (answer `{talk}`), else a message with no session to read it gets 409, bad input 400. `attach` (`[{kind: item | unit | file, ref}]`) goes into the message's text as a line the agent reads; a design unit (the composer's **+ unit**, from the board read's `units`) goes as `unit <id> (<file>)`. `GET /api/p/<project>/chat/<id>/att/<file>` serves a chat picture; **attach to item…** under a picture gives it to an item (`gcf item attach`).
|
|
64
|
+
- **Functional base A** (board 0.10.0, core and harness 0.14.0; docs/Base-A-Plan.md): Settings has `session_timeout_min` and the project's `agent.model` / `agent.effort` (suggested from the agent's presets); the drawer shows the project's model on an item without its own, "(project)". The drawer's Run is off with the run gate's reason when the gate refuses the item now, and the start dialog marks each refused item and runs the rest (`GET /api/p/<project>/gate?ids=` runs `gcf-harness gate --each`). An item's attachments and an inbox entry's pictures are links (`GET /api/p/<project>/attachment?path=`: only `gcf/work/<id>/attachments/` and `gcf/inbox/in-<hex>/attachments/`, no `..`, no link on the way, a picture shown, any other file a download, `nosniff` and `default-src 'none'`), and a picture or link in File or Plan that points there loads through it. A permission card for one MCP tool offers Always, saying it allows every call of the tool with any arguments.
|
|
65
|
+
- **Model and effort** (board 0.8.0, core 0.12.3): pickers in the New item form, in the drawer (**change** beside the model and effort, and **model / effort** under **More**) and in a thread's composer: **default** (the agent picks), the agent's presets, or an own word. An item's next run takes them; a thread's next session does (`chats/<t>/agent.json`), and its line in the chat says so.
|
|
66
|
+
- **Project chat** (the **Chat** screen; core 0.12): threads of an agent in the project's folder, listed newest first and filtered by their item; a new thread is made when its first message is sent. Each thread is run by the bundled session engine (`gcf-session`) through the same detached relay as runs. It asks a card before each edit, git command and framework move (**allow once**, **always** — saved in `.claude/settings.local.json`; the card says saved only when it was — or **deny**); a new item it proposes through the board's MCP server `gcf` (tool `propose_item_new`, asked with no card: the proposal card is the question), the proposal card shows every field it proposed, and the operator's **Create** makes it with `POST /move` (`proposal: {talk, id}`), **Edit…** first in the new-item form. A thread's list entry names the card that waits in it and its limit wait (`card`, `limit_until`); a running item names the card of its run's chat (`chat_card`). A long talk hands over to a fresh agent from a summary; an idle agent closes after `chat.answer_timeout_min` (0 means 15) and the next message resumes it. Each item has at most one thread: a message to an item with no live run goes there. `GET /api/p/<project>/talks[?item=]` lists the threads with their proposals' states; `POST` there makes one (`{item?}`); `GET /api/p/<project>/talk/<t>` follows a thread's events; `POST` there sends `say`, `interrupt`, `answer`, `allow`, `deny` or `handoff`; `POST …/talk/<t>/stop` is the composer's **close agent** (board 0.8.1): the thread's agent ends with everything it started, or its limit wait does, and what it had not taken in is dropped with a "not sent" line; the next message resumes the talk; `GET …/talk/<t>/att/<file>` serves its pictures. The files live in `.gcf-session/chats/` (docs/Chat-Plan.md §3).
|
|
67
|
+
- **Inbox**: add an entry (Enter adds, Shift+Enter breaks the line; its source and tags), tag it, erase it, or turn it into an item (its first line the title, the rest the note); search the entries, filter them by tag and by lesson kind. The D1 questions and the agent's D2 assumptions are listed there too. **Draft with agent** opens a project chat thread bound to the entry and sends "Draft an item from inbox entry <id>:" with its text; a second click opens the same thread. The first proposal's **Create** takes the entry (it is erased); a later one makes an item with no entry. Off while the usage limit holds.
|
|
68
|
+
- **Keys**: `/` search, `i` a new inbox entry, `n` a new item, `j` / `k` between cards, Enter opens one, `r` runs the focused card (it asks), `1`–`7` a column, `?` Help, Esc closes a dialog, Help or the drawer; none while a field has the focus.
|
|
69
|
+
- **Lessons** (core 0.7.10, harness 0.9.2): what got in an agent's way, asked at the end of each session, lands in the inbox with its kind (`tool`, `rules`, `framework`, `template`, `other`) and its item. The inbox filters them; a card shows `N lessons`, and the drawer lists the item's lessons with the inbox's buttons. A run's report line ends with `, N lessons`, and with `— code written outside aif-implement` when a session skipped that skill.
|
|
70
|
+
- **Playtest**: `gcf playtest session` with the checklist grouped by subsystem; keep, tune or kill each item from the list. **Build** runs `dod.build`. A note goes to the inbox as `--source playtest`.
|
|
71
|
+
- **Ended**: history (accepted) and graveyard (killed, dropped, won't-fix); a line opens the item's History.
|
|
72
|
+
- **Metrics**: `gcf-harness metrics --json` of the project — how many runs reached submit or close, what they cost, handoffs, plan checks, DoD attempts, guard firings, block reasons — and, with harness 0.9.5, the cost per item over all its runs and per week and day.
|
|
73
|
+
|
|
74
|
+
The page updates by itself: the server watches each project's `gcf/` and `.gcf-session/runs/`.
|
|
75
|
+
|
|
76
|
+
## Security
|
|
77
|
+
|
|
78
|
+
The board starts agents that write code and commit: whoever can talk to it runs code on this machine.
|
|
79
|
+
|
|
80
|
+
- It listens on `127.0.0.1` only.
|
|
81
|
+
- The token, kept in `~/.gcf/board-token`, opens the board once per server start; delete that file to make a new one. The browser then holds a session cookie that dies with the server: a browser sends a `127.0.0.1` cookie to every local port, so the cookie is never the token.
|
|
82
|
+
- Started while another program holds its port, it refuses rather than hand the token to that program.
|
|
83
|
+
- A request must also name host `127.0.0.1` or `localhost` with the board's port.
|
|
84
|
+
- A change must come from the board's own page (`Origin`). This blocks another site in the same browser.
|
|
85
|
+
- Commands run without a shell: the operator's text reaches `ai-factory` as one argument, never as a command line.
|
|
86
|
+
- The API shows only item files, plans and run logs inside a project.
|
|
87
|
+
- A project chat's agent may not read the board's folder (`~/.gcf`, the token's): not by read, search or a shell command that names it. A command that spells the path another way still could; a separate secret for a card's answer comes with remote access.
|
|
88
|
+
|
|
89
|
+
Do not put the port on a network. Remote and phone access is planned for v2, behind its own authentication.
|
|
90
|
+
|
|
91
|
+
## Files
|
|
92
|
+
|
|
93
|
+
- `~/.gcf/projects.json`: the projects on the board, `{projects: [{name, path}]}`.
|
|
94
|
+
- `~/.gcf/board-token`: the token.
|
|
95
|
+
- `~/.gcf/runs/`: the record of each run in flight, which a board started again finds; a board's start drops the ended runs of projects no longer on it.
|
|
96
|
+
- `~/.gcf/themes/`: the theme files.
|
|
97
|
+
- `GCF_BOARD_HOME` moves them all; `GCF_BOARD_AIF` points at another `ai-factory` entry script; `GCF_SESSION_AGENT` puts another agent command in place of `claude` in project chats (tests).
|
|
98
|
+
|
|
99
|
+
## Roadmap (v2)
|
|
100
|
+
|
|
101
|
+
- **Phone and remote access**: Tailscale or Claude Remote Control, with their own authentication; push notifications when an item blocks or waits for a verdict.
|
|
102
|
+
|
|
103
|
+
## Develop
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
npm install
|
|
107
|
+
npx playwright install chromium # once: the browser the browser scenarios use
|
|
108
|
+
npm test # server and web tests on Node's type stripping; the browser scenarios need npm run build first
|
|
109
|
+
npm run typecheck
|
|
110
|
+
npm run build # vite → dist/web, tsc → dist/server
|
|
111
|
+
node dist/server/main.js --port 4318
|
|
112
|
+
```
|
package/dist/server/app.js
CHANGED
|
@@ -6,20 +6,22 @@
|
|
|
6
6
|
import { execFile } from 'node:child_process';
|
|
7
7
|
import { randomBytes } from 'node:crypto';
|
|
8
8
|
import { createServer } from 'node:http';
|
|
9
|
-
import { existsSync, statSync, writeFileSync } from 'node:fs';
|
|
10
|
-
import { lstat, mkdtemp, readFile, rm } from 'node:fs/promises';
|
|
9
|
+
import { createReadStream, existsSync, statSync, writeFileSync } from 'node:fs';
|
|
10
|
+
import { lstat, mkdtemp, readFile, rm, stat } from 'node:fs/promises';
|
|
11
|
+
import { pipeline } from 'node:stream/promises';
|
|
11
12
|
import os from 'node:os';
|
|
12
13
|
import path from 'node:path';
|
|
13
14
|
import { BOARD_SCHEMA, } from '../shared/board.js';
|
|
14
15
|
import { admit, cookieName, hostAllowed, tokenInUrl } from './auth.js';
|
|
15
16
|
import { briefError, runCli } from './cli.js';
|
|
16
|
-
import { broadcast, planRev, subscribe, watchProject } from './events.js';
|
|
17
|
+
import { broadcast, planRev, SESSION_TTL_MIN, subscribe, watchProject } from './events.js';
|
|
17
18
|
import { attachesUnit, CHAT_BODY_MAX, chatInput, IMAGE_EXT, talkInput, } from './chat.js';
|
|
18
|
-
import { follow, followLog, logPart, readShown, shownShape } from './files.js';
|
|
19
|
+
import { attachmentOf, follow, followLog, logPart, readShown, shownShape } from './files.js';
|
|
19
20
|
import { HttpError } from './http-error.js';
|
|
20
21
|
import { isCenterMove, moveArgs, moveInput, runIds } from './moves.js';
|
|
21
22
|
import { addProject, listProjects, projectOf, removeProject } from './registry.js';
|
|
22
|
-
import {
|
|
23
|
+
import { readThemes } from './themes.js';
|
|
24
|
+
import { adoptRuns, keepProjects, sweepRuns, closeReport, forgetProject, resumeQueue, runsOf, startRun, unqueue, } from './runs.js';
|
|
23
25
|
import { acceptProposal, agentPresets, chatCard, chatOf, entryTalk, listTalks, openTalk, pickTalk, prepareTalk, startTalk, stopTalk, talkEntry, talkId, talkLive, talkSaid, talkWaits, watchTalks, writeTalk, } from './talks.js';
|
|
24
26
|
import { threadDir, threadOfEntry } from 'gcf-session';
|
|
25
27
|
const send = (res, status, body) => {
|
|
@@ -47,6 +49,23 @@ async function bodyOf(req, limit = 1_000_000) {
|
|
|
47
49
|
throw new HttpError(400, 'the body must be a JSON object');
|
|
48
50
|
}
|
|
49
51
|
}
|
|
52
|
+
/**
|
|
53
|
+
* A file of the project, never read as a page: no type sniffing, no script, no fetch from it;
|
|
54
|
+
* streamed, as an attachment may be large. `disposition`: a download's, for one not a picture.
|
|
55
|
+
*/
|
|
56
|
+
async function sendFile(res, type, file, disposition = null) {
|
|
57
|
+
const { size } = await stat(file);
|
|
58
|
+
res.writeHead(200, {
|
|
59
|
+
'content-type': type,
|
|
60
|
+
'content-length': size,
|
|
61
|
+
'cache-control': 'private',
|
|
62
|
+
'x-content-type-options': 'nosniff',
|
|
63
|
+
'content-security-policy': "default-src 'none'",
|
|
64
|
+
...(disposition ? { 'content-disposition': disposition } : {}),
|
|
65
|
+
});
|
|
66
|
+
// A read that breaks after the head is sent can only cut the answer short.
|
|
67
|
+
await pipeline(createReadStream(file), res).catch(() => res.destroy());
|
|
68
|
+
}
|
|
50
69
|
/** Parse the JSON a command printed, or say what it printed instead. */
|
|
51
70
|
function jsonOf(r, what) {
|
|
52
71
|
try {
|
|
@@ -142,13 +161,16 @@ export function createApp(o) {
|
|
|
142
161
|
let closed = false;
|
|
143
162
|
const watchAll = async () => {
|
|
144
163
|
const projects = await listProjects();
|
|
164
|
+
// The kept queues of projects no longer on the board go: one added back starts empty.
|
|
165
|
+
keepProjects(projects.map((p) => p.name));
|
|
166
|
+
sweepRuns(projects);
|
|
145
167
|
// A watcher set up after the server closed would keep the process alive.
|
|
146
168
|
if (closed)
|
|
147
169
|
return;
|
|
148
170
|
for (const p of projects)
|
|
149
171
|
if (!watchers.has(p.name)) {
|
|
150
172
|
const stops = [
|
|
151
|
-
watchProject(p),
|
|
173
|
+
watchProject(p, undefined, () => domains.get(p.name)?.session_ttl_min ?? SESSION_TTL_MIN),
|
|
152
174
|
watchTalks(p, () => broadcast({ type: 'talks', project: p.name }), async (t) => prepareTalk(p, await boardOf(p), t)),
|
|
153
175
|
];
|
|
154
176
|
watchers.set(p.name, () => stops.forEach((stop) => stop()));
|
|
@@ -157,6 +179,8 @@ export function createApp(o) {
|
|
|
157
179
|
}
|
|
158
180
|
};
|
|
159
181
|
const cli = (p, args, timeout, input) => runCli(o.entry, p.path, args, timeout, input);
|
|
182
|
+
// The run gate's answers being worked out, by project and ids (GET …/gate).
|
|
183
|
+
const gates = new Map();
|
|
160
184
|
// The last domain each project's board read gave: an item move is built from its form.
|
|
161
185
|
const domains = new Map();
|
|
162
186
|
/**
|
|
@@ -238,6 +262,7 @@ export function createApp(o) {
|
|
|
238
262
|
const routes = [
|
|
239
263
|
['GET', /^\/api\/events$/, async (_req, res) => subscribe(res)],
|
|
240
264
|
['GET', /^\/api\/projects$/, async (_req, res) => send(res, 200, await listProjects())],
|
|
265
|
+
['GET', /^\/api\/themes$/, async (_req, res) => send(res, 200, await readThemes())],
|
|
241
266
|
[
|
|
242
267
|
'POST',
|
|
243
268
|
/^\/api\/projects$/,
|
|
@@ -344,12 +369,47 @@ export function createApp(o) {
|
|
|
344
369
|
const file = path.join(att, m[3]);
|
|
345
370
|
for (const f of [session, path.dirname(att), att, file]) {
|
|
346
371
|
const st = await lstat(f).catch(() => null);
|
|
347
|
-
if (!st || st.isSymbolicLink())
|
|
372
|
+
if (!st || st.isSymbolicLink() || (f === file && !st.isFile()))
|
|
348
373
|
throw new HttpError(404, `no picture ${m[3]}`);
|
|
349
374
|
}
|
|
350
375
|
const type = m[4] === 'jpg' ? 'jpeg' : m[4];
|
|
351
|
-
res
|
|
352
|
-
|
|
376
|
+
await sendFile(res, `image/${type}`, file);
|
|
377
|
+
},
|
|
378
|
+
],
|
|
379
|
+
[
|
|
380
|
+
// A file given to an item or an inbox entry (`gcf item attach`, an entry's pictures).
|
|
381
|
+
'GET',
|
|
382
|
+
/^\/api\/p\/([^/]+)\/attachment$/,
|
|
383
|
+
async (_req, res, m, url) => {
|
|
384
|
+
const p = await projectOf(m[1]);
|
|
385
|
+
const rel = url.searchParams.get('path') ?? '';
|
|
386
|
+
const { file, type, download } = await attachmentOf(p.path, rel);
|
|
387
|
+
// RFC 5987: encodeURIComponent leaves ' ( ) * and ! as they are.
|
|
388
|
+
const name = encodeURIComponent(path.basename(file)).replace(/['()*!]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
|
|
389
|
+
await sendFile(res, type, file, download ? `attachment; filename*=UTF-8''${name}` : null);
|
|
390
|
+
},
|
|
391
|
+
],
|
|
392
|
+
[
|
|
393
|
+
// The run gate of each named item (none: every ready one) alone now (Board-PRD §5.3):
|
|
394
|
+
// what a Run would be refused for, before the click. An older harness: nothing known.
|
|
395
|
+
'GET',
|
|
396
|
+
/^\/api\/p\/([^/]+)\/gate$/,
|
|
397
|
+
async (_req, res, m, url) => {
|
|
398
|
+
const p = await projectOf(m[1]);
|
|
399
|
+
const names = (url.searchParams.get('ids') ?? '').split(',').filter(Boolean);
|
|
400
|
+
const ids = names.length ? runIds({ ids: names }) : [];
|
|
401
|
+
const harness = await harnessOf(p);
|
|
402
|
+
// One audit for the same question at once: a drawer and a dialog may ask together.
|
|
403
|
+
const key = `${p.name}/${ids.join(',')}`;
|
|
404
|
+
let asked = gates.get(key);
|
|
405
|
+
if (!asked) {
|
|
406
|
+
asked = cli(p, [harness, 'gate', '--each', ...ids, '--json']).finally(() => gates.delete(key));
|
|
407
|
+
gates.set(key, asked);
|
|
408
|
+
}
|
|
409
|
+
const r = await asked;
|
|
410
|
+
if (!r.ok && /unknown option '--each'/.test(r.err))
|
|
411
|
+
return send(res, 200, { items: {} });
|
|
412
|
+
send(res, 200, jsonOf(r, `${harness} gate --each`));
|
|
353
413
|
},
|
|
354
414
|
],
|
|
355
415
|
[
|
|
@@ -502,12 +562,11 @@ export function createApp(o) {
|
|
|
502
562
|
const chats = path.dirname(td);
|
|
503
563
|
for (const f of [path.dirname(chats), chats, td, path.dirname(file), file]) {
|
|
504
564
|
const st = await lstat(f).catch(() => null);
|
|
505
|
-
if (!st || st.isSymbolicLink())
|
|
565
|
+
if (!st || st.isSymbolicLink() || (f === file && !st.isFile()))
|
|
506
566
|
throw new HttpError(404, `no picture ${m[3]}`);
|
|
507
567
|
}
|
|
508
568
|
const type = m[4] === 'jpg' ? 'jpeg' : m[4];
|
|
509
|
-
res
|
|
510
|
-
res.end(await readFile(file));
|
|
569
|
+
await sendFile(res, `image/${type}`, file);
|
|
511
570
|
},
|
|
512
571
|
],
|
|
513
572
|
[
|
package/dist/server/atomic.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { renameSync, rmSync, writeFileSync } from 'node:fs';
|
|
1
2
|
import { rename, writeFile } from 'node:fs/promises';
|
|
2
3
|
/** Write a file whole or not at all: a crash mid-write leaves the old one, never a torn one. */
|
|
3
4
|
export async function writeAtomic(file, text, mode) {
|
|
@@ -5,3 +6,26 @@ export async function writeAtomic(file, text, mode) {
|
|
|
5
6
|
await writeFile(tmp, text, { mode });
|
|
6
7
|
await rename(tmp, file);
|
|
7
8
|
}
|
|
9
|
+
// What a rename over a file another process holds open meets on Windows (a scanner, an indexer).
|
|
10
|
+
const HELD = new Set(['EPERM', 'EACCES', 'EBUSY']);
|
|
11
|
+
/**
|
|
12
|
+
* The same, at once: for state written as it changes, where two writes must not interleave. A
|
|
13
|
+
* file held for a moment is tried again for up to half a second; then the error goes up and the
|
|
14
|
+
* temporary file goes.
|
|
15
|
+
*/
|
|
16
|
+
export function writeAtomicSync(file, text) {
|
|
17
|
+
const tmp = `${file}.${process.pid}.tmp`;
|
|
18
|
+
writeFileSync(tmp, text);
|
|
19
|
+
for (let i = 0;; i++)
|
|
20
|
+
try {
|
|
21
|
+
renameSync(tmp, file);
|
|
22
|
+
return;
|
|
23
|
+
}
|
|
24
|
+
catch (e) {
|
|
25
|
+
if (!HELD.has(e.code ?? '') || i >= 10) {
|
|
26
|
+
rmSync(tmp, { force: true });
|
|
27
|
+
throw e;
|
|
28
|
+
}
|
|
29
|
+
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
|
|
30
|
+
}
|
|
31
|
+
}
|
package/dist/server/events.js
CHANGED
|
@@ -25,10 +25,9 @@ export function broadcast(event) {
|
|
|
25
25
|
for (const c of clients)
|
|
26
26
|
c.write(line);
|
|
27
27
|
}
|
|
28
|
-
//
|
|
29
|
-
//
|
|
30
|
-
|
|
31
|
-
const SESSION_TTL_MS = 120 * 60_000;
|
|
28
|
+
// Minutes a session mark stays fresh before the project's board read names its own
|
|
29
|
+
// (`domain.session_ttl_min`, core 0.15), and with a core older than that.
|
|
30
|
+
export const SESSION_TTL_MIN = 120;
|
|
32
31
|
const LOG_STEP_MS = 10_000;
|
|
33
32
|
export const alive = (pid) => {
|
|
34
33
|
if (!Number.isInteger(pid) || pid <= 0)
|
|
@@ -46,7 +45,7 @@ export const alive = (pid) => {
|
|
|
46
45
|
* lives, whether each session mark is fresh; and how recently each run log was written. A run
|
|
47
46
|
* that died or a session that expired changes it with no file written.
|
|
48
47
|
*/
|
|
49
|
-
export function runsState(dir, now = Date.now()) {
|
|
48
|
+
export function runsState(dir, ttlMin = SESSION_TTL_MIN, now = Date.now()) {
|
|
50
49
|
let names;
|
|
51
50
|
try {
|
|
52
51
|
names = readdirSync(dir).sort();
|
|
@@ -61,7 +60,7 @@ export function runsState(dir, now = Date.now()) {
|
|
|
61
60
|
if (n.endsWith('.lock'))
|
|
62
61
|
return `${n} ${alive(Number(readFileSync(file, 'utf8').split('\n')[0]))}`;
|
|
63
62
|
if (n.endsWith('.session'))
|
|
64
|
-
return `${n} ${now - statSync(file).mtimeMs <
|
|
63
|
+
return `${n} ${now - statSync(file).mtimeMs < ttlMin * 60_000}`;
|
|
65
64
|
// A session writes its log many times a second: its card's activity time moves by steps
|
|
66
65
|
// of LOG_STEP_MS, each one a board read, not one per line.
|
|
67
66
|
if (n.endsWith('.log'))
|
|
@@ -84,7 +83,7 @@ export const planRev = (project) => planRevs.get(project) ?? 0;
|
|
|
84
83
|
* runs directory may not exist yet, so it is polled, not watched. Bursts of writes make one
|
|
85
84
|
* event. Returns the stop.
|
|
86
85
|
*/
|
|
87
|
-
export function watchProject(p, debounceMs = 300) {
|
|
86
|
+
export function watchProject(p, debounceMs = 300, ttlMin = () => SESSION_TTL_MIN) {
|
|
88
87
|
let timer = null;
|
|
89
88
|
const fire = () => {
|
|
90
89
|
if (timer)
|
|
@@ -112,7 +111,7 @@ export function watchProject(p, debounceMs = 300) {
|
|
|
112
111
|
fire();
|
|
113
112
|
});
|
|
114
113
|
const runs = path.join(p.path, '.gcf-session', 'runs');
|
|
115
|
-
let last = runsState(runs);
|
|
114
|
+
let last = runsState(runs, ttlMin());
|
|
116
115
|
const quotaAt = () => {
|
|
117
116
|
try {
|
|
118
117
|
return statSync(path.join(runs, 'quota.json')).mtimeMs;
|
|
@@ -123,7 +122,7 @@ export function watchProject(p, debounceMs = 300) {
|
|
|
123
122
|
};
|
|
124
123
|
let read = quotaAt();
|
|
125
124
|
const poll = setInterval(() => {
|
|
126
|
-
const now = runsState(runs);
|
|
125
|
+
const now = runsState(runs, ttlMin());
|
|
127
126
|
if (now !== last)
|
|
128
127
|
fire();
|
|
129
128
|
last = now;
|
package/dist/server/files.js
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
// The files a board shows: an item, its plan, its run log. Only those shapes (or a plan an item
|
|
2
2
|
// links), only inside the project, symlinks resolved: the API is not a way to read the disk.
|
|
3
|
-
import { realpath, readFile, stat, open } from 'node:fs/promises';
|
|
3
|
+
import { lstat, realpath, readFile, stat, open } from 'node:fs/promises';
|
|
4
4
|
import path from 'node:path';
|
|
5
5
|
import { StringDecoder } from 'node:string_decoder';
|
|
6
|
+
import { attachedShape } from '../shared/board.js';
|
|
6
7
|
import { HttpError } from './http-error.js';
|
|
7
8
|
import { openStream } from './events.js';
|
|
8
9
|
const SHOWN = [
|
|
@@ -119,3 +120,31 @@ export function follow(root, file, res, whole) {
|
|
|
119
120
|
const timer = setInterval(tick, 1000);
|
|
120
121
|
res.on('close', () => clearInterval(timer));
|
|
121
122
|
}
|
|
123
|
+
const PICTURE = /\.(png|jpe?g|gif|webp)$/i;
|
|
124
|
+
/**
|
|
125
|
+
* An attachment of the project to hand out: its absolute path, its type, and whether it goes as
|
|
126
|
+
* a download. Refused, as a 404: a path of another place, one with `..`, a backslash, a drive or
|
|
127
|
+
* a stream (`:`), a NUL, or a link (a junction too) anywhere on it from the project's root, and
|
|
128
|
+
* one that resolves outside the project. A picture shows (svg is none: it may hold a script);
|
|
129
|
+
* any other file goes as a download. A hard link is not seen: it is the file it names.
|
|
130
|
+
*/
|
|
131
|
+
export async function attachmentOf(root, rel) {
|
|
132
|
+
const no = () => new HttpError(404, `no attachment ${rel}`);
|
|
133
|
+
if (!attachedShape(rel) || /[\\:\0]/.test(rel))
|
|
134
|
+
throw no();
|
|
135
|
+
const parts = rel.split('/');
|
|
136
|
+
if (parts.some((s) => s === '' || s === '.' || s === '..'))
|
|
137
|
+
throw no();
|
|
138
|
+
for (let i = 1; i <= parts.length; i++) {
|
|
139
|
+
const st = await lstat(path.join(root, ...parts.slice(0, i))).catch(() => null);
|
|
140
|
+
if (!st || st.isSymbolicLink() || (i === parts.length && !st.isFile()))
|
|
141
|
+
throw no();
|
|
142
|
+
}
|
|
143
|
+
const file = path.join(root, ...parts);
|
|
144
|
+
if (!(await inside(root, file)))
|
|
145
|
+
throw no();
|
|
146
|
+
const ext = PICTURE.exec(rel)?.[1].toLowerCase();
|
|
147
|
+
return ext
|
|
148
|
+
? { file, type: `image/${ext === 'jpg' ? 'jpeg' : ext}`, download: false }
|
|
149
|
+
: { file, type: 'application/octet-stream', download: true };
|
|
150
|
+
}
|