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.
@@ -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.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
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
@@ -0,0 +1,3 @@
1
+ {
2
+ "extends": "./.claude-plugin/types/tsconfig.json"
3
+ }
@@ -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
+ }