modboard 0.0.0-stage → 0.5.1
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/.claude-plugin/plugin.json +50 -0
- package/CHANGELOG.md +123 -0
- package/LICENSE +21 -0
- package/README.md +549 -2
- package/bin/board.mjs +157 -0
- package/examples/store-memory.mjs +34 -0
- package/hooks/blocks/agents.tsx +8 -0
- package/hooks/blocks/attention.ts +14 -0
- package/hooks/blocks/clock.tsx +10 -0
- package/hooks/blocks/command.tsx +58 -0
- package/hooks/blocks/context.tsx +18 -0
- package/hooks/blocks/effort.tsx +30 -0
- package/hooks/blocks/index.ts +18 -0
- package/hooks/blocks/model.tsx +37 -0
- package/hooks/blocks/summary.tsx +46 -0
- package/hooks/blocks/tasks.tsx +77 -0
- package/hooks/blocks/types.tsx +38 -0
- package/hooks/blocks/usage.tsx +68 -0
- package/hooks/hooks.json +1 -0
- package/hooks/register.tsx +356 -0
- package/lib/contract.mjs +61 -0
- package/lib/engine.mjs +217 -0
- package/lib/load-store.mjs +66 -0
- package/lib/store-file.mjs +118 -0
- package/package.json +22 -4
- package/tsconfig.json +3 -0
- package/types/index.d.ts +23 -0
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
// Finds the storage block a board's config.json names and plugs it in.
|
|
2
|
+
//
|
|
3
|
+
// { "store": "file" } the built-in block (the default)
|
|
4
|
+
// { "store": "./stores/supabase.mjs" } a block file, relative to .modboard/
|
|
5
|
+
// { "store": "modboard-supabase" } a block published as a package
|
|
6
|
+
//
|
|
7
|
+
// A block is a module exporting createStore(config, { dir }), which returns a
|
|
8
|
+
// Store (the contract is written out in lib/store-file.mjs). The rest of
|
|
9
|
+
// config.json is the block's own: a URL, which env var holds its key, and so on.
|
|
10
|
+
|
|
11
|
+
import fs from 'node:fs'
|
|
12
|
+
import path from 'node:path'
|
|
13
|
+
import { pathToFileURL } from 'node:url'
|
|
14
|
+
|
|
15
|
+
import { BoardError } from './engine.mjs'
|
|
16
|
+
import * as file from './store-file.mjs'
|
|
17
|
+
|
|
18
|
+
const BUILT_IN = { file }
|
|
19
|
+
const METHODS = ['now', 'snapshot', 'commit', 'events', 'verify']
|
|
20
|
+
|
|
21
|
+
// A package block is looked up from the board's folder upward, the way Node
|
|
22
|
+
// would from the project that installed it. A bare import() would look only
|
|
23
|
+
// beside modboard itself. Returns its entry as a file URL, or null when no
|
|
24
|
+
// node_modules above the board has it (import() then tries modboard's own).
|
|
25
|
+
function findPackage(spec, dir) {
|
|
26
|
+
for (let d = path.resolve(dir); ; d = path.dirname(d)) {
|
|
27
|
+
const pkgDir = path.join(d, 'node_modules', spec)
|
|
28
|
+
const pkgFile = path.join(pkgDir, 'package.json')
|
|
29
|
+
if (fs.existsSync(pkgFile)) {
|
|
30
|
+
const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf8'))
|
|
31
|
+
return pathToFileURL(path.join(pkgDir, entryOf(pkg))).href
|
|
32
|
+
}
|
|
33
|
+
if (path.dirname(d) === d) return null
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
// The package's main entry for an ESM import: exports['.'] (or exports
|
|
38
|
+
// itself), taking the import, then node, then default condition, else main.
|
|
39
|
+
function entryOf(pkg) {
|
|
40
|
+
let e = pkg.exports
|
|
41
|
+
if (e && typeof e === 'object' && '.' in e) e = e['.']
|
|
42
|
+
while (e && typeof e === 'object') e = e.import ?? e.node ?? e.default
|
|
43
|
+
return typeof e === 'string' ? e : (pkg.main ?? 'index.js')
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
export async function loadStore(dir) {
|
|
47
|
+
const configFile = path.join(dir, 'config.json')
|
|
48
|
+
const config = fs.existsSync(configFile) ? JSON.parse(fs.readFileSync(configFile, 'utf8')) : {}
|
|
49
|
+
const spec = config.store ?? 'file'
|
|
50
|
+
|
|
51
|
+
let block = BUILT_IN[spec]
|
|
52
|
+
if (!block) {
|
|
53
|
+
const target = spec.startsWith('.') || path.isAbsolute(spec) ? pathToFileURL(path.resolve(dir, spec)).href : (findPackage(spec, dir) ?? spec)
|
|
54
|
+
try {
|
|
55
|
+
block = await import(target)
|
|
56
|
+
} catch (err) {
|
|
57
|
+
throw new BoardError(2, `cannot load storage block "${spec}": ${err.message}`)
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
if (typeof block.createStore !== 'function') throw new BoardError(2, `storage block "${spec}" does not export createStore`)
|
|
61
|
+
|
|
62
|
+
const store = await block.createStore(config, { dir })
|
|
63
|
+
const missing = METHODS.filter(m => typeof store?.[m] !== 'function')
|
|
64
|
+
if (missing.length) throw new BoardError(2, `storage block "${spec}" is missing: ${missing.join(', ')}`)
|
|
65
|
+
return { store, name: spec }
|
|
66
|
+
}
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
// The local block: a board in a directory.
|
|
2
|
+
//
|
|
3
|
+
// The Store contract every block implements (all methods may be async):
|
|
4
|
+
//
|
|
5
|
+
// now() the store's clock, in ms. Leases use it, so every
|
|
6
|
+
// device agrees on time (a database answers its own).
|
|
7
|
+
// snapshot() { tasks: {id: Task}, agents: {name: Agent} }, each
|
|
8
|
+
// record carrying the `version` it stands at.
|
|
9
|
+
// commit({ writes, events })
|
|
10
|
+
// writes: [{ kind: 'task'|'agent', key, value|null, expect }]
|
|
11
|
+
// Applies every write and appends every event, or
|
|
12
|
+
// nothing: all-or-none, and only if each record still
|
|
13
|
+
// stands at `expect` (0 = must not exist). Answers
|
|
14
|
+
// { ok: true } or { ok: false, conflict }. Each applied
|
|
15
|
+
// record's version becomes expect + 1; null deletes.
|
|
16
|
+
// events(since) ledger events with seq > since.
|
|
17
|
+
// verify() { ok, problems, ... }: does the history match the state?
|
|
18
|
+
//
|
|
19
|
+
// Here a commit runs under one lock per board (mkdir is atomic), the ledger
|
|
20
|
+
// line is appended before the state file is replaced (rename is atomic), so a
|
|
21
|
+
// crash between the two leaves an event the state lacks, which verify reports.
|
|
22
|
+
|
|
23
|
+
import fs from 'node:fs'
|
|
24
|
+
import path from 'node:path'
|
|
25
|
+
|
|
26
|
+
// The entry point every block exports: the board's config.json and its folder in,
|
|
27
|
+
// a Store out.
|
|
28
|
+
export const createStore = (_config, { dir }) => fileStore(dir)
|
|
29
|
+
|
|
30
|
+
const STALE_LOCK_MS = 10_000
|
|
31
|
+
|
|
32
|
+
export function fileStore(dir) {
|
|
33
|
+
const STATE = path.join(dir, 'board.json')
|
|
34
|
+
const LEDGER = path.join(dir, 'ledger.jsonl')
|
|
35
|
+
const LOCK = path.join(dir, 'lock')
|
|
36
|
+
|
|
37
|
+
function load() {
|
|
38
|
+
if (!fs.existsSync(STATE)) return { version: 2, seq: 0, tasks: {}, agents: {} }
|
|
39
|
+
const state = JSON.parse(fs.readFileSync(STATE, 'utf8'))
|
|
40
|
+
// 0.1 boards had no versions or agents.
|
|
41
|
+
for (const t of Object.values(state.tasks)) t.version ??= 1
|
|
42
|
+
state.agents ??= {}
|
|
43
|
+
delete state.nextId
|
|
44
|
+
return state
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
function save(state) {
|
|
48
|
+
const tmp = `${STATE}.${process.pid}.tmp`
|
|
49
|
+
fs.writeFileSync(tmp, JSON.stringify({ ...state, version: 2 }, null, 2) + '\n')
|
|
50
|
+
fs.renameSync(tmp, STATE)
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
function withLock(fn) {
|
|
54
|
+
fs.mkdirSync(dir, { recursive: true })
|
|
55
|
+
const deadline = Date.now() + 5000
|
|
56
|
+
for (;;) {
|
|
57
|
+
try {
|
|
58
|
+
fs.mkdirSync(LOCK)
|
|
59
|
+
break
|
|
60
|
+
} catch (err) {
|
|
61
|
+
if (err.code !== 'EEXIST') throw err
|
|
62
|
+
try {
|
|
63
|
+
if (Date.now() - fs.statSync(LOCK).mtimeMs > STALE_LOCK_MS) fs.rmSync(LOCK, { recursive: true, force: true })
|
|
64
|
+
} catch {}
|
|
65
|
+
if (Date.now() > deadline) return { ok: false, conflict: 'lock' }
|
|
66
|
+
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10 + Math.random() * 20)
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
try {
|
|
70
|
+
return fn()
|
|
71
|
+
} finally {
|
|
72
|
+
fs.rmSync(LOCK, { recursive: true, force: true })
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
function readLedger() {
|
|
77
|
+
if (!fs.existsSync(LEDGER)) return []
|
|
78
|
+
return fs.readFileSync(LEDGER, 'utf8').split('\n').filter(Boolean).map(line => JSON.parse(line))
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
return {
|
|
82
|
+
now: () => Date.now(),
|
|
83
|
+
|
|
84
|
+
snapshot: () => {
|
|
85
|
+
const { tasks, agents } = load()
|
|
86
|
+
return { tasks, agents }
|
|
87
|
+
},
|
|
88
|
+
|
|
89
|
+
commit: ({ writes, events }) =>
|
|
90
|
+
withLock(() => {
|
|
91
|
+
const state = load()
|
|
92
|
+
const table = kind => (kind === 'task' ? state.tasks : state.agents)
|
|
93
|
+
for (const w of writes) {
|
|
94
|
+
if ((table(w.kind)[w.key]?.version ?? 0) !== w.expect) return { ok: false, conflict: `${w.kind}:${w.key}` }
|
|
95
|
+
}
|
|
96
|
+
for (const w of writes) {
|
|
97
|
+
if (w.value === null) delete table(w.kind)[w.key]
|
|
98
|
+
else table(w.kind)[w.key] = { ...w.value, version: w.expect + 1 }
|
|
99
|
+
}
|
|
100
|
+
const at = new Date().toISOString()
|
|
101
|
+
const lines = events.map(e => JSON.stringify({ seq: ++state.seq, at, ...e }) + '\n').join('')
|
|
102
|
+
if (lines) fs.appendFileSync(LEDGER, lines)
|
|
103
|
+
save(state)
|
|
104
|
+
return { ok: true }
|
|
105
|
+
}),
|
|
106
|
+
|
|
107
|
+
events: (since = 0) => readLedger().filter(e => e.seq > since),
|
|
108
|
+
|
|
109
|
+
verify: () => {
|
|
110
|
+
const state = load()
|
|
111
|
+
const events = readLedger()
|
|
112
|
+
const last = events.at(-1)?.seq ?? 0
|
|
113
|
+
const problems = []
|
|
114
|
+
if (last !== state.seq) problems.push(`ledger is at seq ${last}, state at ${state.seq}`)
|
|
115
|
+
return { dir, tasks: Object.keys(state.tasks).length, events: events.length, ok: !problems.length, problems }
|
|
116
|
+
},
|
|
117
|
+
}
|
|
118
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,24 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "modboard",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
}
|
|
3
|
+
"version": "0.5.1",
|
|
4
|
+
"description": "A task board several coding agents share, through one CLI",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"bin": { "board": "bin/board.mjs" },
|
|
7
|
+
"exports": {
|
|
8
|
+
"./lib/contract.mjs": "./lib/contract.mjs",
|
|
9
|
+
"./lib/engine.mjs": "./lib/engine.mjs",
|
|
10
|
+
"./lib/store-file.mjs": "./lib/store-file.mjs",
|
|
11
|
+
"./examples/store-memory.mjs": "./examples/store-memory.mjs",
|
|
12
|
+
"./package.json": "./package.json"
|
|
13
|
+
},
|
|
14
|
+
"files": ["bin/", "lib/", "examples/", "hooks/", "types/", ".claude-plugin/plugin.json", "tsconfig.json", "README.md", "CHANGELOG.md", "LICENSE"],
|
|
15
|
+
"scripts": {
|
|
16
|
+
"test": "node --test test/*.test.mjs",
|
|
17
|
+
"test:mod": "claude plugin test .",
|
|
18
|
+
"prepublishOnly": "npm test"
|
|
19
|
+
},
|
|
20
|
+
"keywords": ["modboard", "claude", "claude-code", "claude-code-plugin", "codex", "opencode", "llm-agents", "coding-agents", "multi-agent", "agent-coordination", "task-board", "kanban", "cli"],
|
|
21
|
+
"repository": { "type": "git", "url": "git+https://github.com/Magithar/modboard.git" },
|
|
22
|
+
"engines": { "node": ">=18" },
|
|
23
|
+
"license": "MIT"
|
|
24
|
+
}
|
package/tsconfig.json
ADDED
package/types/index.d.ts
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
export type Task = {
|
|
2
|
+
id: string
|
|
3
|
+
title: string
|
|
4
|
+
description: string
|
|
5
|
+
accept?: string
|
|
6
|
+
status: 'todo' | 'claimed' | 'done'
|
|
7
|
+
claim: { owner: string; since: string; expiresAt: string } | null
|
|
8
|
+
notes: { at: string; by: string; text: string }[]
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
export type Agent = { name: string; lastSeen: string }
|
|
12
|
+
|
|
13
|
+
export type Usage = {
|
|
14
|
+
limits: { kind: string; percentUsed: number; resetsAt?: string }[]
|
|
15
|
+
context?: number
|
|
16
|
+
costUsd?: number
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
declare module 'claude-code' {
|
|
20
|
+
interface PluginState {
|
|
21
|
+
modboard: { tasks: Task[]; agents: Agent[]; me: string; usage: Usage; model: string; effort: string; custom: Record<string, string> }
|
|
22
|
+
}
|
|
23
|
+
}
|