@mindbricks/genesis-set 0.3.0 → 0.4.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/CHANGELOG.md CHANGED
@@ -3,6 +3,25 @@
3
3
  The package follows semantic versioning. Each release names the mind-set range it needs
4
4
  (`dependencies["@mindbricks/mind-set"]` in `package.json`).
5
5
 
6
+ ## 0.4.0 (pre-release)
7
+
8
+ - **`genesis board`:** a local board for a genesis project. It is read live from the folder and
9
+ shows:
10
+ - the design flow with each document's state and `design-check` result;
11
+ - the rendered documents;
12
+ - the interview (status, coverage ledger, open questions);
13
+ - the blueprint with its validation;
14
+ - the project and global keys;
15
+ - the next step.
16
+
17
+ It runs on 127.0.0.1:4747 (bookmarkable, read-only); the link `genesis board` opens can
18
+ change keys. One board per project, reused. The agent gets it with `genesis_openBoard`, and
19
+ the `genesis init` instructions tell it to offer the board.
20
+ - **Projects:** `genesis init` writes `.genesis/project.json` (a random id and a name).
21
+ - **Project keys:** they live in the home folder under that id. Inside a project,
22
+ `genesis_requestKey` stores a project key by default, `genesis_listKeys` labels each key's
23
+ scope, and `genesis_writeKeyToEnvFile` prefers the project key. `genesis keys` stays global.
24
+
6
25
  ## 0.3.0 (pre-release)
7
26
 
8
27
  - `genesis init [<folder>] [--dry-run]` prepares a project folder so the agent works the
package/README.md CHANGED
@@ -40,8 +40,9 @@ which the agents read at the start of every session:
40
40
  - the order of work with the skill for each step;
41
41
  - the key rules.
42
42
 
43
- It also creates `design/` and the env and secrets lines of `.gitignore`, then prints the API
44
- key status and a starter prompt.
43
+ It also writes the project identity `.genesis/project.json` (a random id and a name, no secret,
44
+ fine to commit), creates `design/` and the env and secrets lines of `.gitignore`, and prints the
45
+ API key status and a starter prompt.
45
46
  - Your own content in `CLAUDE.md` and `AGENTS.md` is kept.
46
47
  - A second run only refreshes the block.
47
48
  - `--dry-run` shows what it would write.
@@ -53,6 +54,29 @@ Let us design a new application with OpenAPPL and compile it with Genesis: a tab
53
54
  system for cafes, with owner, waiter and guest roles. Start with the requirements interview.
54
55
  ```
55
56
 
57
+ ## The project board
58
+
59
+ `genesis board` in a project folder opens the project's board in your browser. The board is read
60
+ live from the folder as the agent writes, and shows:
61
+ - **Overview:** the next step, and the design flow from the interview to the test report, with
62
+ every document written, waiting or "if needed" and its `design-check` result;
63
+ - **Documents:** every design document, rendered;
64
+ - **Interview:** its status, the coverage ledger and the open questions;
65
+ - **Blueprint:** its services, data objects and APIs, and the `mindset validate` result;
66
+ - **Keys:** this project's keys and your global ones; set, replace, clear, delete and add.
67
+
68
+ The board runs on `http://127.0.0.1:4747/` (the next free port if that one is taken;
69
+ `GENESIS_BOARD_PORT` moves it) until it is idle for an hour or you press Ctrl+C.
70
+ - **Bookmark it:** the plain address is read-only.
71
+ - **Changing keys** takes the link `genesis board` opens, which sets a write cookie for that run.
72
+ - **One board per project:** a second `genesis board` for the same project reuses the running
73
+ one.
74
+ - **The agent knows the board** (the `genesis init` instructions and the `genesis_openBoard`
75
+ tool). It offers the link when it finishes a design document, and answers "where can I see
76
+ this?" with it.
77
+
78
+ `genesis keys` stays the page of your global keys only, from any folder.
79
+
56
80
  ## Commands
57
81
 
58
82
  | Command | What it does |
@@ -63,6 +87,7 @@ system for cafes, with owner, waiter and guest roles. Start with the requirement
63
87
  | `genesis uninstall [--dry-run]` | Removes only what `install` recorded in `~/.genesis-set/installed.json`, including the MCP registrations. mind-set and your API key file stay. |
64
88
  | `genesis doctor` | Both versions (genesis-set and mind-set) and whether they are compatible, the skills of each package and the MCP server per agent, where the API key comes from and which key it is (its type prefix and last four characters, such as `sk_mbx_...9f3a`, never the whole key) and the API base. |
65
89
  | `genesis config [show \| set-key \| unset-key \| set-base <url> \| unset-base]` | The API key and API base in `~/.genesis-set/config.json` (mode 0600). `set-key` reads the key from stdin (hidden on a terminal), never from the command line. |
90
+ | `genesis board [<folder>] [--no-open]` | Opens the board of the genesis project in `<folder>` (default: the current one): design flow, documents, interview, blueprint, project and global keys (see "The project board"). |
66
91
  | `genesis keys [--no-open]` | Opens the local key page in your browser: add, change, clear or delete the keys your agent uses. The link is new each time; the page closes after 15 idle minutes or on Ctrl+C. `--no-open` only prints the link. |
67
92
  | `genesis mcp` | Runs the MCP server on stdio from the package (for a registration by hand). |
68
93
 
@@ -90,6 +115,18 @@ comes back in the Genesis error shape `{ "error": { "code", "message", "details"
90
115
 
91
116
  ### Keys: the local key page
92
117
 
118
+ Keys have a **scope**:
119
+ - **project:** this genesis project only; the default for a key the agent requests inside a
120
+ project.
121
+ - **global:** yours in every project, like the Genesis API key.
122
+
123
+ Both scopes are stored in your home folder: the global ones in `~/.genesis-set/config.json`, a
124
+ project's in `~/.genesis-set/projects/<project id>/keys.json`. Neither is ever stored in the
125
+ project folder. A key is looked up in the project first, then globally.
126
+
127
+ - **The board:** inside a project, the board's Keys tab shows both scopes.
128
+ - **`genesis keys`:** shows the global ones.
129
+
93
130
  A coding agent keeps needing secrets: the Genesis API key, and provider keys (payment, mail,
94
131
  storage, AI) to run the generated services. The rule is that no value is ever typed into the chat.
95
132
  Instead the MCP server serves a local key page, and four tools that never call the API and work
@@ -24,6 +24,7 @@ Usage:
24
24
  genesis uninstall [--dry-run]
25
25
  genesis doctor
26
26
  genesis config [show | set-key | unset-key | set-base <url> | unset-base]
27
+ genesis board [<folder>] [--no-open]
27
28
  genesis keys [--no-open]
28
29
  genesis mcp
29
30
  genesis --version | --help
@@ -56,6 +57,14 @@ uninstall removes only what install recorded in ~/.genesis-set/installed.json;
56
57
  doctor both versions (genesis-set and mind-set) and whether they are
57
58
  compatible, the skills and the MCP server per agent, where the API
58
59
  key comes from (never its value) and the API base.
60
+ board opens the project board of the genesis project in <folder>
61
+ (default: the current one; "genesis init" makes a project): the
62
+ design flow with each document's state and check, the documents,
63
+ the interview, the blueprint and its validation, and the project's
64
+ and your global keys. It runs on 127.0.0.1:${'4747'} (or the next free
65
+ port) until it is idle for an hour or Ctrl+C; a board already
66
+ running for the project is reused. The link it opens can change
67
+ keys; the plain address (bookmark it) is read-only.
59
68
  keys opens the local key page in your browser (the page the agent
60
69
  links to): add, change, clear or delete the keys your agent uses.
61
70
  The link is new every time; the page closes after 15 idle minutes
@@ -96,6 +105,7 @@ const KNOWN_FLAGS = {
96
105
  doctor: [],
97
106
  config: [],
98
107
  keys: ['noOpen'],
108
+ board: ['noOpen'],
99
109
  mcp: [],
100
110
  };
101
111
 
@@ -126,6 +136,37 @@ async function main(argv) {
126
136
  }
127
137
  return initProject({ dir: positional[1] ?? process.cwd(), env: process.env, out, err, dryRun: flags.dryRun === true });
128
138
  }
139
+ if (command === 'board') {
140
+ if (positional.length > 2) {
141
+ err('error: board takes one folder at most');
142
+ return 2;
143
+ }
144
+ const { findProject } = await import('../mcp/project.mjs');
145
+ const folder = path.resolve(positional[1] ?? process.cwd());
146
+ const project = findProject(folder);
147
+ if (!project) {
148
+ err(`error: ${folder} is not a genesis project. Run "genesis init" there first (or "genesis keys" for your global keys).`);
149
+ return 1;
150
+ }
151
+ const { ensureBoard, boardClosed, closeBoard } = await import('../mcp/board.mjs');
152
+ const { openInBrowser } = await import('../mcp/key-tools.mjs');
153
+ const board = await ensureBoard({ env: process.env, project });
154
+ out(`Genesis board for "${project.name}": ${board.readUrl}`);
155
+ if (flags.noOpen !== true && !openInBrowser(board.url)) out('Could not open a browser: open the link yourself.');
156
+ if (board.reused && board.idleMinutes === null) {
157
+ out(board.url === board.readUrl ? 'The board already runs in another process (read-only link).' : 'The board already runs in another process; opened it there.');
158
+ return 0;
159
+ }
160
+ if (flags.noOpen === true) out(`To change keys, open: ${board.url}`);
161
+ out(`It closes after ${board.idleMinutes} idle minutes, or press Ctrl+C.`);
162
+ process.once('SIGINT', () => closeBoard());
163
+ process.once('SIGTERM', () => closeBoard());
164
+ const keepAlive = setInterval(() => {}, 1 << 30);
165
+ await boardClosed();
166
+ clearInterval(keepAlive);
167
+ out('The board is closed.');
168
+ return 0;
169
+ }
129
170
  if (command === 'keys') {
130
171
  const { ensureKeyPage, keyPageClosed, closeKeyPage } = await import('../mcp/key-page.mjs');
131
172
  const { openInBrowser } = await import('../mcp/key-tools.mjs');
package/lib/init.mjs CHANGED
@@ -11,6 +11,9 @@
11
11
  // only the block
12
12
  // design/README.md where the design documents go (written only when absent)
13
13
  // .gitignore the env and secrets lines that are missing
14
+ // .genesis/project.json the project identity (random id, name; no secret,
15
+ // may be committed); an existing one is never changed.
16
+ // The project's keys live in the user's home under it.
14
17
  //
15
18
  // This is the one genesis command that writes into a project folder, and only
16
19
  // into the folder it is run on. It never runs git and never touches the key store.
@@ -19,6 +22,7 @@ import fs from 'node:fs';
19
22
  import path from 'node:path';
20
23
 
21
24
  import { maskSecret, portalKeysUrl, resolveSettings } from '../mcp/config.mjs';
25
+ import { PROJECT_DIR, PROJECT_FILE, ensureProject } from '../mcp/project.mjs';
22
26
 
23
27
  export const BLOCK_BEGIN = '<!-- genesis init: begin. "genesis init" rewrites this block; edit outside it -->';
24
28
  export const BLOCK_END = '<!-- genesis init: end -->';
@@ -53,8 +57,15 @@ as its contract (openappl-blueprint-contract).
53
57
  **Keys and secrets:** never ask for a key or a password in the chat, and never write one into
54
58
  a file of this project yourself. Register the key with the genesis key tools, give the user
55
59
  the local key page link to save it there, and check that it is set; a key reaches a service's
56
- gitignored env file only through the key tool that writes it. The user can open the key page
57
- any time with \`genesis keys\`.`;
60
+ gitignored env file only through the key tool that writes it. A key this project needs is a
61
+ project key (the default here); the user's own keys, such as the Genesis API key, are global.
62
+
63
+ **The project board:** the user follows this project on a local board: the design flow with the
64
+ state of every document, the documents, the interview, the blueprint and its validation, and
65
+ the keys. They open it with \`genesis board\` in this folder; you give its link with the genesis
66
+ board tool (and open it in the browser when they ask). Offer it when you finish a design
67
+ document or the blueprint, and answer "where can I see this?" with it. The user's global keys
68
+ alone are behind \`genesis keys\`.`;
58
69
 
59
70
  /** The block with its markers. */
60
71
  export function instructionsBlock() {
@@ -142,6 +153,16 @@ export function initProject({ dir = process.cwd(), env = process.env, out, err =
142
153
  writes.push([file, after]);
143
154
  }
144
155
 
156
+ let project;
157
+ try {
158
+ const res = ensureProject(target, { dryRun });
159
+ project = res.project;
160
+ if (res.created) act(`write ${PROJECT_DIR}/${PROJECT_FILE} (project "${project.name}")`);
161
+ } catch (e) {
162
+ err(`error: ${e.message}`);
163
+ return 1;
164
+ }
165
+
145
166
  const designReadme = path.join(target, 'design', 'README.md');
146
167
  if (read(designReadme) === null) {
147
168
  act('write design/README.md');
@@ -170,6 +191,7 @@ export function initProject({ dir = process.cwd(), env = process.env, out, err =
170
191
 
171
192
  const s = resolveSettings(env);
172
193
  out('');
194
+ out(`Project "${project.name}" (id ${project.id}). Its keys are kept in your home folder, never in this folder.`);
173
195
  out(
174
196
  s.apiKey
175
197
  ? `Genesis API key: ${maskSecret(s.apiKey) ?? 'set'} (from ${s.keySource}).`
@@ -177,6 +199,7 @@ export function initProject({ dir = process.cwd(), env = process.env, out, err =
177
199
  );
178
200
  if (!isGitRepo(target)) out('This folder is not a git repository yet; "git init" makes it one.');
179
201
  out('');
202
+ out('Follow the project on its board: "genesis board" in this folder.');
180
203
  out(`Next: open Claude Code or Codex in ${target} and start with:`);
181
204
  out(` ${STARTER_PROMPT}`);
182
205
  return 0;
package/lib/install.mjs CHANGED
@@ -436,6 +436,9 @@ export function install(ctx, agentNames, { force = false, skipMindSet = false, m
436
436
  corpus: corpusDir,
437
437
  current,
438
438
  mindSetCorpus: mindSet,
439
+ // Where the mind-set package is, so the board can run its design-check and
440
+ // validate code from the standalone MCP server copy (#9386).
441
+ mindSetPackage: bundledMindSet(ctx)?.dir ?? previous?.mindSetPackage,
439
442
  corpora: [...new Set([...(previous?.corpora ?? []), corpusDir])],
440
443
  agents,
441
444
  mcp: mcp || previous?.mcp ? { server: mcpServerFile(ctx), agents: mcpAgents } : undefined,
@@ -0,0 +1,267 @@
1
+ // What the project board shows (#9386), read from the project folder each time:
2
+ // the design flow from the mind-set pipeline, the documents under design/, the
3
+ // interview record, the blueprint and its validation, the keys (masked) and the
4
+ // next step. Nothing here writes; the keys come from the key store.
5
+ //
6
+ // The design pipeline and the schema are read from the installed mind-set
7
+ // corpus (MIND_SET_HOME or ~/.mind-set/current). design-check and validate are
8
+ // mind-set's own code, loaded from the mind-set package that genesis install
9
+ // recorded (or that sits next to this package); without it the board says the
10
+ // checks are unavailable instead of guessing.
11
+
12
+ import fs from 'node:fs';
13
+ import { createRequire } from 'node:module';
14
+ import path from 'node:path';
15
+ import { fileURLToPath, pathToFileURL } from 'node:url';
16
+
17
+ import { dataDirOf } from './config.mjs';
18
+ import { listKeys } from './key-store.mjs';
19
+
20
+ const HERE = path.dirname(fileURLToPath(import.meta.url));
21
+
22
+ export function mindSetCorpusDir(env = process.env) {
23
+ if (env.MIND_SET_HOME) return path.join(path.resolve(env.MIND_SET_HOME), 'current');
24
+ const home = env.HOME || env.USERPROFILE || '';
25
+ return path.join(home, '.mind-set', 'current');
26
+ }
27
+
28
+ function readJson(file) {
29
+ try {
30
+ return JSON.parse(fs.readFileSync(file, 'utf8'));
31
+ } catch {
32
+ return null;
33
+ }
34
+ }
35
+
36
+ function readText(file) {
37
+ try {
38
+ return fs.readFileSync(file, 'utf8');
39
+ } catch {
40
+ return null;
41
+ }
42
+ }
43
+
44
+ /** The mind-set package folder: the env override, the one genesis install recorded, or the one next to this package. */
45
+ export function mindSetPackageDir(env = process.env) {
46
+ const candidates = [];
47
+ if (env.GENESIS_SET_MIND_SET_PACKAGE) candidates.push(path.resolve(env.GENESIS_SET_MIND_SET_PACKAGE));
48
+ const installed = readJson(path.join(dataDirOf(env), 'installed.json'));
49
+ if (installed && typeof installed.mindSetPackage === 'string') candidates.push(installed.mindSetPackage);
50
+ try {
51
+ const req = createRequire(path.join(HERE, '..', 'package.json'));
52
+ candidates.push(path.dirname(req.resolve('@mindbricks/mind-set/package.json')));
53
+ } catch {
54
+ // not next to this package (the standalone server copy)
55
+ }
56
+ return candidates.find((d) => fs.existsSync(path.join(d, 'lib', 'design-check.mjs'))) ?? null;
57
+ }
58
+
59
+ const libCache = new Map();
60
+ async function mindSetLib(env, name) {
61
+ const dir = mindSetPackageDir(env);
62
+ if (!dir) return null;
63
+ const file = path.join(dir, 'lib', name);
64
+ if (!libCache.has(file)) libCache.set(file, import(pathToFileURL(file).href).catch(() => null));
65
+ return libCache.get(file);
66
+ }
67
+
68
+ /** The design documents present: docName -> { file, size, mtime }. */
69
+ function designFiles(root) {
70
+ const dir = path.join(root, 'design');
71
+ const out = new Map();
72
+ let names = [];
73
+ try {
74
+ names = fs.readdirSync(dir);
75
+ } catch {
76
+ return out;
77
+ }
78
+ for (const n of names) {
79
+ if (!n.endsWith('.md') || n === 'README.md') continue;
80
+ const file = path.join(dir, n);
81
+ const st = fs.statSync(file);
82
+ if (st.isFile()) out.set(n.slice(0, -3), { file, size: st.size, mtime: st.mtime.toISOString() });
83
+ }
84
+ return out;
85
+ }
86
+
87
+ const STAGE_LABEL = {
88
+ source: 'Interview',
89
+ requirement: 'Requirements',
90
+ spec: 'Specification',
91
+ test: 'Test',
92
+ };
93
+
94
+ /** The interview record: its status, the OPEN items and the Coverage Ledger rows. */
95
+ export function interviewSummary(text) {
96
+ if (text === null) return null;
97
+ const lines = text.replace(/\r\n?/g, '\n').split('\n');
98
+ let status = null;
99
+ for (let i = 0; i < lines.length; i++) {
100
+ const m = lines[i].match(/^##\s+Status\s*:?\s*(.*)$/i);
101
+ if (m) {
102
+ status = (m[1] || lines.slice(i + 1).find((l) => l.trim()) || '').trim().replace(/[`*_]/g, '').toLowerCase() || null;
103
+ break;
104
+ }
105
+ }
106
+ const open = lines.filter((l) => /\bOPEN\b/.test(l) && !/^#/.test(l)).map((l) => l.replace(/^\s*[-*|]\s*/, '').trim()).slice(0, 50);
107
+ const ledger = [];
108
+ let inLedger = false;
109
+ for (const l of lines) {
110
+ if (/^##\s/.test(l)) inLedger = /coverage ledger/i.test(l);
111
+ else if (inLedger && /^\s*\|/.test(l) && !/^\s*\|?\s*:?-{2,}/.test(l)) {
112
+ const cells = l.trim().replace(/^\||\|$/g, '').split('|').map((c) => c.trim());
113
+ ledger.push(cells);
114
+ }
115
+ }
116
+ return { status, open, ledger };
117
+ }
118
+
119
+ /** The blueprint at the project root: a summary, or the parse error. */
120
+ export function blueprintSummary(root) {
121
+ const file = path.join(root, 'blueprint.json');
122
+ const text = readText(file);
123
+ if (text === null) return null;
124
+ let bp;
125
+ try {
126
+ bp = JSON.parse(text);
127
+ } catch (e) {
128
+ return { file, error: `not valid JSON: ${e.message}` };
129
+ }
130
+ const services = Array.isArray(bp.services) ? bp.services : [];
131
+ return {
132
+ file,
133
+ name: bp?.projectSettings?.basicSettings?.name ?? null,
134
+ services: services.map((s) => ({
135
+ name: s?.serviceSettings?.serviceBasics?.name ?? '(unnamed)',
136
+ dataObjects: Array.isArray(s?.dataObjects) ? s.dataObjects.length : 0,
137
+ businessApis: Array.isArray(s?.businessLogic) ? s.businessLogic.length : Array.isArray(s?.businessApis) ? s.businessApis.length : 0,
138
+ })),
139
+ raw: bp,
140
+ };
141
+ }
142
+
143
+ async function validation(env, bp) {
144
+ if (!bp || bp.error) return null;
145
+ const lib = await mindSetLib(env, 'validate.mjs');
146
+ const schemaText = readText(path.join(mindSetCorpusDir(env), 'openappl.json'));
147
+ if (!lib || !schemaText) return { available: false };
148
+ try {
149
+ const { errors, warnings } = lib.validateBlueprint(lib.loadSchema(JSON.parse(schemaText)), bp.raw);
150
+ return {
151
+ available: true,
152
+ errors: errors.length,
153
+ warnings: warnings.length,
154
+ first: errors.slice(0, 10).map((p) => lib.formatProblem(p)),
155
+ };
156
+ } catch (e) {
157
+ return { available: false, error: e.message };
158
+ }
159
+ }
160
+
161
+ /** The flow: every pipeline document with its state, plus the fan-out specs found. */
162
+ async function flow(env, root, pipeline, files) {
163
+ if (!pipeline) return { available: false, docs: [] };
164
+ const dc = await mindSetLib(env, 'design-check.mjs');
165
+ let roster = null;
166
+ const fan = pipeline.docs.find((d) => d.fanOut);
167
+ const prefix = fan?.fanOut?.docNamePrefix ?? 'service-spec-';
168
+ if (dc && fan?.fanOut?.roster && files.has(fan.fanOut.roster)) {
169
+ try {
170
+ roster = dc.rosterNamesOf(pipeline, readText(files.get(fan.fanOut.roster).file));
171
+ } catch {
172
+ roster = null;
173
+ }
174
+ }
175
+ const check = (docName, file) => {
176
+ if (!dc) return null;
177
+ try {
178
+ const r = dc.checkDesignDraft(pipeline, docName, readText(file) ?? '', roster ? { rosterNames: roster } : {});
179
+ return { ok: r.ok, findings: (r.findings ?? []).map((f) => f.message ?? f.code).slice(0, 10) };
180
+ } catch (e) {
181
+ return { ok: false, findings: [e.message] };
182
+ }
183
+ };
184
+ const docs = [];
185
+ for (const d of pipeline.docs) {
186
+ if (d.fanOut) {
187
+ const names = roster ? roster.map((n) => `${prefix}${dc.serviceRosterKey(n)}`) : [...files.keys()].filter((n) => n.startsWith(prefix));
188
+ const extra = [...files.keys()].filter((n) => n.startsWith(prefix) && !names.includes(n));
189
+ for (const docName of [...names, ...extra]) {
190
+ const f = files.get(docName);
191
+ docs.push({ docName, stage: d.stage, class: d.class, label: STAGE_LABEL[d.class] ?? d.class, fanOut: true, conditional: false, written: Boolean(f), mtime: f?.mtime ?? null, check: f ? check(docName, f.file) : null });
192
+ }
193
+ if (names.length === 0 && extra.length === 0) {
194
+ docs.push({ docName: `${prefix}<service>`, stage: d.stage, class: d.class, label: STAGE_LABEL[d.class] ?? d.class, fanOut: true, conditional: false, written: false, placeholder: true, mtime: null, check: null });
195
+ }
196
+ continue;
197
+ }
198
+ const f = files.get(d.docName);
199
+ docs.push({
200
+ docName: d.docName,
201
+ stage: d.stage,
202
+ class: d.class,
203
+ label: STAGE_LABEL[d.class] ?? d.class,
204
+ conditional: Boolean(d.when),
205
+ written: Boolean(f),
206
+ mtime: f?.mtime ?? null,
207
+ check: f ? check(d.docName, f.file) : null,
208
+ });
209
+ }
210
+ const known = new Set(docs.map((d) => d.docName));
211
+ const other = [...files.keys()].filter((n) => !known.has(n)).sort();
212
+ return { available: true, checksAvailable: Boolean(dc), docs, other };
213
+ }
214
+
215
+ function nextStep(state) {
216
+ const { flow: f, interview, blueprint, validation: v } = state;
217
+ if (!f.available) return 'Install mind-set ("genesis install") so the board can show the design flow.';
218
+ const byName = new Map(f.docs.map((d) => [d.docName, d]));
219
+ const ir = byName.get('interview-record');
220
+ if (!ir?.written) return 'Start the requirements interview: ask the agent to design the application.';
221
+ if (interview?.status && !/closed/.test(interview.status)) return 'Finish the requirements interview (the record is not closed yet).';
222
+ const failing = f.docs.find((d) => d.written && d.check && !d.check.ok);
223
+ if (failing) return `Fix ${failing.docName}: its design-check has findings.`;
224
+ const missing = f.docs.find((d) => !d.written && !d.conditional && d.class !== 'test');
225
+ if (missing) return `Next document: ${missing.placeholder ? 'the service specs (one per service)' : missing.docName}.`;
226
+ if (!blueprint) return 'Write the blueprint (blueprint.json) from the design documents.';
227
+ if (blueprint.error) return `Fix blueprint.json: ${blueprint.error}.`;
228
+ if (v?.available && v.errors > 0) return `Fix the ${v.errors} validation error(s) of the blueprint.`;
229
+ return 'Compile the blueprint with Genesis, one service at a time.';
230
+ }
231
+
232
+ /** The whole board state of a project (or, without one, only the global keys). */
233
+ export async function boardState({ env = process.env, project }) {
234
+ const keys = listKeys(env, { project }).map(({ name, label, description, builtin, scope, status, source, masked, updatedAt }) => ({
235
+ name,
236
+ label,
237
+ description,
238
+ builtin,
239
+ scope,
240
+ status,
241
+ ...(source ? { source } : {}),
242
+ masked,
243
+ updatedAt,
244
+ }));
245
+ if (!project) return { project: null, keys };
246
+ const files = designFiles(project.root);
247
+ const pipeline = readJson(path.join(mindSetCorpusDir(env), 'procedures', 'design', 'pipeline.json'));
248
+ const bp = blueprintSummary(project.root);
249
+ const state = {
250
+ project: { id: project.id, name: project.name, root: project.root },
251
+ flow: await flow(env, project.root, pipeline, files),
252
+ interview: interviewSummary(files.has('interview-record') ? readText(files.get('interview-record').file) : null),
253
+ blueprint: bp ? { file: bp.file, name: bp.name ?? null, services: bp.services ?? [], error: bp.error ?? null } : null,
254
+ validation: await validation(env, bp),
255
+ keys,
256
+ };
257
+ state.next = nextStep(state);
258
+ return state;
259
+ }
260
+
261
+ /** One design document's text, by name; null for a name that is not a document of this project. */
262
+ export function designDoc(project, docName) {
263
+ if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,120}$/.test(docName)) return null;
264
+ const file = path.join(project.root, 'design', `${docName}.md`);
265
+ if (path.dirname(file) !== path.join(project.root, 'design')) return null;
266
+ return readText(file);
267
+ }