gcf-board 0.10.0 → 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 CHANGED
@@ -8,6 +8,7 @@ A local web board for game projects on [GCF](../gcf-aif-ext): the items by statu
8
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
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
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)
11
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)
12
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
13
14
  - gcf-board 0.2 needs `gcf-aif-ext` ≥ 0.7 (priority, questions, session marks, `run_mode`)
@@ -57,6 +58,7 @@ The board knows no domain by name: the project's board read gives its columns, m
57
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.
58
59
  - **Help** (**?**): the domain's terms, columns, moves and field values with what each means, and the words of runs, under one filter.
59
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.
60
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.
61
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`).
62
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.
@@ -90,7 +92,8 @@ Do not put the port on a network. Remote and phone access is planned for v2, beh
90
92
 
91
93
  - `~/.gcf/projects.json`: the projects on the board, `{projects: [{name, path}]}`.
92
94
  - `~/.gcf/board-token`: the token.
93
- - `~/.gcf/runs/`: the record of each run in flight, which a board started again finds.
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.
94
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).
95
98
 
96
99
  ## Roadmap (v2)
@@ -101,7 +104,8 @@ Do not put the port on a network. Remote and phone access is planned for v2, beh
101
104
 
102
105
  ```bash
103
106
  npm install
104
- npm test # server and web tests on Node's type stripping
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
105
109
  npm run typecheck
106
110
  npm run build # vite → dist/web, tsc → dist/server
107
111
  node dist/server/main.js --port 4318
@@ -14,13 +14,14 @@ import path from 'node:path';
14
14
  import { BOARD_SCHEMA, } from '../shared/board.js';
15
15
  import { admit, cookieName, hostAllowed, tokenInUrl } from './auth.js';
16
16
  import { briefError, runCli } from './cli.js';
17
- import { broadcast, planRev, subscribe, watchProject } from './events.js';
17
+ import { broadcast, planRev, SESSION_TTL_MIN, subscribe, watchProject } from './events.js';
18
18
  import { attachesUnit, CHAT_BODY_MAX, chatInput, IMAGE_EXT, talkInput, } from './chat.js';
19
19
  import { attachmentOf, follow, followLog, logPart, readShown, shownShape } from './files.js';
20
20
  import { HttpError } from './http-error.js';
21
21
  import { isCenterMove, moveArgs, moveInput, runIds } from './moves.js';
22
22
  import { addProject, listProjects, projectOf, removeProject } from './registry.js';
23
- import { adoptRuns, keepProjects, closeReport, forgetProject, resumeQueue, runsOf, startRun, unqueue, } from './runs.js';
23
+ import { readThemes } from './themes.js';
24
+ import { adoptRuns, keepProjects, sweepRuns, closeReport, forgetProject, resumeQueue, runsOf, startRun, unqueue, } from './runs.js';
24
25
  import { acceptProposal, agentPresets, chatCard, chatOf, entryTalk, listTalks, openTalk, pickTalk, prepareTalk, startTalk, stopTalk, talkEntry, talkId, talkLive, talkSaid, talkWaits, watchTalks, writeTalk, } from './talks.js';
25
26
  import { threadDir, threadOfEntry } from 'gcf-session';
26
27
  const send = (res, status, body) => {
@@ -162,13 +163,14 @@ export function createApp(o) {
162
163
  const projects = await listProjects();
163
164
  // The kept queues of projects no longer on the board go: one added back starts empty.
164
165
  keepProjects(projects.map((p) => p.name));
166
+ sweepRuns(projects);
165
167
  // A watcher set up after the server closed would keep the process alive.
166
168
  if (closed)
167
169
  return;
168
170
  for (const p of projects)
169
171
  if (!watchers.has(p.name)) {
170
172
  const stops = [
171
- watchProject(p),
173
+ watchProject(p, undefined, () => domains.get(p.name)?.session_ttl_min ?? SESSION_TTL_MIN),
172
174
  watchTalks(p, () => broadcast({ type: 'talks', project: p.name }), async (t) => prepareTalk(p, await boardOf(p), t)),
173
175
  ];
174
176
  watchers.set(p.name, () => stops.forEach((stop) => stop()));
@@ -260,6 +262,7 @@ export function createApp(o) {
260
262
  const routes = [
261
263
  ['GET', /^\/api\/events$/, async (_req, res) => subscribe(res)],
262
264
  ['GET', /^\/api\/projects$/, async (_req, res) => send(res, 200, await listProjects())],
265
+ ['GET', /^\/api\/themes$/, async (_req, res) => send(res, 200, await readThemes())],
263
266
  [
264
267
  'POST',
265
268
  /^\/api\/projects$/,
@@ -25,10 +25,9 @@ export function broadcast(event) {
25
25
  for (const c of clients)
26
26
  c.write(line);
27
27
  }
28
- // The core's SESSION_TTL_MS (session-mark.js): a mark nobody refreshed for this long is a session
29
- // that stopped. shortcut: a copy of the core's constant, read it from the board JSON once the core
30
- // reports a mark's expiry.
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 < SESSION_TTL_MS}`;
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;
@@ -520,13 +520,41 @@ function going(rid, pid) {
520
520
  return false;
521
521
  }
522
522
  }
523
+ /**
524
+ * Drop the run records of projects no longer on the board (removed while no board was up, so none
525
+ * took their ends), once their runs are over: nothing would ever read them.
526
+ */
527
+ export function sweepRuns(projects) {
528
+ let names;
529
+ try {
530
+ names = readdirSync(flightsDir());
531
+ }
532
+ catch {
533
+ return;
534
+ }
535
+ for (const name of names) {
536
+ if (!name.endsWith('.json') || name.endsWith('.end.json'))
537
+ continue;
538
+ const rid = name.slice(0, -'.json'.length);
539
+ if (flights.has(rid))
540
+ continue;
541
+ try {
542
+ const f = JSON.parse(readFileSync(recordOf(rid), 'utf8'));
543
+ if (projects.some((p) => p.name === f.project && p.path === f.path) || going(rid, f.pid))
544
+ continue;
545
+ rmSync(endOf(rid), { force: true });
546
+ rmSync(recordOf(rid), { force: true });
547
+ }
548
+ catch {
549
+ // Unreadable or gone meanwhile: the next start looks again.
550
+ }
551
+ }
552
+ }
523
553
  /**
524
554
  * What a board before this one left for the project: first its queue, pause, reports and trace
525
555
  * (`queue.json`), then its runs: one going shows as active until it ends, one that ended
526
556
  * meanwhile as its report, one whose relay died with no end as a failure, which pauses the
527
557
  * queue. Only then a queue not paused and with no main run going goes on.
528
- * shortcut: the records of a project removed while no board was up stay in the board home until
529
- * it is added back; sweep the ones of unregistered projects at the start if they pile up.
530
558
  */
531
559
  export function adoptRuns(entry, p) {
532
560
  try {
@@ -0,0 +1,75 @@
1
+ // The operator's themes: one JSON file each in `<board home>/themes/<id>.json`, made by the
2
+ // designer or by hand. A theme sets design tokens (`--gcf-<name>` of web/tokens.css) over the
3
+ // built-in dark; the page checks the names, it owns the tokens. Read anew on each request.
4
+ import { readdir, readFile, stat } from 'node:fs/promises';
5
+ import path from 'node:path';
6
+ import { homeDir } from './registry.js';
7
+ export const themesDir = () => path.join(homeDir(), 'themes');
8
+ const ID_RE = /^[a-z0-9-]{1,40}$/;
9
+ const FILE_MAX = 64 * 1024;
10
+ const VALUE_MAX = 200;
11
+ // The page sets each value through the CSSOM, which cannot be broken out of; a function outside
12
+ // the colour and arithmetic ones (`url(`, `image-set(`, `src(`) could fetch from the network.
13
+ const BAD_VALUE = /[;{}<>\\]/;
14
+ const FUNCTIONS = new Set('rgb rgba hsl hsla hwb lab lch oklab oklch color color-mix light-dark var calc min max clamp'.split(' '));
15
+ const badFunction = (v) => [...v.matchAll(/([a-z-]*)\(/gi)].find((m) => m[1] && !FUNCTIONS.has(m[1].toLowerCase()))?.[1];
16
+ const BOM = new RegExp(`^${String.fromCharCode(0xfeff)}`);
17
+ /** A theme file's problem, or null when it is good. */
18
+ export function themeProblem(id, data) {
19
+ if (id === 'dark')
20
+ return 'the name dark is the built-in theme: rename the file';
21
+ if (!ID_RE.test(id))
22
+ return 'a file name takes a-z, 0-9 and -, up to 40';
23
+ if (typeof data !== 'object' || data === null)
24
+ return 'not a JSON object';
25
+ const t = data;
26
+ if (t.gcf_theme !== 1)
27
+ return 'gcf_theme must be 1';
28
+ if (typeof t.name !== 'string' || !t.name.trim())
29
+ return 'name is required';
30
+ if (t.scheme !== 'light' && t.scheme !== 'dark')
31
+ return 'scheme must be light or dark';
32
+ if (typeof t.tokens !== 'object' || t.tokens === null || Array.isArray(t.tokens))
33
+ return 'tokens must be an object';
34
+ for (const [k, v] of Object.entries(t.tokens)) {
35
+ if (!/^[a-z0-9-]+$/.test(k))
36
+ return `token ${k}: a name without --gcf-, a-z, 0-9 and -`;
37
+ if (typeof v !== 'string' || !v.trim() || v.length > VALUE_MAX || BAD_VALUE.test(v))
38
+ return `token ${k}: a CSS value up to ${VALUE_MAX} characters, no ; { } < > \\`;
39
+ const fn = badFunction(v);
40
+ if (fn)
41
+ return `token ${k}: ${fn}( is not a colour function (oklch, rgb, color-mix, var…)`;
42
+ }
43
+ return null;
44
+ }
45
+ /** Every `*.json` of the themes folder: a good theme, or its id and what is wrong with it. */
46
+ export async function readThemes(dir = themesDir()) {
47
+ let names;
48
+ try {
49
+ names = (await readdir(dir)).filter((n) => n.endsWith('.json')).sort();
50
+ }
51
+ catch {
52
+ return [];
53
+ }
54
+ const themes = [];
55
+ for (const n of names) {
56
+ const id = n.slice(0, -'.json'.length);
57
+ const file = path.join(dir, n);
58
+ try {
59
+ if ((await stat(file)).size > FILE_MAX)
60
+ throw new Error(`larger than ${FILE_MAX / 1024} KB`);
61
+ // A file saved by a Windows editor may start with a byte order mark.
62
+ const text = (await readFile(file, 'utf8')).replace(BOM, '');
63
+ const data = JSON.parse(text);
64
+ const problem = themeProblem(id, data);
65
+ if (problem)
66
+ themes.push({ id, error: problem });
67
+ else
68
+ themes.push({ id, name: data.name, scheme: data.scheme, tokens: data.tokens });
69
+ }
70
+ catch (e) {
71
+ themes.push({ id, error: e.message });
72
+ }
73
+ }
74
+ return themes;
75
+ }