@mergeline/agent 0.4.0 → 0.4.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/README.md +4 -1
- package/dist/cli.js +1 -1
- package/dist/init.js +41 -23
- package/dist/mcp.js +3 -2
- package/dist/repo.js +32 -13
- package/dist/service.js +5 -1
- package/kit/done.md +9 -6
- package/kit/rules.md +2 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -22,7 +22,10 @@ npx -y @mergeline/agent start fe-1 # eve
|
|
|
22
22
|
|
|
23
23
|
`init --url` writes the board's address into `.mergeline.json` (no
|
|
24
24
|
secrets; commit it), so in that repository, and in the agents' worktrees of
|
|
25
|
-
it, the commands below use that board.
|
|
25
|
+
it, the commands below use that board. The file also holds the kit's
|
|
26
|
+
version, which every claim sends with the package's: when the board expects
|
|
27
|
+
a newer kit, the claim's answer says to run
|
|
28
|
+
`npx -y @mergeline/agent@latest init --claude` again. `login` checks the key with the
|
|
26
29
|
board and saves it in `~/.config/mergeline/credentials.json` (readable only
|
|
27
30
|
by you, outside any repository), per board and agent: `fe-1` on two boards
|
|
28
31
|
is two saved keys. In a repository with `.mergeline.json`, `--url` can be
|
package/dist/cli.js
CHANGED
|
@@ -175,7 +175,7 @@ function runInit(args) {
|
|
|
175
175
|
` board login <agent name> ${result.board ? "" : "--url <board address> "}--key <key>` +
|
|
176
176
|
(result.board ? ` (the board: ${result.board}, from ${REPO_FILE})` : "") + "\n" +
|
|
177
177
|
"and start each session with: board start <agent name>" + (args.includes("--codex") ? " -- codex" : "") + "\n" +
|
|
178
|
-
"Commit AGENTS.md" + (args.includes("--claude") ? ", CLAUDE.md, .claude/, .mcp.json" : "") +
|
|
178
|
+
"Commit AGENTS.md" + (args.includes("--claude") ? ", CLAUDE.md, .claude/, .mcp.json" : "") + `, ${REPO_FILE}` +
|
|
179
179
|
" so every checkout has the kit; the key is not in any of them.\n");
|
|
180
180
|
if (args.includes("--claude")) {
|
|
181
181
|
out.write("Claude Code applies .claude/settings.json (the board's permissions) only in a trusted folder:\n" +
|
package/dist/init.js
CHANGED
|
@@ -13,8 +13,11 @@
|
|
|
13
13
|
// The permissions also allow the repository's own package manager (from its
|
|
14
14
|
// lockfile) to install and to run its test, lint and typecheck scripts, so an
|
|
15
15
|
// unattended agent does not stop at `pnpm install` in a new worktree.
|
|
16
|
-
// -
|
|
17
|
-
// so the board commands in this repository pick that
|
|
16
|
+
// - .mergeline.json (repo.ts) gets the kit's version and, with --url, the
|
|
17
|
+
// board's address, so the board commands in this repository pick that
|
|
18
|
+
// board's saved key. The version is also in the section's start marker and
|
|
19
|
+
// in each kit file's marker line; init finds both by their prefix, so files
|
|
20
|
+
// from an older kit are still updated.
|
|
18
21
|
// - --codex writes the prompts into $CODEX_HOME/prompts (default
|
|
19
22
|
// ~/.codex/prompts) and prints the MCP snippet for ~/.codex/config.toml,
|
|
20
23
|
// which init does not edit. The snippet names the agent; its key stays in
|
|
@@ -23,15 +26,26 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
|
|
23
26
|
import { homedir } from "node:os";
|
|
24
27
|
import { dirname, join, relative } from "node:path";
|
|
25
28
|
import { fileURLToPath } from "node:url";
|
|
26
|
-
import {
|
|
29
|
+
import { readRepoFile, REPO_FILE } from "./repo.js";
|
|
27
30
|
const KIT = fileURLToPath(new URL("../kit/", import.meta.url));
|
|
31
|
+
const PACKAGE = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
|
|
28
32
|
/** This package's npm name, for the npx commands init writes (one place to rename it). */
|
|
29
|
-
export const PACKAGE_NAME =
|
|
30
|
-
|
|
31
|
-
|
|
33
|
+
export const PACKAGE_NAME = PACKAGE.name;
|
|
34
|
+
/** Sent with every claim as `client`. */
|
|
35
|
+
export const PACKAGE_VERSION = PACKAGE.version;
|
|
36
|
+
/**
|
|
37
|
+
* The version of agent/kit: raise it with every change to the kit's files
|
|
38
|
+
* (kit-check fails until you do). Kit 1 is everything up to package 0.4.0,
|
|
39
|
+
* which wrote no version. The board says when a claim's kit is older than it
|
|
40
|
+
* expects (KIT_MIN in pocketbase/pb_hooks/board_lib.js).
|
|
41
|
+
*/
|
|
42
|
+
export const KIT_VERSION = 2;
|
|
43
|
+
const START = `<!-- mergeline:start (kit ${KIT_VERSION}; managed by \`board init\`; edit outside these markers) -->`;
|
|
44
|
+
/** Markers are found by these prefixes, so an edited marker line or an older kit's still counts. */
|
|
32
45
|
const START_PREFIX = "<!-- mergeline:start";
|
|
33
46
|
const END = "<!-- mergeline:end -->";
|
|
34
|
-
const MANAGED =
|
|
47
|
+
const MANAGED = `<!-- mergeline: written by \`board init\` (kit ${KIT_VERSION}); init updates this file while this line is here -->`;
|
|
48
|
+
const MANAGED_PREFIX = "<!-- mergeline: written by `board init`";
|
|
35
49
|
function kit(name) {
|
|
36
50
|
return readFileSync(join(KIT, name), "utf8").replace(/\s+$/, "") + "\n";
|
|
37
51
|
}
|
|
@@ -109,7 +123,7 @@ export function init(opts) {
|
|
|
109
123
|
return record(path, "create");
|
|
110
124
|
}
|
|
111
125
|
const current = readFileSync(path, "utf8");
|
|
112
|
-
if (!current.includes(
|
|
126
|
+
if (!current.includes(MANAGED_PREFIX))
|
|
113
127
|
return record(path, "skip", "a file of this name exists and was not written by board init");
|
|
114
128
|
if (current === content)
|
|
115
129
|
return record(path, "unchanged");
|
|
@@ -138,32 +152,36 @@ export function init(opts) {
|
|
|
138
152
|
record(path, kind);
|
|
139
153
|
}
|
|
140
154
|
const promptFile = (name) => `---\ndescription: ${COMMANDS[name]}\n---\n\n${MANAGED}\n\n${kit(`${name}.md`)}`;
|
|
141
|
-
/** .mergeline.json: the board's address,
|
|
142
|
-
function
|
|
143
|
-
let current;
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
155
|
+
/** .mergeline.json: the kit's version and the board's address (from --url, else the one there). */
|
|
156
|
+
function repoFile(path, url) {
|
|
157
|
+
let current = {};
|
|
158
|
+
if (existsSync(path)) {
|
|
159
|
+
try {
|
|
160
|
+
current = readRepoFile(path);
|
|
161
|
+
}
|
|
162
|
+
catch (err) {
|
|
163
|
+
if (!url) {
|
|
164
|
+
record(path, "skip", `${err instanceof Error ? err.message : String(err)}`);
|
|
165
|
+
return undefined;
|
|
166
|
+
}
|
|
167
|
+
}
|
|
149
168
|
}
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
const content = JSON.stringify({ board: url }, null, 2) + "\n";
|
|
169
|
+
const board = url ?? current.board;
|
|
170
|
+
const content = JSON.stringify({ ...(board ? { board } : {}), kit: KIT_VERSION }, null, 2) + "\n";
|
|
153
171
|
if (!existsSync(path)) {
|
|
154
172
|
write(path, content, "create");
|
|
155
173
|
record(path, "create");
|
|
156
174
|
}
|
|
157
|
-
else if (
|
|
175
|
+
else if (readFileSync(path, "utf8") === content) {
|
|
158
176
|
record(path, "unchanged");
|
|
159
177
|
}
|
|
160
178
|
else {
|
|
161
179
|
write(path, content, "update");
|
|
162
|
-
record(path, "update", current && current !== url ? `board ${current} -> ${url}` : undefined);
|
|
180
|
+
record(path, "update", current.board && url && current.board !== url ? `board ${current.board} -> ${url}` : undefined);
|
|
163
181
|
}
|
|
164
|
-
return
|
|
182
|
+
return board;
|
|
165
183
|
}
|
|
166
|
-
const board =
|
|
184
|
+
const board = repoFile(join(opts.dir, REPO_FILE), opts.url);
|
|
167
185
|
let project = [];
|
|
168
186
|
const rules = kit("rules.md");
|
|
169
187
|
section(join(opts.dir, "AGENTS.md"), rules);
|
package/dist/mcp.js
CHANGED
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
7
7
|
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
8
8
|
import { z } from "zod";
|
|
9
|
+
import { PACKAGE_VERSION } from "./init.js";
|
|
9
10
|
import { agentCredentialsFromEnv } from "./pb.js";
|
|
10
11
|
import { BoardError, TicketService } from "./service.js";
|
|
11
12
|
const ticketId = z.string().min(1).describe("Ticket id, as returned by claim");
|
|
@@ -32,7 +33,7 @@ async function run(fn) {
|
|
|
32
33
|
}
|
|
33
34
|
}
|
|
34
35
|
export function createServer(board) {
|
|
35
|
-
const server = new McpServer({ name: "board", version:
|
|
36
|
+
const server = new McpServer({ name: "board", version: PACKAGE_VERSION });
|
|
36
37
|
server.registerTool("list_mine", {
|
|
37
38
|
title: "List my tickets",
|
|
38
39
|
description: "List the tickets assigned to you that are not done, with status, priority and block. " +
|
|
@@ -48,7 +49,7 @@ export function createServer(board) {
|
|
|
48
49
|
"The ticket comes with spec_path, branch, answer and notes: the spec on main plus answer and " +
|
|
49
50
|
"notes are your only requirements. Claiming starts a lease (claimed_until); keep it alive with heartbeat. " +
|
|
50
51
|
"If it fails because another session of yours holds your ticket, say so and stop: do not retry and do not " +
|
|
51
|
-
"start other work.",
|
|
52
|
+
"start other work. If the answer has kit_outdated, tell the human what it says and go on with the ticket.",
|
|
52
53
|
}, () => run(() => board.claim()));
|
|
53
54
|
server.registerTool("heartbeat", {
|
|
54
55
|
title: "Extend lease",
|
package/dist/repo.js
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
|
-
// Which board a repository works with: `board init
|
|
2
|
-
//
|
|
3
|
-
//
|
|
1
|
+
// Which board a repository works with and which kit it has: `board init`
|
|
2
|
+
// writes .mergeline.json at the repository's root (no secrets; committed),
|
|
3
|
+
// with the board's address when given --url, so `board start <name>` there
|
|
4
|
+
// picks that board's saved key, and the kit's version, which claims carry so
|
|
5
|
+
// the board can say when the kit is old.
|
|
4
6
|
//
|
|
5
|
-
// { "board": "https://acme.mergeline.app" }
|
|
7
|
+
// { "board": "https://acme.mergeline.app", "kit": 2 }
|
|
6
8
|
//
|
|
7
9
|
// The file is looked up from the current folder upwards, up to the root of
|
|
8
10
|
// the git checkout (a folder with .git, which is a file in a worktree such as
|
|
@@ -38,8 +40,8 @@ export function findRepoFile(dir) {
|
|
|
38
40
|
return null;
|
|
39
41
|
}
|
|
40
42
|
}
|
|
41
|
-
/**
|
|
42
|
-
export function
|
|
43
|
+
/** A .mergeline.json's contents; an error that says which file when it is broken. */
|
|
44
|
+
export function readRepoFile(file) {
|
|
43
45
|
let data;
|
|
44
46
|
try {
|
|
45
47
|
data = JSON.parse(readFileSync(file, "utf8"));
|
|
@@ -47,14 +49,30 @@ export function readRepoBoard(file) {
|
|
|
47
49
|
catch {
|
|
48
50
|
throw new Error(`${file} is not valid JSON; run board init --url <board> to write it again`);
|
|
49
51
|
}
|
|
50
|
-
const board = data
|
|
51
|
-
|
|
52
|
-
|
|
52
|
+
const { board, kit } = (data ?? {});
|
|
53
|
+
const out = {};
|
|
54
|
+
if (board !== undefined) {
|
|
55
|
+
if (typeof board !== "string" || !board)
|
|
56
|
+
throw new Error(`${file} has no "board" address; run board init --url <board>`);
|
|
57
|
+
try {
|
|
58
|
+
out.board = normalizeBoardUrl(board);
|
|
59
|
+
}
|
|
60
|
+
catch (err) {
|
|
61
|
+
throw new Error(`${file}: ${err instanceof Error ? err.message : String(err)}`);
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
if (typeof kit === "number" && Number.isInteger(kit))
|
|
65
|
+
out.kit = kit;
|
|
66
|
+
return out;
|
|
67
|
+
}
|
|
68
|
+
/** The kit version of the repository around cwd, or undefined (no file, no version, or a broken file). */
|
|
69
|
+
export function repoKit(cwd = process.cwd()) {
|
|
70
|
+
const file = findRepoFile(cwd);
|
|
53
71
|
try {
|
|
54
|
-
return
|
|
72
|
+
return file ? readRepoFile(file).kit : undefined;
|
|
55
73
|
}
|
|
56
|
-
catch
|
|
57
|
-
|
|
74
|
+
catch {
|
|
75
|
+
return undefined;
|
|
58
76
|
}
|
|
59
77
|
}
|
|
60
78
|
/** The board in use here: BOARD_URL, else the repository's .mergeline.json, else null. */
|
|
@@ -63,5 +81,6 @@ export function boardInContext(env = process.env, cwd = process.cwd()) {
|
|
|
63
81
|
if (fromEnv)
|
|
64
82
|
return { url: normalizeBoardUrl(fromEnv), from: "BOARD_URL" };
|
|
65
83
|
const file = findRepoFile(cwd);
|
|
66
|
-
|
|
84
|
+
const board = file ? readRepoFile(file).board : undefined;
|
|
85
|
+
return board ? { url: board, from: file } : null;
|
|
67
86
|
}
|
package/dist/service.js
CHANGED
|
@@ -5,6 +5,8 @@
|
|
|
5
5
|
// reimplementing this file only.
|
|
6
6
|
import { randomUUID } from "node:crypto";
|
|
7
7
|
import PocketBase, { ClientResponseError } from "pocketbase";
|
|
8
|
+
import { PACKAGE_VERSION } from "./init.js";
|
|
9
|
+
import { repoKit } from "./repo.js";
|
|
8
10
|
/** An error whose message is safe to show to an agent or a human as is. */
|
|
9
11
|
export class BoardError extends Error {
|
|
10
12
|
status;
|
|
@@ -130,8 +132,10 @@ export class TicketService {
|
|
|
130
132
|
return records;
|
|
131
133
|
});
|
|
132
134
|
}
|
|
135
|
+
/** Carries this package's version and the repository's kit version (repo.ts), so the board can say when the kit is old. */
|
|
133
136
|
claim() {
|
|
134
|
-
|
|
137
|
+
const kit = repoKit();
|
|
138
|
+
return this.post("claim", { client: PACKAGE_VERSION, ...(kit === undefined ? {} : { kit }) });
|
|
135
139
|
}
|
|
136
140
|
heartbeat(ticketId, note) {
|
|
137
141
|
return this.post("heartbeat", { ticket_id: ticketId, note: note ?? "" });
|
package/kit/done.md
CHANGED
|
@@ -6,14 +6,17 @@ the `board` command of the same name (`submit_for_review` is `board submit`).
|
|
|
6
6
|
`npm run lint`; use what the project has). If they fail, fix them. If you
|
|
7
7
|
cannot, call `log_event` kind `warn` with what fails, then `ask_human`,
|
|
8
8
|
and stop.
|
|
9
|
-
2.
|
|
9
|
+
2. Call `heartbeat` before you push. If it says another session holds the
|
|
10
|
+
ticket, stop at once: do not commit, push or open a PR. If it says to
|
|
11
|
+
claim again, stop and claim.
|
|
12
|
+
3. Commit with a clear message and push the branch:
|
|
10
13
|
`git push -u origin <branch>`.
|
|
11
|
-
|
|
14
|
+
4. Open a PR against `main` with `gh pr create`. Title: the ticket title.
|
|
12
15
|
The body names the ticket id, the spec path and the spec commit
|
|
13
16
|
(`record_spec`). If a PR for the branch already exists
|
|
14
17
|
(`gh pr view <branch>`), the push updates it; use its URL.
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
18
|
+
5. Call `submit_for_review` with the PR URL and a 2 to 4 line summary of
|
|
19
|
+
what changed. If your tool tells you what this work cost (tokens, cost),
|
|
20
|
+
pass it as `usage`; otherwise leave it out.
|
|
21
|
+
6. Do not mark the ticket done and do not merge the PR. A human does that.
|
|
19
22
|
Stop here.
|
package/kit/rules.md
CHANGED
|
@@ -27,3 +27,5 @@ the done instructions: `/pick` and `/done` in Claude Code,
|
|
|
27
27
|
at once: no commit, no push, no PR.
|
|
28
28
|
- If a board tool says the board is paused, stop and tell the human: it
|
|
29
29
|
wakes when a person opens it. Do not retry in a loop.
|
|
30
|
+
- If `claim` answers with `kit_outdated`, tell the human what it says once
|
|
31
|
+
and go on with the ticket.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mergeline/agent",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.1",
|
|
4
4
|
"description": "The agent's side of a Mergeline board: an MCP server and the `board` CLI. Works with any agent tool that runs MCP servers or shell commands.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "frontender-ua",
|